diff --git a/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_APP_SPEC.md b/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_APP_SPEC.md new file mode 100644 index 000000000..d166a1017 --- /dev/null +++ b/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_APP_SPEC.md @@ -0,0 +1,46693 @@ +# Matter Application Cluster + +# Specification + +# Version 1.4. + +``` +Document: 23-27350_Matter-1.4.1-Application-Cluster-Specification.pdf +March 17, 2025 +Sponsored by: Connectivity Standards Alliance +Accepted by: This document has been accepted for release by the Connectivity +Standards Alliance Board of Directors on March 17, 2025 +Abstract: The Matter Application Clusters specified in this document are +generic interfaces that are sufficiently general to be of use across a +wide range of application domains. +Keywords: Referenced in Chapter 1. +``` +Copyright © 2022-2025 Connectivity Standards Alliance, Inc. +508 Second Street, Suite 109B Davis, CA 95616 - USA +[http://www.csa-iot.org](http://www.csa-iot.org) +All rights reserved. + +Permission is granted to members of the Connectivity Standards Alliance to reproduce this +document for their own use or the use of other Connectivity Standards Alliance members only, +provided this notice is included. All other rights reserved. Duplication for sale, or for commercial or +for-profit use is strictly prohibited without the prior written consent of the Connectivity Standards +Alliance. + + + +# Matter Application Clusters + +``` +Version 1.4.1, 2025-03-12 06:42:16 -0700: Approved +``` + + +**Copyright Notice, License and Disclaimer** + +Copyright © Connectivity Standards Alliance (2021-2023). All rights reserved. The information +within this document is the property of the Connectivity Standards Alliance and its use and disclo­ +sure are restricted, except as expressly set forth herein. + +Connectivity Standards Alliance hereby grants you a fully-paid, non-exclusive, nontransferable, +worldwide, limited and revocable license (without the right to sublicense), under Connectivity Stan­ +dards Alliance’s applicable copyright rights, to view, download, save, reproduce and use the docu­ +ment solely for your own internal purposes and in accordance with the terms of the license set +forth herein. This license does not authorize you to, and you expressly warrant that you shall not: +(a) permit others (outside your organization) to use this document; (b) post or publish this docu­ +ment; (c) modify, adapt, translate, or otherwise change this document in any manner or create any +derivative work based on this document; (d) remove or modify any notice or label on this docu­ +ment, including this Copyright Notice, License and Disclaimer. The Connectivity Standards Alliance +does not grant you any license hereunder other than as expressly stated herein. + +Elements of this document may be subject to third party intellectual property rights, including +without limitation, patent, copyright or trademark rights, and any such third party may or may not +be a member of the Connectivity Standards Alliance. Connectivity Standards Alliance members +grant other Connectivity Standards Alliance members certain intellectual property rights as set +forth in the Connectivity Standards Alliance IPR Policy. Connectivity Standards Alliance members +do not grant you any rights under this license. The Connectivity Standards Alliance is not responsi­ +ble for, and shall not be held responsible in any manner for, identifying or failing to identify any or +all such third party intellectual property rights. Please visit [http://www.csa-iot.org](http://www.csa-iot.org) for more information +on how to become a member of the Connectivity Standards Alliance. + +This document and the information contained herein are provided on an “AS IS” basis and the Con­ +nectivity Standards Alliance DISCLAIMS 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 INTELLEC­ +TUAL PROPERTY RIGHTS INCLUDING PATENT, COPYRIGHT OR TRADEMARK RIGHTS); OR (B) ANY +IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR +NONINFRINGEMENT. IN NO EVENT WILL THE CONNECTIVITY STANDARDS ALLIANCE BE LIABLE +FOR ANY LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF BUSI­ +NESS, OR FOR ANY OTHER DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTAL, 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 in this document may be trademarks that are the sole prop­ +erty of their respective owners. + +This notice and disclaimer must be included on all copies of this document. + +Connectivity Standards Alliance +508 Second Street, Suite 206 +Davis, CA 95616, USA + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1 +``` + +Page 2 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Revision History** + +``` +Revision Date Details Editor +1 September 23, 2022 Version 1.0 Robert Szewczyk +2 May 17, 2023 Version 1.1 Robert Szewczyk +3 October 18, 2023 Version 1.2 Robert Szewczyk +4 April 17, 2024 Version 1.3 Robert Szewczyk +5 November 4, 2024 Version 1.4 Robert Szewczyk +6 March 17, 2024 Version 1.4.1 Robert Szewczyk +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 3 +``` + +Page 4 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +## Table of Contents + + + + + + + + + + + + +- Copyright Notice, License and Disclaimer.   +- Revision History.   +- Introduction.   + - Scope and Purpose.   + - References.   + - CSA Reference Documents.   + - External Reference Documents.   + - Provisional.   + - List of Provisional Items.   +- 1. General.   + - 1.1. General Description.   + - 1.1.1. Introduction.   + - 1.1.2. Cluster List.   + - 1.2. Identify Cluster.   + - 1.2.1. Revision History.   + - 1.2.2. Classification.   + - 1.2.3. Cluster ID.   + - 1.2.4. Data Types.   + - 1.2.5. Attributes.   + - 1.2.6. Commands.   + - 1.3. Groups Cluster.   + - 1.3.1. Revision History.   + - 1.3.2. Classification.   + - 1.3.3. Cluster ID.   + - 1.3.4. Features.   + - 1.3.5. Data Types.   + - 1.3.6. Attributes.   + - 1.3.7. Commands.   + - 1.4. Scenes Management Cluster.   + - 1.4.1. Revision History.   + - 1.4.2. Classification.   + - 1.4.3. Cluster ID.   + - 1.4.4. Features.   + - 1.4.5. Dependencies.   + - 1.4.6. Handling of fabric-scoping.   + - 1.4.7. Data Types.   + - 1.4.8. Attributes.   + - 1.4.9. Commands.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page +- 1.5. On/Off Cluster.   + - 1.5.1. Revision History.   + - 1.5.2. Classification.   + - 1.5.3. Cluster ID.   + - 1.5.4. Features.   + - 1.5.5. Data Types   + - 1.5.6. Attributes.   + - 1.5.7. Commands.   + - 1.5.8. State Description.   +- 1.6. Level Control Cluster.   + - 1.6.1. Revision History.   + - 1.6.2. Classification.   + - 1.6.3. Cluster ID.   + - 1.6.4. Features.   + - 1.6.5. Data Types   + - 1.6.6. Attributes.   + - 1.6.7. Commands.   + - 1.6.8. State Change Table for Lighting.   +- 1.7. Boolean State Cluster.   + - 1.7.1. Revision History.   + - 1.7.2. Classification.   + - 1.7.3. Cluster ID.   + - 1.7.4. Attributes.   + - 1.7.5. Events.   +- 1.8. Boolean State Configuration Cluster.   + - 1.8.1. Revision History.   + - 1.8.2. Classification.   + - 1.8.3. Cluster ID.   + - 1.8.4. Features.   + - 1.8.5. Data Types   + - 1.8.6. Attributes.   + - 1.8.7. Commands.   + - 1.8.8. Events.   +- 1.9. Mode Select Cluster.   + - 1.9.1. Revision History.   + - 1.9.2. Classification.   + - 1.9.3. Cluster ID.   + - 1.9.4. Features.   + - 1.9.5. Data Types   + - 1.9.6. Attributes.   + - 1.9.7. Commands.   +- 1.10. Mode Base Cluster.   + - 1.10.1. Revision History.   + - 1.10.2. Classification.   + - 1.10.3. Cluster ID.   + - 1.10.4. Features.   + - 1.10.5. Data Types.   + - 1.10.6. Attributes.   + - 1.10.7. Commands.   + - 1.10.8. Mode Namespace.   +- 1.11. Low Power Cluster.   + - 1.11.1. Revision History.   + - 1.11.2. Classification.   + - 1.11.3. Cluster ID.   + - 1.11.4. Commands.   +- 1.12. Wake On LAN Cluster.   + - 1.12.1. Revision History.   + - 1.12.2. Classification.   + - 1.12.3. Cluster ID.   + - 1.12.4. Attributes.   +- 1.13. Switch Cluster.   + - 1.13.1. Revision History.   + - 1.13.2. Classification.   + - 1.13.3. Cluster ID.   + - 1.13.4. Features.   + - 1.13.5. Attributes.   + - 1.13.6. Events.   + - 1.13.7. Sequence of generated events.   + - 1.13.8. Sequence of events for MultiPress.   + - 1.13.9. Summary of cases for MS feature flag.   + - 1.13.10. Multi Position Details.   +- 1.14. Operational State Cluster.   + - 1.14.1. Revision History.   + - 1.14.2. Classification.   + - 1.14.3. Cluster ID.   + - 1.14.4. Data Types.   + - 1.14.5. Attributes.   + - 1.14.6. Commands.   + - 1.14.7. Events.   +- 1.15. Alarm Base Cluster.   + - 1.15.1. Revision History.   + - 1.15.2. Classification.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 1.15.3. Cluster ID.   + - 1.15.4. Features.   + - 1.15.5. Data Types.   + - 1.15.6. Attributes.   + - 1.15.7. Commands.   + - 1.15.8. Events.   + - 1.16. Messages Cluster   + - 1.16.1. Revision History.   + - 1.16.2. Classification.   + - 1.16.3. Cluster ID.   + - 1.16.4. Features.   + - 1.16.5. Data Types.   + - 1.16.6. Attributes.   + - 1.16.7. Commands.   + - 1.16.8. Events.   + - 1.17. Service Area Cluster.   + - 1.17.1. Revision History.   + - 1.17.2. Classification.   + - 1.17.3. Cluster ID.   + - 1.17.4. Features.   + - 1.17.5. Data Types.   + - 1.17.6. Attributes.   + - 1.17.7. Commands.   +- 2. Measurement and Sensing.   + - 2.1. General Description.   + - 2.1.1. Introduction.   + - 2.1.2. Cluster List.   + - 2.1.3. Measured Value.   + - 2.1.4. Measurement Accuracy.   + - 2.2. Illuminance Measurement Cluster.   + - 2.2.1. Revision History.   + - 2.2.2. Classification.   + - 2.2.3. Cluster ID.   + - 2.2.4. Data Types.   + - 2.2.5. Attributes.   + - 2.3. Temperature Measurement Cluster.   + - 2.3.1. Revision History.   + - 2.3.2. Classification.   + - 2.3.3. Cluster ID.   + - 2.3.4. Attributes.   + - 2.4. Pressure Measurement Cluster.   + - 2.4.1. Revision History.   + - 2.4.2. Classification.   + - 2.4.3. Cluster ID.   + - 2.4.4. Features.   + - 2.4.5. Attributes.   +- 2.5. Flow Measurement Cluster.   + - 2.5.1. Revision History.   + - 2.5.2. Classification.   + - 2.5.3. Cluster ID.   + - 2.5.4. Attributes.   +- 2.6. Water Content Measurement Clusters.   + - 2.6.1. Revision History.   + - 2.6.2. Classification.   + - 2.6.3. Cluster ID.   + - 2.6.4. Attributes.   +- 2.7. Occupancy Sensing Cluster.   + - 2.7.1. Revision History.   + - 2.7.2. Classification.   + - 2.7.3. Cluster ID.   + - 2.7.4. Features.   + - 2.7.5. Data Types.   + - 2.7.6. Attributes.   + - 2.7.7. Events.   +- 2.8. Resource Monitoring Clusters.   + - 2.8.1. Revision History.   + - 2.8.2. Classification.   + - 2.8.3. Cluster IDs   + - 2.8.4. Features.   + - 2.8.5. Data Types.   + - 2.8.6. Attributes.   + - 2.8.7. Commands.   +- 2.9. Air Quality Cluster.   + - 2.9.1. Revision History.   + - 2.9.2. Classification.   + - 2.9.3. Cluster ID.   + - 2.9.4. Features.   + - 2.9.5. Data Types.   + - 2.9.6. Attributes.   +- 2.10. Concentration Measurement Clusters.   + - 2.10.1. Revision History.   + - 2.10.2. Classification.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 2.10.3. Cluster IDs   + - 2.10.4. Features.   + - 2.10.5. Data Types.   + - 2.10.6. Attributes.   + - 2.11. Smoke CO Alarm Cluster   + - 2.11.1. Revision History.   + - 2.11.2. Classification.   + - 2.11.3. Cluster ID.   + - 2.11.4. Features.   + - 2.11.5. Data Types.   + - 2.11.6. Attributes.   + - 2.11.7. Commands.   + - 2.11.8. Events.   + - 2.12. Electrical Energy Measurement Cluster.   + - 2.12.1. Revision History.   + - 2.12.2. Classification.   + - 2.12.3. Cluster ID.   + - 2.12.4. Features.   + - 2.12.5. Data Types.   + - 2.12.6. Attributes.   + - 2.12.7. Events.   + - 2.13. Electrical Power Measurement Cluster.   + - 2.13.1. Revision History.   + - 2.13.2. Classification.   + - 2.13.3. Cluster ID.   + - 2.13.4. Features.   + - 2.13.5. Data Types.   + - 2.13.6. Attributes.   + - 2.13.7. Events.   +- 3. Lighting.   + - 3.1. General Description.   + - 3.1.1. Introduction.   + - 3.1.2. Terms.   + - 3.1.3. Cluster List.   + - 3.2. Color Control Cluster.   + - 3.2.1. Revision History.   + - 3.2.2. Classification.   + - 3.2.3. Cluster ID.   + - 3.2.4. Features.   + - 3.2.5. Dependencies.   + - 3.2.6. Data Types.   + - 3.2.7. Attributes.   + - 3.2.8. Commands.   + - 3.3. Ballast Configuration Cluster.   + - 3.3.1. Revision History.   + - 3.3.2. Classification.   + - 3.3.3. Cluster ID.   + - 3.3.4. Dependencies.   + - 3.3.5. Data Types.   + - 3.3.6. Attributes.   + - 3.3.7. The Dimming Light Curve   +- 4. HVAC.   + - 4.1. General Description.   + - 4.1.1. Introduction.   + - 4.1.2. Terms.   + - 4.1.3. Cluster List.   + - 4.2. Pump Configuration and Control Cluster.   + - 4.2.1. Revision History.   + - 4.2.2. Classification.   + - 4.2.3. Cluster ID.   + - 4.2.4. Features.   + - 4.2.5. Dependencies.   + - 4.2.6. Data Types.   + - 4.2.7. Attributes.   + - 4.2.8. Events.   + - 4.3. Thermostat Cluster.   + - 4.3.1. Revision History.   + - 4.3.2. Classification.   + - 4.3.3. Cluster ID.   + - 4.3.4. Features.   + - 4.3.5. Units of Temperature.   + - 4.3.6. Setpoint Limits.   + - 4.3.7. Dependencies.   + - 4.3.8. Data Types.   + - 4.3.9. Attributes.   + - 4.3.10. Commands.   + - 4.4. Fan Control Cluster.   + - 4.4.1. Revision History.   + - 4.4.2. Classification.   + - 4.4.3. Cluster ID.   + - 4.4.4. Features.   + - 4.4.5. Data Types.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 4.4.6. Attributes.   + - 4.4.7. Commands.   + - 4.5. Thermostat User Interface Configuration Cluster.   + - 4.5.1. Revision History.   + - 4.5.2. Classification.   + - 4.5.3. Cluster ID.   + - 4.5.4. Conversion of Temperature Values for Display.   + - 4.5.5. Data Types.   + - 4.5.6. Attributes.   + - 4.6. Valve Configuration and Control Cluster.   + - 4.6.1. Revision History.   + - 4.6.2. Classification.   + - 4.6.3. Cluster ID.   + - 4.6.4. Features.   + - 4.6.5. Data Types.   + - 4.6.6. Status Codes.   + - 4.6.7. Attributes.   + - 4.6.8. Commands.   + - 4.6.9. Events.   +- 5. Closures.   + - 5.1. General Description.   + - 5.1.1. Introduction.   + - 5.1.2. Cluster List.   + - 5.2. Door Lock Cluster.   + - 5.2.1. Revision History.   + - 5.2.2. Classification.   + - 5.2.3. Cluster ID.   + - 5.2.4. Features.   + - 5.2.5. Recommended steps for creating a new User.   + - 5.2.6. Data Types.   + - 5.2.7. Status Codes.   + - 5.2.8. PIN/RFID Code Format.   + - 5.2.9. Attributes.   + - 5.2.10. Commands.   + - 5.2.11. Events.   + - 5.3. Window Covering Cluster   + - 5.3.1. Revision History.   + - 5.3.2. Classification.   + - 5.3.3. Cluster ID.   + - 5.3.4. Features.   + - 5.3.5. Data Types.   + - 5.3.6. Attributes.   + - 5.3.7. Commands.   +- 6. Media   + - 6.1. General Description.   + - 6.1.1. Introduction.   + - 6.1.2. Cluster List.   + - 6.2. Account Login Cluster.   + - 6.2.1. Revision History.   + - 6.2.2. Classification.   + - 6.2.3. Cluster ID.   + - 6.2.4. Commands.   + - 6.2.5. Events.   + - 6.3. Application Basic Cluster.   + - 6.3.1. Revision History.   + - 6.3.2. Classification.   + - 6.3.3. Cluster ID.   + - 6.3.4. Data Types.   + - 6.3.5. Attributes.   + - 6.4. Application Launcher Cluster.   + - 6.4.1. Revision History.   + - 6.4.2. Classification.   + - 6.4.3. Cluster ID.   + - 6.4.4. Features.   + - 6.4.5. Data Types.   + - 6.4.6. Attributes.   + - 6.4.7. Commands.   + - 6.5. Audio Output Cluster.   + - 6.5.1. Revision History.   + - 6.5.2. Classification.   + - 6.5.3. Cluster ID.   + - 6.5.4. Features.   + - 6.5.5. Data Types.   + - 6.5.6. Attributes.   + - 6.5.7. Commands.   + - 6.6. Channel Cluster.   + - 6.6.1. Revision History.   + - 6.6.2. Classification.   + - 6.6.3. Cluster ID.   + - 6.6.4. Features.   + - 6.6.5. Data Types.   + - 6.6.6. Attributes.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 6.6.7. Commands.   +- 6.7. Content Launcher Cluster.   + - 6.7.1. Revision History.   + - 6.7.2. Classification.   + - 6.7.3. Cluster ID.   + - 6.7.4. Features.   + - 6.7.5. Data Types.   + - 6.7.6. Attributes.   + - 6.7.7. Commands.   +- 6.8. Keypad Input Cluster.   + - 6.8.1. Revision History.   + - 6.8.2. Classification.   + - 6.8.3. Cluster ID.   + - 6.8.4. Features.   + - 6.8.5. Data Types.   + - 6.8.6. Commands.   +- 6.9. Media Input Cluster.   + - 6.9.1. Revision History.   + - 6.9.2. Classification.   + - 6.9.3. Cluster ID.   + - 6.9.4. Features.   + - 6.9.5. Data Types.   + - 6.9.6. Attributes.   + - 6.9.7. Commands.   +- 6.10. Media Playback Cluster.   + - 6.10.1. Revision History.   + - 6.10.2. Classification.   + - 6.10.3. Cluster ID.   + - 6.10.4. Features.   + - 6.10.5. Data Types.   + - 6.10.6. Attributes.   + - 6.10.7. Commands.   + - 6.10.8. Events.   +- 6.11. Target Navigator Cluster   + - 6.11.1. Revision History.   + - 6.11.2. Classification.   + - 6.11.3. Cluster ID.   + - 6.11.4. Data Types.   + - 6.11.5. Attributes.   + - 6.11.6. Commands.   + - 6.11.7. Events.   + - 6.12. Content App Observer Cluster.   + - 6.12.1. Revision History.   + - 6.12.2. Classification.   + - 6.12.3. Cluster ID.   + - 6.12.4. Data Types.   + - 6.12.5. Commands.   + - 6.13. Content Control Cluster.   + - 6.13.1. Revision History.   + - 6.13.2. Classification.   + - 6.13.3. Cluster ID.   + - 6.13.4. Features.   + - 6.13.5. Data Types.   + - 6.13.6. Status Codes.   + - 6.13.7. Attributes.   + - 6.13.8. Commands.   + - 6.13.9. Events.   +- 7. Robots.   + - 7.1. General Description.   + - 7.1.1. Introduction.   + - 7.1.2. Cluster List.   + - 7.2. RVC Run Mode Cluster.   + - 7.2.1. Revision History.   + - 7.2.2. Classification.   + - 7.2.3. Cluster ID.   + - 7.2.4. Features.   + - 7.2.5. Data Types.   + - 7.2.6. Attributes.   + - 7.2.7. Derived Cluster Namespace.   + - 7.2.8. Mode Use.   + - 7.3. RVC Clean Mode Cluster.   + - 7.3.1. Revision History.   + - 7.3.2. Classification.   + - 7.3.3. Cluster ID.   + - 7.3.4. Features.   + - 7.3.5. Data Types.   + - 7.3.6. Attributes.   + - 7.3.7. Derived Cluster Namespace.   + - 7.3.8. Mode Examples.   + - 7.4. RVC Operational State Cluster.   + - 7.4.1. Revision History.   + - 7.4.2. Classification.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 7.4.3. Cluster ID.   + - 7.4.4. Data Types.   + - 7.4.5. Commands.   +- 8. Home Appliances.   + - 8.1. General Description.   + - 8.1.1. Introduction.   + - 8.1.2. Cluster List.   + - 8.2. Temperature Control Cluster.   + - 8.2.1. Revision History.   + - 8.2.2. Classification.   + - 8.2.3. Cluster ID.   + - 8.2.4. Features.   + - 8.2.5. Attributes.   + - 8.2.6. Commands.   + - 8.3. Dishwasher Mode Cluster.   + - 8.3.1. Revision History.   + - 8.3.2. Classification.   + - 8.3.3. Cluster ID.   + - 8.3.4. Features.   + - 8.3.5. Data Types.   + - 8.3.6. Attributes.   + - 8.3.7. Derived Cluster Namespace.   + - 8.4. Dishwasher Alarm Cluster.   + - 8.4.1. Revision History.   + - 8.4.2. Classification.   + - 8.4.3. Cluster ID.   + - 8.4.4. Data Types.   + - 8.5. Laundry Washer Mode Cluster.   + - 8.5.1. Revision History.   + - 8.5.2. Classification.   + - 8.5.3. Cluster ID.   + - 8.5.4. Features.   + - 8.5.5. Data Types.   + - 8.5.6. Attributes.   + - 8.5.7. Derived Cluster Namespace.   + - 8.5.8. Mode Examples.   + - 8.6. Laundry Washer Controls Cluster.   + - 8.6.1. Revision History.   + - 8.6.2. Classification.   + - 8.6.3. Cluster ID.   + - 8.6.4. Features.   + + +``` +8.6.5. Data Types.....................................................................  591 +8.6.6. Attributes......................................................................  592 +``` +8.7. Refrigerator And Temperature Controlled Cabinet Mode Cluster........................  593 + +``` +8.7.1. Revision History................................................................  593 +8.7.2. Classification...................................................................  593 +8.7.3. Cluster ID......................................................................  593 +8.7.4. Features........................................................................  593 +8.7.5. Data Types.....................................................................  594 +8.7.6. Attributes......................................................................  594 +8.7.7. Derived Cluster Namespace......................................................  594 +8.7.8. Mode Examples.................................................................  595 +``` +8.8. Refrigerator Alarm Cluster...........................................................  595 + +``` +8.8.1. Revision History................................................................  595 +8.8.2. Classification...................................................................  596 +8.8.3. Cluster ID......................................................................  596 +8.8.4. Features........................................................................  596 +8.8.5. Data Types.....................................................................  596 +8.8.6. Attributes......................................................................  596 +8.8.7. Commands.....................................................................  596 +``` +8.9. Laundry Dryer Controls Cluster......................................................  597 + +``` +8.9.1. Revision History................................................................  597 +8.9.2. Classification...................................................................  597 +8.9.3. Cluster ID......................................................................  597 +8.9.4. Data Types.....................................................................  597 +8.9.5. Attributes......................................................................  598 +``` +8.10. Oven Cavity Operational State Cluster...............................................  598 + +``` +8.10.1. Revision History...............................................................  599 +8.10.2. Classification..................................................................  599 +8.10.3. Cluster ID.....................................................................  599 +8.10.4. Attributes.....................................................................  599 +8.10.5. Commands....................................................................  599 +``` +8.11. Oven Mode Cluster.................................................................  600 + +``` +8.11.1. Revision History...............................................................  600 +8.11.2. Classification..................................................................  600 +8.11.3. Cluster ID.....................................................................  600 +8.11.4. Features.......................................................................  600 +8.11.5. Data Types....................................................................  600 +8.11.6. Attributes.....................................................................  601 +8.11.7. Derived Cluster Namespace.....................................................  601 +8.11.8. Mode Examples................................................................  603 +``` +8.12. Microwave Oven Mode Cluster......................................................  603 + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 17 +``` + +``` +8.12.1. Revision History...............................................................  603 +8.12.2. Classification..................................................................  603 +8.12.3. Cluster ID.....................................................................  603 +8.12.4. Features.......................................................................  603 +8.12.5. Attributes.....................................................................  604 +8.12.6. Commands....................................................................  604 +8.12.7. Derived Cluster Namespace.....................................................  604 +8.13. Microwave Oven Control Cluster....................................................  605 +8.13.1. Revision History...............................................................  605 +8.13.2. Classification..................................................................  605 +8.13.3. Cluster ID.....................................................................  606 +8.13.4. Features.......................................................................  606 +8.13.5. Attributes.....................................................................  606 +8.13.6. Commands....................................................................  608 +``` +9. Energy Management....................................................................  613 + +``` +9.1. General Description.................................................................  613 +9.1.1. Introduction....................................................................  613 +9.1.2. Cluster List.....................................................................  613 +9.2. Device Energy Management Cluster..................................................  613 +9.2.1. Revision History................................................................  615 +9.2.2. Classification...................................................................  615 +9.2.3. Cluster ID......................................................................  615 +9.2.4. Features........................................................................  616 +9.2.5. Dependencies...................................................................  620 +9.2.6. Definitions.....................................................................  620 +9.2.7. Data Types.....................................................................  621 +9.2.8. Attributes......................................................................  636 +9.2.9. Commands.....................................................................  640 +9.2.10. Events........................................................................  649 +9.3. Energy EVSE Cluster................................................................  650 +9.3.1. Revision History................................................................  651 +9.3.2. Classification...................................................................  651 +9.3.3. Cluster ID......................................................................  651 +9.3.4. Features........................................................................  651 +9.3.5. Dependencies...................................................................  653 +9.3.6. Definitions.....................................................................  654 +9.3.7. Data Types.....................................................................  654 +9.3.8. Attributes......................................................................  660 +9.3.9. Commands.....................................................................  667 +9.3.10. Events........................................................................  673 +9.4. Energy EVSE Mode Cluster...........................................................  677 +``` +``` +Page 18 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +9.4.1. Revision History................................................................  677 +9.4.2. Classification...................................................................  677 +9.4.3. Cluster ID......................................................................  678 +9.4.4. Features........................................................................  678 +9.4.5. Data Types.....................................................................  678 +9.4.6. Attributes......................................................................  678 +9.4.7. Derived Cluster Namespace......................................................  679 +9.4.8. Mode Examples.................................................................  680 +``` +9.5. Water Heater Management Cluster...................................................  680 + +``` +9.5.1. Revision History................................................................  680 +9.5.2. Classification...................................................................  680 +9.5.3. Cluster ID......................................................................  681 +9.5.4. Features........................................................................  681 +9.5.5. Dependencies...................................................................  681 +9.5.6. Data Types.....................................................................  681 +9.5.7. Attributes......................................................................  683 +9.5.8. Commands.....................................................................  686 +9.5.9. Events.........................................................................  687 +``` +9.6. Water Heater Mode Cluster..........................................................  687 + +``` +9.6.1. Revision History................................................................  688 +9.6.2. Classification...................................................................  688 +9.6.3. Cluster ID......................................................................  688 +9.6.4. Features........................................................................  688 +9.6.5. Data Types.....................................................................  688 +9.6.6. Attributes......................................................................  688 +9.6.7. Derived Cluster Namespace......................................................  689 +9.6.8. Mode Examples.................................................................  690 +``` +9.7. Energy Preference Cluster...........................................................  690 + +``` +9.7.1. Revision History................................................................  690 +9.7.2. Classification...................................................................  690 +9.7.3. Cluster ID......................................................................  690 +9.7.4. Features........................................................................  691 +9.7.5. Data Types.....................................................................  691 +9.7.6. Attributes......................................................................  692 +``` +9.8. Device Energy Management Mode Cluster............................................  694 + +``` +9.8.1. Revision History................................................................  694 +9.8.2. Classification...................................................................  694 +9.8.3. Cluster ID......................................................................  694 +9.8.4. Features........................................................................  695 +9.8.5. Data Types.....................................................................  695 +9.8.6. Attributes......................................................................  695 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 19 +``` + +``` +9.8.7. Derived Cluster Namespace......................................................  696 +9.8.8. Mode Examples.................................................................  697 +``` +10. Network Infrastructure................................................................  699 + +``` +10.1. General Description................................................................  699 +10.1.1. Introduction...................................................................  699 +10.1.2. Cluster List....................................................................  699 +10.2. Wi-Fi Network Management Cluster.................................................  699 +10.2.1. Revision History...............................................................  699 +10.2.2. Classification..................................................................  699 +10.2.3. Cluster ID.....................................................................  700 +10.2.4. Attributes.....................................................................  700 +10.2.5. Commands....................................................................  701 +10.3. Thread Border Router Management Cluster..........................................  702 +10.3.1. Revision History...............................................................  702 +10.3.2. Classification..................................................................  702 +10.3.3. Cluster ID.....................................................................  702 +10.3.4. Features.......................................................................  702 +10.3.5. Attributes.....................................................................  703 +10.3.6. Commands....................................................................  704 +10.4. Thread Network Directory Cluster...................................................  707 +10.4.1. Revision History...............................................................  707 +10.4.2. Classification..................................................................  707 +10.4.3. Cluster ID.....................................................................  707 +10.4.4. Data Types....................................................................  707 +10.4.5. Attributes.....................................................................  708 +10.4.6. Commands....................................................................  709 +10.4.7. Guidance for Fabrics / Commissioners...........................................  711 +``` +``` +Page 20 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Introduction** + +The Matter Application Cluster specification defines generic interfaces that are sufficiently general +to be of use across a wide range of application domains. + +**Scope and Purpose** + +This document specifies the Matter Application Cluster Library (MACL). The MACL is a repository +for cluster functionality that is developed by the Connectivity Standards Alliance, and is a working +library with regular updates as new functionality is added. A developer constructing a new applica­ +tion should use the MACL to find relevant cluster functionality that can be incorporated into the +new application. Correspondingly, new clusters that are defined for applications should be consid­ +ered for inclusion in the MACL. + +The MACL consists of a number of sets of clusters. Clusters that are generally useful across many +application domains are included in the General set. Clusters that are intended for use mainly in +specific application domains are grouped together in domain oriented sets. + +**References** + +The following standards and specifications contain provisions, which through reference in this doc­ +ument constitute provisions of this specification. All the standards and specifications listed are nor­ +mative references. At the time of publication, the editions indicated were valid. All standards and +specifications are subject to revision, and parties to agreements based on this specification are +encouraged to investigate the possibility of applying the most recent editions of the standards and +specifications indicated below. + +**CSA Reference Documents** + +``` +Reference Reference Location/URL Description +[Aliro] TBD Aliro Specification - Under development +[CSA-PNP] https://groups.csa-iot.org/wg/ +members/document/21624 +``` +``` +Organizational Processes and Procedures, 13- +0625, revision 8, November 2021 +[MatterCore] https://groups.csa-iot.org/wg/ +members-all/document/ +27349 +``` +``` +Matter Core Specification +``` +``` +[MatterDevLib] https://github.com/CHIP- +Specifications/connected­ +homeip-spec/raw/build-sam­ +ple/pdf/device_library.pdf +``` +``` +Matter Device Library Specification +``` +``` +[StandardName­ +spaces] +``` +``` +https://groups.csa-iot.org/wg/ +members-all/document/ +31936 +``` +``` +Standard Namespaces +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 21 +``` + +**External Reference Documents** + +``` +Reference Reference Location/URL Description +[CIE 1931] https://en.wikipedia.org/ +wiki/CIE_1931_color_space +``` +``` +Commission Internationale de l’Éclairage CIE +1931 Color Space +[DIALRegistry] http://www.dial-multi­ +screen.org/dial-registry/ +namespace-database +``` +``` +DIAL Registry +``` +``` +[EU Code of Con­ +duct for ESAs] +``` +``` +https://ses.jrc.ec.europa.eu/ +development-of-policy-pro­ +posals-for-energy-smart- +appliances +``` +``` +EU Code of Conduct for ESAs +``` +``` +[HDMI] https://hdmiforum.org/hdmi- +forum-releases-version-2-1- +hdmi-specification/ +``` +``` +HDMI CEC specification +``` +``` +[IEEE2030.5] https://standards.ieee.org/ +ieee/2030.5/11216/ +``` +### IEEE 2030.5 + +``` +[ISO 4217] https://www.iso.org/iso-4217- +currency-codes.html +``` +``` +Currency Codes +``` +``` +[ISO 8601] https://www.iso.org/iso-8601- +date-and-time-format.html +``` +``` +Date and time format +``` +``` +[OpenADR] https://www.openadr.org/ OpenADR Alliance +[PAS1878] https://www.bsigroup.com/ +globalassets/localfiles/en-th/ +about-bsi/energy-smart- +appliances-programme/bsi- +pas-1878-energy-smart- +appliances-system-function­ +ality-and-architecture-th.pdf +``` +### PAS1878 + +``` +[RFC 1738] https://www.rfc-editor.org/ +rfc/rfc1738 +``` +``` +Uniform Resource Locators (URL) +``` +``` +[RFC 4122] https://www.rfc-editor.org/ +rfc/rfc4122 +``` +``` +A Universally Unique IDentifier (UUID) URN +Namespace +[RFC 5646] https://tools.ietf.org/html/ +rfc5646 +``` +``` +Tags for Identifying Languages +``` +### [SAE J2847/3_2023 + +### 11] + +``` +https://www.sae.org/stan­ +dards/content/j2847/ +3_202311/ +``` +``` +Communication for Plug-in Vehicles as a Distrib­ +uted Energy Source +``` +``` +[SAREF4ENER] https://saref.etsi.org/sare­ +f4ener/v1.1.2/ +``` +``` +SAREF ontology for energy (ETSI TS 103 410-1) +``` +``` +[SEC 1] https://www.secg.org/sec1- +v2.pdf +``` +``` +SEC 1: Elliptic Curve Cryptography, Version 2.0, +Certicom Research, May 2009 +``` +``` +Page 22 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Reference Reference Location/URL Description +[Thread] https://www.thread­ +group.org +``` +``` +Thread 1.3.0 Specification +``` +``` +[WakeOnLAN] https://www.amd.com/sys­ +tem/files/TechDocs/ +20213.pdf +``` +``` +Wake on LAN Magic Packet specification +``` +**Provisional** + +Per [CSA-PNP], when a specification is completed there may be sections of specification text (or +smaller pieces of a section) that are not certifiable at this stage. These sections (or smaller pieces of +a section) are marked as provisional prior to publishing the specification. This specification uses +well-defined notation to mark Provisional Conformance (see [MatterCore], Section 7.3) or notes a +section of text with the term "provisional". + +**List of Provisional Items** + +The following is a list of provisional items: + +- Support for the Frequency feature of the Level control cluster is provisional. +- Support for Ballast Configuration Cluster is provisional. +- Support for InflowError, DrainError, TempTooLow, TempTooHigh, and WaterLevelError alarms + in Dishwasher Alarm Cluster is provisional. +- Support for Energy Preference Cluster is provisional. +- Support for Content Control Cluster is provisional. +- Support for PowerInWatts feature of the Microwave Oven Control cluster is provisional +- Support for Scenes Management Cluster is provisional. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 23 +``` + +Page 24 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 1. General** + +The Cluster Library is made of individual chapters such as this one. See Document Control in the +Cluster Library for a list of all chapters and documents. References between chapters are made +using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. References +to external documents are contained in Chapter 1 and are made using [ _Rn_ ] notation. + +**1.1. General Description** + +**1.1.1. Introduction** + +The clusters specified in this document are generic interfaces that are sufficiently general to be of +use across a wide range of application domains. + +**1.1.2. Cluster List** + +This section lists the general clusters as specified in this chapter. + +_Table 1. Overview of the General Clusters_ + +``` +ID Cluster Name Description +0x0003 Identify Attributes and commands for +putting a device into Identifica­ +tion mode (e.g., flashing a light) +0x0004 Groups Cluster to manage the associ­ +ated endpoint’s membership +into one or more groups to sup­ +port groupcast interactions. +0x0062 Scenes Management Attributes and commands for +setting up and recalling a num­ +ber of scenes for a device. Each +scene corresponds to a set of +stored values of specified +device attributes. +0x0006 On/Off Attributes and commands for +switching devices between On +and Off states. +0x0008 Level Control Attributes and commands for +controlling a characteristic of +devices that can be set to a level +between fully On and fully Off. +0x0045 Boolean State Attribute and event for a +boolean state variable +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 25 +``` + +``` +ID Cluster Name Description +0x0080 Boolean State Configuration Attributes and commands for +configuration related to +boolean state +0x0050 Mode Select Allows a user to choose one +mode option from several pre­ +defined values +n/a Mode Base Allows a user to choose one +mode option from several pre­ +defined values +0x0508 Low Power This cluster provides an inter­ +face for managing low power +mode on a device. +0x0503 Wake On LAN This cluster provides an inter­ +face for managing low power +mode on a device that supports +the Wake On LAN protocol. +0x003B Switch Attributes and events for vari­ +ous types of switch devices. +0x0060 Operational State Commands and attributes for +defining a device’s operational +state +n/a Alarm Base Base alarm cluster from which +all alarms are derived +0x0097 Messages Commands and attributes for +sending messages to devices +0x0150 Service Area Commands and attributes for +controlling and querying the +operating service areas of +devices +``` +**1.2. Identify Cluster** + +This cluster supports an endpoint identification state (e.g., flashing a light), that indicates to an +observer (e.g., an installer) which of several nodes and/or endpoints it is. It also supports a multi­ +cast request that any endpoint that is identifying itself to respond to the initiator. + +The state of this cluster MAY be shared on more than one endpoint on a node. + +``` +For Example: Two endpoints on a single node, one a temperature sensor, and one a humidity +sensor, may both share the same cluster instance and therefore identification state (e.g. single +LED on the node). +``` +``` +Page 26 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 CCB 2808 +3 All Hubs changes +4 New data model format and notation; add Iden­ +tifyType +5 Removed Query feature +``` +**1.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Endpoint I +``` +**1.2.3. Cluster ID** + +``` +ID Name +0x0003 Identify +``` +**1.2.4. Data Types** + +**1.2.4.1. IdentifyTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x00 None No presentation. M +0x01 LightOutput Light output of a light­ +ing product. +``` +### M + +``` +0x02 VisibleIndicator Typically a small LED. M +0x03 AudibleBeep M +0x04 Display Presentation will be +visible on display +screen. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 27 +``` + +``` +Value Name Summary Conformance +0x05 Actuator Presentation will be +conveyed by actuator +functionality such as +through a window +blind operation or in- +wall relay. +``` +### M + +**1.2.4.2. EffectIdentifierEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x00 Blink e.g., Light is turned +on/off once. +``` +### M + +``` +0x01 Breathe e.g., Light is turned +on/off over 1 second +and repeated 15 times. +``` +### M + +``` +0x02 Okay e.g., Colored light turns +green for 1 second; +non-colored light +flashes twice. +``` +### M + +``` +0x0B ChannelChange e.g., Colored light turns +orange for 8 seconds; +non-colored light +switches to the maxi­ +mum brightness for +0.5s and then minimum +brightness for 7.5s. +``` +### M + +``` +0xFE FinishEffect Complete the current +effect sequence before +terminating. e.g., if in +the middle of a breathe +effect (as above), first +complete the current 1s +breathe effect and then +terminate the effect. +``` +### M + +``` +0xFF StopEffect Terminate the effect as +soon as possible. +``` +### M + +**1.2.4.3. EffectVariantEnum Type** + +This data type is derived from enum8. + +``` +Page 28 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0x00 Default Indicates the default +effect is used +``` +### M + +**1.2.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Identify­ +Time +``` +``` +uint16 all 0 RW VO M +``` +``` +0x0001 Identify­ +Type +``` +``` +Identify­ +TypeEnum +``` +``` +desc MS R V M +``` +**1.2.5.1. IdentifyTime Attribute** + +This attribute SHALL represent the remaining length of time, in seconds, that the endpoint will con­ +tinue to identify itself. + +If this attribute is set to a value other than 0 then the device SHALL enter its identification state, in +order to indicate to an observer which of several nodes and/or endpoints it is. It is RECOMMENDED +that this state consists of flashing a light with a period of 0.5 seconds. The IdentifyTime attribute +SHALL be decremented every second while in this state. + +If this attribute reaches or is set to the value 0 then the device SHALL terminate its identification +state. + +**1.2.5.2. IdentifyType Attribute** + +This attribute SHALL indicate how the identification state is presented to the user. + +This attribute SHALL contain one of the values defined in IdentifyTypeEnum. The value None +SHALL NOT be used if the device is capable of presenting its identification state using one of the +other methods defined in IdentifyTypeEnum. + +**1.2.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Identify client ⇒ server Y M M +0x40 TriggerEffect client ⇒ server Y M O +``` +**1.2.6.1. Identify Command** + +This command starts or stops the receiving device identifying itself. + +This command SHALL have the following data fields: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 29 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Identify­ +Time +``` +``` +uint16 all M +``` +**1.2.6.1.1. Effect on Receipt** + +On receipt of this command, the device SHALL set the IdentifyTime attribute to the value of the +IdentifyTime field. This then starts, continues, or stops the device’s identification state as detailed in +IdentifyTime. + +**1.2.6.2. TriggerEffect Command** + +This command allows the support of feedback to the user, such as a certain light effect. It is used to +allow an implementation to provide visual feedback to the user under certain circumstances such +as a color light turning green when it has successfully connected to a network. The use of this com­ +mand and the effects themselves are entirely up to the implementer to use whenever a visual feed­ +back is useful but it is not the same as and does not replace the identify mechanism used during +commissioning. + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 EffectIden­ +tifier +``` +``` +EffectIdenti­ +fierEnum +``` +``` +desc M +``` +``` +1 EffectVari­ +ant +``` +``` +EffectVari­ +antEnum +``` +``` +desc M +``` +**1.2.6.2.1. EffectIdentifier Field** + +This field SHALL indicate the identify effect to use and SHALL contain one of the non-reserved val­ +ues in EffectIdentifierEnum. + +All values of the EffectIdentifierEnum SHALL be supported. Implementors MAY deviate from the +example light effects in EffectIdentifierEnum, but they SHOULD indicate during testing how they +handle each effect. + +**1.2.6.2.2. EffectVariant Field** + +This field SHALL indicate which variant of the effect, indicated in the EffectIdentifier field, SHOULD +be triggered. If a device does not support the given variant, it SHALL use the default variant. This +field SHALL contain one of the values in EffectVariantEnum. + +**1.2.6.2.3. Effect on Receipt** + +On receipt of this command, the device SHALL execute the trigger effect indicated in the EffectIden­ +tifier and EffectVariant fields. If the EffectVariant field specifies a variant that is not supported on +the device, it SHALL execute the default variant. + +``` +Page 30 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.3. Groups Cluster** + +The Groups cluster manages, per endpoint, the content of the node-wide Group Table that is part of +the underlying interaction layer. + +In a network supporting fabrics, group IDs referenced by attributes or other elements of this cluster +are scoped to the accessing fabric. + +The Groups cluster is scoped to the endpoint. Groups cluster commands support discovering the +endpoint membership in a group, adding the endpoint to a group, removing the endpoint from a +group, removing endpoint membership from all groups. All commands defined in this cluster +SHALL only affect groups scoped to the accessing fabric. + +When group names are supported, the server stores a name string, which is set by the client for +each assigned group and indicated in response to a client request. + +Note that configuration of group addresses for outgoing commands is achieved using the Message +Layer mechanisms where the Group Table is not involved. Hence this cluster does not play a part in +that. + +**1.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added; CCB 1745 2100 +2 CCB 2289 +3 CCB 2310 2704 +4 New data model format and notation +``` +**1.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Endpoint G +``` +**1.3.3. Cluster ID** + +``` +ID Name +0x0004 Groups +``` +**1.3.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 31 +``` + +``` +Bit Code Feature Summary +0 GN GroupNames The ability to store a +name for a group. +``` +**1.3.4.1. GroupNames Feature** + +The Group Names feature indicates the ability to store a name for a group when a group is added. + +**1.3.5. Data Types** + +**1.3.5.1. NameSupportBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +7 GroupNames The ability to store a +name for a group. +``` +### M + +**1.3.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 NameSup­ +port +``` +``` +NameSup­ +portBitmap +``` +``` +desc F 0 R V M +``` +**1.3.6.1. NameSupport Attribute** + +This attribute provides legacy, read-only access to whether the Group Names feature is supported. +The most significant bit, bit 7 (GroupNames), SHALL be equal to bit 0 of the FeatureMap attribute +(GN Feature). All other bits SHALL be 0. + +**1.3.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 AddGroup client ⇒ server AddGroupRe­ +sponse +``` +### M F M + +``` +0x01 ViewGroup client ⇒ server ViewGroupRe­ +sponse +``` +### O F M + +``` +0x02 GetGroup­ +Membership +``` +``` +client ⇒ server GetGroupMem­ +ber­ +shipResponse +``` +### O F M + +``` +0x03 RemoveGroup client ⇒ server Remove­ +GroupRe­ +sponse +``` +### M F M + +``` +Page 32 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Direction Response Access Conformance +0x04 RemoveAll­ +Groups +``` +``` +client ⇒ server Y M F M +``` +``` +0x05 AddGroupIfI­ +dentifying +``` +``` +client ⇒ server Y M F M +``` +``` +0x00 AddGroupRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x01 ViewGroupRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x02 GetGroup­ +Member­ +shipResponse +``` +``` +client ⇐ server N M +``` +``` +0x03 Remove­ +GroupRe­ +sponse +``` +``` +client ⇐ server N M +``` +**1.3.7.1. AddGroup Command** + +The AddGroup command allows a client to add group membership in a particular group for the +server endpoint. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id min 1 M +1 GroupName string max 16 M +``` +**1.3.7.1.1. GroupID Field** + +This field SHALL be used to identify the group and any associated key material to which the server +endpoint is to be added. + +**1.3.7.1.2. GroupName Field** + +This field MAY be set to a human-readable name for the group. If the client has no name for the +group, the GroupName field SHALL be set to the empty string. + +Support of group names is optional and is indicated by the FeatureMap and NameSupport attribute. + +**1.3.7.1.3. Effect on Receipt** + +If the server does not support group names, the GroupName field SHALL be ignored. + +On receipt of the AddGroup command, the server SHALL perform the following procedure: + +1. If the command fields are not within constraints, the status SHALL be CONSTRAINT_ERROR, and + the server continues from step 6. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 33 +``` + +2. If the receiving node requires security material to support the group ID and that material does + not exist for this group ID, the status SHALL be UNSUPPORTED_ACCESS and the server contin­ + ues from step 6. +3. If the server endpoint is a member of the group indicated by the GroupID, the group name + SHALL be updated (if supported) to GroupName, the status SHALL be SUCCESS, and the server + continues from step 6. +4. If there are no available resources to add the membership for the server endpoint, the status + SHALL be RESOURCE_EXHAUSTED, and the server continues from step 6. +5. The server SHALL add the server endpoint as a member of the group indicated by the GroupID, + the group name SHALL be updated (if supported) to GroupName, and the status SHALL be SUC­ + CESS. + a.If the GroupID had already been added to the Group Table because of a previous AddGroup + or AddGroupIfIdentifying command and a GroupName is provided and the server supports + GroupName storage, then the GroupName associated with the GroupID in the Group Table + SHALL be updated to reflect the new GroupName provided for the Group, such that subse­ + quent ViewGroup commands yield the same name for all endpoints which have a group + association to the given GroupID. +6. If the AddGroup command was received as a unicast, the server SHALL generate an + AddGroupResponse command with the Status field set to the evaluated status. If the AddGroup + command was received as a groupcast, the server SHALL NOT generate an AddGroupResponse + command. + +See AddGroupResponse for a description of the response command. + +**1.3.7.2. ViewGroup Command** + +The ViewGroup command allows a client to request that the server responds with a ViewGroupRe­ +sponse command containing the name string for a particular group. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id min 1 M +``` +**1.3.7.2.1. Effect on Receipt** + +On receipt of the ViewGroup command, the server SHALL perform the following procedure: + +1. If the command fields are not within constraints, the status SHALL be CONSTRAINT_ERROR and + the server continues from step 4. +2. If the server endpoint is a member of the group indicated by the GroupID, the status SHALL be + SUCCESS, and the server continues from step 4. +3. Else the status SHALL be NOT_FOUND. +4. If the ViewGroup command was received as a unicast, the server SHALL generate a View­ + GroupResponse command for the group, and the Status field set to the evaluated status. If the + ViewGroup command was received as a groupcast, the server SHALL NOT generate a View­ + +``` +Page 34 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +GroupResponse command. +``` +See ViewGroupResponse for a description of the response command. + +**1.3.7.3. GetGroupMembership Command** + +The GetGroupMembership command allows a client to inquire about the group membership of the +server endpoint, in a number of ways. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupList list[group-id] all[min 1] M +``` +**1.3.7.3.1. Effect on Receipt** + +On receipt of the GetGroupMembership command, the server SHALL respond with group member­ +ship information using the GetGroupMembershipResponse command as follows: + +If the GroupList field is empty, the server SHALL respond with all group IDs indicating the groups +of which the server endpoint is a member. + +If the GroupList field contains at least one group ID indicating a group of which the server endpoint +is a member, the server SHALL respond with each group ID indicating a group of which the server +endpoint is a member that matches a group in the GroupList field. + +If the GroupList field contains one or more group IDs but does not contain any group ID indicating +a group of which the server endpoint is a member, the server SHALL only respond if the command +is unicast. The response SHALL return with an empty GroupList field. + +**1.3.7.4. RemoveGroup Command** + +The RemoveGroup command allows a client to request that the server removes the membership for +the server endpoint, if any, in a particular group. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id min 1 M +``` +**1.3.7.4.1. Effect on Receipt** + +On receipt of the RemoveGroup command, the server SHALL perform the following procedure: + +1. If the command fields are not within constraints, the status SHALL be CONSTRAINT_ERROR and + the server continues from step 4. +2. If the server endpoint is a member of the group indicated by the GroupID, the server SHALL + remove the server endpoint membership in the group, the status SHALL be SUCCESS, and the + server continues from step 4. +3. Else the status SHALL be NOT_FOUND. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 35 +``` + +4. If the RemoveGroup command was received as a unicast, the server SHALL generate a Remove­ + GroupResponse command with the Status field set to the evaluated status. If the RemoveGroup + command was received as a groupcast, the server SHALL NOT generate a RemoveGroupRe­ + sponse command. + +See RemoveGroupResponse for a description of the response command. + +Additionally, if the Scenes Management cluster is supported on the same endpoint, scenes associ­ +ated with the indicated group SHALL be removed on that endpoint. + +**1.3.7.5. RemoveAllGroups Command** + +The RemoveAllGroups command allows a client to direct the server to remove all group associa­ +tions for the server endpoint. + +**1.3.7.5.1. Effect on Receipt** + +On receipt of this command, the server SHALL remove all group memberships for the server end­ +point from the Group Table. If the RemoveAllGroups command was received as unicast and a +response is not suppressed, the server SHALL generate a response with the Status field set to SUC­ +CESS. + +Additionally, if the Scenes Management cluster is supported on the same endpoint, all scenes, +except for scenes associated with group ID 0, SHALL be removed on that endpoint. + +**1.3.7.6. AddGroupIfIdentifying Command** + +The AddGroupIfIdentifying command allows a client to add group membership in a particular +group for the server endpoint, on condition that the endpoint is identifying itself. Identifying func­ +tionality is controlled using the Identify cluster, (see Identify Cluster). + +For correct operation of the AddGroupIfIdentifying command, any endpoint that supports the +Groups server cluster SHALL also support the Identify server cluster. + +This command might be used to assist configuring group membership in the absence of a commis­ +sioning tool. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id min 1 M +1 GroupName string max 16 M +``` +**1.3.7.6.1. GroupID Field** + +This field SHALL be used to identify the group and any associated key material to which the server +endpoint is to be added. + +**1.3.7.6.2. GroupName Field** + +This field MAY be set to a human-readable name for the group. If the client has no name for the + +``` +Page 36 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +group, the GroupName field SHALL be set to the empty string. + +Support of group names is optional and is indicated by the FeatureMap and NameSupport attribute. + +**1.3.7.6.3. Effect on Receipt** + +If the server does not support group names, the GroupName field SHALL be ignored. + +On receipt of the AddGroupIfIdentifying command, the server SHALL perform the following proce­ +dure: + +1. The server verifies that it is currently identifying itself. If the server it not currently identifying + itself, the status SHALL be SUCCESS, and the server continues from step 7. +2. If the command fields are not within constraints, the status SHALL be CONSTRAINT_ERROR and + the server continues from step 7. +3. If the receiving node requires security material to support the group ID, and that material does + not exist for this group ID, the status SHALL be UNSUPPORTED_ACCESS and the server contin­ + ues from step 7. +4. If the server endpoint is a member of the group indicated by the GroupID, the status SHALL be + SUCCESS and the server continues from step 7. +5. If there are no available resources to add the membership for the server endpoint, the status + SHALL be RESOURCE_EXHAUSTED and the server continues from step 7. +6. The server SHALL add the server endpoint as a member of the group indicated by the GroupID, + the group name SHALL be updated (if supported) to GroupName, and the status SHALL be SUC­ + CESS. + a. If the GroupID had already been added to the Group Table because of a previous AddGroup + or AddGroupIfIdentifying command and a GroupName is provided and the server supports + GroupName storage, then the GroupName associated with the GroupID in the Group Table + SHALL be updated to reflect the new GroupName provided for the Group, such that subse­ + quent ViewGroup commands yield the same name for all endpoints which have a group + association to the given GroupID. +7. If the AddGroupIfIdentifying command was received as unicast and the evaluated status is not + SUCCESS, or if the AddGroupIfIdentifying command was received as unicast and the evaluated + status is SUCCESS and a response is not suppressed, the server SHALL generate a response with + the Status field set to the evaluated status. + +**1.3.7.7. AddGroupResponse Command** + +The AddGroupResponse is sent by the Groups cluster server in response to an AddGroup command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status enum8 desc M +1 GroupID group-id min 1 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 37 +``` + +**1.3.7.7.1. Status Field** + +This field is set according to the Effect on Receipt section of the AddGroup command. + +**1.3.7.7.2. GroupID Field** + +This field is set to the GroupID field of the received AddGroup command. + +**1.3.7.8. ViewGroupResponse Command** + +The ViewGroupResponse command is sent by the Groups cluster server in response to a ViewGroup +command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status enum8 desc M +1 GroupID group-id min 1 M +2 GroupName string max 16 M +``` +**1.3.7.8.1. Status Field** + +This field is according to the Effect on Receipt section of the ViewGroup command. + +**1.3.7.8.2. GroupID Field** + +This field is set to the GroupID field of the received ViewGroup command. + +**1.3.7.8.3. GroupName Field** + +If the status is SUCCESS, and group names are supported, this field is set to the group name associ­ +ated with that group in the Group Table; otherwise it is set to the empty string. + +**1.3.7.9. GetGroupMembershipResponse Command** + +The GetGroupMembershipResponse command is sent by the Groups cluster server in response to a +GetGroupMembership command. + +The GetGroupMembershipResponse command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Capacity uint8 all X M +1 GroupList list[group-id] all[min 1] M +``` +**1.3.7.9.1. Capacity Field** + +This field SHALL contain the remaining capacity of the Group Table of the node. The following val­ +ues apply: + +``` +Page 38 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- 0 - No further groups MAY be added. +- 0 < Capacity < 0xFE - Capacity holds the number of groups that MAY be added. +- 0xFE - At least 1 further group MAY be added (exact number is unknown). +- null - It is unknown if any further groups MAY be added. + +**1.3.7.9.2. GroupList Field** + +The GroupList field SHALL contain either the group IDs of all the groups in the Group Table for +which the server endpoint is a member of the group (in the case where the GroupList field of the +received GetGroupMembership command was empty), or the group IDs of all the groups in the +Group Table for which the server endpoint is a member of the group _and_ for which the group ID +was included in the the GroupList field of the received GetGroupMembership command (in the case +where the GroupList field of the received GetGroupMembership command was not empty). +Zigbee: If the total number of groups will cause the maximum payload length of a frame to be +exceeded, then the GroupList field SHALL contain only as many groups as will fit. + +**1.3.7.10. RemoveGroupResponse Command** + +The RemoveGroupResponse command is generated by the server in response to the receipt of a +RemoveGroup command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status enum8 desc M +1 GroupID group-id min 1 M +``` +**1.3.7.10.1. Status Field** + +This field is according to the Effect on Receipt section of the RemoveGroup command. + +**1.3.7.10.2. GroupID Field** + +This field is set to the GroupID field of the received RemoveGroup command. + +**1.4. Scenes Management Cluster** + +The Scenes Management cluster provides attributes and commands for setting up and recalling +scenes. Each scene corresponds to a set of stored values of specified attributes for one or more clus­ +ters on the same end point as the Scenes Management cluster. + +In most cases scenes are associated with a particular group identifier. Scenes MAY also exist with­ +out a group, in which case the value 0 replaces the group identifier. Note that extra care is required +in these cases to avoid a scene identifier collision, and that commands related to scenes without a +group MAY only be unicast, i.e., they SHALL NOT be multicast or broadcast. + +``` +NOTE Support for Scenes Management cluster is provisional. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 39 +``` + +**1.4.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Based on the ZCL Scenes Cluster, Updated the +Cluster ID to 0x0062, the name to Scenes Man­ +agement, removed the provisional status; +Removed attributes SceneCount, CurrentScene, +CurrentGroup, SceneValid, and NameSupport; +Removed Explicit, TableSize and FabricScenes +features; Removed EnhancedAddScene, +EnhancedAddSceneResponse, Enhanced­ +ViewScene, EnhancedViewSceneResponse; Tran­ +sitionTime field changed milliseconds in +AddScene, ViewSceneResponse and RecallScene +``` +**1.4.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint S +``` +**1.4.3. Cluster ID** + +``` +ID Name Conformance +0x0062 Scenes Management P +``` +**1.4.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 SN SceneNames O The ability to store +a name for a +scene. +``` +The following sections describe each feature in some detail. Further details are found within the +specification. + +**1.4.4.1. SceneNames Feature** + +This feature indicates the ability to store a name for a scene when a scene is added. + +``` +Page 40 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.4.5. Dependencies** + +Any endpoint that implements the Scenes Management server cluster SHALL also implement the +Groups server cluster. + +Note that the RemoveGroup command and the RemoveAllGroups command of the Groups cluster +also remove scenes. + +**1.4.6. Handling of fabric-scoping** + +Attributes and commands for this cluster are scoped to the accessing fabric and SHALL only affect +or reflect data related to the accessing fabric, with the exception of the SceneValid Field of the Fab­ +ricSceneInfo attribute. + +The following constraints apply in addition to any other stated requirements in individual data +model elements: + +- Any attribute read, attribute write or command invoked on the server when no accessing fabric + is available SHALL fail with a status code of UNSUPPORTED_ACCESS returned to the client. +- When accessing scene information, implementations SHALL ensure that scenes with identical + Group ID and Scene ID across fabrics will only access the data for the accessing fabric, so that + the same identifier values used by different accessing fabrics do not cause mixing or overwrit­ + ing of another fabric’s scenes. +- Upon leaving a fabric with the RemoveFabric command of the Operational Credentials Cluster, + all scenes data for the associated fabric SHALL be removed from the Scene Table. +- The Scene Table capacity for a given fabric SHALL be less than half (rounded down towards 0) + of the Scene Table entries (as indicated in the SceneTableSize attribute), with a maximum of 253 + entries (to allow expressing it in the GetSceneMembershipResponse command). If the Scene Ta­ + ble capacity is about to be exceeded by adding or storing a scene, then the resource exhaustion + behavior of the associated command SHALL apply. + +**1.4.7. Data Types** + +**1.4.7.1. CopyModeBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary +0 CopyAllScenes Copy all scenes in the scene ta­ +ble +``` +**1.4.7.2. SceneInfoStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 41 +``` + +``` +Access Quality: Fabric Scoped +0 SceneCou +nt +``` +``` +uint8 all 0 M +``` +``` +1 Cur­ +rentScene +``` +``` +uint8 desc 0xFF S M +``` +``` +2 Current­ +Group +``` +``` +group-id all 0 S M +``` +``` +3 SceneVali +d +``` +``` +bool all False S M +``` +``` +4 Remain­ +ingCapac­ +ity +``` +``` +uint8 max 253 MS M +``` +**1.4.7.2.1. SceneCount Field** + +This field SHALL indicate the number of scenes currently used in the server’s Scene Table on the +endpoint where the Scenes Management cluster appears. + +This only includes the count for the associated fabric. + +**1.4.7.2.2. CurrentScene Field** + +This field SHALL indicate the scene identifier of the scene last invoked on the associated fabric. If +no scene has been invoked, the value of this field SHALL be 0xFF, the undefined scene identifier. + +**1.4.7.2.3. CurrentGroup Field** + +This field SHALL indicate the group identifier of the scene last invoked on the associated fabric, or 0 +if the scene last invoked is not associated with a group. + +**1.4.7.2.4. SceneValid Field** + +This field SHALL indicate whether the state of the server corresponds to that associated with the +CurrentScene and CurrentGroup fields of the SceneInfoStruct they belong to. TRUE indicates that +these fields are valid, FALSE indicates that they are not valid. + +This field SHALL be set to False for all other fabrics when an attribute with the Scenes ("S") designa­ +tion in the Quality column of another cluster present on the same endpoint is modified or when the +current scene is modified by a fabric through the RecallScene or StoreScene commands, regardless +of the fabric-scoped access quality of the command. + +In the event where the SceneValid field is set to False for a fabric, the CurrentScene and Current­ +Group fields SHALL be the last invoked scene and group for that fabric. In the event where no +scene was previously invoked for that fabric, the CurrentScene and CurrentGroup fields SHALL be +their default values. + +``` +Page 42 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.4.7.2.5. RemainingCapacity Field** + +This field SHALL indicate the remaining capacity of the Scene Table on this endpoint for the access­ +ing fabric. Note that this value may change between reads, even if no entries are added or deleted +on the accessing fabric, due to other clients associated with other fabrics adding or deleting entries +that impact the resource usage on the device. + +**1.4.7.3. AttributeValuePairStruct Type** + +This data type indicates a combination of an identifier and the value of an attribute. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Attribut­ +eID +``` +``` +attribute-idall M +``` +``` +1 ValueUn­ +signed8 +``` +``` +uint8 O.a +``` +``` +2 Value­ +Signed8 +``` +``` +int8 O.a +``` +``` +3 ValueUn­ +signed16 +``` +``` +uint16 O.a +``` +``` +4 Value­ +Signed16 +``` +``` +int16 O.a +``` +``` +5 ValueUn­ +signed32 +``` +``` +uint32 O.a +``` +``` +6 Value­ +Signed32 +``` +``` +int32 O.a +``` +``` +7 ValueUn­ +signed64 +``` +``` +uint64 O.a +``` +``` +8 Value­ +Signed64 +``` +``` +int64 O.a +``` +**1.4.7.3.1. AttributeID Field** + +This field SHALL be present for all instances in a given ExtensionFieldSetStruct. + +Which Value* field is used SHALL be determined based on the data type of the attribute indicated +by AttributeID, as described in the Value* Fields subsection. + +The AttributeID field SHALL NOT refer to an attribute without the Scenes ("S") designation in the +Quality column of the cluster specification. + +**1.4.7.3.2. ValueUnsigned8, ValueSigned8, ValueUnsigned16, ValueSigned16, ValueUnsigned32, ValueSigned32, +ValueUnsigned64, ValueSigned64 Fields** + +These fields SHALL indicate the attribute value as part of an extension field set, associated with a +given AttributeID under an ExtensionFieldSetStruct’s ClusterID. Which of the fields is used SHALL + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 43 +``` + +be determined by the type of the attribute indicated by AttributeID as follows: + +- Data types bool, map8, and uint8 SHALL map to ValueUnsigned8. +- Data types int8 SHALL map to ValueSigned8. +- Data types map16 and uint16 SHALL map to ValueUnsigned16. +- Data types int16 SHALL map to ValueSigned16. +- Data types map32, uint24, and uint32 SHALL map to ValueUnsigned32. +- Data types int24 and int32 SHALL map to ValueSigned32. +- Data types map64, uint40, uint48, uint56 and uint64 SHALL map to ValueUnsigned64. +- Data types int40, int48, int56 and int64 SHALL map to ValueSigned64. +- For derived types, the mapping SHALL be based on the base type. For example, an attribute of + type percent SHALL be treated as if it were of type uint8, whereas an attribute of type per­ + cent100ths SHALL be treated as if it were of type uint16. +- For boolean nullable attributes, any value that is not 0 or 1 SHALL be considered to have the + null value. +- For boolean non-nullable attributes, any value that is not 0 or 1 SHALL be considered to have + the value FALSE. +- For non-boolean nullable attributes, any value that is not a valid numeric value for the + attribute’s type after accounting for range reductions due to being nullable and constraints + SHALL be considered to have the null value for the type. +- For non-boolean non-nullable attributes, any value that is not a valid numeric value for the + attribute’s type after accounting for constraints SHALL be considered to be the valid attribute + value that is closest to the provided value. + ◦ In the event that an invalid provided value is of equal numerical distance to the two closest + valid values, the lowest of those values SHALL be considered the closest valid attribute + value. + +If the used field does not match the data type of the attribute indicated by AttributeID, the Attribut­ +eValuePairStruct SHALL be considered invalid. + +Examples of processing are: + +- ColorControl cluster CurrentX (AttributeID 0x0003) has a type of uint16 and is not nullable. + ◦ ValueUnsigned16 of 0xAB12 would be used as-is, as it is in range. + ◦ ValueUnsigned16 of 0xFF80 is outside of the range allowed for attribute CurrentX, and + would be saturated to the closest valid value, which is the maximum of the attribute’s con­ + straint range: 0xFEFF. +- LevelControl cluster CurrentLevel (AttributeID 0x0000) has a type of uint8 and is nullable. + ◦ ValueUnsigned8 of 0xA1 would be used as-is, as it is in range. + ◦ ValueUnsigned8 of 0xFF is outside the range allowed for nullable attribute CurrentLevel, + and would be considered as the null value. + +``` +Page 44 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.4.7.4. ExtensionFieldSetStruct Type** + +This data type indicates for a given cluster a set of attributes and their values. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ClusterID cluster-id all M +1 Attribute­ +ValueList +``` +``` +list[Attrib­ +uteValue­ +PairStruct] +``` +``` +desc M +``` +**1.4.7.4.1. ClusterID Field** + +This field SHALL indicate the cluster-id of the cluster whose attributes are in the AttributeValueList +field. + +**1.4.7.4.2. AttributeValueList Field** + +This field SHALL indicate a set of attributes and their values which are stored as part of a scene. + +Attributes which do not have the Scenes ("S") designation in the Quality column of their cluster +specification SHALL NOT be used in the AttributeValueList field. + +**1.4.7.4.3. Form of ExtensionFieldSetStruct** + +The AttributeValuePairStructs in the AttributeValueList MAY be in any order. + +The AttributeValueList SHOULD contain all the attributes with the Scenes ("S") quality as the specifi­ +cation of the cluster identified by ClusterID describes, but AttributeValuePairStruct MAY be omitted. + +An example using the Color Control cluster: + +- Attribute 0x0001, CurrentSaturation, S quality, optional, implemented +- Attribute 0x0003, CurrentX, S quality, optional based on feature, implemented +- Attribute 0x0004, CurrentY, S quality, optional based on feature, implemented +- Attribute 0x0007, ColorTemperatureMireds, S quality, optional based on feature, implemented +- Attribute 0x4000, EnhancedCurrentHue, S quality, optional based on feature, implemented +- Attribute 0x4001, EnhancedColorMode, S quality, mandatory, implemented +- Attribute 0x4002, ColorLoopActive, S quality, optional based on feature, NOT implemented +- Attribute 0x4003, ColorLoopDirection, S quality, optional based on feature, NOT implemented +- Attribute 0x4004, ColorLoopTime, S quality, optional based on feature, NOT implemented + +An ExtensionFieldSetStruct containing an invalid AttributeValuePairStruct SHALL be considered +invalid. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 45 +``` + +**1.4.7.5. Logical Scene Table** + +The Scene Table is used to store information for each scene capable of being invoked on the server. +Each scene is defined for a particular group. The Scene Table is defined here as a conceptual illus­ +tration to assist in understanding the underlying data to be stored when scenes are defined. Though +the Scene Table is defined here using the data model architecture rules and format, the design is +not normative. + +The Scene table is logically a list of fabric-scoped structs. The logical fields of each Scene Table entry +struct are illustrated below. An ExtensionFieldSetStruct MAY be present for each Scenes-supporting +cluster implemented on the same endpoint. + +``` +Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Scene­ +GroupID +``` +``` +group-id all M +``` +``` +1 SceneID uint8 max 254 M +2 Scene­ +Name +``` +``` +string max 16 SN +``` +``` +3 Scene­ +Transi­ +tionTime +``` +``` +uint32 max +60000000 +``` +### 0 M + +``` +4 Extension­ +Fields +``` +``` +list[Exten­ +sionField­ +SetStruct] +``` +``` +empty M +``` +**1.4.7.5.1. SceneGroupID Field** + +This field is the group identifier for which this scene applies, or 0 if the scene is not associated with +a group. + +**1.4.7.5.2. SceneID Field** + +This field is unique within this group, which is used to identify this scene. + +**1.4.7.5.3. SceneName Field** + +The field is the name of the scene. + +If scene names are not supported, any commands that write a scene name SHALL simply discard +the name, and any command that returns a scene name SHALL return an empty string. + +**1.4.7.5.4. SceneTransitionTime Field** + +This field is the amount of time, in milliseconds, it will take for a cluster to change from its current +state to the requested state. + +``` +Page 46 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.4.7.5.5. ExtensionFields Field** + +See the Scene Table Extensions subsections of individual clusters. A Scene Table Extension SHALL +only use attributes with the Scene quality. Each ExtensionFieldSetStruct holds a set of values of +these attributes for a cluster implemented on the same endpoint where the Scene ("S") designation +appears in the quality column. A scene is the aggregate of all such fields across all clusters on the +endpoint. + +**1.4.8. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 LastCon­ +figuredBy +``` +``` +node-id all X null R V O +``` +``` +0x0001 SceneTa­ +bleSize +``` +``` +uint16 desc F 16 R V M +``` +``` +0x0002 Fabric­ +SceneInfo +``` +``` +list[Scene­ +InfoStruct] +``` +``` +desc R V F M +``` +**1.4.8.1. LastConfiguredBy Attribute** + +This attribute SHALL indicate the Node ID of the node that last configured the Scene Table. + +The null value indicates that the server has not been configured, or that the identifier of the node +that last configured the Scenes Management cluster is not known. + +The Node ID is scoped to the accessing fabric. + +**1.4.8.2. SceneTableSize Attribute** + +This attribute SHALL indicate the number of entries in the Scene Table on this endpoint. This is the +total across all fabrics; note that a single fabric cannot use all those entries (see Handling of fabric- +scoping). The minimum size of this table, (i.e., the minimum number of scenes to support across all +fabrics per endpoint) SHALL be 16, unless a device type in which this cluster is used, defines a +larger value in the device type definition. + +**1.4.8.3. FabricSceneInfo Attribute** + +This attribute SHALL indicate a list of fabric scoped information about scenes on this endpoint. + +The number of list entries for this attribute SHALL NOT exceed the number of supported fabrics by +the device. + +**1.4.9. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 AddScene client ⇒ server AddSceneRe­ +sponse +``` +### F M M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 47 +``` + +``` +ID Name Direction Response Access Conformance +0x00 AddSceneRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x01 ViewScene client ⇒ server ViewSceneRe­ +sponse +``` +### F O M + +``` +0x01 ViewSceneRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x02 RemoveScene client ⇒ server RemoveSceneR +esponse +``` +### F M M + +``` +0x02 RemoveScene +Response +``` +``` +client ⇐ server N M +``` +``` +0x03 RemoveAllSce +nes +``` +``` +client ⇒ server RemoveAllSce­ +nesResponse +``` +### F M M + +``` +0x03 RemoveAllSce +nesResponse +``` +``` +client ⇐ server N M +``` +``` +0x04 StoreScene client ⇒ server StoreSceneRe­ +sponse +``` +### F M M + +``` +0x04 StoreSceneRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x05 RecallScene client ⇒ server Y F O M +0x06 GetScene­ +Membership +``` +``` +client ⇒ server GetSceneMem­ +ber­ +shipResponse +``` +### F O M + +``` +0x06 GetScene­ +Member­ +shipResponse +``` +``` +client ⇐ server N M +``` +``` +0x40 CopyScene client ⇒ server CopySceneRe­ +sponse +``` +### F M O + +``` +0x40 CopySceneRe­ +sponse +``` +``` +client ⇐ server N CopyScene +``` +**1.4.9.1. Generic Usage Notes** + +The scene identifier 0, when used with group identifier 0, is reserved for the global scene used by +the On/Off cluster. + +**1.4.9.2. AddScene Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +``` +``` +Page 48 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 SceneID uint8 max 254 M +2 Transition­ +Time +``` +``` +uint32 max +60000000 +``` +### M + +``` +3 SceneName string max 16 M +4 Extension­ +FieldSet­ +Structs +``` +``` +list[Exten­ +sionFieldSet­ +Struct] +``` +``` +desc M +``` +It is not mandatory for an extension field set to be included in the command for every cluster on +that endpoint that has a defined extension field set. Extension field sets MAY be omitted, including +the case of no extension field sets at all. + +**1.4.9.2.1. GroupID Field** + +This field SHALL indicate the group identifier in the Group Table. + +**1.4.9.2.2. SceneID Field** + +This field SHALL indicate the scene identifier in the Scene Table. + +**1.4.9.2.3. TransitionTime Field** + +This field SHALL indicate the transition time of the scene, measured in milliseconds. + +**1.4.9.2.4. SceneName Field** + +This field SHALL indicate the name of the scene. + +**1.4.9.2.5. ExtensionFieldSetStructs Field** + +This field SHALL contains the list of extension fields. + +**1.4.9.2.6. Effect on Receipt** + +On receipt of this command, the server SHALL perform the following procedure: + +1. If the value of the GroupID field is non-zero, the server verifies that the endpoint has an entry + for that GroupID in the Group Table. If there is no such entry in the Group Table, the status + SHALL be INVALID_COMMAND and the server continues from step 5. +2. If the ExtensionFieldSetStructs list is formatted in a way deemed invalid according to the Exten­ + sionFieldSetStruct structure definition (see ExtensionFieldSetStruct), then the status SHALL be + INVALID_COMMAND in the AddSceneResponse, and the server continues from step 5. +3. If a scene already exists under the same group/scene identifier pair, in step 4 the already exist­ + ing scene entry SHALL be replaced with the new scene being added. Otherwise, if a scene can­ + not be created due to the lack of Scene Table capacity for the given fabric, the status SHALL be + RESOURCE_EXHAUSTED and the server continues from step 5. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 49 +``` + +4. The server adds the scene entry into its Scene Table with fields copied from the AddScene com­ + mand data fields and the status SHALL be SUCCESS. + a.Any ExtensionFieldSetStruct referencing a ClusterID that is not implemented on the end­ + point MAY be omitted during processing. +b. Any AttributeValuePairStruct referencing an AttributeID from the referenced cluster that is +not implemented on the endpoint MAY be omitted during processing. +c.If the ExtensionFieldSetStructs list has multiple entries listing the same ClusterID, the last +one within the list SHALL be the one recorded. +d. Within a single entry of the ExtensionFieldSetStructs list, if an ExtensionFieldSet contains +the same AttributeID more than once, the last one within the ExtensionFieldSet SHALL be +the one recorded. +5. If the AddScene command was received as a unicast, the server SHALL then generate an + AddSceneResponse command with the Status field set to the evaluated status. + +The SceneTransitionTime field of the Scene Table SHALL be updated with the value of the Transi­ +tionTime. + +**1.4.9.3. AddSceneResponse Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status status desc M +1 GroupID group-id all M +2 SceneID uint8 max 254 M +``` +**1.4.9.3.1. Status Field** + +This field SHALL be set according to the Effect on Receipt section for AddScene command. + +**1.4.9.3.2. GroupID Field** + +The GroupID field SHALL be set to the corresponding field of the received AddScene command. + +**1.4.9.3.3. SceneID Field** + +The SceneID field SHALL be set to the corresponding field of the received AddScene command. + +**1.4.9.3.4. When Generated** + +This command is generated in response to a received AddScene command. + +**1.4.9.4. ViewScene Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +``` +``` +Page 50 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 SceneID uint8 max 254 M +``` +**1.4.9.4.1. GroupID Field** + +This field SHALL indicate the group identifier in the Group Table. + +**1.4.9.4.2. SceneID Field** + +This field SHALL indicate the scene identifier in the Scene Table. + +**1.4.9.4.3. Effect on Receipt** + +On receipt of this command, the server SHALL perform the following procedure: + +1. If the value of the GroupID field is non-zero, the server verifies that the endpoint has an entry + for that GroupID in the Group Table. If there is no such entry in the Group Table, the status + SHALL be INVALID_COMMAND and the server continues from step 4. +2. The server verifies that the scene entry corresponding to the GroupID and SceneID fields exists + in its Scene Table. If there is no such entry in its Scene Table, the status SHALL be NOT_FOUND + and the server continues from step 4. +3. The server retrieves the requested scene entry from its Scene Table and the status SHALL be + SUCCESS. +4. If the ViewScene command was received as a unicast, the server SHALL then generate a + ViewSceneResponse command with the retrieved scene entry and the Status field set to the + evaluated status. + +### NOTE + +``` +The order of attributes within the ExtensionFieldSetStruct MAY differ in implemen­ +tation-defined ways from any potential order given in a prior AddScene. +``` +**1.4.9.5. ViewSceneResponse Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status status desc M +1 GroupID group-id all M +2 SceneID uint8 max 254 M +3 Transition­ +Time +``` +``` +uint32 max +60000000 +``` +``` +desc +``` +``` +4 SceneName string max 16 desc +5 Extension­ +FieldSet­ +Structs +``` +``` +list[Exten­ +sionFieldSet­ +Struct] +``` +``` +desc +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 51 +``` + +**1.4.9.5.1. Status Field** + +This field SHALL be set according to the Effect on Receipt section for ViewScene command. + +**1.4.9.5.2. GroupID Field** + +The GroupID field SHALL be set to the corresponding field of the received ViewScene command. + +**1.4.9.5.3. SceneID Field** + +The SceneID field SHALL be set to the corresponding field of the received ViewScene command. + +**1.4.9.5.4. TransitionTime Field** + +If the status is SUCCESS, this field SHALL be copied from the corresponding field in the Scene Table +entry, otherwise it SHALL be omitted. + +**1.4.9.5.5. SceneName Field** + +If the status is SUCCESS, this field SHALL be copied from the corresponding field in the Scene Table +entry, otherwise it SHALL be omitted. + +**1.4.9.5.6. ExtensionFieldSetStructs Field** + +If the status is SUCCESS, this field SHALL be copied from the corresponding field in the Scene Table +entry, otherwise it SHALL be omitted. + +**1.4.9.5.7. When Generated** + +This command is generated in response to a received ViewScene command. + +**1.4.9.6. RemoveScene Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +1 SceneID uint8 max 254 M +``` +**1.4.9.6.1. GroupID Field** + +This field SHALL indicate the group identifier in the Group Table. + +**1.4.9.6.2. SceneID Field** + +This field SHALL indicate the scene identifier in the Scene Table. + +**1.4.9.6.3. Effect on Receipt** + +On receipt of this command, the server SHALL perform the following procedure: + +1. If the value of the GroupID field is non-zero, the server verifies that the endpoint has an entry + for that GroupID in the Group Table. If there is no such entry in the Group Table, the status + +``` +Page 52 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +SHALL be INVALID_COMMAND and the server continues from step 4. +``` +2. The server verifies that the scene entry corresponding to the GroupID and SceneID fields exists + in its Scene Table. If there is no such entry in its Scene Table, the status SHALL be NOT_FOUND + and the server continues from step 4. +3. The server removes the requested scene entry from its Scene Table and the status SHALL be + SUCCESS. +4. If the RemoveScene command was received as a unicast, the server SHALL then generate a + RemoveSceneResponse command with the Status field set to the evaluated status. + +**1.4.9.7. RemoveSceneResponse Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status status desc M +1 GroupID group-id all M +2 SceneID uint8 max 254 M +``` +**1.4.9.7.1. Status Field** + +This field SHALL be set according to the Effect on Receipt section for RemoveScene command. + +**1.4.9.7.2. GroupID Field** + +The GroupID field SHALL be set to the corresponding field of the received RemoveScene command. + +**1.4.9.7.3. SceneID Field** + +The SceneID field SHALL be set to the corresponding field of the received RemoveScene command. + +**1.4.9.7.4. When Generated** + +This command is generated in response to a received RemoveScene command. + +**1.4.9.8. RemoveAllScenes Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +``` +**1.4.9.8.1. GroupID Field** + +This field SHALL indicate the group identifier in the Group Table. + +**1.4.9.8.2. Effect on Receipt** + +On receipt of this command, the server SHALL perform the following procedure: + +1. If the value of the GroupID field is non-zero, the server verifies that the endpoint has an entry + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 53 +``` + +``` +for that GroupID in the Group Table. If there is no such entry in the Group Table, the status +SHALL be INVALID_COMMAND and the server continues from step 3. +``` +2. The server SHALL remove all scenes, corresponding to the value of the GroupID field, from its + Scene Table and the status SHALL be SUCCESS. +3. If the RemoveAllScenes command was received as a unicast, the server SHALL then generate a + RemoveAllScenesResponse command with the Status field set to the evaluated status. + +**1.4.9.9. RemoveAllScenesResponse Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status status desc M +1 GroupID group-id all M +``` +**1.4.9.9.1. Status Field** + +This field SHALL be set according to the Effect on Receipt section for RemoveAllScenes command. + +**1.4.9.9.2. GroupID Field** + +The GroupID field SHALL be set to the corresponding field of the received RemoveAllScenes com­ +mand. + +**1.4.9.9.3. When Generated** + +This command is generated in response to a received RemoveAllScenes command. + +**1.4.9.10. StoreScene Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +1 SceneID uint8 max 254 M +``` +**1.4.9.10.1. GroupID Field** + +This field SHALL indicate the group identifier in the Group Table. + +**1.4.9.10.2. SceneID Field** + +This field SHALL indicate the scene identifier in the Scene Table. + +**1.4.9.10.3. Effect on Receipt** + +On receipt of this command, the server SHALL perform the following procedure: + +1. If the value of the GroupID field is non-zero, the server verifies that the endpoint has an entry + for that GroupID in the Group Table. If there is no such entry in the Group Table, the status + +``` +Page 54 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +SHALL be INVALID_COMMAND and the server continues from step 4. +``` +2. If a scene already exists under the same group/scene identifier pair, in step 3 the already exist­ + ing scene entry SHALL be used to store the current state. + If a scene cannot be created due to the lack of Scene Table capacity for the given fabric, the sta­ + tus SHALL be RESOURCE_EXHAUSTED and the server continues from step 4. +3. If a scene already exists under the same group/scene identifier pair, the ExtensionFieldSets of + the stored scene SHALL be replaced with the ExtensionFieldSets corresponding to the current + state of other clusters on the same endpoint and the other fields of the scene table entry SHALL + remain unchanged. + Otherwise, a new entry SHALL be added to the scene table, using the provided GroupID and + SceneID, with SceneTransitionTime set to 0, with SceneName set to the empty string, and with + ExtensionFieldSets corresponding to the current state of other clusters on the same endpoint. + The status SHALL be SUCCESS. +4. If the StoreScene command was received as a unicast, the server SHALL then generate a + StoreSceneResponse command with the Status field set to the evaluated status. + +Note that if a scene to be stored requires a TransitionTime field and/or a SceneName field, these +must be set up by a prior AddScene command, e.g., with no scene extension field sets. + +**1.4.9.11. StoreSceneResponse Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status status desc M +1 GroupID group-id all M +2 SceneID uint8 max 254 M +``` +**1.4.9.11.1. Status Field** + +This field SHALL be set according to the Effect on Receipt section for StoreScene command. + +**1.4.9.11.2. GroupID Field** + +The GroupID field SHALL be set to the corresponding field of the received StoreScene command. + +**1.4.9.11.3. SceneID Field** + +The SceneID field SHALL be set to the corresponding field of the received StoreScene command. + +**1.4.9.11.4. When Generated** + +This command is generated in response to a received StoreScene command. + +**1.4.9.12. RecallScene Command** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 55 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +1 SceneID uint8 max 254 M +2 Transition­ +Time +``` +``` +uint32 max +60000000 +``` +### X O + +**1.4.9.12.1. GroupID Field** + +This field SHALL indicate the group identifier in the Group Table. + +**1.4.9.12.2. SceneID Field** + +This field SHALL indicate the scene identifier in the Scene Table. + +**1.4.9.12.3. TransitionTime Field** + +This field SHALL indicate the transition time of the scene, measured in milliseconds. + +**1.4.9.12.4. Effect on Receipt** + +On receipt of this command, the server SHALL perform the following procedure: + +1. If the value of the GroupID field is non-zero, the server verifies that the endpoint has an entry + for that GroupID in the Group Table. If there is no such entry in the Group Table, the status + SHALL be INVALID_COMMAND and the server continues from step 4. +2. The server verifies that the scene entry corresponding to the GroupID and SceneID fields exists + in its Scene Table. If there is no such entry in its Scene Table, the status SHALL be NOT_FOUND + and the server continues from step 4. +3. The server retrieves the requested scene entry from its Scene Table. For each other cluster + implemented on the endpoint, it SHALL retrieve any corresponding extension field sets from + the Scene Table and set the attributes and corresponding state of the cluster accordingly. If + there is no extension field set for a cluster, the state of that cluster SHALL remain unchanged. If + an extension field set omits the values of any attributes, the values of these attributes SHALL + remain unchanged. If an extension field set would cause an unknown or missing attribute to be + set for any reason, that attribute SHALL be skipped. The status SHALL be SUCCESS. +4. If the RecallScene command was received as a unicast, the server SHALL then generate a + response with the Status field set to the evaluated status. + +If the TransitionTime data field is present in the command and its value is not equal to null, this +field SHALL indicate the transition time in milliseconds. In all other cases (command data field not +present or value equal to null), the SceneTransitionTime field of the Scene Table entry SHALL indi­ +cate the transition time. The transition time determines how long the transition takes from the old +cluster state to the new cluster state. It is recommended that, where possible (e.g., it is not possible +for attributes with Boolean data type), a gradual transition SHOULD take place from the old to the +new state over this time. However, the exact transition algorithm is implementation-defined. + +``` +Page 56 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.4.9.13. GetSceneMembership Command** + +This command can be used to get the used scene identifiers within a certain group, for the endpoint +that implements this cluster. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +``` +**1.4.9.13.1. GroupID Field** + +This field SHALL indicate the group identifier in the Group Table. + +**1.4.9.13.2. Effect on Receipt** + +On receipt of this command, the server SHALL perform the following procedure: + +1. If the value of the GroupID field is non-zero, the server verifies that the endpoint has an entry + for that GroupID in the Group Table. If there is no such entry in the Group Table, the status + SHALL be INVALID_COMMAND and the server continues from step 3. +2. The status SHALL be SUCCESS. +3. If the GetSceneMembership command was received as a unicast, the server SHALL then gener­ + ate a GetSceneMembershipResponse command with the Status field set to the evaluated status. + +**1.4.9.14. GetSceneMembershipResponse Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status status desc M +1 Capacity uint8 all X M +2 GroupID group-id all M +3 SceneList list[uint8] Status==Suc­ +cess +``` +**1.4.9.14.1. Status Field** + +This field SHALL be set according to the Effect on Receipt section for GetSceneMembership com­ +mand. + +**1.4.9.14.2. Capacity Field** + +This field SHALL contain the remaining capacity of the Scene Table of the server (for all groups for +the accessing fabric). The following values apply: + +- 0 - No further scenes MAY be added. +- 0 < Capacity < 0xFE - Capacity holds the number of scenes that MAY be added. +- 0xFE - At least 1 further scene MAY be added (exact number is unknown). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 57 +``` + +- null - It is unknown if any further scenes MAY be added. + +**1.4.9.14.3. GroupID Field** + +This field SHALL be set to the corresponding field of the received GetSceneMembership command. + +**1.4.9.14.4. SceneList Field** + +If the status is not SUCCESS then this field SHALL be omitted, else this field SHALL contain the iden­ +tifiers of all the scenes in the Scene Table with the corresponding Group ID. + +**1.4.9.14.5. When Generated** + +This command is generated in response to a received GetSceneMembership command. + +**1.4.9.15. CopyScene Command** + +This command allows a client to efficiently copy scenes from one group/scene identifier pair to +another group/scene identifier pair. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Mode CopyModeB­ +itmap +``` +``` +desc M +``` +``` +1 GroupIden­ +tifierFrom +``` +``` +group-id all M +``` +``` +2 SceneIdenti­ +fierFrom +``` +``` +uint8 max 254 M +``` +``` +3 GroupIden­ +tifierTo +``` +``` +group-id all M +``` +``` +4 SceneIdenti­ +fierTo +``` +``` +uint8 max 254 M +``` +**1.4.9.15.1. Mode Field** + +This field SHALL contain the information of how the scene copy is to proceed. + +The CopyAllScenes bit of the Mode indicates whether all scenes are to be copied. If this value is set +to 1, all scenes are to be copied and the SceneIdentifierFrom and SceneIdentifierTo fields SHALL be +ignored. Otherwise this bit is set to 0. + +**1.4.9.15.2. GroupIdentifierFrom Field** + +This field SHALL indicate the identifier of the group from which the scene is to be copied. Together +with the SceneIdentifierFrom field, this field uniquely identifies the scene to copy from the Scene +Table. + +``` +Page 58 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.4.9.15.3. SceneIdentifierFrom Field** + +This field SHALL indicate the identifier of the scene from which the scene is to be copied. Together +with the GroupIdentifierFrom field, this field uniquely identifies the scene to copy from the Scene +Table. + +**1.4.9.15.4. GroupIdentifierTo Field** + +This field SHALL indicate the identifier of the group to which the scene is to be copied. Together +with the SceneIdentifierTo field, this field uniquely identifies the scene to copy to the Scene Table. + +**1.4.9.15.5. SceneIdentifierTo Field** + +This field SHALL indicate the identifier of the scene to which the scene is to be copied. Together +with the GroupIdentifierTo field, this field uniquely identifies the scene to copy to the Scene Table. + +**1.4.9.15.6. Effect on Receipt** + +On receipt of this command, the server SHALL perform the following procedure: + +1. If the value of either the GroupIdentifierFrom field or the Group Identifier To field is non-zero, + the server verifies that the endpoint has an entry for these non-zero group identifiers in the + Group Table. If there are no such entries in the Group Table, the status SHALL be INVALID_­ + COMMAND and the server continues from step 5. +2. If the CopyAllScenes sub-field of the Mode field is set to 0, the server verifies that the scene + entry corresponding to the GroupIdentifierFrom and SceneIdentifierFrom fields exists in its + Scene Table. If there is no such entry in its Scene Table, the status SHALL be NOT_FOUND and + the server continues from step 5. +3. If the CopyAllScenes sub-field of the Mode field is set to 1, the server SHALL copy all its avail­ + able scenes with group identifier equal to the GroupIdentifierFrom field under the group identi­ + fier specified in the GroupIdentifierTo field, leaving the scene identifiers the same. In this case, + the SceneIdentifierFrom and SceneIdentifierTo fields SHALL be ignored. + If the CopyAllScenes sub-field of the Mode field is set to 0, the server SHALL copy the Scene Ta­ + ble entry corresponding to the GroupIdentifierFrom and SceneIdentifierFrom fields to the + Scene Table entry corresponding to the GroupIdentifierTo and SceneIdentifierTo fields. + Regardless of the value of the CopyAllScenes subfield, if a scene already exists under the same + group/scene identifier pair, it SHALL be replaced with the scene being copied. + Regardless of the value of the CopyAllScenes subfield, if a scene cannot be copied due to the lack + of Scene Table capacity for the given fabric, the status SHALL be RESOURCE_EXHAUSTED and + the server continues from step 5. In this case, scenes already copied SHALL be kept. +4. The status SHALL be SUCCESS. +5. If the CopyScene command was received as a unicast, the server SHALL then generate a Copy­ + SceneResponse command with the Status field set to the evaluated status. + +**1.4.9.16. CopySceneResponse Command** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 59 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status status desc M +1 GroupIden­ +tifierFrom +``` +``` +group-id all M +``` +``` +2 SceneIdenti­ +fierFrom +``` +``` +uint8 max 254 M +``` +**1.4.9.16.1. Status Field** + +This field SHALL be set according to the Effect on Receipt section for the CopyScene command. + +**1.4.9.16.2. GroupIdentifierFrom Field** + +This field SHALL be set to the same values as in the corresponding fields of the received CopyScene +command. + +**1.4.9.16.3. SceneIdentifierFrom Field** + +This field SHALL be set to the same values as in the corresponding fields of the received CopyScene +command. + +**1.4.9.16.4. When Generated** + +The CopySceneResponse command is generated in response to a received CopyScene command. + +**1.5. On/Off Cluster** + +Attributes and commands for turning devices on and off. + +**1.5.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added; CCB 1555 +2 ZLO 1.0: StartUpOnOff +3 FeatureMap global attribute support with Level +Control and Lighting feature +4 New data model format and notation +5 Addition of Dead Front behavior and associated +FeatureMap entry +``` +``` +Page 60 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Revision Description +6 Addition of OffOnly feature and associated Fea­ +tureMap entry +``` +**1.5.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint OO +``` +**1.5.3. Cluster ID** + +``` +ID Name +0x0006 On/Off +``` +**1.5.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 LT Lighting [!OFFONLY] Behavior that sup­ +ports lighting +applications. +1 DF DeadFrontBehav­ +ior +``` +``` +[!OFFONLY] Device has Dead +Front behavior +2 OFFONLY OffOnly [!(LT | DF)] Device supports +the OffOnly fea­ +ture +``` +**1.5.4.1. Lighting Feature** + +This cluster is used for a lighting application. + +On receipt of a Level Control cluster command that causes the OnOff attribute to be set to FALSE, +the OnTime attribute SHALL be set to 0. + +On receipt of a Level Control cluster command that causes the OnOff attribute to be set to TRUE, if +the value of the OnTime attribute is equal to 0, the server SHALL set the OffWaitTime attribute to 0. + +**1.5.4.2. DeadFrontBehavior Feature** + +When this feature is supported, the device exposing this server cluster exhibits "dead front" behav­ +ior when the "OnOff " attribute is FALSE (Off ). This "dead front" behavior includes: + +- clusters other than this cluster that are also exposed MAY respond with failures to Invoke and + Write interactions. Such failure responses when in a "dead front" SHALL be with an + INVALID_IN_STATE status code. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 61 +``` + +- clusters other than this cluster MAY change the values of their attributes to best-effort values, + due to the actual values not being defined or available in this state. Device type specifications + that require support for the DF feature SHOULD define what these best-effort values are. +- Report Transactions SHALL continue to be generated. Such transactions MAY include best-effort + values as noted above. +- Event generation logic for clusters other than this cluster is unchanged (noting possible use of + best-effort attribute values as in the preceding bullets). + +When this feature is supported and the OnOff attribute changes from TRUE to FALSE (e.g. when +receiving an Off Command, or due to a manual interaction on the device), it SHALL start executing +this "dead front" behavior. + +When this feature is supported and the OnOff attribute changes from FALSE to TRUE (e.g. when +receiving an On Command, or due to a manual interaction on the device), it SHALL stop executing +this "dead front" behavior. + +When this feature is supported, and any change of the "dead front" state leads to changes in attrib­ +utes of other clusters due to the "dead front" feature, these attribute changes SHALL NOT be +skipped or omitted from the usual processing associated with attribute changes. For example, if an +attribute changes from value 4 to null on "dead front" behavior due to an Off command being +received, this change SHALL be processed for reporting and subscriptions. + +**1.5.4.3. OffOnly Feature** + +When this feature is supported, the Off command SHALL be supported and the On and Toggle com­ +mands SHALL NOT be supported. + +This feature is useful for devices which can be turned off via the Off command received by an +instance of this cluster but cannot be turned on via commands received by an instance of this clus­ +ter due to regulatory requirements. + +**1.5.5. Data Types** + +**1.5.5.1. OnOffControlBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 AcceptOnlyWhenOn Indicates a command is +only accepted when in +On state. +``` +### M + +**1.5.5.2. StartUpOnOffEnum Type** + +This data type is derived from enum8. + +``` +Page 62 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0 Off Set the OnOff attribute +to FALSE +``` +### M + +``` +1 On Set the OnOff attribute +to TRUE +``` +### M + +``` +2 Toggle If the previous value of +the OnOff attribute is +equal to FALSE, set the +OnOff attribute to +TRUE. If the previous +value of the OnOff +attribute is equal to +TRUE, set the OnOff +attribute to FALSE (tog­ +gle). +``` +### M + +**1.5.5.3. EffectIdentifierEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x00 DelayedAllOff Delayed All Off M +0x01 DyingLight Dying Light M +``` +**1.5.5.4. DelayedAllOffEffectVariantEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x00 DelayedOffFastFade Fade to off in 0.8 sec­ +onds +``` +### M + +``` +0x01 NoFade No fade M +0x02 DelayedOffSlowFade 50% dim down in 0.8 +seconds then fade to off +in 12 seconds +``` +### M + +**1.5.5.5. DyingLightEffectVariantEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x00 DyingLightFadeOff 20% dim up in 0.5s then +fade to off in 1 second +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 63 +``` + +**1.5.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 OnOff bool all SN FALSE R V M +0x4000 Glob­ +alSceneCo +ntrol +``` +``` +bool all TRUE R V LT +``` +``` +0x4001 OnTime uint16 all 0 RW VO LT +0x4002 OffWait­ +Time +``` +``` +uint16 all 0 RW VO LT +``` +``` +0x4003 Star­ +tUpOnOff +``` +``` +Star­ +tUpOnOf­ +fEnum +``` +``` +desc XN MS RW VM LT +``` +**1.5.6.1. Scene Table Extensions** + +If the Scenes Management server cluster is implemented on the same endpoint, the following +attribute SHALL be part of the ExtensionFieldSetStruct of the Scene Table. + +- OnOff + +**1.5.6.2. OnOff Attribute** + +This attribute indicates whether the device type implemented on the endpoint is turned off or +turned on, in these cases the value of the OnOff attribute equals FALSE, or TRUE respectively. + +**1.5.6.3. GlobalSceneControl Attribute** + +In order to support the use case where the user gets back the last setting of a set of devices (e.g. +level settings for lights), a global scene is introduced which is stored when the devices are turned +off and recalled when the devices are turned on. The global scene is defined as the scene that is +stored with group identifier 0 and scene identifier 0. + +This attribute is defined in order to prevent a second Off command storing the all-devices-off situa­ +tion as a global scene, and to prevent a second On command destroying the current settings by +going back to the global scene. + +This attribute SHALL be set to TRUE after the reception of a command which causes the OnOff +attribute to be set to TRUE, such as a standard On command, a MoveToLevel(WithOnOff ) command, +a RecallScene command or a OnWithRecallGlobalScene command. + +This attribute is set to FALSE after reception of a OffWithEffect command. + +These concepts are illustrated in Explanation of the Behavior of Store and Recall Global Scene func­ +tionality using a State Diagram. + +``` +Page 64 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +recall global scene +``` +``` +store global scene +``` +``` +other +commands +``` +``` +other +commands +``` +``` +OnWithRecallGlobalScene +``` +``` +OffWithEffect +``` +``` +GlobalSceneControl:= TRUE GlobalSceneControl:= FALSE +``` +``` +Note 1 : Any command which causes the OnOff attribute to be set to TRUE except OnWithRecallGlobalScene, e.g. On or Toggle. +``` +``` +On^1 +``` +_Figure 1. Explanation of the Behavior of Store and Recall Global Scene functionality using a State Diagram_ + +**1.5.6.4. OnTime Attribute** + +This attribute specifies the length of time (in 1/10ths second) that the On state SHALL be maintained +before automatically transitioning to the Off state when using the OnWithTimedOff command. This +attribute can be written at any time, but writing a value only has effect when in the Timed On state. +See OnWithTimedOff for more details. + +**1.5.6.5. OffWaitTime Attribute** + +This attribute specifies the length of time (in 1/10ths second) that the Off state SHALL be guarded to +prevent another OnWithTimedOff command turning the server back to its On state (e.g., when leav­ +ing a room, the lights are turned off but an occupancy sensor detects the leaving person and +attempts to turn the lights back on). This attribute can be written at any time, but writing a value +only has an effect when in the Timed On state followed by a transition to the Delayed Off state, or in +the Delayed Off state. See OnWithTimedOff for more details. + +**1.5.6.6. StartUpOnOff Attribute** + +This attribute SHALL define the desired startup behavior of a device when it is supplied with power +and this state SHALL be reflected in the OnOff attribute. If the value is null, the OnOff attribute is +set to its previous value. Otherwise, the behavior is defined in the table defining StartUpOnOf­ +fEnum. + +This behavior does not apply to reboots associated with OTA. After an OTA restart, the OnOff +attribute SHALL return to its value prior to the restart. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 65 +``` + +**1.5.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Off client ⇒ server Y O M +0x01 On client ⇒ server Y O !OFFONLY +0x02 Toggle client ⇒ server Y O !OFFONLY +0x40 OffWithEffect client ⇒ server Y O LT +0x41 OnWithRecall­ +GlobalScene +``` +``` +client ⇒ server Y O LT +``` +``` +0x42 OnWith­ +TimedOff +``` +``` +client ⇒ server Y O LT +``` +**1.5.7.1. Off Command** + +**1.5.7.1.1. Effect on Receipt** + +On receipt of the Off command, a server SHALL set the OnOff attribute to FALSE. + +Additionally, when the OnTime attribute is supported, the server SHALL set the OnTime attribute to +0. + +**1.5.7.2. On Command** + +**1.5.7.2.1. Effect on Receipt** + +If the OffOnly feature is supported, on receipt of the On command, an UNSUPPORTED_COMMAND +failure status response SHALL be sent. Otherwise, on receipt of the On command, a server SHALL +set the OnOff attribute to TRUE. + +Additionally, when the OnTime and OffWaitTime attributes are both supported, if the value of the +OnTime attribute is equal to 0, the server SHALL set the OffWaitTime attribute to 0. + +**1.5.7.3. Toggle Command** + +**1.5.7.3.1. Effect on Receipt** + +If the OffOnly feature is supported, on receipt of the Toggle command, an UNSUPPORTED_COM­ +MAND failure status response SHALL be sent. Otherwise, on receipt of the Toggle command, if the +value of the OnOff attribute is equal to FALSE, the server SHALL set the OnOff attribute to TRUE, +otherwise, the server SHALL set the OnOff attribute to FALSE. + +Additionally, when the OnTime and OffWaitTime attributes are both supported, if the value of the +OnOff attribute is equal to FALSE and if the value of the OnTime attribute is equal to 0, the server +SHALL set the OffWaitTime attribute to 0. If the value of the OnOff attribute is equal to TRUE, the +server SHALL set the OnTime attribute to 0. + +``` +Page 66 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.5.7.4. OffWithEffect Command** + +The OffWithEffect command allows devices to be turned off using enhanced ways of fading. + +The OffWithEffect command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 EffectIden­ +tifier +``` +``` +EffectIdenti­ +fierEnum +``` +``` +desc M +``` +``` +1 EffectVari­ +ant +``` +``` +enum8 desc 0 M +``` +**1.5.7.4.1. EffectIdentifier Field** + +This field specifies the fading effect to use when turning the device off. This field SHALL contain +one of the non-reserved values listed in EffectIdentifierEnum. + +**1.5.7.4.2. EffectVariant Field** + +This field is used to indicate which variant of the effect, indicated in the EffectIdentifier field, +SHOULD be triggered. If the server does not support the given variant, it SHALL use the default +variant. This field is dependent on the value of the EffectIdentifier field and SHALL contain one of +the non-reserved values listed in either DelayedAllOffEffectVariantEnum or DyingLightEffectVari­ +antEnum. + +**1.5.7.4.3. Effect on Receipt** + +On receipt of the OffWithEffect command the server SHALL check the value of the GlobalSceneCon­ +trol attribute. + +If the GlobalSceneControl attribute is equal to TRUE, the server SHALL store its settings in its global +scene then set the GlobalSceneControl attribute to FALSE, then set the OnOff attribute to FALSE and +if the OnTime attribute is supported set the OnTime attribute to 0. + +If the GlobalSceneControl attribute is equal to FALSE, the server SHALL only set the OnOff attribute +to FALSE. + +**1.5.7.5. OnWithRecallGlobalScene Command** + +This command allows the recall of the settings when the device was turned off. + +**1.5.7.5.1. Effect on Receipt** + +On receipt of the OnWithRecallGlobalScene command, if the GlobalSceneControl attribute is equal +to TRUE, the server SHALL discard the command. + +If the GlobalSceneControl attribute is equal to FALSE, the Scenes Management cluster server on the +same endpoint SHALL recall its global scene, updating the OnOff attribute accordingly. The OnOff +server SHALL then set the GlobalSceneControl attribute to TRUE. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 67 +``` + +Additionally, when the OnTime and OffWaitTime attributes are both supported, if the value of the +OnTime attribute is equal to 0, the server SHALL set the OffWaitTime attribute to 0. + +**1.5.7.6. OnWithTimedOff Command** + +This command allows devices to be turned on for a specific duration with a guarded off duration so +that SHOULD the device be subsequently turned off, further OnWithTimedOff commands, received +during this time, are prevented from turning the devices back on. Further OnWithTimedOff com­ +mands received while the server is turned on, will update the period that the device is turned on. + +The OnWithTimedOff command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 OnOffCon­ +trol +``` +``` +OnOffCon­ +trolBitmap +``` +``` +0 to 1 M +``` +``` +1 OnTime uint16 max 0xFFFE M +2 OffWait­ +Time +``` +``` +uint16 max 0xFFFE M +``` +**1.5.7.6.1. OnOffControl Field** + +This field contains information on how the server is to be operated. + +**1.5.7.6.1.1. AcceptOnlyWhenOn Bit** + +This bit specifies whether the OnWithTimedOff command is to be processed unconditionally or +only when the OnOff attribute is equal to TRUE. If this sub-field is set to 1, the OnWithTimedOff +command SHALL only be accepted if the OnOff attribute is equal to TRUE. If this sub-field is set to 0, +the OnWithTimedOff command SHALL be processed unconditionally. + +**1.5.7.6.2. OnTime Field** + +This field is used to adjust the value of the OnTime attribute. + +**1.5.7.6.3. OffWaitTime Field** + +This field is used to adjust the value of the OffWaitTime attribute. + +**1.5.7.6.4. Effect on Receipt** + +On receipt of this command, if the AcceptOnlyWhenOn sub-field of the OnOffControl field is set to 1, +and the value of the OnOff attribute is equal to FALSE, the command SHALL be discarded. + +If the value of the OffWaitTime attribute is greater than zero and the value of the OnOff attribute is +equal to FALSE, then the server SHALL set the OffWaitTime attribute to the minimum of the +OffWaitTime attribute and the value specified in the OffWaitTime field. + +In all other cases, the server SHALL set the OnTime attribute to the maximum of the OnTime +attribute and the value specified in the OnTime field, set the OffWaitTime attribute to the value + +``` +Page 68 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +specified in the OffWaitTime field and set the OnOff attribute to TRUE. + +If the values of the OnTime and OffWaitTime attributes are both not equal to 0xFFFF, the server +SHALL then update these attributes every 1/10th second until both the OnTime and OffWaitTime +attributes are equal to 0, as follows: + +- If the value of the OnOff attribute is equal to TRUE and the value of the OnTime attribute is + greater than zero, the server SHALL decrement the value of the OnTime attribute. If the value of + the OnTime attribute reaches 0, the server SHALL set the OffWaitTime and OnOff attributes to 0 + and FALSE, respectively. +- If the value of the OnOff attribute is equal to FALSE and the value of the OffWaitTime attribute + is greater than zero, the server SHALL decrement the value of the OffWaitTime attribute. If the + value of the OffWaitTime attribute reaches 0, the server SHALL terminate the update. + +**1.5.8. State Description** + +The operation of the On/Off cluster with respect to the On, Off, and OnWithTimedOff commands is +illustrated in On/Off Cluster Operation State Machine. In this diagram, the values X and Y corre­ +spond to the OnTime and OffWaitTime fields, respectively, of the OnWithTimedOff command. In the +Timed On state, the OnTime attribute is decremented every 1/10th second, unless its value equals +0xFFFF. Similarly, in the Delayed Off state, the OffWaitTime attribute is decremented every 1/10th +second, unless its value equals 0xFFFF. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 69 +``` + +``` +“On” +OnOff := TRUE +``` +``` +“Off ” +OnOff := FALSE +``` +``` +“Delayed Off ” +OnOff := FALSE +OffWaitTime +decrements +``` +``` +“Timed On” +OnOff := TRUE +OnTime decrements +``` +``` +On^2 On^2 +``` +``` +Off^1 Off 1 +``` +``` +Off^1 +``` +``` +On^2 / +OffWaitTime:=0; +``` +``` +OnTime == 0 / +OffWaitTime:=0; +``` +``` +OffWaitTime == 0 +``` +``` +Off^1 / +OnTime:=0; +``` +``` +Off^1 : Any command which causes the OnOff attribute to be set to FALSE, e.g. Off, Toggle or OffWithEffect. +On^2 : Any command which causes the OnOff attribute to be set to TRUE, e.g. On, Toggle or OnWithRecallGlobalScene. +``` +``` +OnWithTimedOff(x,y) / +OnTime:=x; OffWaitTime:=y; +``` +``` +OnWithTimedOff(x,y) / +OnTime:= max (x,OnTime); OffWaitTime:=y; +``` +``` +OnWithTimedOff(x,y) / +OffWaitTime:= min (y,OffWaitTime); +``` +``` +OnWithTimedOff(x,y) / +OnTime:=x; OffWaitTime:=y; +``` +``` +On^2 +``` +_Figure 2. On/Off Cluster Operation State Machine_ + +**1.6. Level Control Cluster** + +This cluster provides an interface for controlling a characteristic of a device that can be set to a +level, for example the brightness of a light, the degree of closure of a door, or the power output of a +heater. + +**1.6.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 Added Options attribute, state change table; ZLO +1.0; Base cluster (no change) CCB 2085 1775 2281 +2147 +``` +``` +Page 70 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Revision Description +3 CCB 2574 2616 2659 2702 2814 2818 2819 2898 +4 FeatureMap support with On/Off, Lighting and +Frequency features +5 New data model format and notation +6 Added Q quality for CurrentLevel, CurrentFre­ +quency and RemainingTime attributes, +added clarifications for behavior related to Step +value and +adjusted constraint of DefaultMoveRate +``` +**1.6.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint LVL +``` +**1.6.3. Cluster ID** + +Derived cluster specifications are defined elsewhere. This base cluster specification MAY be used +for generic level control; however, it is recommended to derive another cluster to better define the +application and domain requirements. If one of more derived cluster identifiers and the base iden­ +tifier exists on a device endpoint, then they SHALL all represent a single instance of the device level +control. + +``` +ID Name +0x0008 Level Control +``` +**1.6.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Default Conformance Summary +0 OO OnOff 1 O Dependency +with the On/Off +cluster +1 LT Lighting 0 O Behavior that +supports light­ +ing applica­ +tions +2 FQ Frequency 0 P Supports fre­ +quency attrib­ +utes and +behavior. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 71 +``` + +The following sections describe each feature in some detail. Further details are found within the +specification. + +**1.6.4.1. On/Off Feature** + +For many applications, a close relationship between this cluster and the On/Off cluster is needed. +This section describes the dependencies that are required when an endpoint that implements this +server cluster and also implements the On/Off server cluster. Before the On/Off feature bit in the +FeatureMap existed, there was a dependency between this cluster and the On/Off cluster. + +The OnOff attribute of the On/Off cluster and the CurrentLevel attribute of the Level Control cluster +are intrinsically independent variables, as they are on different clusters. However, when both clus­ +ters are implemented on the same endpoint, dependencies MAY be introduced between them. Facil­ +ities are provided to introduce dependencies if required. + +**1.6.4.1.1. Effect of On/Off Commands on the CurrentLevel attribute** + +The OnLevel attribute determines whether commands of the On/Off cluster have a permanent +effect on the CurrentLevel attribute or not. If this attribute is defined (i.e., implemented and not +equal to null) they do have a permanent effect, otherwise they do not. There is always a temporary +effect, due to fading up / down. + +The effect on the Level Control cluster on receipt of the various commands of the On/Off cluster are +as detailed in the Effect of On/Off Commands when associated with Level Control table. In this ta­ +ble, and throughout this cluster specification, 'level' means the value of the CurrentLevel attribute. + +_Table 2. Effect of On/Off Commands when associated with Level Control_ + +``` +Command Action On Receipt +On Temporarily store CurrentLevel. +Set CurrentLevel to the minimum level allowed +for the device. +Change CurrentLevel to OnLevel, or to the +stored level if OnLevel is not defined, over the +time period OnOffTransitionTime. +Off Temporarily store CurrentLevel. +Change CurrentLevel to the minimum level +allowed for the device over the time period +OnOffTransitionTime. +If OnLevel is not defined, set the CurrentLevel to +the stored level. +Toggle If the OnOff attribute has the value FALSE, pro­ +ceed as for the On command. Otherwise proceed +as for the Off command. +``` +Intention of the actions described in the table above is that CurrentLevel, which was in effect +before any of the On, Off or Toggle commands were issued, SHALL be restored, after the transition +is completed. If another of these commands is received, before the transition is completed, the orig­ +inally stored CurrentLevel SHALL be preserved and restored. + +``` +Page 72 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.6.4.1.2. Effect of Level Control Commands on the OnOff Attribute** + +There are two sets of commands provided in the Level Control cluster. These are identical, except +that the first set (MoveToLevel, Move and Step commands) SHALL NOT affect the OnOff attribute, +whereas the second set ('with On/Off ' variants) SHALL. + +The first set is used to maintain independence between the CurrentLevel and OnOff attributes, so +changing CurrentLevel has no effect on the OnOff attribute. As examples, this represents the behav­ +ior of a volume control with a separate mute button, or a 'turn to set level and press to turn on/off ' +light dimmer. + +The second set is used to link the CurrentLevel and OnOff attributes. When the level is reduced to +its minimum the OnOff attribute is automatically turned to FALSE, and when the level is increased +above its minimum the OnOff attribute is automatically turned to TRUE. As an example, this repre­ +sents the behavior of a light dimmer with no independent on/off switch. + +For the Stop command, the StopWithOnOff is included solely for symmetry, to allow easy choice of +one or other set of commands – both Stop commands are identical, because the dependency on +On/Off is determined by the original command that is being stopped. + +**1.6.4.1.3. Effect of Level Control Commands Depends on OnOff** + +Before the Options attribute was introduced, all commands except those postfixed with ‘with +On/Off ’, had no effect if the OnOff attribute of the On/Off cluster, on the same endpoint, was FALSE. +Even if the On/Off (OO) feature set bit is set to zero, this is still true. To allow such commands to +function, please see the Options attribute below. + +**1.6.4.1.4. GlobalSceneControl and Commands with On/Off** + +If a MoveToLevel(WithOnOff ), Move(WithOnOff ) or Step(WithOnOff ) command is received that +causes a change to the value of the OnOff attribute of the On/Off cluster, the value of the Glob­ +alSceneControl attribute of the On/Off cluster SHALL be updated according to section Glob­ +alSceneControl. + +**1.6.4.2. Lighting Feature** + +This feature supports an interface for controlling the level of a light source. + +For the CurrentLevel attribute: + +``` +A value of 0x00 SHALL NOT be used. +A value of 0x01 SHALL indicate the minimum level that can be attained on a device. +A value of 0xFE SHALL indicate the maximum level that can be attained on a device. +A value of null SHALL represent an undefined value. +All other values are application specific gradations from the minimum to the maximum level. +``` +**1.6.4.3. Frequency Feature** + +``` +NOTE The Frequency feature is provisional. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 73 +``` + +**1.6.5. Data Types** + +**1.6.5.1. OptionsBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 ExecuteIfOff Dependency on On/Off +cluster +``` +### LT | OO + +``` +1 CoupleColorTemp­ +ToLevel +``` +``` +Dependency on Color +Control cluster +``` +### LT + +**1.6.5.1.1. ExecuteIfOff Bit** + +This bit indicates if this cluster has a dependency with the On/Off cluster. + +**1.6.5.1.2. CoupleColorTempToLevel Bit** + +This bit indicates if this cluster has a dependency with the Color Control cluster. + +**1.6.5.2. MoveModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Up Increase the level M +1 Down Decrease the level M +``` +**1.6.5.3. StepModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Up Step upwards M +1 Down Step downwards M +``` +**1.6.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Cur­ +rentLevel +``` +``` +uint8 MinLevel +to +MaxLevel +``` +``` +S N X Q null R V M +``` +``` +0x0001 Remain­ +ingTime +``` +``` +uint16 all Q 0 R V LT +``` +``` +Page 74 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0002 MinLevel uint8 1 to 254 1 R V [LT] +0x0002 MinLevel uint8 max 254 0 R V [!LT] +0x0003 MaxLevel uint8 MinLevel +to 254 +``` +### 254 R V O + +``` +0x0004 Current­ +Frequency +``` +``` +uint16 MinFre­ +quency to +MaxFre­ +quency +``` +### P S Q 0 R V FQ + +``` +0x0005 MinFre­ +quency +``` +``` +uint16 all 0 R V FQ +``` +``` +0x0006 MaxFre­ +quency +``` +``` +uint16 min Min­ +Frequency +``` +### 0 R V FQ + +``` +0x0010 OnOff­ +Transi­ +tionTime +``` +``` +uint16 all 0 RW VO O +``` +``` +0x0011 OnLevel uint8 MinLevel +to +MaxLevel +``` +``` +X null RW VO M +``` +``` +0x0012 OnTransi­ +tionTime +``` +``` +uint16 all X null RW VO O +``` +``` +0x0013 OffTransi­ +tionTime +``` +``` +uint16 all X null RW VO O +``` +``` +0x0014 Default­ +MoveRate +``` +``` +uint8 min 1 X MS RW VO O +``` +``` +0x000F Options Options­ +Bitmap +``` +``` +desc 0 RW VO M +``` +``` +0x4000 Star­ +tUpCur­ +rentLevel +``` +``` +uint8 desc XN MS RW VM LT +``` +**1.6.6.1. Scene Table Extensions** + +If the Scenes Management server cluster is implemented on the same endpoint, the following +attributes SHALL be part of the ExtensionFieldSetStruct of the Scene Table. If the implicit form of +the ExtensionFieldSetStruct is used, the order of the attributes in the AttributeValueList is in the +given order, i.e., the attribute listed as 1 is added first: + +1. CurrentLevel +2. CurrentFrequency + +Attributes in the scene table that are not supported by the device (according to the FeatureMap + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 75 +``` + +attribute) SHALL be present in the scene table but ignored. An extension field set value outside of +the accepted values of the corresponding MoveTo command, e.g. a null value for the Cur­ +rentLevel attribute, corresponding to the MoveToLevel command, SHALL be ignored. + +**1.6.6.2. CurrentLevel Attribute** + +This attribute SHALL indicate the current level of this device. The meaning of 'level' is device +dependent. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once per second, or +- At the end of the movement/transition, or +- When it changes from null to any other value and vice versa. + +**1.6.6.3. RemainingTime Attribute** + +This attribute SHALL indicate the time remaining until the current command is complete - it is +specified in 1/10ths of a second. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- When it changes from 0 to any value higher than 10, or +- When it changes, with a delta larger than 10, caused by the invoke of a command, or +- When it changes to 0. + +For commands with a transition time or changes to the transition time less than 1 second, changes +to this attribute SHALL NOT be reported. + +As this attribute is not being reported during a regular countdown, clients SHOULD NOT rely on the +reporting of this attribute in order to keep track of the remaining duration. + +**1.6.6.4. MinLevel Attribute** + +This attribute SHALL indicate the minimum value of CurrentLevel that is capable of being assigned. + +**1.6.6.5. MaxLevel Attribute** + +This attribute SHALL indicate the maximum value of CurrentLevel that is capable of being +assigned. + +**1.6.6.6. CurrentFrequency Attribute** + +This attribute SHALL indicate the frequency at which the device is at CurrentLevel. A CurrentFre­ +quency of 0 is unknown. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once per second, or + +``` +Page 76 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- At the start of the movement/transition, or +- At the end of the movement/transition. + +**1.6.6.7. MinFrequency Attribute** + +This attribute SHALL indicate the minimum value of CurrentFrequency that is capable of being +assigned. MinFrequency SHALL be less than or equal to MaxFrequency. A value of 0 indicates unde­ +fined. + +**1.6.6.8. MaxFrequency Attribute** + +This attribute SHALL indicate the maximum value of CurrentFrequency that is capable of being +assigned. MaxFrequency SHALL be greater than or equal to MinFrequency. A value of 0 indicates +undefined. + +**1.6.6.9. Options Attribute** + +This attribute SHALL indicate the selected options of the device. + +The Options attribute is a bitmap that determines the default behavior of some cluster commands. +Each command that is dependent on the Options attribute SHALL first construct a temporary +Options bitmap that is in effect during the command processing. The temporary Options bitmap has +the same format and meaning as the Options attribute, but includes any bits that may be overrid­ +den by command fields. + +This attribute is meant to be changed only during commissioning. + +Command execution SHALL NOT continue beyond the Options processing if all of these criteria are +true: + +- The command is one of the ‘without On/Off ’ commands: Move, Move to Level, Step, or Stop. +- The On/Off cluster exists on the same endpoint as this cluster. +- The OnOff attribute of the On/Off cluster, on this endpoint, is FALSE. +- The value of the ExecuteIfOff bit is 0. + +**1.6.6.9.1. ExecuteIfOff Bit** + +If this bit is set, commands in this cluster are executed and potentially change the CurrentLevel +attribute when the OnOff attribute of the On/Off cluster is FALSE. + +**1.6.6.9.2. CoupleColorTempToLevel Bit** + +If this bit is set, changes to the CurrentLevel attribute SHALL be coupled with the color temperature +set in the Color Control cluster. + +When not supporting the Lighting feature, this bit SHALL be zero and ignored. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 77 +``` + +**1.6.6.10. OnOffTransitionTime Attribute** + +This attribute SHALL indicate the time taken to move to or from the target level when On or Off +commands are received by an On/Off cluster on the same endpoint. It is specified in 1/10ths of a sec­ +ond. + +The actual time taken SHOULD be as close to OnOffTransitionTime as the device is able. Please note +that if the device is not able to move at a variable rate, the OnOffTransitionTime attribute SHOULD +NOT be implemented. + +**1.6.6.11. OnLevel Attribute** + +This attribute SHALL indicate the value that the CurrentLevel attribute is set to when the OnOff +attribute of an On/Off cluster on the same endpoint is set to TRUE, as a result of processing an +On/Off cluster command. If the OnLevel attribute is not implemented, or is set to the null value, it +has no effect. For more details see Effect of On/Off Commands on the CurrentLevel attribute. + +OnLevel represents a mandatory field that was previously not present or optional. Implementers +should be aware that older devices may not implement it. + +**1.6.6.12. OnTransitionTime Attribute** + +This attribute SHALL indicate the time taken to move the current level from the minimum level to +the maximum level when an On command is received by an On/Off cluster on the same endpoint. It +is specified in 1/10ths of a second. If this attribute is not implemented, or contains a null value, the +OnOffTransitionTime SHALL be used instead. + +**1.6.6.13. OffTransitionTime Attribute** + +This attribute SHALL indicate the time taken to move the current level from the maximum level to +the minimum level when an Off command is received by an On/Off cluster on the same endpoint. It +is specified in 1/10ths of a second. If this attribute is not implemented, or contains a null value, the +OnOffTransitionTime SHALL be used instead. + +**1.6.6.14. DefaultMoveRate Attribute** + +This attribute SHALL indicate the movement rate, in units per second, when a Move command is +received with a null value Rate parameter. + +**1.6.6.15. StartUpCurrentLevel Attribute** + +This attribute SHALL indicate the desired startup level for a device when it is supplied with power +and this level SHALL be reflected in the CurrentLevel attribute. The values of the StartUpCur­ +rentLevel attribute are listed below: + +``` +Value Action on power up +0 Set the CurrentLevel attribute to the minimum +value permitted on the device +``` +``` +Page 78 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Action on power up +null Set the CurrentLevel attribute to its previous +value +other values Set the CurrentLevel attribute to this value +``` +This behavior does not apply to reboots associated with OTA. After an OTA restart, the CurrentLevel +attribute SHALL return to its value prior to the restart. + +**1.6.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 MoveToLevel client ⇒ server Y O M +0x01 Move client ⇒ server Y O M +0x02 Step client ⇒ server Y O M +0x03 Stop client ⇒ server Y O M +0x04 MoveToLevel­ +WithOnOff +``` +``` +client ⇒ server Y O M +``` +``` +0x05 MoveWith­ +OnOff +``` +``` +client ⇒ server Y O M +``` +``` +0x06 StepWith­ +OnOff +``` +``` +client ⇒ server Y O M +``` +``` +0x07 StopWith­ +OnOff +``` +``` +client ⇒ server Y O M +``` +``` +0x08 MoveToClos­ +estFrequency +``` +``` +client ⇒ server Y O FQ +``` +**1.6.7.1. MoveToLevel Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Level uint8 max 254 M +1 Transition­ +Time +``` +``` +uint16 all X M +``` +``` +2 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +3 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**1.6.7.1.1. Effect on Receipt** + +The OptionsMask and OptionsOverride fields SHALL both be present. Default values are provided +to interpret missing fields from legacy devices. A temporary Options bitmap SHALL be created from + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 79 +``` + +the Options attribute, using the OptionsMask and OptionsOverride fields. Each bit of the temporary +Options bitmap SHALL be determined as follows: + +Each bit in the Options attribute SHALL determine the corresponding bit in the temporary Options +bitmap, unless the OptionsMask field is present and has the corresponding bit set to 1, in which +case the corresponding bit in the OptionsOverride field SHALL determine the corresponding bit in +the temporary Options bitmap. + +The resulting temporary Options bitmap SHALL then be processed as defined in the Options +attribute. + +On receipt of this command, a device SHALL move from its current level to the value given in the +Level field. The meaning of ‘level’ is device dependent – e.g., for a light it MAY mean brightness +level. + +The movement SHALL be as continuous as technically practical, i.e., not a step function, and the +time taken to move to the new level SHALL be equal to the value of the TransitionTime field, in +tenths of a second, or as close to this as the device is able. + +If the TransitionTime field takes the value null then the time taken to move to the new level SHALL +instead be determined by the OnOffTransitionTime attribute. If OnOffTransitionTime, which is an +optional attribute, is not present, the device SHALL move to its new level as fast as it is able. + +If the device is not able to move at a variable rate, the TransitionTime field MAY be disregarded. + +**1.6.7.2. Move Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 MoveMode MoveMod­ +eEnum +``` +``` +desc M +``` +``` +1 Rate uint8 all X M +2 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +3 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**1.6.7.2.1. MoveMode Field** + +This field SHALL be one of the non-reserved values in MoveModeEnum. + +**1.6.7.2.2. Rate Field** + +This field SHALL indicate the rate of movement in units per second. The actual rate of movement +SHOULD be as close to this rate as the device is able. If the Rate field is null, then the value of the +DefaultMoveRate attribute SHALL be used if that attribute is supported and its value is not null. If +the Rate field is null and the DefaultMoveRate attribute is either not supported or set to null, then +the device SHOULD move as fast as it is able. If the device is not able to move at a variable rate, this + +``` +Page 80 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +field MAY be disregarded. + +**1.6.7.2.3. Effect on Receipt** + +On receipt of this command, if the Rate field has a value of zero, the command has no effect and a +response SHALL be returned with the status code set to INVALID_COMMAND. + +Otherwise, a device SHALL first create and process a temporary Options bitmap as described in the +MoveToLevel command. + +On receipt of this command, a device SHALL move from its current level in an up or down direction +in a continuous fashion, as detailed below. + +``` +MoveMode Action on Receipt +Up Increase the device’s level at the rate given in +the Rate field. If the level reaches the maximum +allowed for the device, stop. +Down Decrease the device’s level at the rate given in +the Rate field. If the level reaches the minimum +allowed for the device, stop. +``` +**1.6.7.3. Step Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StepMode StepMod­ +eEnum +``` +``` +desc M +``` +``` +1 StepSize uint8 all M +2 Transition­ +Time +``` +``` +uint16 all X M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**1.6.7.3.1. StepMode Field** + +This field SHALL be one of the non-reserved values in StepModeEnum. + +**1.6.7.3.2. StepSize Field** + +This field SHALL indicate the change to CurrentLevel. + +**1.6.7.3.3. TransitionTime Field** + +This field SHALL indicate the time that SHALL be taken to perform the step, in tenths of a second. A +step is a change in the CurrentLevel of StepSize units. The actual time taken SHOULD be as close to + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 81 +``` + +this as the device is able. If the TransitionTime field is equal to null, the device SHOULD move as +fast as it is able. + +If the device is not able to move at a variable rate, the TransitionTime field MAY be disregarded. + +**1.6.7.3.4. Effect on Receipt** + +On receipt of this command, if the StepSize field has a value of zero, the command has no effect and +a response SHALL be returned with the status code set to INVALID_COMMAND. + +Otherwise, a device SHALL first create and process a temporary Options bitmap as described in the +MoveToLevel command. + +On receipt of this command, a device SHALL move from its current level in an up or down direction +as detailed below. + +``` +StepMode Action on Receipt +Up Increase CurrentLevel by StepSize units, or until +it reaches the maximum level allowed for the +device if this reached in the process. In the latter +case, the transition time SHALL be proportion­ +ally reduced. +Down Decrease CurrentLevel by StepSize units, or until +it reaches the minimum level allowed for the +device if this reached in the process. In the latter +case, the transition time SHALL be proportion­ +ally reduced. +``` +**1.6.7.4. Stop Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +1 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**1.6.7.4.1. Effect of Receipt** + +On receipt of this command, a device SHALL first create and process a temporary Options bitmap +as described in the MoveToLevel command. + +Upon receipt of this command, any MoveToLevel, Move or Step command (and their 'with On/Off ' +variants) currently in process SHALL be terminated. The value of CurrentLevel SHALL be left at its +value upon receipt of the Stop command, and RemainingTime SHALL be set to zero. + +This command has two entries in the Commands list, one for the MoveToLevel, Move and Step com­ +mands, and one for their 'with On/Off ' counterparts. This is solely for symmetry, to allow easy + +``` +Page 82 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +choice of one or other set of commands – the Stop commands are identical, because the dependency +on On/Off is determined by the original command that is being stopped. + +**1.6.7.5. MoveToClosestFrequency Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Frequency uint16 all 0 M +``` +**1.6.7.5.1. Effect of Receipt** + +Upon receipt of this command, the device SHALL change its current frequency to the requested fre­ +quency, or to the closest frequency that it can generate. If the device cannot approximate the fre­ +quency, then it SHALL return a default response with an error code of CONSTRAINT_ERROR. Deter­ +mining if a requested frequency can be approximated by a supported frequency is a manufacturer- +specific decision. + +**1.6.7.6. 'With On/Off ' Commands** + +The MoveToLevelWithOnOff, MoveWithOnOff and StepWithOnOff commands have identical data +fields compared to the MoveToLevel, Move and Step commands respectively. They also have the +same effects, except for the following additions. + +Before commencing any command that has the effect of setting the CurrentLevel attribute above +the minimum level allowed by the device, the OnOff attribute of the On/Off cluster on the same end­ +point, if implemented, SHALL be set to TRUE (‘On’). + +If any command that has the effect of setting the CurrentLevel attribute to the minimum level +allowed by the device, the OnOff attribute of the On/Off cluster on the same endpoint, if imple­ +mented, SHALL be set to FALSE (‘Off ’). + +The StopWithOnOff command has identical data fields compared to the Stop command. Both Stop +commands are identical, because the dependency on On/Off is determined by the original com­ +mand that is being stopped. + +**1.6.8. State Change Table for Lighting** + +Below is a table of examples of state changes when Level Control and On/Off clusters are on the +same endpoint and the Lighting feature is set. + +``` +EiO - ExecuteIfOff field in the Options attribute +OnOff – Attribute value of On/Off cluster: FALSE=‘Off ’, TRUE=‘On’ +MIN - MinLevel +MAX - MaxLevel +MID – Midpoint between MinLevel and MaxLevel +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 83 +``` + +**1.6.8.1. Lighting Device State Change examples** + +``` +Cur­ +rentLeve +l +``` +``` +EiO OnOff Physical +Device +``` +``` +Com­ +mand +Before +After +``` +``` +Cur­ +rentLeve +l +``` +``` +OnOff Physical +Device +``` +``` +Device +Output +Result +``` +``` +any 0 FALSE Off Move­ +ToLevel(l += MID , t=2 +sec) +``` +``` +same FALSE Off Stays off +``` +``` +any 0 FALSE Off Move­ +ToLevel­ +With­ +OnOff(l= +MID , t=2 +sec +``` +``` +MID TRUE On (mid- +point +bright­ +ness) +``` +``` +Turns on +and out­ +put level +adjusts or +stays at +half +any 1 FALSE Off Move­ +ToLevel(l += MID , t=2 +sec) +``` +``` +MID FALSE Off Stays off +``` +``` +any 1 FALSE Off Move­ +ToLevel­ +With­ +OnOff(l= +MID , t=2 +sec) +``` +``` +MID TRUE On Turns on +and out­ +put level +adjusts to +or stays +at half +any 1 FALSE Off Move(up, +rate=64/s) +``` +``` +MAX FALSE Off Stays off +``` +``` +any 1 FALSE Off Move­ +With­ +OnOff(up, +rate=64/s) +``` +``` +MAX TRUE On Turn on +and out­ +put level +adjusts to +or stays +at full +any 1 FALSE Off Move­ +With­ +OnOff(do +wn, +rate=64/s) +``` +``` +MIN FALSE Off Stays off +``` +``` +any any TRUE On (any +bright­ +ness) +``` +``` +Move­ +ToLevel­ +With­ +OnOff(l= +MID , t=2 +sec) +``` +``` +MID TRUE On (mid- +point +bright­ +ness) +``` +``` +Output +level +adjusts to +or stays +at half +``` +``` +Page 84 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Cur­ +rentLeve +l +``` +``` +EiO OnOff Physical +Device +``` +``` +Com­ +mand +Before +After +``` +``` +Cur­ +rentLeve +l +``` +``` +OnOff Physical +Device +``` +``` +Device +Output +Result +``` +``` +any any TRUE On (any +bright­ +ness) +``` +``` +Move­ +With­ +OnOff(up, +rate=64/s) +``` +``` +MAX TRUE On (full +bright­ +ness) +``` +``` +Output +level +adjusts to +or stays +at full +any any TRUE On (any +bright­ +ness) +``` +``` +Move(do +wn, +rate=64/s) +``` +``` +MIN TRUE On (at +minimum +bright­ +ness) +``` +``` +Output +level +adjusts to +minimum +any any TRUE On (any +bright­ +ness) +``` +``` +Move­ +With­ +OnOff(do +wn, +rate=64/s) +``` +``` +MIN FALSE Off Output +level +adjusts to +off +``` +**1.7. Boolean State Cluster** + +This cluster provides an interface to a boolean state. + +**1.7.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**1.7.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint BOOL +``` +**1.7.3. Cluster ID** + +``` +ID Name +0x0045 Boolean State +``` +**1.7.4. Attributes** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 85 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 StateValue bool P R V M +``` +**1.7.4.1. StateValue Attribute** + +This represents a boolean state. + +The semantics of this boolean state are defined by the device type using this cluster. +For example, in a Contact Sensor device type, FALSE=open or no contact, TRUE=closed or contact. + +**1.7.5. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 StateChange INFO V O +``` +**1.7.5.1. StateChange Event** + +If this event is supported, it SHALL be generated when the StateValue attribute changes. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StateValue bool M +``` +**1.7.5.1.1. StateValue Field** + +This field SHALL indicate the new value of the StateValue attribute. + +**1.8. Boolean State Configuration Cluster** + +This cluster is used to configure a boolean sensor, including optional state change alarm features +and configuration of the sensitivity level associated with the sensor. + +**1.8.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**1.8.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint BOOLCFG +``` +``` +Page 86 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.8.3. Cluster ID** + +``` +ID Name +0x0080 Boolean State Configuration +``` +**1.8.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 VIS Visual O Supports visual +alarms +1 AUD Audible O Supports audible +alarms +2 SPRS AlarmSuppress [VIS | AUD] Supports ability to +suppress or +acknowledge +alarms +3 SENSLVL SensitivityLevel O Supports ability to +set sensor sensitiv­ +ity +``` +**1.8.4.1. AlarmSuppress Feature** + +This feature SHALL indicate that the device is able to suppress the supported alarm modes, when +the user acknowledges the alarm. This is intended to stop visual and/or audible alarms, when the +user has become aware that the sensor is triggered, but it is no longer desired to have the alarm +modes active on the device, e.g.: + +- The triggering cause have been resolved by the user, but the sensor has not yet stopped detect­ + ing the triggering cause. +- The user is not able to address the triggering cause, but is aware of the alarm and sup­ + press/acknowledge it be addressed at a later point. + +Acknowledge of alarms will for the remainder of this cluster be referred to as suppress. + +A suppressed alarm is still considered active and will remain so unless it is actively disabled or the +triggering condition is not longer present. The action of suppressing an alarm mode is only applica­ +ble to and is intended to stop the physical alarming, e.g. emitting a sound or blinking a light; it does +not impact alarm reporting in AlarmsActive. + +**1.8.5. Data Types** + +**1.8.5.1. AlarmModeBitmap Type** + +This data type is derived from map8. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 87 +``` + +``` +Bit Name Summary Conformance +0 Visual Visual alarming VIS +1 Audible Audible alarming AUD +``` +**1.8.5.2. SensorFaultBitmap Type** + +This data type is derived from map16. + +``` +Bit Name Summary Conformance +0 GeneralFault Unspecified fault +detected +``` +### M + +**1.8.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Cur­ +rentSensi­ +tivityLevel +``` +``` +uint8 max (Sup­ +portedSen­ +sitiv­ +ityLevels - +1) +``` +### N MS RW VO SENSLVL + +``` +0x0001 Support­ +edSensi­ +tiv­ +ityLevels +``` +``` +uint8 2 to 10 F MS R V SENSLVL +``` +``` +0x0002 Default­ +Sensitiv­ +ityLevel +``` +``` +uint8 max (Sup­ +portedSen­ +sitiv­ +ityLevels - +1) +``` +### F MS R V [SENSLVL] + +``` +0x0003 AlarmsAc­ +tive +``` +``` +Alarm­ +ModeB­ +itmap +``` +``` +all 0 R V VIS | AUD +``` +``` +0x0004 AlarmsSu +ppressed +``` +``` +Alarm­ +ModeB­ +itmap +``` +``` +all 0 R V SPRS +``` +``` +0x0005 AlarmsEn­ +abled +``` +``` +Alarm­ +ModeB­ +itmap +``` +``` +all N MS R V [VIS | +AUD] +``` +``` +0x0006 AlarmsSu +pported +``` +``` +Alarm­ +ModeB­ +itmap +``` +``` +all F 0 R V VIS | AUD +``` +``` +Page 88 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0007 Sensor­ +Fault +``` +``` +Sensor­ +Fault­ +Bitmap +``` +``` +all 0 R V O +``` +**1.8.6.1. CurrentSensitivityLevel Attribute** + +This attribute SHALL indicate the currently selected sensitivity level. + +If a write interaction to this attribute contains an unsupported sensitivity value, a CONSTRAINT_ER­ +ROR status SHALL be returned. + +**1.8.6.2. SupportedSensitivityLevels Attribute** + +This attribute SHALL indicate the number of supported sensitivity levels by the device. + +These supported sensitivity levels SHALL be ordered by sensitivity, where a value of 0 SHALL be +considered the lowest sensitivity level (least sensitive) and the highest supported value SHALL be +considered the highest sensitivity level. +The number of supported sensitivity levels SHOULD represent unique sensitivity levels supported +by the device. + +**1.8.6.3. DefaultSensitivityLevel Attribute** + +This attribute SHALL indicate the default sensitivity level selected by the manufacturer. + +**1.8.6.4. AlarmsActive Attribute** + +This attribute SHALL indicate which specific alarm modes on the server are currently active. When +the sensor is no longer triggered, this attribute SHALL be set to the inactive state, by setting the bit +to 0, for all supported alarm modes. + +If an alarm mode is not supported, the bit indicating this alarm mode SHALL always be 0. + +A bit SHALL indicate whether the alarm mode inactive or not: + +- 0 = Inactive +- 1 = Active + +**1.8.6.5. AlarmsSuppressed Attribute** + +This attribute SHALL indicate which specific alarm modes on the server are currently suppressed. +When the sensor is no longer triggered, this attribute SHALL be set to the unsuppressed state, by +setting the bit to 0, for all supported alarm modes. + +If an alarm mode is not supported, the bit indicating this alarm mode SHALL always be 0. + +A bit SHALL indicate whether the alarm mode is suppressed or not: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 89 +``` + +- 0 = Not suppressed +- 1 = Suppressed + +**1.8.6.6. AlarmsEnabled Attribute** + +This attribute SHALL indicate the alarm modes that will be emitted if the sensor is triggered. + +If an alarm mode is not supported, the bit indicating this alarm mode SHALL always be 0. + +A bit SHALL indicate whether the alarm mode is enabled or disabled: + +- 0 = Disabled +- 1 = Enabled + +**1.8.6.7. AlarmsSupported Attribute** + +This attribute SHALL indicate the alarms supported by the sensor. + +A bit SHALL indicate whether the alarm mode is supported: + +- 0 = Not supported +- 1 = Supported + +**1.8.6.8. SensorFault Attribute** + +This attribute SHALL indicate any faults registered by the device. + +**1.8.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Suppres­ +sAlarm +``` +``` +client ⇒ server Y O SPRS +``` +``` +0x01 EnableDis­ +ableAlarm +``` +``` +client ⇒ server Y O VIS | AUD +``` +**1.8.7.1. SuppressAlarm Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 AlarmsTo­ +Suppress +``` +``` +Alarm­ +ModeBitmap +``` +``` +all M +``` +**1.8.7.1.1. AlarmsToSuppress Field** + +This field SHALL indicate the alarm modes to suppress. + +``` +Page 90 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.8.7.1.2. Effect on Receipt** + +If any of the requested alarm modes are not supported this command SHALL be ignored and the +server SHALL return an CONSTRAINT_ERROR status code. + +If any of the requested alarm modes are not active, in case the sensor is not triggered or the alarm +mode is disabled/not supported, this command SHALL be ignored and the server SHALL return an +INVALID_IN_STATE status code. + +In the case an alarm is already suppressed and the specific bit is set in the AlarmsSuppressed +attribute, the bit SHALL be ignored and the remaining bits SHALL be evaluated. + +For the valid bits in the AlarmsToSuppress field, the device SHALL suppress the specified alarm +modes as requested in the AlarmsToSuppress field and set the AlarmsSuppressed attribute accord­ +ingly. + +**1.8.7.2. EnableDisableAlarm Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Alarm­ +sToEn­ +ableDisable +``` +``` +Alarm­ +ModeBitmap +``` +``` +all M +``` +**1.8.7.2.1. AlarmsToEnableDisable Field** + +This field SHALL indicate the alarm modes to either enable or disable depending on the bit status, +as specified for the AlarmsEnabled attribute. + +**1.8.7.2.2. Effect on Receipt** + +If any of the requested alarm modes are not supported this command SHALL be ignored and the +server SHALL return an CONSTRAINT_ERROR status code. + +If all the bits are valid, the value of the AlarmsEnabled attribute SHALL be set to the value of the +AlarmsToEnableDisable field. + +If an alarm mode is being enabled and the trigger condition is met, the device SHALL immediately +activate the alarm mode and set the associated bit in the AlarmsActive attribute. + +If an alarm mode is being disabled, any alarm mode which is either in the active or suppressed +state SHALL be cleared and the alarm mode SHALL be considered not active. + +**1.8.8. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 AlarmsState­ +Changed +``` +### INFO V VIS | AUD + +``` +0x01 SensorFault INFO V O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 91 +``` + +**1.8.8.1. AlarmsStateChanged Event** + +This event SHALL be generated after any bits in the AlarmsActive and/or AlarmsSuppressed attrib­ +utes change. This MAY occur in situations such as when internal processing by the server deter­ +mines that an alarm mode becomes active or inactive, or when the SuppressAlarm or EnableDis­ +ableAlarm commands are processed in a way that some alarm modes becomes suppressed, active +or inactive. + +If several alarm modes change state at the same time, a single event combining multiple changes +MAY be emitted instead of multiple events each representing a single change. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 AlarmsAc­ +tive +``` +``` +Alarm­ +ModeBitmap +``` +``` +all M +``` +``` +1 AlarmsSup­ +pressed +``` +``` +Alarm­ +ModeBitmap +``` +``` +all SPRS +``` +**1.8.8.1.1. AlarmsActive Field** + +This field SHALL indicate the state of active alarm modes, as indicated by the AlarmsActive +attribute, at the time the event was generated. + +**1.8.8.1.2. AlarmsSuppressed Field** + +This field SHALL indicate the state of suppressed alarm modes, as indicated by the AlarmsSup­ +pressed attribute, at the time the event was generated. + +**1.8.8.2. SensorFault Event** + +This event SHALL be generated when the device registers or clears a fault. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SensorFault SensorFault­ +Bitmap +``` +``` +all M +``` +**1.8.8.2.1. SensorFault Field** + +This field SHALL indicate the value of the SensorFault attribute, at the time this event is generated. + +**1.9. Mode Select Cluster** + +This cluster provides an interface for controlling a characteristic of a device that can be set to one +of several predefined values. For example, the light pattern of a disco ball, the mode of a massage +chair, or the wash cycle of a laundry machine. + +The server allows the client to set a mode on the server. A mode is one of a list of options that may +be presented by a client for a user choice, or understood by the client, via the semantic tags on the + +``` +Page 92 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +mode. + +A semantic tag is either a standard tag within a standard category namespace, or a manufacturer +specific tag, within the namespace of the vendor ID of the manufacturer. If there is no semantic tag, +the mode is anonymous, and the selection is made by the user solely based on the Label string. + +Each cluster ID that indicates this specification SHALL define a distinct purpose for the cluster +instance. For example: A LightBlinking cluster ID supports blinking modes for a light (and is +described that way). + +An anonymous mode SHALL support the derived cluster purpose. A manufacturer specific seman­ +tic tag SHALL support the derived cluster purpose. An anonymous mode SHALL NOT replace the +meaning of a standard semantic tag, when one exists, for the cluster purpose. + +**1.9.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 The MfgCode field was marked non-nullable. +Updated the related text. Reorder sections. +``` +**1.9.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint MOD +``` +**1.9.3. Cluster ID** + +``` +ID Name +0x0050 Mode Select +``` +**1.9.4. Features** + +This cluster SHALL support the FeatureMap global attribute: + +``` +Bit Code Feature Summary +0 DEPONOFF OnOff Dependency with the +OnOff cluster +``` +**1.9.4.1. OnOff Feature** + +This feature creates a dependency between an OnOff cluster instance and this cluster instance on +the same endpoint. See OnMode for more information. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 93 +``` + +**1.9.5. Data Types** + +**1.9.5.1. SemanticTagStruct Type** + +A Semantic Tag is meant to be interpreted by the client for the purpose the cluster serves. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 MfgCode vendor-id desc F M +1 Value enum16 all F M +``` +**1.9.5.1.1. Value Field** + +This field SHALL indicate the semantic tag within a semantic tag namespace which is either manu­ +facturer specific or standard. For semantic tags in a standard namespace, see Standard Namespace. + +**1.9.5.1.2. MfgCode Field** + +This field SHALL indicate a manufacturer code (Vendor ID), and the Value field SHALL indicate a +semantic tag defined by the manufacturer. Each manufacturer code supports a single namespace of +values. The same manufacturer code and semantic tag value in separate cluster instances are part +of the same namespace and have the same meaning. For example: a manufacturer tag meaning +"pinch", has the same meaning in a cluster whose purpose is to choose the amount of sugar, or +amount of salt. + +**1.9.5.2. ModeOptionStruct Type** + +This is a struct representing a possible mode of the server. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label string max 64 F MS M +1 Mode uint8 F MS M +2 Semantic­ +Tags +``` +``` +list[Seman­ +tic­ +TagStruct] +``` +``` +max 64 F MS M +``` +**1.9.5.2.1. Label Field** + +This field is readable text that describes the mode option that can be used by a client to indicate to +the user what this option means. This field is meant to be readable and understandable by the user. + +**1.9.5.2.2. Mode Field** + +The Mode field is used to identify the mode option. The value SHALL be unique for every item in +the SupportedModes attribute. + +``` +Page 94 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.9.5.2.3. SemanticTags Field** + +This field is a list of semantic tags that map to the mode option. This MAY be used by clients to +determine the meaning of the mode option as defined in a standard or manufacturer specific name­ +space. Semantic tags can help clients look for options that meet certain criteria. A semantic tag +SHALL be either a standard tag or manufacturer specific tag as defined in each SemanticTagStruct +list entry. + +A mode option MAY have more than one semantic tag. A mode option MAY be mapped to a mixture +of standard and manufacturer specific semantic tags. + +All standard semantic tags are from a single namespace indicated by the StandardNamespace +attribute. + +For example: A mode labeled "100%" can have both the HIGH (MS) and MAX (standard) semantic tag. +Clients seeking the option for either HIGH or MAX will find the same option in this case. + +**1.9.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Descrip­ +tion +``` +``` +string max 64 F MS R V M +``` +``` +0x0001 Standard­ +Name­ +space +``` +``` +enum16 desc FX null R V M +``` +``` +0x0002 Support­ +edModes +``` +``` +list[Mod­ +eOption­ +Struct] +``` +``` +max 255 F MS R V M +``` +``` +0x0003 Current­ +Mode +``` +``` +uint8 desc N MS R V M +``` +``` +0x0004 StartUp­ +Mode +``` +``` +uint8 desc NX MS RW VO O +``` +``` +0x0005 OnMode uint8 desc NX null RW VO DEPONOFF +``` +**1.9.6.1. Description Attribute** + +This attribute describes the purpose of the server, in readable text. + +For example, a coffee machine may have a Mode Select cluster for the amount of milk to add, and +another Mode Select cluster for the amount of sugar to add. In this case, the first instance can have +the description Milk and the second instance can have the description Sugar. This allows the user to +tell the purpose of each of the instances. + +**1.9.6.2. StandardNamespace Attribute** + +This attribute, when not null, SHALL indicate a single standard namespace for any standard seman­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 95 +``` + +tic tag value supported in this or any other cluster instance with the same value of this attribute. A +null value indicates no standard namespace, and therefore, no standard semantic tags are provided +in this cluster instance. Each standard namespace and corresponding values and value meanings +SHALL be defined in another document. + +**1.9.6.3. SupportedModes Attribute** + +This attribute is the list of supported modes that may be selected for the CurrentMode attribute. +Each item in this list represents a unique mode as indicated by the Mode field of the ModeOption­ +Struct. Each entry in this list SHALL have a unique value for the Mode field. + +**1.9.6.4. CurrentMode Attribute** + +This attribute represents the current mode of the server. + +The value of this field must match the Mode field of one of the entries in the SupportedModes +attribute. + +**1.9.6.5. StartUpMode Attribute** + +The StartUpMode attribute value indicates the desired startup mode for the server when it is sup­ +plied with power. + +If this attribute is not null, the CurrentMode attribute SHALL be set to the StartUpMode value, when +the server is powered up, except in the case when the OnMode attribute overrides the StartUpMode +attribute (see OnModeWithPowerUp). + +This behavior does not apply to reboots associated with OTA. After an OTA restart, the CurrentMode +attribute SHALL return to its value prior to the restart. + +The value of this field SHALL match the Mode field of one of the entries in the SupportedModes +attribute. + +If this attribute is not implemented, or is set to the null value, it SHALL have no effect. + +**1.9.6.6. OnMode Attribute** + +This attribute SHALL indicate the value of CurrentMode that depends on the state of the On/Off +cluster on the same endpoint. If this attribute is not present or is set to null, it SHALL NOT have an +effect, otherwise the CurrentMode attribute SHALL depend on the OnOff attribute of the On/Off +cluster as described in the table below: + +``` +OnOff Change CurrentMode Change +ON → OFF No change +OFF → ON Change CurrentMode to OnMode +OFF → OFF No change +ON → ON No change +``` +The value of this field SHALL match the Mode field of one of the entries in the SupportedModes + +``` +Page 96 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +attribute. + +**1.9.6.6.1. OnMode with Power Up** + +If the On/Off feature is supported and the On/Off cluster attribute StartUpOnOff is present, with a +value of On (turn on at power up), then the CurrentMode attribute SHALL be set to the OnMode +attribute value when the server is supplied with power, except if the OnMode attribute is null. + +**1.9.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 ChangeTo­ +Mode +``` +``` +client ⇒ server Y O M +``` +**1.9.7.1. ChangeToMode Command** + +On receipt of this command, if the NewMode field indicates a valid mode transition within the sup­ +ported list, the server SHALL set the CurrentMode attribute to the NewMode value, otherwise, the +server SHALL respond with an INVALID_COMMAND status response. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NewMode uint8 desc M +``` +**1.10. Mode Base Cluster** + +This cluster provides an interface for controlling a characteristic of a device that can be set to one +of several predefined values. For example, the light pattern of a disco ball, the mode of a massage +chair, or the wash cycle of a laundry machine. + +The server allows the client to set a mode on the server. A mode is one of a list of options that may +be presented by a client for a user choice, or understood by the client, via the mode’s tags. + +A mode tag is either a standard tag within a standard category namespace, or a manufacturer spe­ +cific tag, within the namespace of the vendor ID of the manufacturer. + +Any derived cluster specification based on this cluster SHALL support the standard mode tag value +definitions and command status definitions defined in this cluster and MAY define additional stan­ +dard mode tag values and standard command status values that are supported in the respective +derived cluster instances. + +Each cluster ID that indicates this specification SHALL define a distinct purpose for the cluster +instance. For example: A LightBlinking cluster ID supports blinking modes for a light (and is +described that way). + +An anonymous mode SHALL NOT replace the meaning of a standard mode tag, when one exists, for +the cluster purpose. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 97 +``` + +**1.10.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 ChangeToModeResponse command: StatusText +must be provided for InvalidInMode status. +Require at least one standard mode tag. Define +reserved ranges for base/derived clusters +``` +**1.10.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint MODB +``` +**1.10.3. Cluster ID** + +``` +ID Name +n/a Mode Base +``` +**1.10.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 DEPONOFF OnOff Dependency with the +OnOff cluster +``` +**1.10.4.1. OnOff Feature** + +This feature creates a dependency between an OnOff cluster instance and this cluster instance on +the same endpoint. See OnMode for more information. + +**1.10.5. Data Types** + +**1.10.5.1. ModeTagStruct Type** + +A Mode Tag is meant to be interpreted by the client for the purpose the cluster serves. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 MfgCode vendor-id desc O +1 Value enum16 all M +``` +``` +Page 98 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.10.5.1.1. MfgCode Field** + +If the MfgCode field exists, the Value field SHALL be in the manufacturer-specific value range (see +Section 1.10.8, “Mode Namespace”). + +This field SHALL indicate the manufacturer’s VendorID and it SHALL determine the meaning of the +Value field. + +The same manufacturer code and mode tag value in separate cluster instances are part of the same +namespace and have the same meaning. For example: a manufacturer tag meaning "pinch" can be +used both in a cluster whose purpose is to choose the amount of sugar, or in a cluster whose pur­ +pose is to choose the amount of salt. + +**1.10.5.1.2. Value Field** + +This field SHALL indicate the mode tag within a mode tag namespace which is either manufacturer +specific or standard. + +**1.10.5.2. ModeOptionStruct Type** + +This is a struct representing a possible mode of the server. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label string max 64 F MS M +1 Mode uint8 F MS M +2 ModeTags list[Mode­ +TagStruct] +``` +``` +max 8 F MS M +``` +**1.10.5.2.1. Label Field** + +This field SHALL indicate readable text that describes the mode option, so that a client can provide +it to the user to indicate what this option means. This field is meant to be readable and understand­ +able by the user. + +**1.10.5.2.2. Mode Field** + +This field is used to identify the mode option. + +**1.10.5.2.3. ModeTags Field** + +This field SHALL contain a list of tags that are associated with the mode option. This MAY be used +by clients to determine the full or the partial semantics of a certain mode, depending on which tags +they understand, using standard definitions and/or manufacturer specific namespace definitions. + +The standard mode tags are defined in this cluster specification. For the derived cluster instances, if +the specification of the derived cluster defines a namespace, the set of standard mode tags also +includes the mode tag values from that namespace. + +Mode tags can help clients look for options that meet certain criteria, render the user interface, use + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 99 +``` + +the mode in an automation, or to craft help text their voice-driven interfaces. A mode tag SHALL be +either a standard tag or a manufacturer specific tag, as defined in each ModeTagStruct list entry. + +A mode option MAY have more than one mode tag. A mode option MAY be associated with a mix­ +ture of standard and manufacturer specific mode tags. A mode option SHALL be associated with at +least one standard mode tag. + +A few examples are provided below. + +- A mode named "100%" can have both the High (manufacturer specific) and Max (standard) + mode tag. Clients seeking the mode for either High or Max will find the same mode in this case. +- A mode that includes a LowEnergy tag can be displayed by the client using a widget icon that + shows a green leaf. +- A mode that includes a LowNoise tag may be used by the client when the user wishes for a + lower level of audible sound, less likely to disturb the household’s activities. +- A mode that includes a LowEnergy tag (standard, defined in this cluster specification) and also a + Delicate tag (standard, defined in the namespace of a Laundry Mode derived cluster). +- A mode that includes both a generic Quick tag (defined here), and Vacuum and Mop tags, + (defined in the RVC Clean cluster that is a derivation of this cluster). + +**1.10.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +``` +``` +list[Mod­ +eOption­ +Struct] +``` +``` +2 to 255 F MS R V M +``` +``` +0x0001 Current­ +Mode +``` +``` +uint8 desc N MS R V M +``` +``` +0x0002 StartUp­ +Mode +``` +``` +uint8 desc NX MS RW VO O +``` +``` +0x0003 OnMode uint8 desc NX null RW VO DEPONOFF +``` +**1.10.6.1. SupportedModes Attribute** + +This attribute SHALL contain the list of supported modes that may be selected for the CurrentMode +attribute. Each item in this list represents a unique mode as indicated by the Mode field of the Mod­ +eOptionStruct. + +Each entry in this list SHALL have a unique value for the Mode field. + +Each entry in this list SHALL have a unique value for the Label field. + +**1.10.6.2. CurrentMode Attribute** + +This attribute SHALL indicate the current mode of the server. + +``` +Page 100 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The value of this field SHALL match the Mode field of one of the entries in the SupportedModes +attribute. + +The value of this attribute may change at any time via an out-of-band interaction outside of the +server, such as interactions with a user interface, via internal mode changes due to autonomously +progressing through a sequence of operations, on system time-outs or idle delays, or via interac­ +tions coming from a fabric other than the one which last executed a ChangeToMode. + +**1.10.6.3. StartUpMode Attribute** + +This attribute SHALL indicate the desired startup mode for the server when it is supplied with +power. + +If this attribute is not null, the CurrentMode attribute SHALL be set to the StartUpMode value, when +the server is powered up, except in the case when the OnMode attribute overrides the StartUpMode +attribute (see OnModeWithPowerUp). + +This behavior does not apply to reboots associated with OTA. After an OTA restart, the CurrentMode +attribute SHALL return to its value prior to the restart. + +The value of this field SHALL match the Mode field of one of the entries in the SupportedModes +attribute. + +If this attribute is not implemented, or is set to the null value, it SHALL have no effect. + +**1.10.6.4. OnMode Attribute** + +This attribute SHALL indicate whether the value of CurrentMode depends on the state of the On/Off +cluster on the same endpoint. If this attribute is not present or is set to null, there is no dependency, +otherwise the CurrentMode attribute SHALL depend on the OnOff attribute in the On/Off cluster as +described in the table below: + +``` +OnOff Change CurrentMode Change +ON → OFF No change +OFF → ON Change CurrentMode to OnMode +OFF → OFF No change +ON → ON No change +``` +The value of this field SHALL match the Mode field of one of the entries in the SupportedModes +attribute. + +**1.10.6.4.1. OnMode with Power Up** + +If the On/Off feature is supported and the On/Off cluster attribute StartUpOnOff is present, with a +value of On (turn on at power up), then the CurrentMode attribute SHALL be set to the OnMode +attribute value when the server is supplied with power, except if the OnMode attribute is null. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 101 +``` + +**1.10.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 ChangeTo­ +Mode +``` +``` +client ⇒ server ChangeToMod­ +eResponse +``` +### O M + +``` +0x01 ChangeTo­ +ModeRe­ +sponse +``` +``` +client ⇐ server N M +``` +**1.10.7.1. ChangeToMode Command** + +This command is used to change device modes. + +On receipt of this command the device SHALL respond with a ChangeToModeResponse command. + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NewMode uint8 desc M +``` +**1.10.7.1.1. NewMode Field** + +If the NewMode field doesn’t match the Mode field of any entry of the SupportedModes list, the +ChangeToModeResponse command’s Status field SHALL indicate UnsupportedMode and the Status­ +Text field SHALL be included and MAY be used to indicate the issue, with a human readable string, +or include an empty string. + +If the NewMode field matches the Mode field of one entry of the SupportedModes list, but the +device is not able to transition as requested, the ChangeToModeResponse command SHALL: + +- Have the Status set to a product-specific Status value representing the error, or GenericFailure if + a more specific error cannot be provided. See Status field for details. +- Provide a human readable string in the StatusText field. + +If the NewMode field matches the Mode field of one entry of the SupportedModes list and the +device is able to transition as requested, the server SHALL transition into the mode associated with +NewMode, the ChangeToModeResponse command SHALL have the Status field set to Success, the +StatusText field MAY be supplied with a human readable string or include an empty string and the +CurrentMode field SHALL be set to the value of the NewMode field. + +If the NewMode field is the same as the value of the CurrentMode attribute the ChangeToModeRe­ +sponse command SHALL have the Status field set to Success and the StatusText field MAY be sup­ +plied with a human readable string or include an empty string. + +**1.10.7.2. ChangeToModeResponse Command** + +This command is sent by the device on receipt of the ChangeToMode command. This command + +``` +Page 102 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status enum8 desc M +1 StatusText string max 64 [Status == +Success], M +``` +**1.10.7.2.1. Status Field** + +**1.10.7.2.1.1. Mode Base Status Code Ranges** + +The following table defines the enumeration ranges for the ChangeToModeResponse command’s +Status field values. + +``` +Status Code Range Range Name Summary +0x00 to 0x3F CommonCodes Common standard values +defined in the generic Mode +Base cluster specification. +0x40 to 0x7F DerivedClusterCodes Derived cluster specific stan­ +dard values defined in the +derived Mode Base cluster spec­ +ification. +0x80 to 0xBF MfgCodes Manufacturer specific values. +For the derived Mode Base clus­ +ter instances, these are manu­ +facturer specific under the +derived cluster. +``` +The set of Status field values defined in each of the generic or derived Mode Base cluster specifica­ +tions is called StatusCode. + +**1.10.7.2.1.2. Mode Base Status CommonCodes Range** + +The following table defines the common StatusCode values. + +``` +Status Code Name Summary +0x00 Success Switching to the mode indicated +by the NewMode field is +allowed and possible. The Cur­ +rentMode attribute is set to the +value of the NewMode field. +0x01 UnsupportedMode The value of the NewMode field +doesn’t match any entries in the +SupportedModes attribute. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 103 +``` + +``` +Status Code Name Summary +0x02 GenericFailure Generic failure code, indicating +that switching to the mode indi­ +cated by the NewMode field is +not allowed or not possible. +0x03 InvalidInMode The received request cannot be +handled due to the current +mode of the device +``` +The derived cluster code definitions SHALL NOT duplicate the common code definitions. For exam­ +ple, a derived cluster specification SHALL NOT define a status code with the same semantic as the +common code of 0x01 (UnsupportedMode). + +If the Status field is set to Success, the StatusText field is optional. + +If the Status field is set to UnsupportedMode, the StatusText field SHALL be an empty string. + +If the Status field is not set to Success or UnsupportedMode, the StatusText field SHALL include a +vendor-defined error description which can be used to explain the error to the user. For example, if +the Status field is set to InvalidInMode, the StatusText field SHOULD indicate why the transition to +the requested mode is not allowed, given the current mode of the device, which may involve other +clusters. + +**1.10.8. Mode Namespace** + +This section provides the definitions of the mode tag ranges and of the common standard mode tag +values available in the instances of this cluster. + +The following table defines the enumeration ranges for the ModeTagStruct Value field values. + +``` +Mode Tag Value Range Range Name Summary +0x0000 to 0x3FFF CommonTags Common standard values +defined in this cluster specifica­ +tion. +0x4000 to 0x7FFF DerivedClusterTags Derived cluster specific stan­ +dard values defined in the +derived cluster specification. +0x8000 to 0xBFFF MfgTags Manufacturer-specific values. +For the derived cluster +instances, these are manufac­ +turer specific under the derived +cluster. +``` +The derived cluster specific standard value definitions SHALL not duplicate the common standard +value definitions. For example, a derived cluster specification can’t define a mode tag value with +the same mode as the common standard tag value of 0x0001 (Quick). + +``` +Page 104 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The set of ModeTagStruct Value field values defined in each of the generic or derived Mode Base +cluster specifications is called ModeTag. + +The following table defines the common ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +``` +**1.10.8.1. Auto Tag** + +The device decides which options, features and setting values to use. + +**1.10.8.2. Quick Tag** + +The mode of the device is optimizing for faster completion. + +**1.10.8.3. Quiet Tag** + +The device is silent or barely audible while in this mode. + +**1.10.8.4. LowNoise Tag** + +Either the mode is inherently low noise or the device optimizes for that. + +**1.10.8.5. LowEnergy Tag** + +The device is optimizing for lower energy usage in this mode. Sometimes called "Eco mode". + +**1.10.8.6. Vacation Tag** + +A mode suitable for use during vacations or other extended absences. + +**1.10.8.7. Min Tag** + +The mode uses the lowest available setting value. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 105 +``` + +**1.10.8.8. Max Tag** + +The mode uses the highest available setting value. + +**1.10.8.9. Night Tag** + +The mode is recommended or suitable for use during night time. + +**1.10.8.10. Day Tag** + +The mode is recommended or suitable for use during day time. + +**1.11. Low Power Cluster** + +This cluster provides an interface for managing low power mode on a device. + +This cluster would be supported on an endpoint that represents a physical device with a low power +mode. This cluster provides a sleep() command to allow clients to manually put the device into low +power mode. There is no command here to wake up a sleeping device because that operation often +involves other protocols such as Wake On LAN. Most devices automatically enter low power mode +based upon inactivity. + +The cluster server for Low Power is implemented by a device that supports a low power mode, such +as a TV, Set-top box, or Smart Speaker. + +### NOTE + +``` +We have considered a “DisableLowPowerMode” command but have not added it +due to suspected issues with energy consumption regulations. This can be added in +the future. +``` +**1.11.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**1.11.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint LOWPOWER +``` +**1.11.3. Cluster ID** + +``` +ID Name +0x0508 Low Power +``` +``` +Page 106 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.11.4. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Sleep client ⇒ server Y O M +``` +**1.11.4.1. Sleep Command** + +This command SHALL put the device into low power mode. + +**1.12. Wake On LAN Cluster** + +This cluster provides an interface for managing low power mode on a device that supports the +Wake On LAN or Wake On Wireless LAN (WLAN) protocol (see [Wake On LAN]). + +This cluster would be supported on IP devices that have a low power mode AND support the ability +to be woken up using the Wake on LAN or Wake on WLAN protocol. This cluster provides the +device MAC address which is a required input to the Wake on LAN protocol. Besides the MAC +address, this cluster provides an optional link-local IPv6 address which is useful to support "Wake +on Direct Packet" used by some Ethernet and Wi-Fi devices. + +Acting on the MAC address or link-local IPv6 address information does require the caller to be in +the same broadcast domain as the destination. To wake the destination up, the caller sends a multi­ +cast-based magic UDP packet that contains destination’s MAC address in the UDP payload to FF02::1, +the IPv6 all-nodes link-local multicast group address. If the optional link-local address is provided +by the destination through this cluster, the caller also sends the magic UDP packet in unicast to that +link-local address. This unicast-based method is particularly useful for Wi-Fi devices, since due to +lack of MAC layer retransmission mechanism, multicast over Wi-Fi is not as reliable as unicast. If a +device provides the link-local address in this cluster, its Ethernet controller or Wi-Fi radio SHALL +respond to the IPv6 neighbor solicitation message for the link-local address without the need to +wake host CPU up. In order to receive the magic or neighbor solicitation packets in multicast, the +Wi-Fi devices must support Group Temporal Key (GTK) rekey operation in low power mode. + +Most devices automatically enter low power mode based upon inactivity. + +The cluster server for Wake on LAN or Wake on WLAN is implemented by a device that supports +the Wake on LAN/WLAN protocol, such as a TV, Set-top Box, or Smart Speaker. + +**1.12.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**1.12.2. Classification** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 107 +``` + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint WAKEONLAN +``` +**1.12.3. Cluster ID** + +``` +ID Name +0x0503 Wake on LAN +``` +**1.12.4. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 MACAd­ +dress +``` +``` +string max 12 F R V O +``` +``` +0x0001 LinkLocal­ +Address +``` +``` +ipv6adr desc F R V O +``` +**1.12.4.1. MACAddress Attribute** + +This attribute SHALL indicate the current MAC address of the device. Only 48-bit MAC Addresses +SHALL be used for this attribute as required by the Wake on LAN protocol. + +Format of this attribute SHALL be an upper-case hex-encoded string representing the hex address, +like 12345678ABCD. + +**1.12.4.2. LinkLocalAddress Attribute** + +This attribute SHALL indicate the current link-local address of the device. Only 128-bit IPv6 link- +local addresses SHALL be used for this attribute. + +### NOTE + +``` +Some companies may consider MAC Address to be protected data subject to PII han­ +dling considerations and will therefore choose not to include it or read it. The MAC +Address can often be determined using ARP in IPv4 or NDP in IPv6. +``` +**1.13. Switch Cluster** + +This cluster exposes interactions with a switch device, for the purpose of using those interactions +by other devices. +Two types of switch devices are supported: latching switch (e.g. rocker switch) and momentary +switch (e.g. push button), distinguished with their feature flags. +Interactions with the switch device are exposed as attributes (for the latching switch) and as events +(for both types of switches). +An interested client MAY subscribe to these attributes/events and thus be informed of the interac­ +tions, and can perform actions based on this, for example by sending commands to perform an +action such as controlling a light or a window shade. + +``` +Page 108 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.13.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Behavior clarifications for ambiguous combina­ +tions of events; Introduction of TotalNumberOf­ +PressesCounted == 0 when MultiPressMax is +exceeded; Introduction of ActionSwitch feature +flag. +``` +**1.13.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint SWTCH +``` +**1.13.3. Cluster ID** + +``` +ID Name +0x003B Switch +``` +**1.13.4. Features** + +These feature flags SHALL be used to indicate the physics as well as the detection/reporting capabil­ +ities of the device represented by the cluster. + +``` +Bit Code Feature Conformance Summary +0 LS LatchingSwitch O.a Switch is latching +1 MS MomentarySwitch O.a Switch is momen­ +tary +2 MSR Momen­ +tarySwitchRelease +``` +``` +[MS & !AS] Switch supports +release events +generation +3 MSL Momen­ +tarySwitchLong­ +Press +``` +``` +[MS & (MSR | AS)] Switch supports +long press detec­ +tion +4 MSM Momen­ +tarySwitchMulti­ +Press +``` +``` +AS, [MS & MSR] Switch supports +multi-press detec­ +tion +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 109 +``` + +``` +Bit Code Feature Conformance Summary +5 AS ActionSwitch [MS] Switch is momen­ +tary, targeted at +specific user +actions (focus on +multi-press and +optionally long +press) with a +reduced event +generation +scheme +``` +**1.13.4.1. LatchingSwitch Feature** + +This feature flag is for a switch that maintains its position after being pressed (or turned). + +**1.13.4.2. MomentarySwitch Feature** + +This feature flag is for a switch that does not maintain its position after being pressed (or turned). +After releasing, it goes back to its idle position. + +**1.13.4.3. MomentarySwitchRelease Feature** + +This feature flag is for a momentary switch that can distinguish and report release events. + +**1.13.4.4. MomentarySwitchLongPress Feature** + +This feature flag is for a momentary switch that can distinguish and report long presses from short +presses. + +**1.13.4.5. MomentarySwitchMultiPress Feature** + +This feature flag is for a momentary switch that can distinguish and report double press and poten­ +tially multiple presses with more events, such as triple press, etc. + +**1.13.4.6. ActionSwitch Feature** + +This feature flag indicates simplified handling of events for multi-press-capable switches. See Multi +Press Details. + +**1.13.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Num­ +berOfPosi­ +tions +``` +``` +uint8 min 2 F 2 R V M +``` +``` +Page 110 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0001 Current­ +Position +``` +``` +uint8 max Num­ +berOfPosi­ +tions-1 +``` +### N 0 R V M + +``` +0x0002 Multi­ +PressMax +``` +``` +uint8 min 2 F 2 R V MSM +``` +**1.13.5.1. NumberOfPositions Attribute** + +This attribute SHALL indicate the maximum number of positions the switch has. Any kind of switch +has a minimum of 2 positions. Also see Multi Position Details for the case NumberOfPositions>2. + +**1.13.5.2. CurrentPosition Attribute** + +This attribute SHALL indicate the position of the switch. + +The valid range is zero to NumberOfPositions - 1. + +CurrentPosition value 0 SHALL be assigned to the default position of the switch: for example the +"open" state of a rocker switch, or the "idle" state of a push button switch. + +**1.13.5.3. MultiPressMax Attribute** + +This attribute SHALL indicate how many consecutive presses can be detected and reported by a +momentary switch which supports multi-press (MSM feature flag set). + +For example, a momentary switch supporting single press, double press and triple press, but not +quad press and beyond, would return the value 3. + +When more than MultiPressMax presses are detected within a multi-press sequence: + +- The server for cluster revision < 2 SHOULD generate a MultiPressComplete event with the Total­ + NumberOfPressesCounted field set to the value of the MultiPressMax attribute, and avoid gener­ + ating any further InitialPress and MultiPressOngoing events until the switch has become fully + idle (i.e. no longer in the process of counting presses within the multipress). +- The server for cluster revision >= 2 SHALL generate a MultiPressComplete event with the Total­ + NumberOfPressesCounted field set to zero (indicating an aborted sequence), and SHALL NOT + generate any further InitialPress and MultiPressOngoing events until the switch has become + fully idle (i.e. no longer in the process of counting presses within the multipress). + +This approach avoids unintentionally causing intermediate actions where there is a very long +sequence of presses beyond MultiPressMax that MAY be taken in account specially by switches (e.g. +to trigger special behavior such as factory reset for which generating events towards the client is +not appropriate). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 111 +``` + +**1.13.6. Events** + +``` +ID Name Priority Access Conformance +0x00 SwitchLatched INFO V LS +0x01 InitialPress INFO V MS +0x02 LongPress INFO V MSL +0x03 ShortRelease INFO V MSR +0x04 LongRelease INFO V MSL +0x05 MultiPressOngo­ +ing +``` +### INFO V MSM & !AS + +``` +0x06 MultiPressCom­ +plete +``` +### INFO V MSM + +**1.13.6.1. SwitchLatched Event** + +This event SHALL be generated, when the latching switch is moved to a new position. +It MAY have been delayed by debouncing within the switch. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NewPosi­ +tion +``` +``` +uint8 0 to Num­ +berOfPosi­ +tions-1 +``` +### M + +**1.13.6.1.1. NewPosition Field** + +This field SHALL indicate the new value of the CurrentPosition attribute, i.e. after the move. + +**1.13.6.2. InitialPress Event** + +This event SHALL be generated, when the momentary switch starts to be pressed (after debounc­ +ing). + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NewPosi­ +tion +``` +``` +uint8 0 to Num­ +berOfPosi­ +tions-1 +``` +### M + +**1.13.6.2.1. NewPosition Field** + +This field SHALL indicate the new value of the CurrentPosition attribute, i.e. while pressed. + +``` +Page 112 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.13.6.3. LongPress Event** + +This event SHALL be generated when the momentary switch has been pressed for a "long" time. +The time interval constituting a "long" time is manufacturer-determined, since it depends on the +switch physics. + +- When the AS feature flag is set, this event: + ◦ SHALL NOT be generated during a multi-press sequence (since a long press is a separate + cycle from any multi-press cycles); + ◦ SHALL only be generated after the first InitialPress following a MultiPressComplete when a + long press is detected after the idle time. +- Else, when the MSM feature flag is set, this event: + ◦ SHALL NOT be generated during a multi-press sequence (since a long press is a separate + cycle from any multi-press cycles); + ◦ SHALL only be generated after the first InitialPress following a MultiPressComplete when a + long press is detected after the idle time; + ◦ SHALL NOT be generated after a MultiPressOngoing event without an intervening Multi­ + PressComplete event. + +The above constraints imply that for a given activity detection cycle of a switch having MSM and/or +MSL feature flags set, the entire activity is either a single long press detection cycle of (InitialPress, +LongPress, LongRelease), or a single multi-press detection cycle (ending in MultiPressComplete), +where presses that would otherwise be reported as long presses are instead reported as a counted +press in the MultiPressComplete event, and as InitialPress/ShortRelease pairs otherwise (where +applicable). + +The rationale for this constraint is the ambiguity of interpretation of events when mixing long +presses and multi-press events. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NewPosi­ +tion +``` +``` +uint8 0 to Num­ +berOfPosi­ +tions-1 +``` +### M + +**1.13.6.3.1. NewPosition Field** + +This field SHALL indicate the new value of the CurrentPosition attribute, i.e. while pressed. + +**1.13.6.4. ShortRelease Event** + +If the server has the Action Switch (AS) feature flag set, this event SHALL NOT be generated at all, +since setting the Action Switch feature flag forbids the Momentary Switch ShortRelease (MSR) fea­ +ture flag from being set. Otherwise, the following paragraphs describe the situations where this +event is generated. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 113 +``` + +This event SHALL be generated, when the momentary switch has been released (after debouncing). + +- If the server has the Momentary Switch LongPress (MSL) feature flag set, then this event SHALL + be generated when the switch is released if **_no_** LongPress event had been generated since the + previous InitialPress event. +- If the server does not have the Momentary Switch LongPress (MSL) feature flag set, this event + SHALL be generated when the switch is released - even when the switch was pressed for a long + time. +- Also see Section 1.13.7, “Sequence of generated events”. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PreviousPo­ +sition +``` +``` +uint8 0 to Num­ +berOfPosi­ +tions-1 +``` +### M + +**1.13.6.4.1. PreviousPosition Field** + +This field SHALL indicate the previous value of the CurrentPosition attribute, i.e. just prior to +release. + +**1.13.6.5. LongRelease Event** + +This event SHALL be generated, when the momentary switch has been released (after debouncing) +and after having been pressed for a long time, i.e. this event SHALL be generated when the switch +is released if a LongPress event has been generated since the previous InitialPress event. Also see +Section 1.13.7, “Sequence of generated events”. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PreviousPo­ +sition +``` +``` +uint8 0 to Num­ +berOfPosi­ +tions-1 +``` +### M + +**1.13.6.5.1. PreviousPosition Field** + +This field SHALL indicate the previous value of the CurrentPosition attribute, i.e. just prior to +release. + +**1.13.6.6. MultiPressOngoing Event** + +If the server has the Action Switch (AS) feature flag set, this event SHALL NOT be generated at all. +Otherwise, the following paragraphs describe the situations where this event is generated. + +``` +Page 114 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +This event SHALL be generated to indicate how many times the momentary switch has been +pressed in a multi-press sequence, _during_ that sequence. See Multi Press Details below. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NewPosi­ +tion +``` +``` +uint8 0 to Num­ +berOfPosi­ +tions-1 +``` +### M + +``` +1 Current­ +NumberOf­ +Press­ +esCounted +``` +``` +uint8 2 to Multi­ +PressMax +``` +### M + +**1.13.6.6.1. NewPosition Field** + +This field SHALL indicate the new value of the CurrentPosition attribute, i.e. while pressed. + +**1.13.6.6.2. CurrentNumberOfPressesCounted Field** + +This field SHALL contain: + +- a value of 2 when the second press of a multi-press sequence has been detected, +- a value of 3 when the third press of a multi-press sequence has been detected, +- a value of N when the Nth press of a multi-press sequence has been detected. + +**1.13.6.7. MultiPressComplete Event** + +This event SHALL be generated to indicate how many times the momentary switch has been +pressed in a multi-press sequence, after it has been detected that the sequence has _ended_. See Multi +Press Details. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PreviousPo­ +sition +``` +``` +uint8 0 to Num­ +berOfPosi­ +tions-1 +``` +### M + +``` +1 TotalNum­ +berOfPress­ +esCounted +``` +``` +uint8 max Multi­ +PressMax +``` +### M + +The PreviousPosition field SHALL indicate the previous value of the CurrentPosition attribute, i.e. +just prior to release. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 115 +``` + +The TotalNumberOfPressesCounted field SHALL contain: + +- a value of 0 when there was an aborted multi-press sequence, where the number of presses + goes beyond MultiPressMax presses, +- a value of 1 when there was exactly one press in a multi-press sequence (and the sequence has + ended), i.e. there was no double press (or more), +- a value of 2 when there were exactly two presses in a multi-press sequence (and the sequence + has ended), +- a value of 3 when there were exactly three presses in a multi-press sequence (and the sequence + has ended), +- a value of N when there were exactly N presses in a multi-press sequence (and the sequence has + ended). + +### NOTE + +``` +The introduction of TotalNumberOfPressesCounted supporting the value 0 MAY +impact clients of switches using cluster revision 1 since such servers would not use +this value of TotalNumberOfPressesCounted to indicate an aborted sequence. +Clients SHOULD always act using the TotalNumberOfPressesCounted field taken +into account since for values from 1 to MultiPressMax, the user action that led to the +event was different depending on the count. +``` +**1.13.7. Sequence of generated events** + +This section describes the sequence of events that will be generated by three types of momentary +switches (distinguished by their feature flags). For each switch type, we will define the sequence of +generated events for these three interactions: + +1. Sequence for a switch which is pressed briefly. +2. Sequence for a switch pressed for a long time. +3. Sequence for a switch pressed for a very long time. + +In the three interactions described in the subsections below, if the NumberOfPositions attribute is +equal to 2, the InitialPress and LongPress events have the NewPosition field set to 1 and the Short­ +Release and LongRelease events have the PreviousPosition field set to 1. For larger values of the +NumberOfPositions attribute, see Multi Position Details. + +**1.13.7.1. Switches with long-press detection support (MSL feature flag set)** + +This switch (with feature flags MS & MSL both set) SHALL generate either a sequence of two or +three (depending on how long the switch is pressed) events for one interaction cycle, in the order +given below and illustrated in the figure below. + +- Upon a short press: + ◦ Generate InitialPress + ◦ If the MSR feature flag is set and the AS feature flag is NOT set, generate ShortRelease after + the previous event, when release is detected. + +``` +Page 116 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +◦ If the MSM feature flag is set, generate MultiPressComplete(1) after the previous event(s). +``` +- Upon a long press (or very long press): + ◦ Generate InitialPress + ◦ Generate LongPress after the previous event, when long press is detected + ◦ Generate LongRelease (and NOT MultiPressComplete(1)) after the previous event, when + switch release is detected. + +A LongPress event SHALL be generated exactly once for this case and SHALL NOT be repeated, irre­ +spective how long the switch is pressed. + +The image shows a time representation of the state of the switch (low=not pressed, high=pressed) +with the colored dots indicating the various events generated at that moment in time. + +_Figure 3. Switch device with MSL feature flag set (single press case)_ + +**1.13.7.2. Switches without long-press detection support (MSL feature flag not set)** + +This switch (with feature flags states MS & !MSL) SHALL NOT generate LongPress and LongRelease +events and therefore it SHALL generate a sequence of two events for one interaction cycle, irre­ +spective of how long the switch is pressed, in the order given and illustrated below, based on +whether the MSM, AS and MSR flags are set. + +- Any press length: + 1. Generate InitialPress + 2. If the MSR feature flag is set and the AS feature flag is NOT set, generate ShortRelease after + the previous event, when the release is detected. + 3. If the MSM feature flag is set, generate MultiPressComplete(1) after the previous event(s). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 117 +``` + +### NOTE + +``` +Even after a "long" period being pressed, the release event is never LongRelease. A +device without the MSL feature flag SHALL NOT generate the LongPress and Lon­ +gRelease events. +``` +_Figure 4. Switch device without MSL feature flag not set (single press case)_ + +**1.13.7.3. Switches with most basic MS-only feature flag set, not (MSR | MSL | MSM | AS)** + +This switch (with feature flags states MS & !MSR & !MSL & !MSM & !AS) SHALL generate a single Ini­ +tialPress event for one interaction cycle, irrespective of how long the switch is pressed, as illus­ +trated in the figure below. + +A device with this set of feature flags SHALL NOT generate any of the ShortRelease, LongPress and +LongRelease events. + +``` +Page 118 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 5. Switch device delivering only 'InitialPress' events (single press case)_ + +**1.13.8. Sequence of events for MultiPress** + +Multi-press detection is a feature of momentary switches (indicated with feature flag MSM being +set, with optional AS feature flag set) that they can count and report sequences of press-release +cycles within a certain time frame, for example to indicate that the user has pressed the switch +once, twice or three (or even more) times in succession. The definition of the time window for this +detection is manufacturer-specific since it depends on the switch physics. The maximum number of +presses which can be detected and reported SHALL be indicated in attribute MultiPressMax. The +minimum value and default value for MultiPressMax are both 2. + +A switch supporting MultiPress SHALL set feature flags MS & MSM, and MAY optionally, according +to conformance rules of each flag, set flags MSL, MSR, and AS. + +The ActionSwitch (AS) feature flag is a behavior selector which, when set, reduces the number of +events generated by the switch. + +A press cycle when MSM is set is **either** a long-press cycle (if MSL set), **or** a multi-press cycle. + +- If the MSL feature flag is set and the cycle is deemed "long" during the first press cycle after Ini­ + tialPress, then the switch SHALL react as described in Section 1.13.7.1, “Switches with long-press + detection support (MSL feature flag set)”, and SHALL NOT consider this to be the start of a + multi-press sequence (see penultimate case illustrated in Figure 7, “Switch device with MSM and + !AS feature flags (multi-press case)”). +- If the MSL feature flag is not set or if the first button press cycle is short, then the switch SHALL + count presses until the switch becomes sufficiently idle, and SHALL NOT generate LongPress + and LongRelease events for intermediate presses within the multi-press cycle that are "long". + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 119 +``` + +**1.13.8.1. Multi-press behavior when ActionsSwitch (AS) feature flag is not set** + +A switch with the MSM feature flag set but the AS flag unset: + +- SHALL generate an InitialPress event at the start of every button press within a button multi- + press cycle; +- SHALL generate a ShortRelease event at the end of every button press within a button multi- + press cycle if MSR is set; +- SHALL generate a MultiPressOngoing event after the InitialPress event of the second and subse­ + quent presses of a button multi-press cycle; +- SHALL generate a MultiPressComplete at the end of a multi-press cycle, including single + presses; +- SHALL NOT (for cluster revision >=2) or SHOULD NOT (for cluster revision <2) generate any + LongPress and LongRelease events within the multi-press cycle. + +The MultiPressOngoing event is provided for parties interested in keeping track of the actual +presses during the multi-press sequence. The MultiPressComplete event is provided for parties +interested in the outcome of the whole sequence: after the multi-press sequence has ended, they +will receive the MultiPressComplete event indicating how many times the switch was pressed. + +In the figure below, several sequences of user interaction are indicated: + +- Single press sequence: after the press and release moments, the InitialPress SHALL be gener­ + ated, and ShortRelease events SHALL be generated if the MSR feature flag is set. After some fur­ + ther time, when the switch has detected that there is no second press, it SHALL generate Multi­ + PressComplete(1) since it has detected that the sequence consisted of one press. No MultiPres­ + sOngoing event SHALL be generated for this case. +- Double press sequence: after each of the press and release moments, the InitialPress SHALL be + generated, and ShortRelease events SHALL be generated if the MSR feature flag is set. Addition­ + ally, when the switch is pressed for the second time, the MultiPressOngoing(2) event SHALL be + generated, as the switch has detected the second press. Note that this event coincides with the + second InitialPress event; both SHALL be generated. After some further time, when the switch + has detected that there is no third press, it SHALL generate MultiPressComplete(2) since it has + detected that the sequence consisted of two presses. +- Triple press sequence: after each press and release moments, the InitialPress SHALL be gener­ + ated, and ShortRelease events SHALL be generated if the MSR feature flag is set. Additionally, + when the switch is pressed for the second time, the MultiPressOngoing(2) event SHALL be gen­ + erated, as the switch has detected the second press. Note that this event coincides with the sec­ + ond InitialPress event; both SHALL be generated. Additionally, when the switch is pressed for + the third time, the MultiPressOngoing(3) event SHALL be generated, as the switch has detected + the third press. Note that this event coincides with the third InitialPress event; both SHALL be + generated. After some further time, when the switch has detected that there is no fourth press, + it SHALL generate MultiPressComplete(3) since it has detected that the sequence consisted of + three presses. + ◦ This case specifically does NOT generate LongPress and LongRelease events within the + sequence (even though the figure below illustrates a longer press duration for the second + +``` +Page 120 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +press in one of the cases), since multi-press sequences SHOULD/SHALL NOT generate Long­ +Press and LongRelease events within the sequence (see Section 1.13.6.3, “LongPress Event” +for more details). +``` +- N presses starting with a long press (if MSL feature flag is set): this starts with a long press + sequence wish SHALL be considered according to Section 1.13.7.1, “Switches with long-press + detection support (MSL feature flag set)”. Then it is a sequence similar to triple press, with N + presses instead of 3. + +For the above cases where multiple events need to be generated at the same time, the MultiPres­ +sOngoing event SHALL be generated directly after the InitialPress event. + +### NOTE + +``` +The numbers in parentheses in the bulleted text above and in the figure below indi­ +cate the value of the CurrentNumberOfPressesCounted resp. TotalNumberOfPress­ +esCounted field in the event data. +``` +### NOTE + +``` +As with the other figures, sufficient debounce time needs to be take into account for +the detection of press and release events. This is included in the figure, and has +been left out of the description above for readability, but SHALL be applied. +``` +### NOTE + +``` +Several of the events require very low congestion and latency in the final system to +be usable for real-time control and use cases. Care must be taken during design not +to rely on very low latency and real-time event timestamps if the low-latency +assumptions do not hold. +``` +_Figure 6. Switch device with MSM and !AS feature flags (multi-press case)_ + +**1.13.8.2. Multi-press behavior when ActionsSwitch (AS) feature flag is set** + +When the ActionSwitch feature flag is set, the behavior for all presses: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 121 +``` + +- The switch SHALL only generate an InitialPress event at the start of every button press cycle + (whether long or not); +- The switch SHALL NOT generate ShortRelease events; +- The switch SHALL NOT generate MultiPressOngoing events. + +Because of these simplifications, clients can decide to act purely on the following to determine user +action: + +- LongRelease (if MSL feature flag is set) to determine the end of a long press. + ◦ InitialPress and LongPress (if MSL feature flag is set), if needed, to detect the start of the + press and long-press periods so that actions such as "do action X while long pressed and stop + on release" can be supported. +- MultiPressComplete to determine the end of a series of presses (0 .. MultiPressMax) + ◦ Only the final count of presses detected by the switch is provided. + ◦ The value of 0 indicates an aborted press (e.g. maybe too many presses in a row, button held + down for too long, etc). + ◦ The value of 1 indicates a single press, 2 a double-press, etc. + +Because of the omission of ShortRelease, MultiPressOngoing and the "inner" InitialPress events, less +network traffic is generated, while not missing the overall "action" intent from the end-user. + +In the figure below, several sequences of user interaction are indicated: + +- Single press sequence: after the initial press detection, the InitialPress event is generated. After + some further time, when the switch has detected that there is no second press, and the press is + not a long press (if MSL feature flag is set), it generates the MultiPressComplete(1) event since it + has detected that the sequence consisted of one press. +- Double press sequence: after the initial press detection, the InitialPress event is generated. After + some further time, when the switch has detected that there is no third press, it generates the + MultiPressComplete(2) event since it has detected that the sequence consisted of two presses. +- N-press sequence: after the initial press detection, the InitialPress event is generated. Addition­ + ally, when the switch is pressed for the second time, we note that the press is long, but there is + not a LongPress or LongRelease event, since long presses inside (not at the start) of a multi-press + sequence are treated as short presses. After some further time, when the switch has detected + that there are no further presses beyond N presses, it generates a MultiPressComplete(N) event + since it has detected that the sequence consisted of N presses. +- Long press sequence followed by N-press sequence: + ◦ This case contains to two separate sequences, since a long press sequence is always an inde­ + pendent sequence, and does not get reported as "long" within multi-presses (see previous + example case). + ◦ The first sequence is a Long Press sequence of: InitialPress, LongPress, and finally, LongRe­ + lease. + ◦ The second sequence, whether immediate or not, is a N-press sequence of: InitialPress, and + finally, MultiPressComplete(N). + +``` +Page 122 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- N-press sequence with N > MultiPressMax: after the initial press detection, the InitialPress event + is generated. After some further time, when the switch has detected that there are no further + presses beyond N presses, it generates a MultiPressComplete(0) event since it has detected that + the multi-press sequence is done, but since there were more presses than MultiPressMax, the + sequence uses 0 for TotalNumberOfPressesCounted to indicate invalid complete sequence. + +_Figure 7. Switch device with MSM and !AS feature flags (multi-press case)_ + +**1.13.9. Summary of cases for MS feature flag** + +Given the variety of situations that may arise due to the different switch capabilities, the following +describes the edges that would unambiguously convey user action intents: + +- MS & !MSR & !MSM: Every action cycle is only a single InitialPress event. +- MS & !MSM: Every action cycle ends on ShortRelease or LongRelease (if MSL feature flag is set), + depending on long or short press and whether MSR/MSL feature flags are set. +- MS & MSM: Every action cycle ends on either LongRelease (if MSL feature flag is set and first + press was long) or MultiPressComplete. + ◦ The AS feature flag does not change the outcome of which events can be used for action + detection. + ◦ The AS feature flag is backwards-compatible with previous revisions of this cluster. + ◦ The AS feature flag primarily offers a reduction of events generated. + +The above list is relevant for the case of a client which does not use the events indicating progress +during the action cycle (i.e. ShortRelease, MultiPressOngoing, repeated InitialPress) for its opera­ +tion. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 123 +``` + +**1.13.10. Multi Position Details** + +This section will discuss some archetypes of switch devices with more than 2 positions and how +they SHALL set attribute values and generate events matching their characteristics. + +For the SwitchLatched, InitialPress, LongPress and MultiPressOngoing events, the field NewPosition +SHALL be set to the value corresponding to the new position to which the switch was moved. For +the ShortRelease, LongRelease and MultiPressComplete events, the field PreviousPosition SHALL be +set to the value corresponding to the position of the switch just preceding the (latest) release. + +**1.13.10.1. Latching Switch with N stable positions (N>2) with fixed sequence** + +With such a device, the user can move the switch from a position M to positions M-1 and M+1 +(either with a wraparound between the end positions, or fixed stop at the end positions). +On each interaction with the switch device, it SHALL generate a SwitchLatched event with the New­ +Position field set to the value associated with the new position. +Due to the physical constraints, such an event will have a NewPosition field which is equal to the +previous NewPosition field plus or minus 1 (modulo NumPositions if the switch does not have end +stops). + +In a first example, a switch has 3 positions, associated with values 0, 1 and 2. In this case, wrap­ +around is not possible: from position 0 it can only be moved to position 1. + +``` +pos A => report 0 +``` +``` +A B C A B C A B C +``` +``` +pos B => report 1 pos C => report 2 +``` +_Figure 8. Rotary switch device with 3 positions_ + +In another example, a switch has 8 positions, associated with values 0 through 7. In this case, the +physics of the switch allow wraparound: from position 0 it can be moved to position 1 or to position +7. + +``` +Page 124 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +0 +1 +``` +``` +2 +``` +``` +3 +4 +``` +``` +5 +``` +``` +6 +``` +``` +7 +``` +_Figure 9. Rotary switch device with 8 positions and wraparound_ + +**1.13.10.2. Latching Switch with N stable positions (N>2) with random sequence (example: +radio buttons)** + +With such a device, the user can press any of the available buttons, so this switch does not show the +incrementing or decrementing behavior of NewPosition which we discussed for the latching switch +with fixed sequence. In the example in the figure below, the 5 buttons are labeled "A" through "E" +for the user and are associated with values 0 through 4. The user first presses the "A" button, and +the switch device generates a SwitchLatched event with NewPosition set to 0. Then the user first +presses the "D" button, and the switch device generates a SwitchLatched event with NewPosition set +to 4. + +``` +button A pressed => report 0 +``` +``` +A B C D E +``` +``` +button D pressed => report 4 +``` +``` +A B C D E +``` +_Figure 10. Switch device with radio buttons_ + +**1.13.10.3. Momentary Switch with 2 or more non-stable positions** + +For a Momentary Switch with more than 1 stable position, it depends on the physics of the switch +device which sequence of events will be generated. + +### NOTE + +``` +In this section we will mention only the InitialPress and ShortRelease events. The +switch device could also generate the other events defined above for a momentary +switch, depending on the capabilities of the switch device and the interaction with +the switch device. +``` +The first variant (figure below, example: up/down control for window blinds) shows a switch in +neutral position (left figure) which corresponds to CurrentPosition=0. The user can press the top + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 125 +``` + +side (position value 1) or the bottom side (position value 2). It is not possible to go directly from +position 1 to position 2 or vice versa - the switch will always need to go through the neutral position +0. + +So when the user presses the top side of the switch, the InitialPress (NewPosition=1) event will be +generated. When they release the top side, the ShortRelease (PreviousPosition=1) event will be gen­ +erated. The user continues to press the bottom side, and the event InitialPress (NewPosition=2) is +generated. Upon release of the bottom side, the event ShortRelease (PreviousPosition=2) is gener­ +ated. + +``` +neutral position (0) top side pressed (1) bottom side pressed (2) +``` +_Figure 11. Up/down control switch device_ + +Another variant (figure below, example: joystick) has a control handle with a neutral position in the +middle (left figure) which corresponds to CurrentPosition=0. The handle can be moved along the +dotted lines. + +In the middle figure, the user moves the handle to the East position and then releases it (which +makes it return to the neutral middle position). This generates this sequence of events: + +``` +InitialPress (NewPosition=3) // move to East +ShortRelease (PreviousPosition=3) // back to middle (from East) +``` +In the righthand figure, the user moves the handle to the SouthWest position, then to the South +position and then releases it (which makes it return to the neutral middle position). This generates +this sequence of events: + +``` +InitialPress (NewPosition=6) // move to SouthWest +InitialPress (NewPosition=5) // move to South +ShortRelease (PreviousPosition=5) // back to middle (from South) +``` +``` +Page 126 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +1 2 +``` +``` +3 +``` +``` +6 5 4 +``` +``` +7 +``` +``` +8 +0 +``` +``` +1 2 +``` +``` +3 +``` +(^654) +7 +8 +0 +1 2 +3 +(^654) +7 +8 +0 +a +b +c +d +e +(i) no interaction, stick in middle position (ii) move to East and release (to middle) (iii) move to then release (to middle position)SouthWest, then to South, +_Figure 12. Switch device with joystick_ +Therefore, in the "joystick" variation, there could be a succession of InitialPress events without an +intermediate ShortRelease events - unlike the "window blinds control" variation which will always +have such an intermediate ShortRelease event. +**1.14. Operational State Cluster** +This cluster supports remotely monitoring and, where supported, changing the operational state of +any device where a state machine is a part of the operation. +This cluster defines common states, scoped to this cluster (e.g. Stopped, Running, Paused, Error). A +derived cluster specification may define more states scoped to the derivation. Manufacturer spe­ +cific states are supported in this cluster and any derived clusters thereof. When defined in a +derived instance, such states are scoped to the derivation. +Actual state transitions are dependent on both the implementation, and the requirements that may +additionally be imposed by a derived cluster. +An implementation that supports remotely starting its operation can make use of this cluster’s Start +command to do so. A device that supports remote pause or stop of its currently selected operation +can similarly make use of this cluster’s Pause and Stop commands to do so. The ability to remotely +pause or stop is independent of how the operation was started (for example, an operation started +by using a manual button press can be stopped by using a Stop command if the device supports +remotely stopping the operation). +Additionally, this cluster provides events for monitoring the operational state of the device. +**1.14.1. Revision History** +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. +**Revision Description** +1 Initial revision +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 127 + + +``` +Revision Description +2 The Pause and Resume commands are usable in +all compatible states. Define reserved ranges for +base/derived clusters. +3 Changed CountdownTime attribute to Q quality. +``` +**1.14.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint OPSTATE +``` +**1.14.3. Cluster ID** + +``` +ID Name +0x0060 Operational State +``` +**1.14.4. Data Types** + +**1.14.4.1. OperationalStateEnum Type** + +This type defines the set of known operational state values, and is derived from enum8. The follow­ +ing table defines the applicable ranges for values that are defined within this type. All values that +are undefined SHALL be treated as reserved. As shown by the table, states that may be specific to a +certain Device Type or other modality SHALL be defined in a derived cluster of this cluster. + +``` +Value Name Summary +0x00 to 0x3F GeneralStates Generally applicable values for +state, defined herein +0x40 to 0x7F DerivedClusterStates Derived Cluster defined states +0x80 to 0xBF ManufacturerStates Vendor specific states +``` +The derived cluster-specific state definitions SHALL NOT duplicate any general state definitions. +That is, a derived cluster specification of this cluster cannot define states with the same semantics +as the general states defined below. + +A manufacturer-specific state definition SHALL NOT duplicate the general state definitions or +derived cluster state definitions. That is, a manufacturer-defined state defined for this cluster or a +derived cluster thereof cannot define a state with the same semantics as the general states defined +below or states defined in a derived cluster. Such manufacturer-specific state definitions SHALL be +scoped in the context of the Vendor ID present in the Basic Information cluster. + +The following table defines the generally applicable states. + +``` +Page 128 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0x00 Stopped The device is stopped M +0x01 Running The device is operating M +0x02 Paused The device is paused +during an operation +``` +### M + +``` +0x03 Error The device is in an +error state +``` +### M + +**1.14.4.2. OperationalStateStruct Type** + +The OperationalStateStruct is used to indicate a possible state of the device. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Opera­ +tional­ +StateID +``` +``` +Operational­ +StateEnum +``` +``` +all 0 M +``` +``` +1 Opera­ +tionalState­ +Label +``` +``` +string max 64 desc +``` +**1.14.4.2.1. OperationalStateID Field** + +This SHALL be populated with a value from the OperationalStateEnum. + +**1.14.4.2.2. OperationalStateLabel Field** + +This field SHALL be present if the OperationalStateID is from the set reserved for Manufacturer +Specific States, otherwise it SHALL NOT be present. If present, this SHALL contain a human-read­ +able description of the operational state. + +**1.14.4.3. ErrorStateEnum Type** + +This type defines the set of known operational error values, and is derived from enum8. The follow­ +ing table defines the applicable ranges for values that are defined within this type. All values that +are undefined SHALL be treated as reserved. As shown by the table, errors that may be specific to a +certain Device Type or other modality SHALL be defined in a derived cluster of this cluster. + +``` +Value Name Summary +0x00 to 0x3F GeneralErrors Generally applicable values for +error, defined herein +0x40 to 0x7F DerivedClusterErrors Derived Cluster defined errors +0x80 to 0xBF ManufacturerError Vendor specific errors +``` +The derived cluster-specific error definitions SHALL NOT duplicate the general error definitions. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 129 +``` + +That is, a derived cluster specification of this cluster cannot define errors with the same semantics +as the general errors defined below. + +The manufacturer-specific error definitions SHALL NOT duplicate the general error definitions or +derived cluster-specific error definitions. That is, a manufacturer-defined error defined for this +cluster or a derived cluster thereof cannot define errors with the same semantics as the general +errors defined below or errors defined in a derived cluster. Such manufacturer-specific error defin­ +itions SHALL be scoped in the context of the Vendor ID present in the Basic Information cluster. + +The set of ErrorStateID field values defined in each of the generic or derived Operational State clus­ +ter specifications is called ErrorState. + +**1.14.4.3.1. ErrorStateEnum GeneralErrors Range** + +The following table defines the generally applicable ErrorState values. + +``` +Value Name Summary Conformance +0x00 NoError The device is not in an +error state +``` +### M + +``` +0x01 UnableToStartOrRe­ +sume +``` +``` +The device is unable to +start or resume opera­ +tion +``` +### M + +``` +0x02 UnableToCompleteOp­ +eration +``` +``` +The device was unable +to complete the current +operation +``` +### M + +``` +0x03 CommandInvalidIn­ +State +``` +``` +The device cannot +process the command +in its current state +``` +### M + +**1.14.4.4. ErrorStateStruct Type** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ErrorStateI +D +``` +``` +ErrorSta­ +teEnum +``` +``` +all 0 M +``` +``` +1 ErrorState­ +Label +``` +``` +string max 64 empty desc +``` +``` +2 ErrorStat­ +eDetails +``` +``` +string max 64 empty O +``` +**1.14.4.4.1. ErrorStateID Field** + +This SHALL be populated with a value from the ErrorStateEnum. + +``` +Page 130 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.14.4.4.2. ErrorStateLabel Field** + +This field SHALL be present if the ErrorStateID is from the set reserved for Manufacturer Specific +Errors, otherwise it SHALL NOT be present. If present, this SHALL contain a human-readable +description of the ErrorStateID; e.g. for a manufacturer specific ErrorStateID of "0x80" the +ErrorStateLabel MAY contain "My special error". + +**1.14.4.4.3. ErrorStateDetails Field** + +This SHALL be a human-readable string that provides details about the error condition. As an +example, if the ErrorStateID indicates that the device is a Robotic Vacuum that is stuck, the +ErrorStateDetails contains "left wheel blocked". + +**1.14.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 PhaseList list[string] max +32[max 64] +``` +### X MS R V M + +``` +0x0001 Current­ +Phase +``` +``` +uint8 desc X MS R V M +``` +``` +0x0002 Count­ +downTime +``` +``` +elapsed-s max +259200 +``` +``` +X Q null R V O +``` +``` +0x0003 Opera­ +tional­ +StateList +``` +``` +list[Opera­ +tionalStat­ +eStruct] +``` +``` +desc MS R V M +``` +``` +0x0004 Opera­ +tional­ +State +``` +``` +Opera­ +tionalSta­ +teEnum +``` +``` +all R V M +``` +``` +0x0005 Opera­ +tionalEr­ +ror +``` +``` +ErrorStat­ +eStruct +``` +``` +desc R V M +``` +**1.14.5.1. PhaseList Attribute** + +This attribute SHALL indicate a list of names of different phases that the device can go through for +the selected function or mode. The list may not be in sequence order. For example in a washing +machine this could include items such as "pre-soak", "rinse", and "spin". These phases are manufac­ +turer specific and may change when a different function or mode is selected. + +A null value indicates that the device does not present phases during its operation. When this +attribute’s value is null, the CurrentPhase attribute SHALL also be set to null. + +**1.14.5.2. CurrentPhase Attribute** + +This attribute represents the current phase of operation being performed by the server. This SHALL +be the positional index representing the value from the set provided in the PhaseList Attribute, + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 131 +``` + +where the first item in that list is an index of 0. Thus, this attribute SHALL have a maximum value +that is "length(PhaseList) - 1". + +This attribute SHALL be null if the PhaseList attribute is null or if the PhaseList attribute is an +empty list. + +**1.14.5.3. CountdownTime Attribute** + +This attribute SHALL represent the estimated time left before the operation is completed, in sec­ +onds. + +A value of 0 (zero) means that the operation has completed. + +A value of null represents that there is no time currently defined until operation completion. This +MAY happen, for example, because no operation is in progress or because the completion time is +unknown. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- If it has changed due to a change in the CurrentPhase or OperationalState attributes, or +- When it changes from 0 to any other value and vice versa, or +- When it changes from null to any other value and vice versa, or +- When it increases, or +- When there is any increase or decrease in the estimated time remaining that was due to pro­ + gressing insight of the server’s control logic, or +- When it changes at a rate significantly different from one unit per second. + +Changes to this attribute merely due to the normal passage of time with no other dynamic change +of device state SHALL NOT be reported. + +As this attribute is not being reported during a regular countdown, clients SHOULD NOT rely on the +reporting of this attribute in order to keep track of the remaining duration. + +**1.14.5.4. OperationalStateList Attribute** + +This attribute describes the set of possible operational states that the device exposes. An opera­ +tional state is a fundamental device state such as Running or Error. Details of the phase of a device +when, for example, in a state of Running are provided by the CurrentPhase attribute. + +All devices SHALL, at a minimum, expose the set of states matching the commands that are also +supported by the cluster instance, in addition to Error. The set of possible device states are defined +in the OperationalStateEnum. A device type requiring implementation of this cluster SHALL define +the set of states that are applicable to that specific device type. + +**1.14.5.5. OperationalState Attribute** + +This attribute specifies the current operational state of a device. This SHALL be populated with a +valid OperationalStateID from the set of values in the OperationalStateList Attribute. + +``` +Page 132 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.14.5.6. OperationalError Attribute** + +This attribute SHALL specify the details of any current error condition being experienced on the +device when the OperationalState attribute is populated with Error. Please see ErrorStateStruct for +general requirements on the population of this attribute. + +When there is no error detected, this SHALL have an ErrorStateID of NoError. + +**1.14.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Pause client ⇒ server Operational­ +Comman­ +dResponse +``` +``` +O Resume, O +``` +``` +0x01 Stop client ⇒ server Operational­ +Comman­ +dResponse +``` +``` +O Start, O +``` +``` +0x02 Start client ⇒ server Operational­ +Comman­ +dResponse +``` +### O O + +``` +0x03 Resume client ⇒ server Operational­ +Comman­ +dResponse +``` +``` +O Pause, O +``` +``` +0x04 Operational­ +Comman­ +dResponse +``` +``` +client ⇐ server N O Pause | Stop | +Start | Resume +``` +Note that it is entirely possible due to regulatory or other reasons for an instance of this cluster to +expose no possible commands. When that occurs, this cluster does not provide any ability to actu­ +ate the device, instead it provides readable (and by extension, can be subscribed to) information as +to the state of the device only. The commands that are supported SHALL be exposed by the device +in the AcceptedCommandList global attribute. + +**1.14.6.1. Pause Command** + +This command SHALL be supported if the device supports remotely pausing the operation. If this +command is supported, the Resume command SHALL also be supported. + +On receipt of this command, the device SHALL pause its operation if it is possible based on the cur­ +rent function of the server. For example, if it is at a point where it is safe to do so and/or permitted, +but can be restarted from the point at which pause occurred. + +If this command is received when already in the Paused state the device SHALL respond with an +OperationalCommandResponse command with an ErrorStateID of NoError but take no further +action. + +A device that receives this command in any state which is not Pause-compatible SHALL respond + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 133 +``` + +with an OperationalCommandResponse command with an ErrorStateID of CommandInvalidInState +and SHALL take no further action. + +States are defined as Pause-compatible as follows: + +- For states defined in this cluster specification, in Table 3, “Pause Compatibility”. +- For states defined by derived cluster specifications, in the corresponding specifications. +- For manufacturer-specific states, by the manufacturer. + +A device that is unable to honor the Pause command for whatever reason SHALL respond with an +OperationalCommandResponse command with an ErrorStateID of CommandInvalidInState but +take no further action. + +Otherwise, on success: + +- The OperationalState attribute SHALL be set to Paused. +- The device SHALL respond with an OperationalCommandResponse command with an + ErrorStateID of NoError. + +The following table defines the compatibility of this cluster’s states with the Pause command. + +_Table 3. Pause Compatibility_ + +``` +State Value State Name Pause-Compatible +0x00 Stopped N +0x01 Running Y +0x02 Paused Y +0x03 Error N +``` +**1.14.6.2. Stop Command** + +This command SHALL be supported if the device supports remotely stopping the operation. + +On receipt of this command, the device SHALL stop its operation if it is at a position where it is safe +to do so and/or permitted. Restart of the device following the receipt of the Stop command SHALL +require attended operation unless remote start is allowed by the device type and any jurisdiction +governing remote operation of the device. + +If this command is received when already in the Stopped state the device SHALL respond with an +OperationalCommandResponse command with an ErrorStateID of NoError but take no further +action. + +A device that is unable to honor the Stop command for whatever reason SHALL respond with an +OperationalCommandResponse command with an ErrorStateID of CommandInvalidInState but +take no further action. + +Otherwise, on success: + +- The OperationalState attribute SHALL be set to Stopped. + +``` +Page 134 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- The device SHALL respond with an OperationalCommandResponse command with an + ErrorStateID of NoError. + +**1.14.6.3. Start Command** + +This command SHALL be supported if the device supports remotely starting the operation. If this +command is supported, the 'Stop command SHALL also be supported. + +On receipt of this command, the device SHALL start its operation if it is safe to do so and the device +is in an operational state from which it can be started. There may be either regulatory or manufac­ +turer-imposed safety and security requirements that first necessitate some specific action at the +device before a Start command can be honored. In such instances, a device SHALL respond with a +status code of CommandInvalidInState if a Start command is received prior to the required on- +device action. + +If this command is received when already in the Running state the device SHALL respond with an +OperationalCommandResponse command with an ErrorStateID of NoError but take no further +action. + +A device that is unable to honor the Start command for whatever reason SHALL respond with an +OperationalCommandResponse command with an ErrorStateID of UnableToStartOrResume but +take no further action. + +Otherwise, on success: + +- The OperationalState attribute SHALL be set to Running. +- The device SHALL respond with an OperationalCommandResponse command with an + ErrorStateID of NoError. + +**1.14.6.4. Resume Command** + +This command SHALL be supported if the device supports remotely resuming the operation. If this +command is supported, the Pause command SHALL also be supported. + +On receipt of this command, the device SHALL resume its operation from the point it was at when +it received the Pause command, or from the point when it was paused by means outside of this clus­ +ter (for example by manual button press). + +If this command is received when already in the Running state the device SHALL respond with an +OperationalCommandResponse command with an ErrorStateID of NoError but take no further +action. + +A device that receives this command in any state which is not Resume-compatible SHALL respond +with an OperationalCommandResponse command with an ErrorStateID of CommandInvalidInState +and SHALL take no further action. + +States are defined as Resume-compatible as follows: + +- For states defined in this cluster specification, in Table 4, “Resume Compatibility”. +- For states defined by derived cluster specifications, in the corresponding specifications. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 135 +``` + +- For manufacturer-specific states, by the manufacturer. + +The following table defines the compatibility of this cluster’s states with the Resume command. + +_Table 4. Resume Compatibility_ + +``` +State Value State Name Resume-Compatible +0x00 Stopped N +0x01 Running Y +0x02 Paused Y +0x03 Error N +``` +A device that is unable to honor the Resume command for any other reason SHALL respond with +an OperationalCommandResponse command with an ErrorStateID of UnableToStartOrResume but +take no further action. + +Otherwise, on success: + +- The OperationalState attribute SHALL be set to the most recent non-Error operational state + prior to entering the Paused state. +- The device SHALL respond with an OperationalCommandResponse command with an + ErrorStateID of NoError. + +**1.14.6.5. OperationalCommandResponse Command** + +This command SHALL be supported by an implementation if any of the other commands defined by +this cluster are supported (i.e. listed in the AcceptedCommandList global attribute). This command +SHALL also be supported by an implementation of a derived cluster as a response to any com­ +mands that MAY be additionally defined therein. + +This command SHALL be generated in response to any of the Start, Stop, Pause, or Resume com­ +mands. The data for this command SHALL be as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0x00 Comman­ +dResponseS­ +tate +``` +``` +ErrorStat­ +eStruct +``` +``` +all M +``` +**1.14.6.5.1. CommandResponseState Field** + +This SHALL indicate the success or otherwise of the attempted command invocation. On a success­ +ful invocation of the attempted command, the ErrorStateID SHALL be populated with NoError. +Please see the individual command sections for additional specific requirements on population. + +**1.14.7. Events** + +``` +Page 136 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Priority Access Conformance +0x00 OperationalError CRITICAL V M +0x01 OperationCom­ +pletion +``` +### INFO V O + +**1.14.7.1. OperationalError Event** + +This event is generated when a reportable error condition is detected. A device that generates this +event SHALL also set the OperationalState attribute to Error, indicating an error condition. + +This event SHALL contain the following fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ErrorState ErrorStat­ +eStruct +``` +``` +all M +``` +**1.14.7.2. OperationCompletion Event** + +This event SHOULD be generated when the overall operation ends, successfully or otherwise. For +example, the completion of a cleaning operation in a Robot Vacuum Cleaner, or the completion of a +wash cycle in a Washing Machine. + +It is highly RECOMMENDED that appliances device types employing the Operational State cluster +support this event, even if it is optional. This assists clients in executing automations or issuing noti­ +fications at critical points in the device operation cycles. + +This event SHALL contain the following fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Completion­ +ErrorCode +``` +``` +enum8 all M +``` +``` +1 TotalOpera­ +tionalTime +``` +``` +elapsed-s all X O +``` +``` +2 PausedTime elapsed-s all X O +``` +**1.14.7.2.1. CompletionErrorCode Field** + +This field provides an indication of the state at the end of the operation. This field SHALL have a +value from the ErrorStateEnum set. A value of NoError indicates success, that is, no error has been +detected. + +**1.14.7.2.2. TotalOperationalTime Field** + +The total operational time, in seconds, from when the operation was started via an initial Start com­ +mand or autonomous/manual starting action, until the operation completed. This includes any time + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 137 +``` + +spent while paused. There may be cases whereby the total operational time exceeds the maximum +value that can be conveyed by this attribute, in such instances, this attribute SHALL be populated +with null. + +**1.14.7.2.3. PausedTime Field** + +The total time spent in the paused state, in seconds. There may be cases whereby the total paused +time exceeds the maximum value that can be conveyed by this attribute, in such instances, this +attribute SHALL be populated with null. + +**1.15. Alarm Base Cluster** + +This cluster is a base cluster from which clusters for particular alarms for a device type can be +derived. Each derivation SHALL define the values for the AlarmBitmap data type used in this clus­ +ter. Each derivation SHALL define which alarms are latched. + +**1.15.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**1.15.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint ALARM +``` +**1.15.3. Cluster ID** + +``` +ID Name +n/a Alarm Base +``` +**1.15.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 RESET Reset Supports the ability to +reset alarms +``` +**1.15.4.1. Reset Feature** + +This feature indicates that alarms can be reset via the Reset command. + +``` +Page 138 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.15.5. Data Types** + +**1.15.5.1. AlarmBitmap Type** + +This data type SHALL be a map32 with values defined by the derived cluster. The meaning of each +bit position SHALL be consistent for all attributes in a derived cluster. That is, if bit 0 is defined for +an alarm, the Latch, State, and Supported information for that alarm are also bit 0. + +**1.15.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Mask Alarm­ +Bitmap +``` +``` +all 0 R V M +``` +``` +0x0001 Latch Alarm­ +Bitmap +``` +``` +all F 0 R V RESET +``` +``` +0x0002 State Alarm­ +Bitmap +``` +``` +all 0 R V M +``` +``` +0x0003 Supported Alarm­ +Bitmap +``` +``` +all F 0 R V M +``` +**1.15.6.1. Mask Attribute** + +This attribute SHALL indicate a bitmap where each bit set in the Mask attribute corresponds to an +alarm that SHALL be enabled. + +**1.15.6.2. Latch Attribute** + +This attribute SHALL indicate a bitmap where each bit set in the Latch attribute SHALL indicate +that the corresponding alarm will be latched when set, and will not reset to inactive when the +underlying condition which caused the alarm is no longer present, and so requires an explicit reset +using the Reset command. + +**1.15.6.3. State Attribute** + +This attribute SHALL indicate a bitmap where each bit SHALL represent the state of an alarm. The +value of true means the alarm is active, otherwise the alarm is inactive. + +**1.15.6.4. Supported Attribute** + +This attribute SHALL indicate a bitmap where each bit SHALL represent whether or not an alarm is +supported. The value of true means the alarm is supported, otherwise the alarm is not supported. + +If an alarm is not supported, the corresponding bit in Mask, Latch, and State SHALL be false. + +**1.15.7. Commands** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 139 +``` + +``` +ID Name Direction Response Access Conformance +0x00 Reset client ⇒ server Y O RESET +0x01 ModifyEn­ +abledAlarms +``` +``` +client ⇒ server Y O O +``` +**1.15.7.1. Reset Command** + +This command resets active and latched alarms (if possible). Any generated Notify event SHALL +contain fields that represent the state of the server after the command has been processed. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Alarms Alarm­ +Bitmap +``` +``` +all 0 M +``` +**1.15.7.1.1. Alarms Field** + +This field SHALL indicate a bitmap where each bit set in this field corresponds to an alarm that +SHALL be reset to inactive in the State attribute unless the alarm definition requires manual inter­ +vention. If the alarms indicated are successfully reset, the response status code SHALL be SUCCESS, +otherwise, the response status code SHALL be FAILURE. + +**1.15.7.2. ModifyEnabledAlarms Command** + +This command allows a client to request that an alarm be enabled or suppressed at the server. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Mask Alarm­ +Bitmap +``` +``` +all 0 M +``` +**1.15.7.2.1. Mask Field** + +This field SHALL indicate a bitmap where each bit set in the this field corresponds to an alarm that +SHOULD be enabled or suppressed. A value of 1 SHALL indicate that the alarm SHOULD be enabled +while a value of 0 SHALL indicate that the alarm SHOULD be suppressed. + +A server that receives this command with a Mask that includes bits that are set for unknown +alarms SHALL respond with a status code of INVALID_COMMAND. + +A server that receives this command with a Mask that includes bits that are set for alarms which +are not supported, as indicated in the Supported attribute, SHALL respond with a status code of +INVALID_COMMAND. + +A server that is unable to enable a currently suppressed alarm, or is unable to suppress a currently +enabled alarm SHALL respond with a status code of FAILURE; otherwise the server SHALL respond +with a status code of SUCCESS. + +``` +Page 140 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +On a SUCCESS case, the server SHALL also change the value of the Mask attribute to the value of the +Mask field from this command. After that the server SHALL also update the value of its State +attribute to reflect the status of the new alarm set as indicated by the new value of the Mask +attribute. + +**1.15.8. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 Notify INFO V M +``` +**1.15.8.1. Notify Event** + +This event SHALL be generated when one or more alarms change state, and SHALL have these +fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 Active Alarm­ +Bitmap +``` +``` +all 0 M +``` +``` +2 Inactive Alarm­ +Bitmap +``` +``` +all 0 M +``` +``` +3 State Alarm­ +Bitmap +``` +``` +all 0 M +``` +``` +4 Mask Alarm­ +Bitmap +``` +``` +all 0 M +``` +**1.15.8.1.1. Active Field** + +This field SHALL indicate those alarms that have become active. + +**1.15.8.1.2. Inactive Field** + +This field SHALL indicate those alarms that have become inactive. + +**1.15.8.1.3. Mask Field** + +This field SHALL be a copy of the Mask attribute when this event was generated. + +**1.15.8.1.4. State Field** + +This field SHALL be a copy of the new State attribute value that resulted in the event being gener­ +ated. That is, this field SHALL have all the bits in Active set and SHALL NOT have any of the bits in +Inactive set. + +**1.16. Messages Cluster** + +This cluster provides an interface for passing messages to be presented by a device. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 141 +``` + +**1.16.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 Updated from SE1.4 version; CCB 1819 +3 Initial Matter release; renamed from Ener­ +gyMessaging to Messages +``` +**1.16.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint MESS +``` +**1.16.3. Cluster ID** + +``` +ID Name +0x0097 Messages +``` +**1.16.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 CONF ReceivedConfir­ +mation +``` +### O + +``` +1 RESP ConfirmationRe­ +sponse +``` +### [CONF] + +``` +2 RPLY ConfirmationRe­ +ply +``` +### [CONF] + +``` +3 PROT ProtectedMessages O +``` +**1.16.4.1. ReceivedConfirmation Feature** + +This feature SHALL indicate that the device can get confirmation from a user that the message was +received. + +**1.16.4.2. ConfirmationResponse Feature** + +This feature SHALL indicate that the device is capable of presenting a list of responses to the user +and recording the user’s choice of response. + +``` +Page 142 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.16.4.3. ConfirmationReply Feature** + +This feature SHALL indicate that the device is capable of collecting a free-form text response to a +message. + +**1.16.4.4. ProtectedMessages Feature** + +This feature SHALL indicate that the device is capable of requiring the user to authenticate before +viewing a message; e.g. entering a PIN or password before viewing a message with billing informa­ +tion. + +**1.16.5. Data Types** + +**1.16.5.1. MessageID Type** + +This data type is an octstr of fixed length 16, containing the binary encoding of a UUID as specified +in RFC 4122. + +**1.16.5.2. MessageControlBitmap Type** + +This data type is derived from map16, and indicates control information related to a message. + +``` +Bit Name Summary Conformance +0 ConfirmationRe­ +quired +``` +``` +Message requires con­ +firmation from user +``` +### CONF + +``` +1 ResponseRequired Message requires +response from user +``` +### RESP + +``` +2 ReplyMessage Message supports reply +message from user +``` +### RPLY + +``` +3 MessageConfirmed Message has already +been confirmed +``` +### CONF + +``` +4 MessageProtected Message required +PIN/password protec­ +tion +``` +### PROT + +**1.16.5.2.1. ConfirmationRequired Bit** + +This bit SHALL indicate that the message originator requests a confirmation of receipt by the user. +If confirmation is required, the device SHOULD present the message until it is either confirmed by +the user selecting a confirmation option, or the message expires. + +**1.16.5.2.2. ResponseRequired Bit** + +This bit SHALL indicate that a MessagePresented event SHOULD be generated based on the +response of the user to the message. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 143 +``` + +**1.16.5.2.3. ReplyMessage Bit** + +This bit SHALL indicate that a free-form user reply is to be included in the confirmation of receipt. + +**1.16.5.2.4. MessageConfirmed Bit** + +This bit SHALL indicate the current confirmation state of a message, which is useful in the event +that there are multiple Messages cluster client devices on a network. + +**1.16.5.2.5. MessageProtected Bit** + +This bit SHALL indicate that user authentication (e.g. by password or PIN) is required before view­ +ing a message. + +**1.16.5.3. FutureMessagePreferenceEnum Type** + +This data type is derived from enum8. + +A display device MAY include this preference in the MessageComplete event as a hint to clients +about how to handle future similar messages. + +``` +Value Name Summary Conformance +0 Allowed Similar messages are +allowed +``` +### M + +``` +1 Increased Similar messages +should be sent more +often +``` +### M + +``` +2 Reduced Similar messages +should be sent less +often +``` +### M + +``` +3 Disallowed Similar messages +should not be sent +``` +### M + +``` +4 Banned No further messages +should be sent +``` +### M + +**1.16.5.4. MessagePriorityEnum Type** + +This data type is derived from enum8. + +Priority SHOULD be used to decide which messages to show when the number of eligible messages +is larger than the device’s capacity to present them. + +``` +Value Name Summary Conformance +0 Low Message to be trans­ +ferred with a low level +of importance +``` +### M + +``` +Page 144 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +1 Medium Message to be trans­ +ferred with a medium +level of importance +``` +### M + +``` +2 High Message to be trans­ +ferred with a high level +of importance +``` +### M + +``` +3 Critical Message to be trans­ +ferred with a critical +level of importance +``` +### M + +**1.16.5.5. MessageStruct Type** + +This represents a single message. + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 MessageID MessageID all S M +1 Priority Mes­ +sagePriori­ +tyEnum +``` +### 0 S M + +``` +2 Message­ +Control +``` +``` +Message­ +Control­ +Bitmap +``` +### 0 S M + +``` +3 StartTime epoch-s X 0 S M +4 Duration uint64 all X 0 S M +5 Message­ +Text +``` +``` +string max 256 S M +``` +``` +6 Responses list[Mes­ +sageRe­ +sponseOp­ +tionStruct] +``` +``` +max 4 empty S RESP +``` +**1.16.5.5.1. MessageID Field** + +This field SHALL indicate a globally unique ID for this message. + +**1.16.5.5.2. Priority Field** + +This field SHALL indicate the priority level for this message. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 145 +``` + +**1.16.5.5.3. MessageControl Field** + +This field SHALL indicate control information related to the message. + +**1.16.5.5.4. StartTime Field** + +This field SHALL indicate the time in UTC at which the message becomes available to be presented. +A null value SHALL indicate "now." + +**1.16.5.5.5. Duration Field** + +This field SHALL indicate the amount of time, in milliseconds, after the StartTime during which the +message is available to be presented. A null value SHALL indicate "until changed". + +**1.16.5.5.6. MessageText Field** + +This field SHALL indicate a string containing the message to be presented. + +**1.16.5.5.7. Responses Field** + +This field SHALL indicate a list of potential responses to the message. The entries in this list SHALL +have unique values of MessageResponseID. + +If the ResponseRequired bit is set on the message but this list is empty, the device SHALL provide a +generic acknowledgement button, e.g. "OK". + +If the ResponseRequired bit is not set on the message, this list SHALL be ignored. + +**1.16.5.6. MessageResponseOptionStruct Type** + +This represents a possible response to a message. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Mes­ +sageRe­ +sponseID +``` +``` +uint32 min 1 M +``` +``` +1 Label string max 32 M +``` +**1.16.5.6.1. MessageResponseID Field** + +This field SHALL indicate a unique unsigned 32-bit number identifier for this message response +option. + +**1.16.5.6.2. Label Field** + +This field SHALL indicate the text for this option; e.g. "Yes", "No", etc. + +**1.16.6. Attributes** + +``` +Page 146 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Messages list[Mes­ +sageStruct] +``` +``` +max 8 empty R V F M +``` +``` +0x0001 ActiveMes +sageIDs +``` +``` +list[Mes­ +sageID] +``` +``` +max 8 empty R V M +``` +**1.16.6.1. Messages Attribute** + +This attribute SHALL indicate a list of queued messages. + +In addition to filtering based upon fabric, to preserve user privacy, the server MAY further limit the +set of messages returned in a read request. At minimum, the server SHALL return to a client those +messages that the client itself created/submitted. + +**1.16.6.2. ActiveMessageIDs Attribute** + +This attribute SHALL indicate a list of the MessageIDs of the Messages currently being presented. If +this list is empty, no messages are currently being presented. + +This list SHALL NOT be fabric-scoped; it SHALL contain MessageIDs for all Messages being pre­ +sented, no matter what fabric the client that queued them is on. + +**1.16.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 PresentMes­ +sagesRequest +``` +``` +client ⇒ server Y O F M +``` +``` +0x01 CancelMes­ +sagesRequest +``` +``` +client ⇒ server Y O F M +``` +**1.16.7.1. PresentMessagesRequest Command** + +Upon receipt, this SHALL cause the message in the passed fields to be appended to the Messages +attribute. + +If appending the message would cause the number of messages to be greater than the capacity of +the list, the device SHALL NOT append any message to Messages, and SHALL return a status code of +RESOURCE_EXHAUSTED. + +When displaying a message in response to this command, an indication (ex. visual) of the origin +node of the command SHALL be provided. This could be in the form of a friendly name label which +uniquely identifies the node to the user. This friendly name label is typically assigned by the Matter +Admin at the time of commissioning and, when it’s a device, is often editable by the user. It might +be a combination of a company name and friendly name, for example, ”Acme” or “Acme Streaming +Service on Alice’s Phone”. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 147 +``` + +### NOTE + +``` +It is currently not specified where the friendly name label can be found on the +node, meaning that clients SHOULD NOT rely on a certain method they happen to +observe in a particular server instance, since other instances could employ a differ­ +ent method. +``` +The device SHOULD make it possible for the user to view which nodes have access to this cluster +and to individually remove privileges for each node. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 MessageID MessageID all M +1 Priority MessagePri­ +orityEnum +``` +### 0 M + +``` +2 Message­ +Control +``` +``` +MessageCon­ +trolBitmap +``` +### 0 M + +``` +3 StartTime epoch-s X 0 M +4 Duration uint64 all X 0 M +5 Message­ +Text +``` +``` +string max 256 M +``` +``` +6 Responses list[Mes­ +sageRespon­ +seOption­ +Struct] +``` +``` +max 4 empty RESP +``` +**1.16.7.1.1. MessageID Field** + +This field SHALL indicate a globally unique ID for this message. See MessageID. + +**1.16.7.1.2. Priority Field** + +This field SHALL indicate the priority level for this message. See Priority. + +**1.16.7.1.3. MessageControl Field** + +This field SHALL indicate control information related to the message. See MessageControl. + +**1.16.7.1.4. StartTime Field** + +This field SHALL indicate the time in UTC at which the message becomes available to be presented. +A null value SHALL indicate "now." See StartTime. + +**1.16.7.1.5. Duration Field** + +This field SHALL indicate the amount of time, in milliseconds, after the StartTime during which the +message is available to be presented. A null value SHALL indicate "until changed". See Duration. + +``` +Page 148 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.16.7.1.6. MessageText Field** + +This field SHALL indicate a string containing the message to be presented. See MessageText. + +**1.16.7.1.7. Responses Field** + +This field SHALL indicate a list of potential responses to the message. The entries in this list SHALL +have unique values of MessageResponseID. + +If the ResponseRequired bit is set on the message but this list is empty, the device SHALL provide a +generic acknowledgement button, e.g. "OK". + +If the ResponseRequired bit is not set on the message, this list SHALL be ignored. + +See Responses. + +**1.16.7.2. CancelMessagesRequest Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 MessageIDs list[Mes­ +sageID] +``` +``` +max 8 M +``` +**1.16.7.2.1. MessageIDs Field** + +This field SHALL indicate the MessageIDs for the messages being cancelled. + +Cancelling a message SHALL cause it to be removed from Messages, cause its MessageID to be +removed from ActiveMessageIDs and cause any active presentation of the message to cease. + +Message IDs in this command that indicate messages that do not exist in Messages, or that are not +scoped to the fabric of the sender, SHALL be ignored. + +**1.16.8. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 Message­ +Queued +``` +### INFO V M + +``` +0x01 MessagePre­ +sented +``` +### INFO V M + +``` +0x02 MessageCom­ +plete +``` +### INFO V M + +**1.16.8.1. MessageQueued Event** + +This event SHALL be generated when a message is added to the messages attribute. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 149 +``` + +``` +Access Quality: Fabric-Sensitive +ID Name Type Constraint Quality Default Confor­ +mance +0 MessageID MessageID M +``` +**1.16.8.1.1. MessageID Field** + +This field SHALL indicate the MessageID for newly added message. + +**1.16.8.2. MessagePresented Event** + +This event SHALL be generated when the message is presented to the user. + +``` +Access Quality: Fabric-Sensitive +ID Name Type Constraint Quality Default Confor­ +mance +0 MessageID MessageID M +``` +**1.16.8.2.1. MessageID Field** + +This field SHALL indicate the MessageID for the message being presented. + +**1.16.8.3. MessageComplete Event** + +This event SHALL be generated when the message is confirmed by the user, or when the Duration +of the message has elapsed without confirmation. + +``` +Access Quality: Fabric-Sensitive +ID Name Type Constraint Quality Default Confor­ +mance +0 MessageID MessageID M +1 ResponseID uint32 all X null RESP +2 Reply string max 256 X null RPLY +3 FutureMes­ +sagesPrefer­ +ence +``` +``` +FutureMes­ +sagePrefer­ +enceEnum +``` +``` +all X null M +``` +**1.16.8.3.1. MessageID Field** + +This field SHALL indicate the MessageID for the message being confirmed. + +**1.16.8.3.2. ResponseID Field** + +This field SHALL indicate the MessageResponseID selected by the user. If there was no response +before the Duration of the message has elapsed, this field SHALL be null. + +``` +Page 150 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**1.16.8.3.3. Reply Field** + +This field SHALL indicate a user-provided reply to the message. If there was no reply, or the mes­ +sage did not have the ReplyRequired bit set, this field SHALL be null. + +**1.16.8.3.4. FutureMessagesPref Field** + +This field SHALL indicate a user-provided preference for the delivery of similar messages in the +future. A null value SHALL indicate no change in preference. + +**1.17. Service Area Cluster** + +This cluster provides an interface for controlling the areas where a device should operate, for +reporting the status at each area, and for querying the current area. + +The device MAY operate at one area at a time, as in the case of a mobile device, such as a robot. +Other devices MAY operate at (service) multiple areas simultaneously, as in the case of a sensor that +can monitor multiple areas. This cluster specification uses the term "operate" to describe both the +operating and servicing actions, regardless of the device type. + +The cluster allows the client to select one or more areas on the server, to indicate where the device +SHOULD attempt to operate. An area is one of a list of options that MAY be presented by a client for +a user choice, or understood by the client, via the semantic data of the area. + +The area semantic data is a combination of semantic tags, indicating one or more of the following: +the building floor, area type, landmark, and relative position. + +**1.17.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**1.17.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint SEAR +``` +**1.17.3. Cluster ID** + +``` +ID Name +0x0150 Service Area +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 151 +``` + +**1.17.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 SELRUN SelectWhileRunning The device allows +changing the selected +areas while running +1 PROG ProgressReporting The device implements +the progress reporting +feature +2 MAPS Maps The device has map +support +``` +**1.17.4.1. SelectWhileRunning Feature** + +This feature indicates whether this device allows changing the selected areas, by using the SelectAr­ +eas command, while operating. + +**1.17.5. Data Types** + +**1.17.5.1. LandmarkInfoStruct Type** + +The data from this structure indicates a landmark and position relative to the landmark. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Land­ +markTag +``` +``` +tag all M +``` +``` +1 Relative­ +Position­ +Tag +``` +``` +tag all X M +``` +**1.17.5.1.1. LandmarkTag Field** + +This field SHALL indicate that the area is associated with a landmark. + +This field SHALL be the ID of a landmark semantic tag, located within the Common Landmark +Namespace. For example, this tag MAY indicate that the area refers to an area next to a table. + +**1.17.5.1.2. RelativePositionTag Field** + +This field SHALL identify the position of the area relative to a landmark. This is a static description +of a zone known to the server, and this field never reflects the device’s own proximity or position +relative to the landmark, but that of the zone. + +This field SHALL be the ID of a relative position semantic tag, located within the Common Relative +Position Namespace. + +``` +Page 152 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +If the RelativePositionTag field is null, this field indicates proximity to the landmark. Otherwise, the +RelativePositionTag field indicates the position of the area relative to the landmark indicated by the +LandmarkTag field. For example, this tag, in conjunction with the LandmarkTag field, MAY indicate +that the area refers to a zone under a table. + +**1.17.5.2. AreaInfoStruct Type** + +The data from this structure indicates the name and/or semantic data describing an area, as +detailed below. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Location­ +Info +``` +``` +location­ +desc +``` +``` +all X M +``` +``` +1 Land­ +markInfo +``` +``` +Landmark­ +InfoStruct +``` +``` +all X M +``` +This data type includes the LocationInfo field, with the following fields: LocationName, FloorNum­ +ber, AreaType. Additional semantic data MAY be available in the LandmarkInfo field. + +For an area description to be meaningful, it SHALL have at least one of the following: + +- a non-empty name (LocationInfo’s LocationName field) + +OR + +- some semantic data (one or more of these: FloorNumber, AreaType or LandmarkTag) + +The normative text from the remainder of this section describes these constraints. + +If the LocationInfo field is null, the LandmarkInfo field SHALL NOT be null. + +If the LandmarkInfo field is null, the LocationInfo field SHALL NOT be null. + +If LocationInfo is not null, and its LocationName field is an empty string, at least one of the follow­ +ing SHALL NOT be null: + +- LocationInfo’s FloorNumber field +- LocationInfo’s AreaType field +- LandmarkInfo field + +If all three of the following are null, LocationInfo’s LocationName field SHALL NOT be an empty +string: + +- LocationInfo’s FloorNumber field +- LocationInfo’s AreaType field +- LandmarkInfo field + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 153 +``` + +**1.17.5.2.1. LocationInfo Field** + +This field SHALL indicate the name of the area, floor number and/or area type. + +A few examples are provided below. + +- An area can have LocationInfo’s LocationName field set to "blue room", and the AreaType field + set to the ID of a "Living Room" semantic tag. Clients wishing to direct the device to operate in + (or service) the living room can use this area. +- An area can have LocationInfo set to null, the LandmarkInfo’s LandmarkTag field set to the ID + of the "Table" landmark semantic tag, and the RelativePositionTag field set to the ID of the + "Under" position semantic tag. With such an area indication, the client can request the device to + operate in (or service) the area located under the table. + +**1.17.5.2.2. LandmarkInfo Field** + +This field SHALL indicate an association with a landmark. A value of null indicates that the infor­ +mation is not available or known. For example, this may indicate that the area refers to a zone next +to a table. + +If this field is not null, that indicates that the area is restricted to the zone where the landmark is +located, as indicated by the LandmarkTag and, if not null, by the RelativePositionTag fields, rather +than to the entire room or floor where the landmark is located, if those are indicated by the Loca­ +tionInfo field. + +**1.17.5.3. MapStruct Type** + +This is a struct representing a map. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 MapID uint32 MS M +1 Name string max 64 MS M +``` +**1.17.5.3.1. MapID Field** + +This field SHALL represent the map’s identifier. + +**1.17.5.3.2. Name Field** + +This field SHALL represent a human understandable map description. + +For example: "Main Floor", or "Second Level". + +**1.17.5.4. AreaStruct Type** + +This is a struct representing an area known to the server. + +``` +Page 154 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 AreaID uint32 MS M +1 MapID uint32 desc X MS M +2 AreaInfo AreaInfoS­ +truct +``` +### MS M + +**1.17.5.4.1. AreaID Field** + +This field SHALL represent the identifier of the area. + +**1.17.5.4.2. MapID Field** + +This field SHALL indicate the map identifier which the area is associated with. A value of null indi­ +cates that the area is not associated with a map. + +If the SupportedMaps attribute is not empty, this field SHALL match the MapID field of an entry +from the SupportedMaps attribute’s list. If the SupportedMaps attribute is empty, this field SHALL +be null. + +**1.17.5.4.3. AreaInfo Field** + +This field SHALL contain data describing the area. + +This SHOULD be used by clients to determine the name and/or the full, or the partial, semantics of a +certain area. + +### NOTE + +``` +If any entries on the SupportedAreas attribute’s list have the AreaInfo field missing +the semantic data, the client MAY remind the user to assign the respective data. +``` +**1.17.5.5. ProgressStruct Type** + +This is a struct indicating the progress. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 AreaID uint32 MS M +1 Status Opera­ +tionalSta­ +tusEnum +``` +### MS M + +``` +2 TotalOper­ +ational­ +Time +``` +``` +elapsed-s X MS O +``` +``` +3 Initial­ +TimeEsti­ +mate +``` +``` +elapsed-s X MS O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 155 +``` + +**1.17.5.5.1. AreaID Field** + +This field SHALL indicate the identifier of the area, and the identifier SHALL be an entry in the Sup­ +portedAreas attribute’s list. + +**1.17.5.5.2. Status Field** + +This field SHALL indicate the operational status of the device regarding the area indicated by the +AreaID field. + +**1.17.5.5.3. TotalOperationalTime Field** + +This field SHALL indicate the total operational time, in seconds, from when the device started to +operate at the area indicated by the AreaID field, until the operation finished, due to completion or +due to skipping, including any time spent while paused. + +A value of null indicates that the total operational time is unknown. + +There MAY be cases where the total operational time exceeds the maximum value that can be con­ +veyed by this attribute, and in such instances this attribute SHALL be populated with null. + +This attribute SHALL be null if the Status field is not set to Completed or Skipped. + +**1.17.5.5.4. InitialTimeEstimate Field** + +This field SHALL indicate the estimated time for the operation, in seconds, from when the device +will start operating at the area indicated by the AreaID field, until the operation completes, exclud­ +ing any time spent while not operating in the area. + +A value of null indicates that the estimated time is unknown. If the estimated time is unknown, or if +it exceeds the maximum value that can be conveyed by this attribute, this attribute SHALL be null. + +After initializing the ProgressStruct instance, the server SHOULD NOT change the value of this field, +except when repopulating the entire instance, to avoid excessive reporting of the Progress attribute +changes. + +**1.17.5.6. OperationalStatusEnum Type** + +This data type is derived from enum8. + +The following table defines the status values. + +``` +Value Name Summary Conformance +0x00 Pending The device has not yet +started operating at the +given area, or has not +finished operating at +that area but it is not +currently operating at +the area +``` +### M + +``` +Page 156 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0x01 Operating The device is currently +operating at the given +area +``` +### M + +``` +0x02 Skipped The device has skipped +the given area, before +or during operating at +it, due to a SkipArea +command, due an out +of band command (e.g. +from the vendor’s +application), due to a +vendor specific reason, +such as a time limit +used by the device, or +due the device ending +operating unsuccess­ +fully +``` +### M + +``` +0x03 Completed The device has com­ +pleted operating at the +given area +``` +### M + +**1.17.5.6.1. SelectAreasStatus Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x00 Success Attempting to operate +in the areas identified +by the entries of the +NewAreas field is +allowed and possible. +The SelectedAreas +attribute is set to the +value of the NewAreas +field. +``` +### M + +``` +0x01 UnsupportedArea The value of at least +one of the entries of the +NewAreas field doesn’t +match any entries in +the SupportedAreas +attribute. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 157 +``` + +``` +Value Name Summary Conformance +0x02 InvalidInMode The received request +cannot be handled due +to the current mode of +the device. +``` +### M + +``` +0x03 InvalidSet The set of values is +invalid. For example, +areas on different +floors, that a robot +knows it can’t reach on +its own. +``` +### M + +**1.17.5.6.2. SkipAreaStatus Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x00 Success Skipping the area is +allowed and possible, +or the device was oper­ +ating at the last avail­ +able area and has +stopped. +``` +### M + +``` +0x01 InvalidAreaList The SelectedAreas +attribute is empty. +``` +### M + +``` +0x02 InvalidInMode The received request +cannot be handled due +to the current mode of +the device. For exam­ +ple, the CurrentArea +attribute is null or the +device is not operating. +``` +### M + +``` +0x03 InvalidSkippedArea The SkippedArea field +doesn’t match an entry +in the SupportedAreas +list. +``` +### M + +**1.17.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edAreas +``` +``` +list[AreaS­ +truct] +``` +``` +max 255 MS R V M +``` +``` +Page 158 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0001 Support­ +edMaps +``` +``` +list[Map­ +Struct] +``` +``` +max 255 MS R V MAPS +``` +``` +0x0002 SelectedA +reas +``` +``` +list[uint32] desc empty R V M +``` +``` +0x0003 Cur­ +rentArea +``` +``` +uint32 desc X null R V desc +``` +``` +0x0004 Estimate­ +dEndTime +``` +``` +epoch-s X Q null R V [Cur­ +rentArea] +0x0005 Progress list[Pro­ +gressStruct +] +``` +``` +max 255 empty R V PROG +``` +**1.17.6.1. SupportedAreas Attribute** + +This attribute SHALL contain the list of areas that can be included in the SelectedAreas attribute’s +list. Each item in this list represents a unique area, as indicated by the AreaID field of AreaStruct. + +Each entry in this list SHALL have a unique value for the AreaID field. + +If the SupportedMaps attribute is not empty, each entry in this list SHALL have a unique value for +the combination of the MapID and AreaInfo fields. + +If the SupportedMaps attribute is empty, each entry in this list SHALL have a unique value for the +AreaInfo field and SHALL have the MapID field set to null. + +An empty value indicates that the device is currently unable to provide the list of supported areas. + +### NOTE + +``` +due to the maximum size of this list and to the fact that the entries MAY include +strings (see LocationName), care must be taken by implementers to avoid creating a +data structure that is overly large, which can result in significant latency in access­ +ing this attribute. +``` +The value of this attribute MAY change at any time via an out-of-band interaction outside of the +server, such as interactions with a user interface, or due to internal device changes. + +When removing entries in the SupportedAreas attribute list the server SHALL adjust the values of +the SelectedAreas, CurrentArea, and Progress attributes such that they only reference valid entries +in the updated SupportedAreas attribute list. These changes to the SelectedAreas, CurrentArea, and +Progress attributes MAY result in the server setting some or all of them to empty (for SelectedAreas +and Progress) or null (for CurrentArea), or updating them with data that matches the constraints +from the description of the respective attributes. These actions are required to ensure having a con­ +sistent representation of the maps and locations available to the clients. + +The SupportedAreas attribute list changes mentioned above SHOULD NOT be allowed while the +device is operating, to reduce the impact on the clients, and the potential confusion for the users. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 159 +``` + +A few examples are provided below. + +Valid list of areas: + +- AreaID=0, LocationName="yellow bedroom", MapID=null +- AreaID=1, LocationName="orange bedroom", MapID=null + +Valid list of areas: + +- AreaID=5, LocationName="hallway", MapID=1 +- AreaID=3, LocationName="hallway", MapID=2 + +**1.17.6.2. SupportedMaps Attribute** + +This attribute SHALL contain the list of supported maps. + +A map is a full or a partial representation of a home, known to the device. For example: + +- a single level home MAY be represented using a single map +- a two level home MAY be represented using two maps, one for each level +- a single level home MAY be represented using two maps, each including a different set of + rooms, such as "map of living room and kitchen" and "map of bedrooms and hallway" +- a single level home MAY be represented using one map for the indoor areas (living room, bed­ + rooms etc.) and one for the outdoor areas (garden, swimming pool etc.) + +Each map includes one or more areas - see the SupportedAreas attribute. In the context of this clus­ +ter specification, a map is effectively a group label for a set of areas, rather than a graphical repre­ +sentation that the clients can display to the users. The clients that present the list of available areas +for user selection (see the SelectAreas command) MAY choose to filter the SupportedAreas list based +on the associated map. For example, the clients MAY allow the user to indicate that the device is to +operate on the first floor, and allow the user to choose only from the areas situated on that level. + +If empty, that indicates that the device is currently unable to provide this information. + +Each entry in this list SHALL have a unique value for the MapID field. + +Each entry in this list SHALL have a unique value for the Name field. + +### NOTE + +``` +due to the maximum size of this list and to the fact that the entries MAY include +strings (see the Name field of the MapStruct data type), care must be taken by imple­ +menters to avoid creating a data structure that is overly large, which can result in +significant latency in accessing this attribute. +``` +The value of this attribute MAY change at any time via an out-of-band interaction outside of the +server, such as interactions with a user interface. + +When updating the SupportedMaps attribute list by deleting entries, or by setting the attribute to an +empty list, the SupportedLocations attribute SHALL be updated such that all entries in that list meet +the constraints indicated in the description of the SupportedLocations attribute. This MAY result in + +``` +Page 160 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +the server removing entries from the SupportedAreas attribute list. See the SupportedAreas +attribute description for the implications of changing that attribute. + +The SupportedMaps attribute list changes mentioned above SHOULD NOT be allowed while the +device is operating, to reduce the impact on the clients, and the potential confusion for the users. + +**1.17.6.3. SelectedAreas Attribute** + +This attribute SHALL indicate the set of areas where the device SHOULD attempt to operate. + +The mobile devices MAY travel without operating across any areas while attempting to reach the +areas indicated by the SelectedAreas attribute. For example, a robotic vacuum cleaner MAY drive +without cleaning when traveling without operating. + +If this attribute is empty, the device is not constrained to operate in any specific areas. + +If this attribute is not empty: + +- each item in this list SHALL match the AreaID field of an entry in the SupportedAreas attribute’s + list +- each entry in this list SHALL have a unique value + +**1.17.6.4. CurrentArea Attribute** + +If the device is mobile, this attribute SHALL indicate the area where the device is currently located, +regardless of whether it is operating or not, such as while traveling between areas. + +If the device is not mobile and can operate at multiple areas sequentially, this attribute SHALL indi­ +cate the area which is currently being serviced, or the area which is currently traversed by the +device. For example, a camera device MAY use this attribute to indicate which area it currently +takes video of (serviced area) or which area it currently has in view but not taking video of (e.g. an +area which is traversed while panning). + +### NOTE + +``` +A device MAY traverse an area regardless of the status of the area (pending, +skipped, or completed). +``` +If a device can simultaneously operate at multiple areas, such as in the case of a sensor that can +monitor multiple areas at the same time, the CurrentArea attribute SHALL NOT be implemented, +since it doesn’t apply. Else this attribute SHALL be optionally implemented. + +A null value indicates that the device is currently unable to provide this information. For example, +the device is traversing an unknown area, or the SupportedAreas attribute was updated and the +area where the device is located was removed from that list. + +If not null, the value of this attribute SHALL match the AreaID field of an entry on the SupportedAr­ +eas attribute’s list. + +**1.17.6.5. EstimatedEndTime Attribute** + +This attribute SHALL represent the estimated Epoch time for completing operating at the area indi­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 161 +``` + +cated by the CurrentArea attribute, in seconds. + +A value of 0 means that the operation has completed. + +When this attribute is null, that represents that there is no time currently defined until operation +completion. This MAY happen, for example, because no operation is in progress or because the +completion time is unknown. + +This attribute SHALL be null if the CurrentArea attribute is null. + +If the Progress attribute is available, and it contains an entry matching CurrentArea, the server +MAY use the time estimate provided in the InitialTimeEstimate field of that entry to compute the +EstimatedEndTime attribute. + +The value of this attribute SHALL only be reported in the following cases: + +- when it changes to or from 0 +- when it decreases +- when it changes to or from null + +### NOTE + +``` +If the device is capable of pausing its operation, this attribute MAY be set to null, to +indicate that completion time is unknown, or increment the value while being in +the paused state. +``` +**1.17.6.6. Progress Attribute** + +This attribute SHALL indicate the operating status at one or more areas. + +Each entry in this list SHALL have a unique value for the AreaID field. + +For each entry in this list, the AreaID field SHALL match an entry on the SupportedAreas attribute’s +list. + +When this attribute is empty, that represents that no progress information is currently available. + +If the SelectedAreas attribute is empty, indicating the device is not constrained to operate in any +specific areas, the Progress attribute list MAY change while the device operates, due to the device +adding new entries dynamically, when it determines which ones it can attempt to operate at. + +If the SelectedAreas attribute is not empty, and the device starts operating: + +- the Progress attribute list SHALL be updated so each entry of SelectedAreas has a matching + Progress list entry, based on the AreaID field +- the length of the Progress and SelectedAreas list SHALL be the same +- the entries in the Progress list SHALL be initialized by the server, by having their status set to + Pending or Operating, and the TotalOperationalTime field set to null + +When the device ends operation unexpectedly, such as due to an error, the server SHALL update all +Progress list entries with the Status field set to Operating or Pending to Skipped. + +``` +Page 162 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +When the device finishes operating, successfully or not, it SHALL NOT change the Progress +attribute, except in the case of an unexpected end of operation as described above, or due to +changes to the SupportedMaps or SupportedAreas attributes, so the clients can retrieve the +progress information at that time. + +### NOTE + +``` +if the device implements the Operational Status cluster, or a derivation of it, in case +the device fails to service any locations in the SelectedAreas list before ending the +operation, it SHOULD use the Operational Status cluster to indicate that the device +was unable to complete the operation (see the UnableToCompleteOperation error +from that cluster specification). The clients SHOULD then read the Progress +attribute, and indicate which areas have been successfully serviced (marked as +completed). +``` +**1.17.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 SelectAreas client ⇒ server SelectAreasRe­ +sponse +``` +### O M + +``` +0x01 SelectAreas­ +Response +``` +``` +client ⇐ server N O M +``` +``` +0x02 SkipArea client ⇒ server SkipAreaRe­ +sponse +``` +``` +O desc +``` +``` +0x03 SkipAreaRe­ +sponse +``` +``` +client ⇐ server N O SkipArea +``` +**1.17.7.1. SelectAreas Command** + +This command is used to select a set of device areas, where the device is to operate. + +On receipt of this command the device SHALL respond with a SelectAreasResponse command. + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NewAreas list[uint32] desc M +``` +**1.17.7.1.1. NewAreas Field** + +This field indicates which areas the device is to operate at. + +If this field is empty, that indicates that the device is to operate without being constrained to any +specific areas, and the operation will not allow skipping using the SkipArea Command, otherwise +the field SHALL be a list of unique values that match the AreaID field of entries on the Support­ +edAreas list. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 163 +``` + +**1.17.7.1.2. Effect on Receipt** + +If the NewAreas field contains any duplicated entries, the device SHALL operate on only the first +instance of an entry in the list. + +For example, if the list [1, 2, 2, 3, 2] were received, the device would ignore the duplicated +instances of 2 in the list and operate as if the list [1, 2, 3] had been received instead. + +If the device determines that it can’t operate at all areas from the list, the SelectAreasResponse com­ +mand’s Status field SHALL indicate InvalidSet. + +If at least one entry on the NewAreas field doesn’t match the AreaID field of any entry of the Sup­ +portedAreas list, the SelectAreasResponse command’s Status field SHALL indicate Unsupport­ +edArea. + +If the current state of the device doesn’t allow for the areas to be selected, the SelectAreasResponse +command SHALL have the Status field set to InvalidInMode. + +Unless the SelectWhileRunning feature indicates that selecting areas is allowed while the device is +in a non-idle state, such as operating or paused, the SelectAreasResponse command SHALL have +the Status field set to InvalidInMode if this restriction prevents changing the selected areas. + +Otherwise, if the device accepts the request, the server will attempt to operate at the areas indi­ +cated by the entries of the NewArea field, the SelectAreasResponse command SHALL have the Sta­ +tus field set to Success, and the SelectedAreas attribute SHALL be set to the value of the NewAreas +field. + +### NOTE + +``` +The device MAY start to operate immediately or wait until specifically requested to +operate. The behavior of the device is manufacturer specific. +``` +If the NewAreas field is the same as the value of the SelectedAreas attribute the SelectAreasRe­ +sponse command SHALL have the Status field set to Success and the StatusText field MAY be sup­ +plied with a human readable string or include an empty string. + +**1.17.7.2. SelectAreasResponse Command** + +This command is sent by the device on receipt of the SelectAreas command. This command SHALL +have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status SelectAre­ +asStatus +``` +``` +all M +``` +``` +1 StatusText string max 256 M +``` +**1.17.7.2.1. Status Field** + +If the Status field is set to Success or UnsupportedArea, the server MAY use a non-empty string for +the StatusText field to provide additional information. For example, if Status is set to Unsupport­ + +``` +Page 164 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +edArea, the server MAY use StatusText to indicate which areas are unsupported. + +If the Status field is not set to Success, or UnsupportedArea, the StatusText field SHALL include a +vendor-defined error description which can be used to explain the error to the user. For example, if +the Status field is set to InvalidInMode, the StatusText field SHOULD indicate why the request is not +allowed, given the current mode of the device, which MAY involve other clusters. + +**1.17.7.3. SkipArea Command** + +This command is used to skip the given area, and to attempt operating at other areas on the Sup­ +portedAreas attribute list. + +This command SHALL NOT be implemented if the CurrentArea attribute and the Progress attribute +are both not implemented. Else, this command SHALL be optionally implemented. + +On receipt of this command the device SHALL respond with a SkipAreaResponse command. + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SkippedAre +a +``` +``` +uint32 desc M +``` +**1.17.7.3.1. SkippedArea Field** + +The SkippedArea field indicates the area to be skipped. + +The SkippedArea field SHALL match an entry in the SupportedAreas list. + +**1.17.7.3.2. Effect on Receipt** + +If the SelectedAreas attribute is empty, the SkipAreaResponse command’s Status field SHALL indi­ +cate InvalidAreaList. + +If the SkippedArea field does not match an entry in the SupportedAreas attribute, the SkipAreaRe­ +sponse command’s Status field SHALL indicate InvalidSkippedArea. + +If the SkipArea command can not be handled by the device, e.g. due to the current state, the +SkipAreaResponse command’s Status field SHALL indicate InvalidInMode. + +Otherwise, if the device accepts the request, the device SHALL return a SkipAreaResponse with the +Status field set to Success and: + +- If the device is currently operating at the area identified by SkippedArea, as indicated by either + the CurrentArea or the Progress attributes, if implemented, the device SHALL stop operating at + that area. +- If the Progress attribute is implemented, the entry corresponding to SkippedArea SHALL be + updated to indicate that the area was skipped. +- The device SHALL attempt to operate only at the areas in the SelectedAreas attribute list where + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 165 +``` + +``` +operating has not been skipped or completed, using a vendor defined order. +``` +- If the device has either skipped or completed operating at all areas on the SelectedAreas + attribute list, the server SHALL stop operating. + +**1.17.7.4. SkipAreaResponse Command** + +This command is sent by the device on receipt of the SkipArea command. + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status SkipAreaSta­ +tus +``` +``` +all M +``` +``` +1 StatusText string max 256 M +``` +**1.17.7.4.1. Status Field** + +If the Status field is set to Success or InvalidAreaList, the server MAY use a non-empty string for the +StatusText field to provide additional information. For example, if Status is set to InvalidAreaList, +the server MAY use StatusText to indicate why this list is invalid. + +If the Status field is not set to Success or InvalidAreaList, the StatusText field SHALL include a ven­ +dor defined error description which can be used to explain the error to the user. For example, if the +Status field is set to InvalidInMode, the StatusText field SHOULD indicate why the request is not +allowed, given the current mode of the device, which MAY involve other clusters. + +``` +Page 166 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 2. Measurement and Sensing** + +The Cluster Library is made of individual chapters such as this one. See Document Control in the +Cluster Library for a list of all chapters and documents. References between chapters are made +using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. References +to external documents are contained in Chapter 1 and are made using [ _Rn_ ] notation. + +**2.1. General Description** + +**2.1.1. Introduction** + +The clusters specified in this document are generic measurement and sensing interfaces that are +sufficiently general to be of use across a wide range of application domains. + +**2.1.2. Cluster List** + +This section lists the measurement and sensing clusters as specified in this chapter. + +_Table 5. Overview of the Measurement and Sensing Clusters_ + +``` +Cluster ID Cluster Name Description +0x0400 Illuminance Measurement Attributes and commands for +configuring the measurement +of illuminance, and reporting +illuminance measurements +0x0402 Temperature Measurement Attributes and commands for +configuring the measurement +of temperature, and reporting +temperature measurements +0x0403 Pressure Measurement Attributes and commands for +configuring the measurement +of pressure, and reporting pres­ +sure measurements +0x0404 Flow Measurement Attributes and commands for +configuring the measurement +of flow, and reporting flow rates +0x0405 Relative Humidity Measure­ +ment +``` +``` +Supports configuring the mea­ +surement of relative humidity, +and reporting relative humidity +measurements of water in the +air +0x0406 Occupancy Sensing Attributes and commands for +configuring occupancy sensing, +and reporting occupancy status +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 167 +``` + +``` +Cluster ID Cluster Name Description +various Resource Monitoring Attributes and commands for +reporting conditions of various +resources +0x005B Air Quality Measurement Attributes for reporting air +quality classification +various Concentration Measurement Attributes and aliases for con­ +centration measurements +0x005C Smoke and CO Alarm An interface to smoke and CO +alarms +0x0091 Electrical Energy Measurement Attributes and commands for +measuring electrical energy +0x0090 Electrical Power Measurement Attributes and commands for +measuring electrical power +``` +**2.1.3. Measured Value** + +This section provides requirements on the attributes MeasuredValue, MinMeasuredValue, MaxMea­ +suredValue. Accuracy of MeasuredValue is discussed in the following section. + +**2.1.3.1. Constraint** + +Where MinMeasuredValue or MaxMeasuredValue attributes are mandatory the null value MAY be +used to indicate that a limit is unknown. + +For any measurement cluster with MeasuredValue, MinMeasuredValue and MaxMeasuredValue +attributes, the following SHALL be always be true: + +- If MinMeasuredValue and MaxMeasuredValue are both known, then MaxMeasuredValue + SHALL be greater than MinMeasuredValue. +- If MaxMeasuredValue is known, then MeasuredValue SHALL be less than or equal to MaxMea­ + suredValue. +- If MinMeasuredValue is known, then MeasuredValue SHALL be greater than or equal to Min­ + MeasuredValue. + +**2.1.4. Measurement Accuracy** + +Measurement clusters MAY express the accuracy of their measurements with a Tolerance attribute +expressing a simple magnitude of error, or with a MeasurementAccuracyStruct expressing magni­ +tude or percentage ranges of error for different ranges of measured values. + +**2.1.4.1. Tolerance Attribute** + +For any measurement cluster with a MeasuredValue and Tolerance attribute, when Tolerance is +implemented the following SHALL always be true: + +``` +Page 168 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- The Tolerance attribute SHALL indicate the magnitude of the possible error that is associated + with MeasuredValue attribute, using the same units and resolution. The true value SHALL be in + the range (MeasuredValue – Tolerance) to (MeasuredValue + Tolerance). +- If known, the true value SHALL never be outside the possible physical range. Some examples: + ◦ a temperature SHALL NOT be below absolute zero + ◦ a concentration SHALL NOT be negative + +**2.1.4.2. MeasurementTypeEnum Type** + +This data type is derived from enum16. + +``` +Value Name Summary Conformance +0 Unspecified M +1 Voltage Voltage in millivolts +(mV) +``` +### M + +``` +2 ActiveCurrent Active current in mil­ +liamps (mA) +``` +### M + +``` +3 ReactiveCurrent Reactive current in mil­ +liamps (mA) +``` +### M + +``` +4 ApparentCurrent Apparent current in +milliamps (mA) +``` +### M + +``` +5 ActivePower Active power in milli­ +watts (mW) +``` +### M + +``` +6 ReactivePower Reactive power in milli­ +volt-amps reactive +(mVAR) +``` +### M + +``` +7 ApparentPower Apparent power in mil­ +livolt-amps (mVA) +``` +### M + +``` +8 RMSVoltage Root mean squared +voltage in millivolts +(mV) +``` +### M + +``` +9 RMSCurrent Root mean squared +current in milliamps +(mA) +``` +### M + +``` +10 RMSPower Root mean squared +power in milliwatts +(mW) +``` +### M + +``` +11 Frequency AC frequency in milli­ +hertz (mHz) +``` +### M + +``` +12 PowerFactor Power Factor ratio in ++/- 1/100ths of a per­ +cent. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 169 +``` + +``` +Value Name Summary Conformance +13 NeutralCurrent AC neutral current in +milliamps (mA) +``` +### M + +``` +14 ElectricalEnergy Electrical energy in mil­ +liwatt-hours (mWh) +``` +### M + +**2.1.4.3. MeasurementAccuracyRangeStruct Type** + +This struct represents the accuracy of a measurement for a range of measurement values. Accuracy +SHALL be expressed as a maximum +/- percentage of the true value, a maximum +/- fixed value of +the true value, or both. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 RangeMin int64 -2^62 to 2^62 F R M +1 RangeMax int64 -2^62 to 2^62 F R M +2 Percent­ +Max +``` +``` +per­ +cent100ths +``` +``` +all F R O.a+ +``` +``` +3 Percent­ +Min +``` +``` +per­ +cent100ths +``` +``` +max Per­ +centTypi­ +cal +``` +``` +F R [Percent­ +Max] +``` +``` +4 Percent­ +Typical +``` +``` +per­ +cent100ths +``` +``` +Percent­ +Min to Per­ +centMax +``` +``` +F R [Percent­ +Min] +``` +``` +5 FixedMax uint64 max 2^62 - 1 F R O.a+ +6 FixedMin uint64 max Fixed­ +Max +``` +``` +F R [FixedMax] +``` +``` +7 FixedTypi­ +cal +``` +``` +uint64 FixedMin +to Fixed­ +Max +``` +``` +F R [FixedMin] +``` +- If both PercentMax and FixedMax are indicated, then for a given true value in the range + between RangeMin and RangeMax, + ◦ the reported value SHALL be less than or equal to the sum of the true value, FixedMax and + PercentMax percent of the true value. + ◦ the reported value SHALL be greater than or equal to the true value minus the sum of Fixed­ + Max and PercentMax percent of the true value. +- If only PercentMax is indicated, then for a given true value in the range between RangeMin and + RangeMax, + ◦ the reported value SHALL be less than or equal to the sum of the true value and PercentMax + percent of the true value. + ◦ the reported value SHALL be greater than or equal to the true value minus PercentMax per­ + +``` +Page 170 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +cent of the true value. +``` +- If only FixedMax is indicated, then for a given true value in the range between RangeMin and + RangeMax, + ◦ the reported value SHALL be less than or equal to the sum of the true value and FixedMax. + ◦ the reported value SHALL be greater than or equal to the true value minus FixedMax. + +**2.1.4.3.1. RangeMin Field** + +This field SHALL indicate the minimum measurement value for the specified level of accuracy. + +The value of this field SHALL be greater than or equal to the value of the MinMeasuredValue field +on the encompassing MeasurementAccuracyStruct. + +The value of this field SHALL be less than or equal to the value of the MaxMeasuredValue field on +the encompassing MeasurementAccuracyStruct. + +**2.1.4.3.2. RangeMax Field** + +This field SHALL indicate the maximum measurement value for the specified level of accuracy. + +The value of this field SHALL be greater than the value of the RangeMin field. + +The value of this field SHALL be greater than or equal to the value of the MinMeasuredValue field +on the encompassing MeasurementAccuracyStruct. + +The value of this field SHALL be less than or equal to the value of the MaxMeasuredValue field on +the encompassing MeasurementAccuracyStruct. + +**2.1.4.3.3. PercentMax Field** + +This field SHALL indicate the maximum +/- percentage accuracy for the associated measurement. + +**2.1.4.3.4. PercentMin Field** + +This field SHALL indicate the minimum +/- percentage accuracy for the associated measurement. + +**2.1.4.3.5. PercentTypical Field** + +This field SHALL indicate the typical +/- percentage accuracy for the associated measurement. + +**2.1.4.3.6. FixedMax Field** + +This field SHALL indicate the maximum +/- fixed accuracy for the associated measurement, in the +unit indicated by MeasurementType. + +**2.1.4.3.7. FixedMin Field** + +This field SHALL indicate the minimum +/- fixed accuracy for the associated measurement, in the +unit indicated by MeasurementType. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 171 +``` + +**2.1.4.3.8. FixedTypical Field** + +This field SHALL indicate the typical +/- fixed accuracy for the associated measurement, in the unit +indicated by MeasurementType. + +**2.1.4.4. MeasurementAccuracyStruct Type** + +This struct represents the set of accuracy ranges for a given measurement, the maximum and mini­ +mum values for the measurement, and whether the measurement is directly measured or just esti­ +mated from other information. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Measure­ +mentType +``` +``` +Measure­ +mentType­ +Enum +``` +### F R M + +``` +1 Measured bool F false R M +2 MinMea­ +sured­ +Value +``` +``` +int64 -2^62 to 2^62 F R M +``` +``` +3 MaxMea­ +sured­ +Value +``` +``` +int64 -2^62 to 2^62 F R M +``` +``` +4 Accura­ +cyRanges +``` +``` +list[Mea­ +suremen­ +tAccura­ +cyRangeStr +uct] +``` +``` +min 1 F R M +``` +**2.1.4.4.1. MeasurementType Field** + +This field SHALL indicate the type of measurement for the accuracy provided. + +**2.1.4.4.2. Measured Field** + +This field SHALL indicate whether the associated measurement was directly measured. If this field +is not set to true, then the associated measurement was estimated. + +**2.1.4.4.3. MinMeasuredValue Attribute** + +This field SHALL indicate the minimum value that can be measured. + +**2.1.4.4.4. MaxMeasuredValue Attribute** + +This field SHALL indicate the maximum value that can be measured. + +**2.1.4.4.5. AccuracyRanges Field** + +This field SHALL indicate a list of measurement ranges and their associated accuracies. + +``` +Page 172 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The value of the RangeMin field on the first MeasurementAccuracyRangeStruct in this list SHALL +be equal to the value of the MinMeasuredValue field. + +The value of the RangeMax field on the last MeasurementAccuracyRangeStruct in this list SHALL be +less than or equal to the value of the MaxMeasuredValue field. + +The value of the RangeMin field on each MeasurementAccuracyRangeStruct in this list other than +the first SHALL be one more the value of the RangeMax field on the previous MeasurementAccura­ +cyRangeStruct in this list (i.e. there SHALL be no gaps in the accuracy ranges, and the ranges SHALL +be in increasing order). + +**2.2. Illuminance Measurement Cluster** + +The Illuminance Measurement cluster provides an interface to illuminance measurement function­ +ality, including configuration and provision of notifications of illuminance measurements. + +**2.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added; CCB 2048 2049 2050 +2 CCB 2167 +3 New data model format and notation +``` +**2.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint ILL +``` +**2.2.3. Cluster ID** + +``` +ID Name +0x0400 Illuminance Measurement +``` +**2.2.4. Data Types** + +**2.2.4.1. LightSensorTypeEnum Type** + +This data type is derived from enum8. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 173 +``` + +``` +Value Name Summary Conformance +0 Photodiode Indicates photodiode +sensor type +``` +### M + +``` +1 CMOS Indicates CMOS sensor +type +``` +### M + +``` +64 to 254 MS Reserved for manufac­ +turer specific light sen­ +sor types +``` +### O + +**2.2.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Measured­ +Value +``` +``` +uint16 0, MinMea­ +suredValue +to +MaxMea­ +suredValue +``` +### PX 0 R V M + +``` +0x0001 MinMea­ +sured­ +Value +``` +``` +uint16 1 to 65533 X R V M +``` +``` +0x0002 MaxMea­ +sured­ +Value +``` +``` +uint16 min (Min­ +Measured­ +Value + 1) +``` +### X R V M + +``` +0x0003 Tolerance uint16 max 2048 R V O +0x0004 LightSen­ +sorType +``` +``` +LightSen­ +sorType­ +Enum +``` +``` +all X null R V O +``` +**2.2.5.1. MeasuredValue Attribute** + +This attribute SHALL indicate the illuminance in Lux (symbol lx) as follows: + +- MeasuredValue = 10,000 x log 10 (illuminance) + 1, + +where 1 lx <= illuminance <= 3.576 Mlx, corresponding to a MeasuredValue in the range 1 to 0xFFFE. + +The MeasuredValue attribute can take the following values: + +- 0 indicates a value of illuminance that is too low to be measured, +- MinMeasuredValue <= MeasuredValue <= MaxMeasuredValue under normal circumstances, +- null indicates that the illuminance measurement is invalid. + +The MeasuredValue attribute is updated continuously as new measurements are made. + +``` +Page 174 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.2.5.2. MinMeasuredValue Attribute** + +This attribute SHALL indicate the minimum value of MeasuredValue that can be measured. A value +of null indicates that this attribute is not defined. See Measured Value for more details. + +**2.2.5.3. MaxMeasuredValue Attribute** + +This attribute SHALL indicate the maximum value of MeasuredValue that can be measured. A value +of null indicates that this attribute is not defined. See Measured Value for more details. + +**2.2.5.4. Tolerance Attribute** + +See Measured Value. + +**2.2.5.5. LightSensorType Attribute** + +This attribute SHALL indicate the electronic type of the light sensor. This attribute SHALL be set to +one of the non-reserved values listed in LightSensorTypeEnum or null in case the sensor type is +unknown. + +**2.3. Temperature Measurement Cluster** + +This cluster provides an interface to temperature measurement functionality, including configura­ +tion and provision of notifications of temperature measurements. + +**2.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 CCB 2241 2370 +3 CCB 2823 +4 New data model format and notation +``` +**2.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint TMP +``` +**2.3.3. Cluster ID** + +``` +ID Name +0x0402 Temperature Measurement +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 175 +``` + +**2.3.4. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Measured­ +Value +``` +``` +tempera­ +ture +``` +``` +MinMea­ +suredValue +to +MaxMea­ +suredValue +``` +### XP R V M + +``` +0x0001 MinMea­ +sured­ +Value +``` +``` +tempera­ +ture +``` +``` +-27315 to +32766 +``` +### X R V M + +``` +0x0002 MaxMea­ +sured­ +Value +``` +``` +tempera­ +ture +``` +``` +min (Min­ +Measured­ +Value + 1) +``` +### X R V M + +``` +0x0003 Tolerance uint16 max 2048 0 R V O +``` +**2.3.4.1. MeasuredValue Attribute** + +This attribute SHALL indicate the measured temperature. + +The null value indicates that the temperature is unknown. + +**2.3.4.2. MinMeasuredValue Attribute** + +This attribute SHALL indicate the minimum value of MeasuredValue that is capable of being mea­ +sured. See Measured Value for more details. + +The null value indicates that the value is not available. + +**2.3.4.3. MaxMeasuredValue Attribute** + +This attribute indicates the maximum value of MeasuredValue that is capable of being measured. +See Measured Value for more details. + +The null value indicates that the value is not available. + +**2.3.4.4. Tolerance Attribute** + +See Measured Value. + +**2.4. Pressure Measurement Cluster** + +This cluster provides an interface to pressure measurement functionality, including configuration +and provision of notifications of pressure measurements. + +``` +Page 176 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.4.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 CCB 2241 2370 +3 New data model format and notation +``` +**2.4.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint PRS +``` +**2.4.3. Cluster ID** + +``` +ID Name +0x0403 Pressure Measurement +``` +**2.4.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 EXT Extended O Extended range +and resolution +``` +**2.4.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Measured­ +Value +``` +``` +int16 MinMea­ +suredValue +to +MaxMea­ +suredValue +``` +### XP R V M + +``` +0x0001 MinMea­ +sured­ +Value +``` +``` +int16 max 32766 X R V M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 177 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0002 MaxMea­ +sured­ +Value +``` +``` +int16 (MinMea­ +suredValue ++ 1) to +32767 +``` +### X R V M + +``` +0x0003 Tolerance uint16 max 2048 0 R V O +0x0010 Scaled­ +Value +``` +``` +int16 MinScaled­ +Value to +MaxScaled­ +Value +``` +### X 0 R V EXT + +``` +0x0011 Min­ +Scaled­ +Value +``` +``` +int16 max 32766 X 0 R V EXT +``` +``` +0x0012 MaxS­ +caled­ +Value +``` +``` +int16 (Min­ +Scaled­ +Value + 1) +to 32767 +``` +### X 0 R V EXT + +``` +0x0013 ScaledTol­ +erance +``` +``` +uint16 max 2048 0 R V [EXT] +``` +``` +0x0014 Scale int8 min -127 0 R V EXT +``` +**2.4.5.1. MeasuredValue Attribute** + +This attribute SHALL represent the pressure in kPa as follows: + +MeasuredValue = 10 x Pressure [kPa] + +The null value indicates that the value is not available. + +**2.4.5.2. MinMeasuredValue Attribute** + +This attribute SHALL indicate the minimum value of MeasuredValue that can be measured. See +Measured Value for more details. + +The null value indicates that the value is not available. + +**2.4.5.3. MaxMeasuredValue Attribute** + +This attribute SHALL indicate the maximum value of MeasuredValue that can be measured. See +Measured Value for more details. + +The null value indicates that the value is not available. + +**2.4.5.4. Tolerance Attribute** + +See Measured Value. + +``` +Page 178 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.4.5.5. ScaledValue Attribute** + +This attribute SHALL represent the pressure in Pascals as follows: + +ScaledValue = 10Scale x Pressure [Pa] + +The null value indicates that the value is not available. + +**2.4.5.6. MinScaledValue Attribute** + +This attribute SHALL indicate the minimum value of ScaledValue that can be measured. + +The null value indicates that the value is not available. + +**2.4.5.7. MaxScaledValue Attribute** + +This attribute SHALL indicate the maximum value of ScaledValue that can be measured. + +The null value indicates that the value is not available. + +**2.4.5.8. ScaledTolerance Attribute** + +This attribute SHALL indicate the magnitude of the possible error that is associated with Scaled­ +Value. The true value is located in the range + +(ScaledValue – ScaledTolerance) to (ScaledValue + ScaledTolerance). + +**2.4.5.9. Scale Attribute** + +This attribute SHALL indicate the base 10 exponent used to obtain ScaledValue (see ScaledValue). + +**2.5. Flow Measurement Cluster** + +This cluster provides an interface to flow measurement functionality, including configuration and +provision of notifications of flow measurements. + +**2.5.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 CCB 2241 2370 +3 New data model format and notation +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 179 +``` + +**2.5.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint FLW +``` +**2.5.3. Cluster ID** + +``` +ID Name +0x0404 Flow Measurement +``` +**2.5.4. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Measured­ +Value +``` +``` +uint16 MinMea­ +suredValue +to +MaxMea­ +suredValue +``` +``` +XP null R V M +``` +``` +0x0001 MinMea­ +sured­ +Value +``` +``` +uint16 max 65533 X R V M +``` +``` +0x0002 MaxMea­ +sured­ +Value +``` +``` +uint16 min (Min­ +Measured­ +Value + 1) +``` +### X R V M + +``` +0x0003 Tolerance uint16 max 2048 0 R V O +``` +**2.5.4.1. MeasuredValue Attribute** + +This attribute SHALL indicate the flow in m^3 /h as follows: + +MeasuredValue = 10 x Flow + +The null value indicates that the flow measurement is unknown, otherwise the range SHALL be as +described in Measured Value. + +**2.5.4.2. MinMeasuredValue Attribute** + +This attribute SHALL indicate the minimum value of MeasuredValue that can be measured. See +Measured Value for more details. + +The null value indicates that the value is not available. + +**2.5.4.3. MaxMeasuredValue Attribute** + +This attribute SHALL indicate the maximum value of MeasuredValue that can be measured. See + +``` +Page 180 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Measured Value for more details. + +The null value indicates that the value is not available. + +**2.5.4.4. Tolerance Attribute** + +See Measured Value. + +**2.6. Water Content Measurement Clusters** + +This is a base cluster. The server cluster provides an interface to water content measurement func­ +tionality. The measurement is reportable and may be configured for reporting. Water content mea­ +surements currently is, but are not limited to relative humidity. + +**2.6.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 CCB 2241 +3 New data model format and notation +``` +**2.6.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint RH +``` +**2.6.3. Cluster ID** + +``` +ID Name +0x0405 Relative Humidity Measurement +``` +**2.6.4. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Measured­ +Value +``` +``` +uint16 MinMea­ +suredValue +to +MaxMea­ +suredValue +``` +### XP R V M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 181 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0001 MinMea­ +sured­ +Value +``` +``` +uint16 max 9999 X R V M +``` +``` +0x0002 MaxMea­ +sured­ +Value +``` +``` +uint16 (MinMea­ +suredValue ++ 1) to +10000 +``` +### X R V M + +``` +0x0003 Tolerance uint16 max 2048 R V O +``` +**2.6.4.1. MeasuredValue Attribute** + +MeasuredValue represents the water content in % as follows: + +MeasuredValue = 100 x water content + +Where 0% < = water content < = 100%, corresponding to a MeasuredValue in the range 0 to 10000. + +The maximum resolution this format allows is 0.01%. + +MinMeasuredValue and MaxMeasuredValue define the range of the sensor. + +The null value indicates that the measurement is unknown, otherwise the range SHALL be as +described in Measured Value. + +MeasuredValue is updated continuously as new measurements are made. + +**2.6.4.2. MinMeasuredValue Attribute** + +The MinMeasuredValue attribute indicates the minimum value of MeasuredValue that can be mea­ +sured. The null value means this attribute is not defined. See Measured Value for more details. + +**2.6.4.3. MaxMeasuredValue Attribute** + +The MaxMeasuredValue attribute indicates the maximum value of MeasuredValue that can be mea­ +sured. The null value means this attribute is not defined. See Measured Value for more details. + +**2.6.4.4. Tolerance Attribute** + +See Measured Value. + +**2.7. Occupancy Sensing Cluster** + +The server cluster provides an interface to occupancy sensing functionality based on one or more +sensing modalities, including configuration and provision of notifications of occupancy status. + +``` +Page 182 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.7.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute added +2 Physical Contact Occupancy feature with mandatory OccupancySen­ +sorTypeBitmap +3 New data model format and notation +4 Remove nullable from PhysicalContact delay attributes and ability to not report +transitions +5 Rework to add modalities: radar-, ambient-sensing- and vision-based sensors; add +sensitivity setting (via co-located BooleanStateConfiguration cluster on same end­ +point); add new attribute for tuning the sensor’s reporting; add event Occupancy­ +Changed; add N quality for HoldTime and other timing attributes; describe how to +accommodate legacy clients +``` +**2.7.1.1. Backward compatibility** + +With the introduction of new sensor modalities in cluster revision 5, the indication for those modal­ +ities SHALL be done using feature bits. Indication of those new modalities is not feasible via the +legacy attributes OccupancySensorType and OccupancySensorTypeBitmap. Servers SHALL set +these attributes for backward compatibility with clients implementing a cluster revision <= 4 as +described in OccupancySensorType and OccupancySensorTypeBitmap Attributes. Clients imple­ +menting a cluster revision >= 5 SHOULD use the server’s ClusterRevision attribute, and SHOULD +ignore these legacy attributes. + +With the same revision 5, the attribute HoldTime (along with the HoldTimeLimits) is used to deter­ +mine the reporting when occupancy is no longer detected. This replaces the 9 legacy attributes +PIROccupiedToUnoccupiedDelay through PhysicalContactUnoccupiedToOccupiedThreshold. +Servers MAY use the applicable attributes from this set of legacy attributes if and only if HoldTime +is supported (see Attribute table and the corresponding explanation for details on conformance). + +For the case of a server which supports none of the modalities supported in ClusterRevision <= 4 +(i.e. none of PIR, US and PHY), specific mappings for the legacy attributes OccupancySensorType +and OccupancySensorTypeBitmap are provided below, representing this sensor as a PIR sensor for +best-effort backward compatibility. For this case, the legacy timing attributes linked to PIR (i.e. +PIROccupiedToUnoccupiedDelay through PIRUnoccupiedToOccupiedThreshold) apply. + +**2.7.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint OCC +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 183 +``` + +**2.7.3. Cluster ID** + +``` +ID Name +0x0406 Occupancy Sensing +``` +**2.7.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. For sensor devices +implementing multiple modalities, please see the guidance provided in the Occupancy Sensor +device type description. + +``` +Bit Code Feature Conformance Summary +0 OTHER Other O.a+ Supports sensing +using a modality +not listed in the +other bits +1 PIR PassiveInfrared O.a+ Supports sensing +using PIR (Passive +InfraRed) +2 US Ultrasonic O.a+ Supports sensing +using UltraSound +3 PHY PhysicalContact O.a+ Supports sensing +using a physical +contact +4 AIR ActiveInfrared O.a+ Supports sensing +using Active +InfraRed measure­ +ment (e.g. time-of- +flight or transflec­ +tive/reflective IR +sensing) +5 RAD Radar O.a+ Supports sensing +using radar waves +(microwave) +6 RFS RFSensing O.a+ Supports sensing +based on RF signal +analysis +7 VIS Vision O.a+ Supports sensing +based on analyz­ +ing images +``` +**2.7.5. Data Types** + +``` +Page 184 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.7.5.1. OccupancyBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 Occupied Indicates the sensed +occupancy state +``` +### M + +**2.7.5.1.1. Occupied Bit** + +If this bit is set, it SHALL indicate the occupied state else if the bit if not set, it SHALL indicate the +unoccupied state. + +**2.7.5.2. OccupancySensorTypeBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 PIR Indicates a passive +infrared sensor. +``` +### M + +``` +1 Ultrasonic Indicates a ultrasonic +sensor. +``` +### M + +``` +2 PhysicalContact Indicates a physical +contact sensor. +``` +### M + +### NOTE + +``` +This enum is as defined in ClusterRevision 4 and its definition SHALL NOT be +extended; the feature flags provide the sensor modality (or modalities) for later +cluster revisions. See Backward Compatibility section. +``` +**2.7.5.3. OccupancySensorTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 PIR Indicates a passive +infrared sensor. +``` +### M + +``` +1 Ultrasonic Indicates a ultrasonic +sensor. +``` +### M + +``` +2 PIRAndUltrasonic Indicates a passive +infrared and ultrasonic +sensor. +``` +### M + +``` +3 PhysicalContact Indicates a physical +contact sensor. +``` +### M + +``` +NOTE This enum is as defined in ClusterRevision 4 and its definition SHALL NOT be +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 185 +``` + +``` +extended; the feature flags provide the sensor modality (or modalities) for later +cluster revisions. See Backward Compatibility section. +``` +**2.7.5.4. HoldTimeLimitsStruct Type** + +This structure provides information on the server’s supported values for the HoldTime attribute. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Hold­ +TimeMin +``` +``` +uint16 min 1 M +``` +``` +1 Hold­ +TimeMax +``` +``` +uint16 min (Hold­ +TimeMin), +min 10 +``` +### M + +``` +2 Hold­ +TimeDe­ +fault +``` +``` +uint16 Hold­ +TimeMin +to Hold­ +TimeMax +``` +### M + +**2.7.5.4.1. HoldTimeMin Field** + +This field SHALL specify the minimum value of the server’s supported value for the HoldTime +attribute, in seconds. + +**2.7.5.4.2. HoldTimeMax Field** + +This field SHALL specify the maximum value of the server’s supported value for the HoldTime +attribute, in seconds. + +**2.7.5.4.3. HoldTimeDefault Field** + +This field SHALL specify the (manufacturer-determined) default value of the server’s HoldTime +attribute, in seconds. This is the value that a client who wants to reset the settings to a valid default +SHOULD use. + +**2.7.6. Attributes** + +``` +ID Name Type Con­ +strai +nt +``` +``` +Qual +ity +``` +``` +Defa +ult +``` +``` +Acce +ss +``` +``` +Conformance +``` +``` +0x00 +00 +``` +``` +Occupancy Occupan­ +cyBitmap +``` +``` +0 to +1 +``` +### P R V M + +``` +0x00 +01 +``` +``` +OccupancySen­ +sorType +``` +``` +Occupan­ +cySen­ +sorType­ +Enum +``` +``` +desc F R V M, D +``` +``` +Page 186 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**ID Name Type Con­ +strai +nt** + +``` +Qual +ity +``` +``` +Defa +ult +``` +``` +Acce +ss +``` +``` +Conformance +``` +0x00 +02 + +``` +OccupancySen­ +sorTypeBitmap +``` +``` +Occupan­ +cySen­ +sorTypeBit +map +``` +``` +0 to +7 +``` +### F R V M, D + +0x00 +03 + +``` +HoldTime uint16 desc N RW +VM +``` +### O + +0x00 +04 + +``` +HoldTimeLimits HoldTime­ +Lim­ +itsStruct +``` +``` +F R V HoldTime +``` +0x00 +10 + +``` +PIROccupied­ +ToUnoccupied­ +Delay +``` +``` +uint16 all N 0 RW +VM +``` +``` +[HoldTime & (PIR | (!PIR & !US & +!PHY))], D +``` +0x00 +11 + +``` +PIRUnoccupied­ +ToOccupiedDe­ +lay +``` +``` +uint16 all N 0 RW +VM +``` +``` +(HoldTime & (PIR | (!PIR & !US & +!PHY))) & PIRUnoccupiedToOccu­ +piedThreshold, [HoldTime & (PIR | +(!PIR & !US & !PHY))], D +``` +0x00 +12 + +``` +PIRUnoccupied­ +ToOccu­ +piedThreshold +``` +``` +uint8 1 to +254 +``` +### N 1 RW + +### VM + +``` +(HoldTime & (PIR | (!PIR & !US & +!PHY))) & PIRUnoccupiedToOccu­ +piedDelay, [HoldTime & (PIR | (!PIR +& !US & !PHY))], D +``` +0x00 +20 + +``` +UltrasonicOccu­ +piedToUnoccu­ +piedDelay +``` +``` +uint16 all N 0 RW +VM +``` +``` +[HoldTime & US], D +``` +0x00 +21 + +``` +UltrasonicUnoc­ +cupiedToOccu­ +piedDelay +``` +``` +uint16 all N 0 RW +VM +``` +``` +HoldTime & US & UltrasonicUnoccu­ +piedToOccupiedThreshold, [Hold­ +Time & US], D +``` +0x00 +22 + +``` +UltrasonicUnoc­ +cupiedToOccu­ +piedThreshold +``` +``` +uint8 1 to +254 +``` +### N 1 RW + +### VM + +``` +HoldTime & US & UltrasonicUnoccu­ +piedToOccupiedDelay, [HoldTime & +US], D +``` +0x00 +30 + +``` +PhysicalContac­ +tOccupied­ +ToUnoccupied­ +Delay +``` +``` +uint16 all N 0 RW +VM +``` +``` +[HoldTime & PHY], D +``` +0x00 +31 + +``` +PhysicalContac­ +tUnoccupied­ +ToOccupiedDe­ +lay +``` +``` +uint16 all N 0 RW +VM +``` +``` +HoldTime & PHY & PhysicalContac­ +tUnoccupiedToOccupiedThreshold, +[HoldTime & PHY], D +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 187 +``` + +``` +ID Name Type Con­ +strai +nt +``` +``` +Qual +ity +``` +``` +Defa +ult +``` +``` +Acce +ss +``` +``` +Conformance +``` +``` +0x00 +32 +``` +``` +PhysicalContac­ +tUnoccupied­ +ToOccu­ +piedThreshold +``` +``` +uint8 1 to +254 +``` +### N 1 RW + +### VM + +``` +HoldTime & PHY & PhysicalContac­ +tUnoccupiedToOccupiedDelay, +[HoldTime & PHY], D +``` +**2.7.6.1. Occupancy Attribute** + +This attribute SHALL indicate the sensed (processed) status of occupancy. For compatibility reasons +this is expressed as a bitmap where the status is indicated in bit 0: a value of 1 means occupied, and +0 means unoccupied, with the other bits set to 0; this can be considered equivalent to a boolean. + +**2.7.6.2. OccupancySensorType and OccupancySensorTypeBitmap Attributes** + +These attributes SHALL indicate the type of sensor. In ClusterRevision <= 4, these were used to spec­ +ify the type of the occupancy sensor using a bitmap. For ClusterRevision >= 5, the server SHALL +indicate the type of sensor using the feature flags, and the server SHALL provide these attributes +for the backward compatibility with clients implementing a cluster revision <= 4, using the mapping +according to the following table. Also see Backward Compatibility section. + +``` +Feature Flag Value Value of Occu­ +pancySen­ +sorTypeBitmap +``` +``` +Value of Occu­ +pancySensorType +``` +### PIR US PHY + +### 0 0 0 PIR * PIR * + +### 1 0 0 PIR PIR + +``` +0 1 0 Ultrasonic Ultrasonic +1 1 0 PIR + Ultrasonic PIRAndUltrasonic +0 0 1 PhysicalContact PhysicalContact +1 0 1 PhysicalContact + +PIR +``` +### PIR ** + +``` +0 1 1 PhysicalContact + +Ultrasonic +``` +``` +Ultrasonic ** +``` +``` +1 1 1 PhysicalContact + +PIR + Ultrasonic +``` +``` +PIRAndUltrasonic** +``` +* In case the feature flags PIR, US and PHY are all set to 0, these attributes are set to mimic a PIR sen­ + +sor since this likely will give the best compatibility with clients implementing a cluster revision <= 4, +which are not aware of the feature flags and the added modalities. In this case, timing parameters +(when HoldTime is supported) are expressed using the PIROccupiedToUnoccupiedDelay, PIRUnoc­ +cupiedToOccupiedDelay and PIRUnoccupiedToOccupiedThreshold attributes. + +``` +Page 188 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +** These combinations of sensor type were not defined for OccupancySensorType in ClusterRevision + +<= 4, so they are mapped to a combination which _was_ defined in that version. + +**2.7.6.3. HoldTime Attribute** + +This attribute SHALL specify the time delay, in seconds, before the sensor changes to its unoccupied +state after the last detection of occupancy in the sensed area. This is equivalent to the legacy *Occu­ +piedToUnoccupiedDelay attributes. + +The value of HoldTime SHALL be within the limits provided in the HoldTimeLimits attribute, i.e. +HoldTimeMin <= HoldTime <= HoldTimeMax + +Low values of HoldTime SHOULD be avoided since they could lead to many reporting messages. A +value 0 for HoldTime SHALL NOT be used. + +The figure below illustrates this with an example of how this attribute is used for a PIR sensor. It +uses threshold detection to generate an "internal detection" signal, which needs post-processing to +become usable for transmission (traffic shaping). The bit in the Occupancy attribute will be set to 1 +when the internal detection signal goes high, and will stay at 1 for HoldTime after the (last) instance +where the internal detection signal goes low. + +The top half of the figure shows the case of a single trigger: the bit in the Occupancy attribute will +be 1 for the duration of the PIR signal exceeding the threshold plus HoldTime. The bottom half of +the figure shows the case of multiple triggers: the second trigger starts before the HoldTime of the +first trigger has expired; this results in a single period of the bit in the Occupancy attribute being 1. +The bit in the Occupancy attribute will be set to 1 from the start of the first period where the PIR +signal exceeds the threshold until HoldTime after the last moment where the PIR exceeded the +threshold. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 189 +``` + +_Figure 13. Processing of PIR signal towards Occupancy attribute using HoldTime_ + +**2.7.6.4. HoldTimeLimits Attribute** + +This attribute SHALL indicate the server’s limits, and default value, for the HoldTime attribute. + +**2.7.6.5. Attributes to support legacy implementations** + +The following 3 sets of 3 attributes each were used in ClusterRevision <= 4 to indicate timings and +conditions to tune the reporting by the sensor - separately for each of the three sensor modalities +defined in that revision. In ClusterRevision >= 5, these are replaced by the HoldTime attribute +(shared for all modalities). A server with ClusterRevision >= 5 MAY (under the conformance condi­ +tions stated in the attributes table above) provide these attributes for backward compatibility with +clients implementing a cluster revision <= 4. When doing so, the provided values for these legacy +*OccupiedToUnoccupied attributes SHALL follow the values in the HoldTime attribute when +updated, and vice-versa, such that any present *OccupiedToUnoccupiedDelay attribute maintains +equality to HoldTime. + +``` +Page 190 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Also see Backward Compatibility section. + +Some, but not all, of the implications of the conformance rules for these attributes are: + +- if attribute HoldTime is not supported, these 9 legacy attributes SHALL NOT be supported +- if modality PIR is supported, while both PHY and US modalities are not supported, + ◦ the 3 legacy attributes related to PIR MAY be supported (if allowed by the other rules) + ◦ the 6 legacy attributes related to Ultrasonic and PhysicalContact SHALL NOT be supported +- if modality US is supported while both PIR and PHY modalities are not supported: + ◦ the 3 legacy attributes related to UltraSonic MAY be supported (if allowed by the other rules) + ◦ the 6 legacy attributes related to PIR and PhysicalContact SHALL NOT be supported +- if modality PHY is supported while both PIR and US modalities are not supported: + ◦ the 3 legacy attributes related to PhysicalContact MAY be supported (if allowed by the other + rules) + ◦ the 6 legacy attributes related to PIR and Ultrasonic SHALL NOT be supported +- the legacy attributes related to UnoccupiedToOccupiedDelay and UnoccupiedToOccu­ + piedThreshold for a certain modality SHALL be both supported or both not supported +- if none of the modalities PIR, US, and PHY is supported (this case is presented as a PIR sensor for + compatibility): + ◦ the 3 legacy attributes related to PIR MAY be supported (if allowed by the other rules) + ◦ the 6 legacy attributes related to Ultrasonic and PhysicalContact SHALL NOT be supported + +For cases where more than one of the PIR, PHY and US modalities is supported _and_ the timing para­ +meters are provided for more than one modality, it is manufacturer specific how to combine those +timing parameters. + +**2.7.6.6. PIROccupiedToUnoccupiedDelay Attribute** + +This attribute SHALL specify the time delay, in seconds, before the PIR sensor changes to its unoccu­ +pied state after the last detection of occupancy in the sensed area. + +**2.7.6.7. PIRUnoccupiedToOccupiedDelay Attribute** + +This attribute SHALL specify the time delay, in seconds, before the PIR sensor changes to its occu­ +pied state after the first detection of occupancy in the sensed area. + +**2.7.6.8. PIRUnoccupiedToOccupiedThreshold Attribute** + +This attribute SHALL specify the number of occupancy detection events that must occur in the +period PIRUnoccupiedToOccupiedDelay, before the PIR sensor changes to its occupied state. + +**2.7.6.9. UltrasonicOccupiedToUnoccupiedDelay Attribute** + +This attribute SHALL specify the time delay, in seconds, before the Ultrasonic sensor changes to its +unoccupied state after the last detection of occupancy in the sensed area. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 191 +``` + +**2.7.6.10. UltrasonicUnoccupiedToOccupiedDelay Attribute** + +This attribute SHALL specify the time delay, in seconds, before the Ultrasonic sensor changes to its +occupied state after the first detection of occupancy in the sensed area. + +**2.7.6.11. UltrasonicUnoccupiedToOccupiedThreshold Attribute** + +This attribute SHALL specify the number of occupancy detection events that must occur in the +period UltrasonicUnoccupiedToOccupiedDelay, before the Ultrasonic sensor changes to its occupied +state. + +**2.7.6.12. PhysicalContactOccupiedToUnoccupiedDelay Attribute** + +This attribute SHALL specify the time delay, in seconds, before the physical contact occupancy sen­ +sor changes to its unoccupied state after detecting the unoccupied event. + +**2.7.6.13. PhysicalContactUnoccupiedToOccupiedDelay Attribute** + +This attribute SHALL specify the time delay, in seconds, before the physical contact sensor changes +to its occupied state after the first detection of the occupied event. + +**2.7.6.14. PhysicalContactUnoccupiedToOccupiedThreshold Attribute** + +This attribute SHALL specify the number of occupancy detection events that must occur in the +period PhysicalContactUnoccupiedToOccupiedDelay, before the PhysicalContact sensor changes to +its occupied state. + +**2.7.7. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 Occupancy­ +Changed +``` +### INFO V O + +**2.7.7.1. OccupancyChanged Event** + +If this event is supported, it SHALL be generated when the Occupancy attribute changes. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Occupancy Occupancy­ +Bitmap +``` +### M + +**2.7.7.1.1. Occupancy Field** + +This field SHALL indicate the new value of the Occupancy attribute. + +**2.8. Resource Monitoring Clusters** + +This generic cluster provides an interface to the current condition of a resource. A resource is a + +``` +Page 192 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +component of a device that is designed to be replaced, refilled, or emptied when exhausted or full. +Examples of resources include filters, cartridges, and water tanks. While batteries fit this definition +they are not intended to be used with this cluster. Use the power source cluster for batteries +instead. + +### NOTE + +``` +This cluster is not meant to be used for monitoring of the system resources, such as +processing, memory utilization, networking properties, etc. +``` +This cluster SHALL be used via an alias to a specific resource type (see Cluster IDs). + +**2.8.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**2.8.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint REPM +``` +**2.8.3. Cluster IDs** + +The table below is a list of aliased Cluster IDs which represent different resource types and conform +to this cluster definition. + +``` +ID Name PICS +0x0071 HEPA Filter Monitoring HEPAFREMON +0x0072 Activated Carbon Filter Moni­ +toring +``` +### ACFREMON + +``` +0x0079 Water Tank Level Monitoring WTLREPMON +``` +**2.8.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 CON Condition O Supports monitor­ +ing the condition +of the resource in +percentage +1 WRN Warning O Supports warning +indication +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 193 +``` + +``` +Bit Code Feature Conformance Summary +2 REP ReplacementPro­ +ductList +``` +``` +O Supports specify­ +ing the list of +replacement prod­ +ucts +``` +**2.8.5. Data Types** + +**2.8.5.1. DegradationDirectionEnum Type** + +This data type is derived from enum8. + +Indicates the direction in which the condition of the resource changes over time. + +``` +Value Name Summary Conformance +0 Up The degradation of the +resource is indicated by +an upwards mov­ +ing/increasing value +``` +### M + +``` +1 Down The degradation of the +resource is indicated by +a downwards mov­ +ing/decreasing value +``` +### M + +**2.8.5.2. ChangeIndicationEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 OK Resource is in good +condition, no interven­ +tion required +``` +### M + +``` +1 Warning Resource will be +exhausted soon, inter­ +vention will shortly be +required +``` +### WRN + +``` +2 Critical Resource is exhausted, +immediate intervention +is required +``` +### M + +**2.8.5.3. ProductIdentifierTypeEnum Type** + +This data type is derived from enum8. + +Indicate the type of identifier used to describe the product. Devices SHOULD use globally-recog­ +nized IDs over OEM specific ones. + +``` +Page 194 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0 UPC 12-digit Universal Prod­ +uct Code +``` +### M + +``` +1 GTIN-8 8-digit Global Trade +Item Number +``` +### M + +``` +2 EAN 13-digit European Arti­ +cle Number +``` +### M + +``` +3 GTIN-14 14-digit Global Trade +Item Number +``` +### M + +``` +4 OEM Original Equipment +Manufacturer part +number +``` +### M + +**2.8.5.4. ReplacementProductStruct Type** + +Indicates the product identifier that can be used as a replacement for the resource. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ProductI­ +dentifier­ +Type +``` +``` +ProductI­ +dentifier­ +TypeEnum +``` +``` +desc M +``` +``` +1 ProductI­ +dentifier­ +Value +``` +``` +string max 20 M +``` +**2.8.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Condition percent R V CON +0x0001 Degrada­ +tionDirec­ +tion +``` +``` +Degrada­ +tionDirec­ +tionEnum +``` +``` +desc F R V CON +``` +``` +0x0002 ChangeInd +ication +``` +``` +ChangeInd +icatio­ +nEnum +``` +### 0 R V M + +``` +0x0003 InPla­ +ceIndica­ +tor +``` +``` +bool R V O +``` +``` +0x0004 LastChang +edTime +``` +``` +epoch-s all X N null RW VO O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 195 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0005 Replace­ +mentPro­ +ductList +``` +``` +list[Replac +ement­ +Product­ +Struct] +``` +``` +max 5 F R V REP +``` +**2.8.6.1. Condition Attribute** + +This attribute SHALL indicate the current condition of the resource in percent. + +**2.8.6.2. DegradationDirection Attribute** + +This attribute SHALL indicate the direction of change for the condition of the resource over time, +which helps to determine whether a higher or lower condition value is considered optimal. + +**2.8.6.3. ChangeIndication Attribute** + +This attribute SHALL be populated with a value from ChangeIndicationEnum that is indicative of +the current requirement to change the resource. + +**2.8.6.4. InPlaceIndicator Attribute** + +This attribute SHALL indicate whether a resource is currently installed. A value of true SHALL indi­ +cate that a resource is installed. A value of false SHALL indicate that a resource is not installed. + +**2.8.6.5. LastChangedTime Attribute** + +This attribute MAY indicates the time at which the resource has been changed, if supported by the +server. The attribute SHALL be null if it was never set or is unknown. + +**2.8.6.6. ReplacementProductList Attribute** + +This attribute SHALL indicate the list of supported products that may be used as replacements for +the current resource. Each item in this list represents a unique ReplacementProductStruct. + +**2.8.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 ResetCondi­ +tion +``` +``` +client ⇒ server Y O O +``` +**2.8.7.1. ResetCondition Command** + +Upon receipt, the device SHALL reset the Condition and ChangeIndicator attributes, indicating full +resource availability and readiness for use, as initially configured. Invocation of this command +MAY cause the LastChangedTime to be updated automatically based on the clock of the server, if +the server supports setting the attribute. + +``` +Page 196 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.9. Air Quality Cluster** + +This cluster provides an interface to air quality classification using distinct levels with human-read­ +able labels. + +**2.9.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**2.9.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint AIRQUAL +``` +**2.9.3. Cluster ID** + +``` +ID Name +0x005B Air Quality +``` +**2.9.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 FAIR Fair O Cluster supports +the Fair air quality +level +1 MOD Moderate O Cluster supports +the Moderate air +quality level +2 VPOOR VeryPoor O Cluster supports +the Very poor air +quality level +3 XPOOR ExtremelyPoor O Cluster supports +the Extremely +poor air quality +level +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 197 +``` + +**2.9.5. Data Types** + +**2.9.5.1. AirQualityEnum Type** + +This data type is derived from enum8. + +The AirQualityEnum provides a representation of the quality of the analyzed air. It is up to the +device manufacturer to determine the mapping between the measured values and their corre­ +sponding enumeration values. + +``` +Value Name Summary Conformance +0 Unknown The air quality is +unknown. +``` +### M + +``` +1 Good The air quality is good. M +2 Fair The air quality is fair. FAIR +3 Moderate The air quality is mod­ +erate. +``` +### MOD + +``` +4 Poor The air quality is poor. M +5 VeryPoor The air quality is very +poor. +``` +### VPOOR + +``` +6 ExtremelyPoor The air quality is +extremely poor. +``` +### XPOOR + +**2.9.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 AirQuality AirQuali­ +tyEnum +``` +``` +desc 0 R V M +``` +**2.9.6.1. AirQuality Attribute** + +This attribute SHALL indicate a value from AirQualityEnum that is indicative of the currently mea­ +sured air quality. + +**2.10. Concentration Measurement Clusters** + +The server cluster provides an interface to concentration measurement functionality. + +This cluster SHALL to be used via an alias to a specific substance (see Cluster IDs). + +**2.10.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Page 198 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 CCB 2882 +3 Cluster redesigned to add support for Level Indi­ +cation, Peak/Average Measurement, +Medium/Unit of Measurement and Uncertainty. +``` +**2.10.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint CONC +``` +**2.10.3. Cluster IDs** + +The table below is a list of Cluster IDs that conform to this specification. + +``` +ID Name PICS +0x040C Carbon Monoxide Concentra­ +tion Measurement +``` +### CMOCONC + +``` +0x040D Carbon Dioxide Concentration +Measurement +``` +### CDOCONC + +``` +0x0413 Nitrogen Dioxide Concentration +Measurement +``` +### NDOCONC + +``` +0x0415 Ozone Concentration Measure­ +ment +``` +### OZCONC + +``` +0x042A PM2.5 Concentration Measure­ +ment +``` +### PMICONC + +``` +0x042B Formaldehyde Concentration +Measurement +``` +### FLDCONC + +``` +0x042C PM1 Concentration Measure­ +ment +``` +### PMHCONC + +``` +0x042D PM10 Concentration Measure­ +ment +``` +### PMKCONC + +``` +0x042E Total Volatile Organic Com­ +pounds Concentration Measure­ +ment +``` +### TVOCCONC + +``` +0x042F Radon Concentration Measure­ +ment +``` +### RNCONC + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 199 +``` + +**2.10.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 MEA NumericMeasure­ +ment +``` +``` +O.a+ Cluster supports +numeric measure­ +ment of substance +1 LEV LevelIndication O.a+ Cluster supports +basic level indica­ +tion for substance +using the Concen­ +trationLevel enum +2 MED MediumLevel [LEV] Cluster supports +the Medium Con­ +centration Level +3 CRI CriticalLevel [LEV] Cluster supports +the Critical Con­ +centration Level +4 PEA PeakMeasurement [MEA] Cluster supports +peak numeric +measurement of +substance +5 AVG AverageMeasure­ +ment +``` +``` +[MEA] Cluster supports +average numeric +measurement of +substance +``` +**2.10.5. Data Types** + +**2.10.5.1. MeasurementUnitEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 PPM Parts per Million (10^6 ) MEA +1 PPB Parts per Billion (10^9 ) MEA +2 PPT Parts per Trillion (10^12 ) MEA +3 MGM3 Milligram per m^3 MEA +4 UGM3 Microgram per m^3 MEA +5 NGM3 Nanogram per m^3 MEA +6 PM3 Particles per m^3 MEA +``` +``` +Page 200 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +7 BQM3 Becquerel per m^3 MEA +``` +Where mentioned, Billion refers to 10^9 , Trillion refers to 10^12 (short scale). + +**2.10.5.2. MeasurementMediumEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Air The measurement is +being made in Air +``` +### M + +``` +1 Water The measurement is +being made in Water +``` +### M + +``` +2 Soil The measurement is +being made in Soil +``` +### M + +**2.10.5.3. LevelValueEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown The level is Unknown M +1 Low The level is considered +Low +``` +### M + +``` +2 Medium The level is considered +Medium +``` +### MED + +``` +3 High The level is considered +High +``` +### M + +``` +4 Critical The level is considered +Critical +``` +### CRI + +**2.10.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Measured­ +Value +``` +``` +single MinMea­ +suredValue +to +MaxMea­ +suredValue +``` +``` +X P null R V MEA +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 201 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0001 MinMea­ +sured­ +Value +``` +``` +single all X null R V MEA +``` +``` +0x0002 MaxMea­ +sured­ +Value +``` +``` +single min Min­ +Measured­ +Value +``` +``` +X null R V MEA +``` +``` +0x0003 PeakMea­ +sured­ +Value +``` +``` +single MinMea­ +suredValue +to +MaxMea­ +suredValue +``` +``` +X P null R V PEA +``` +``` +0x0004 PeakMea­ +suredVal­ +ueWindow +``` +``` +elapsed-s max +604800 +``` +### P 1 R V PEA + +``` +0x0005 Average­ +Measured­ +Value +``` +``` +single MinMea­ +suredValue +to +MaxMea­ +suredValue +``` +``` +X P null R V AVG +``` +``` +0x0006 Average­ +Measured­ +ValueWin­ +dow +``` +``` +elapsed-s max +604800 +``` +### P 1 R V AVG + +``` +0x0007 Uncer­ +tainty +``` +``` +single MS MS R V [MEA] +``` +``` +0x0008 Measure­ +mentUnit +``` +``` +Measure­ +mentU­ +nitEnum +``` +### F MS R V MEA + +``` +0x0009 Measure­ +mentMedi +um +``` +``` +Measure­ +mentMedi­ +umEnum +``` +### F MS R V M + +``` +0x000A Level­ +Value +``` +``` +LevelVal­ +ueEnum +``` +### 0 R V LEV + +**2.10.6.1. MeasuredValue Attribute** + +This attribute SHALL represent the most recent measurement as a single-precision floating-point +number. MeasuredValue’s unit is represented by MeasurementUnit. + +A value of null indicates that the measurement is unknown or outside the valid range. + +MinMeasuredValue and MaxMeasuredValue define the valid range for MeasuredValue. + +``` +Page 202 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.10.6.2. MinMeasuredValue Attribute** + +This attribute SHALL represent the minimum value of MeasuredValue that is capable of being mea­ +sured. A MinMeasuredValue of null indicates that the MinMeasuredValue is not defined. + +**2.10.6.3. MaxMeasuredValue Attribute** + +This attribute SHALL represent the maximum value of MeasuredValue that is capable of being mea­ +sured. A MaxMeasuredValue of null indicates that the MaxMeasuredValue is not defined. + +**2.10.6.4. PeakMeasuredValue Attribute** + +This attribute SHALL represent the maximum value of MeasuredValue that has been measured +during the PeakMeasuredValueWindow. If this attribute is provided, the PeakMeasuredValueWin­ +dow attribute SHALL also be provided. + +**2.10.6.5. PeakMeasuredValueWindow Attribute** + +This attribute SHALL represent the window of time used for determining the PeakMeasuredValue. +The value is in seconds. + +**2.10.6.6. AverageMeasuredValue Attribute** + +This attribute SHALL represent the average value of MeasuredValue that has been measured dur­ +ing the AverageMeasuredValueWindow. If this attribute is provided, the AverageMeasuredVal­ +ueWindow attribute SHALL also be provided. + +**2.10.6.7. AverageMeasuredValueWindow Attribute** + +This attribute SHALL represent the window of time used for determining the AverageMeasured­ +Value. The value is in seconds. + +**2.10.6.8. Uncertainty Attribute** + +This attribute SHALL represent the range of error or deviation that can be found in MeasuredValue +and PeakMeasuredValue. This is considered a +/- value and should be considered to be in Measure­ +mentUnit. + +**2.10.6.9. MeasurementUnit Attribute** + +This attribute SHALL represent the unit of MeasuredValue. See MeasurementUnitEnum. + +**2.10.6.10. MeasurementMedium Attribute** + +This attribute SHALL represent the medium in which MeasuredValue is being measured. See Mea­ +surementMediumEnum. + +**2.10.6.11. LevelValue Attribute** + +This attribute SHALL represent the level of the substance detected. See LevelValueEnum. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 203 +``` + +**2.11. Smoke CO Alarm Cluster** + +This cluster provides an interface for observing and managing the state of smoke and CO alarms. + +**2.11.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**2.11.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint SMOKECO +``` +**2.11.3. Cluster ID** + +``` +ID Name +0x005C Smoke CO Alarm +``` +**2.11.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 SMOKE SmokeAlarm O.a+ Supports Smoke +alarm +1 CO COAlarm O.a+ Supports CO alarm +``` +**2.11.5. Data Types** + +**2.11.5.1. AlarmStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Normal Nominal state, the +device is not alarming +``` +### M + +``` +1 Warning Warning state O +2 Critical Critical state M +``` +``` +Page 204 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.11.5.1.1. Normal Value** + +This value SHALL indicate that this alarm is not alarming. + +**2.11.5.1.2. Warning Value** + +This value SHALL indicate that this alarm is in a warning state. Alarms in this state SHOULD be sub­ +ject to being muted via physical interaction. + +**2.11.5.1.3. Critical Value** + +This value SHALL indicate that this alarm is in a critical state. Alarms in this state SHALL NOT be +subject to being muted via physical interaction. + +**2.11.5.2. SensitivityEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 High High sensitivity O +1 Standard Standard Sensitivity M +2 Low Low sensitivity O +``` +**2.11.5.3. ExpressedStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Normal Nominal state, the +device is not alarming +``` +### M + +``` +1 SmokeAlarm Smoke Alarm state SMOKE +2 COAlarm CO Alarm state CO +3 BatteryAlert Battery Alert State M +4 Testing Test in Progress M +5 HardwareFault Hardware Fault Alert +State +``` +### M + +``` +6 EndOfService End of Service Alert +State +``` +### M + +``` +7 InterconnectSmoke Interconnected Smoke +Alarm State +``` +### O + +``` +8 InterconnectCO Interconnected CO +Alarm State +``` +### O + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 205 +``` + +**2.11.5.3.1. Normal Value** + +This value SHALL indicate that this alarm is not alarming. + +**2.11.5.3.2. SmokeAlarm Value** + +This value SHALL indicate that this alarm is currently expressing visual indication of Smoke Alarm. +This value SHALL indicate that the alarm is currently expressing audible indication of Smoke +Alarm unless the DeviceMuted attribute is supported and set to Muted. + +**2.11.5.3.3. COAlarm Value** + +This value SHALL indicate that this alarm is currently expressing visual indication of CO Alarm. +This value SHALL indicate that the alarm is currently expressing audible indication of CO Alarm +unless the DeviceMuted attribute is supported and set to Muted. + +**2.11.5.3.4. BatteryAlert Value** + +This value SHALL indicate that this alarm is currently expressing visual indication of Critical Low +Battery. This value SHALL indicate that the alarm is currently expressing audible indication of Criti­ +cal Low Battery unless the DeviceMuted attribute is supported and set to Muted. + +**2.11.5.3.5. Testing Value** + +This value SHALL indicate that this alarm is currently expressing visual and audible indication of +SelfTest. + +**2.11.5.3.6. HardwareFault Value** + +This value SHALL indicate that this alarm is currently expressing visual indication of Hardware +Fault. This value SHALL indicate that the alarm is currently expressing audible indication of Hard­ +ware Fault unless the DeviceMuted attribute is supported and set to Muted. + +**2.11.5.3.7. EndOfService Value** + +This value SHALL indicate that this alarm is currently expressing visual indication of End Of Ser­ +vice. This value SHALL indicate that the alarm is currently expressing audible indication of End of +Service unless the DeviceMuted attribute is supported and set to Muted. + +**2.11.5.3.8. InterconnectSmoke Value** + +This value SHALL indicate that this alarm is currently expressing visual indication of Smoke Alarm +caused by Interconnect. This value SHALL indicate that the alarm is currently expressing audible +indication of Smoke Alarm caused by Interconnect unless the DeviceMuted attribute is supported +and set to Muted. + +**2.11.5.3.9. InterconnectCO Value** + +This value SHALL indicate that this alarm is currently expressing visual indication of CO Alarm +caused by Interconnect. This value SHALL indicate that the alarm is currently expressing audible +indication of CO Alarm caused by Interconnect unless the DeviceMuted attribute is supported and +set to Muted. + +``` +Page 206 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.11.5.4. MuteStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 NotMuted Not Muted M +1 Muted Muted M +``` +**2.11.5.4.1. NotMuted Value** + +This value SHALL indicate that the device is not muted. + +**2.11.5.4.2. Muted Value** + +This value SHALL indicate that the device is muted. + +**2.11.5.5. EndOfServiceEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Normal Device has not expired M +1 Expired Device has reached its +end of service +``` +### M + +**2.11.5.5.1. Expired Value** + +This value SHALL indicate that the device has reached its end of service, and needs to be replaced. + +**2.11.5.5.2. Normal Value** + +This value SHALL indicate that the device has not yet reached its end of service, and does not need +to be imminently replaced. + +**2.11.5.6. ContaminationStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Normal Nominal state, the sen­ +sor is not contaminated +``` +### M + +``` +1 Low Low contamination O +2 Warning Warning state O +3 Critical Critical state, will cause +nuisance alarms +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 207 +``` + +**2.11.5.6.1. Normal Value** + +This value SHALL indicate that the smoke sensor has nominal contamination levels, no customer +action is required. + +**2.11.5.6.2. Low Value** + +This value SHALL indicate that the smoke sensor has detectable contamination levels, but the cont­ +amination is too low to cause a visible or audible alarm. + +**2.11.5.6.3. Warning Value** + +This value SHALL indicate that the smoke sensor has contamination levels in a warning state. At +this level, the contamination may cause a visible or audible alarm. User intervention is suggested. + +**2.11.5.6.4. Critical Value** + +This value SHALL indicate that the smoke sensor has contamination levels in a critical state. At this +level, the contamination should cause a visible or audible alarm. User intervention is required. Crit­ +ical contamination of the sensor SHALL also be reflected as a HardwareFault. + +**2.11.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Expressed +State +``` +``` +Expressed­ +StateEnum +``` +``` +all N R V M +``` +``` +0x0001 Smoke­ +State +``` +``` +AlarmSta­ +teEnum +``` +``` +all N R V SMOKE +``` +``` +0x0002 COState AlarmSta­ +teEnum +``` +``` +all N R V CO +``` +``` +0x0003 Bat­ +teryAlert +``` +``` +AlarmSta­ +teEnum +``` +``` +all N R V M +``` +``` +0x0004 Device­ +Muted +``` +``` +MuteSta­ +teEnum +``` +``` +all N R V O +``` +``` +0x0005 TestIn­ +Progress +``` +``` +bool all R V M +``` +``` +0x0006 Hardware­ +FaultAlert +``` +``` +bool all N R V M +``` +``` +0x0007 EndOfSer­ +viceAlert +``` +``` +EndOfSer­ +viceEnum +``` +``` +all N R V M +``` +``` +0x0008 Intercon­ +nectSmok +eAlarm +``` +``` +AlarmSta­ +teEnum +``` +``` +all R V O +``` +``` +Page 208 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0009 Intercon­ +nect­ +COAlarm +``` +``` +AlarmSta­ +teEnum +``` +``` +all R V O +``` +``` +0x000A Contami­ +nation­ +State +``` +``` +Contami­ +nationSta­ +teEnum +``` +``` +all R V [SMOKE] +``` +``` +0x000B Smoke­ +Sensitiv­ +ityLevel +``` +``` +Sensitivi­ +tyEnum +``` +``` +all RW VM [SMOKE] +``` +``` +0x000C Expiry­ +Date +``` +``` +epoch-s all F R V O +``` +**2.11.6.1. ExpressedState Attribute** + +This attribute SHALL indicate the visibly- and audibly-expressed state of the alarm. When multiple +alarm conditions are being reflected in the server, this attribute SHALL indicate the condition with +the highest priority. Priority order of conditions is determined by the manufacturer and SHALL be +supplied as a part of certification procedure. If the value of ExpressedState is not Normal, the +attribute corresponding to the value SHALL NOT be Normal. For example, if the ExpressedState is +set to SmokeAlarm, the value of the SmokeState will indicate the severity of the alarm (Warning or +Critical). Clients SHOULD also read the other attributes to be aware of further alarm conditions +beyond the one indicated in ExpressedState. + +Visible expression is typically a LED light pattern. Audible expression is a horn or speaker pattern. +Audible expression SHALL BE suppressed if the DeviceMuted attribute is supported and set to +Muted. + +**2.11.6.2. SmokeState Attribute** + +This attribute SHALL indicate whether the device’s smoke sensor is currently triggering a smoke +alarm. + +**2.11.6.3. COState Attribute** + +This attribute SHALL indicate whether the device’s CO sensor is currently triggering a CO alarm. + +**2.11.6.4. BatteryAlert Attribute** + +This attribute SHALL indicate whether the power resource fault detection mechanism is currently +triggered at the device. If the detection mechanism is triggered, this attribute SHALL be set to Warn­ +ing or Critical, otherwise it SHALL be set to Normal. The battery state SHALL also be reflected in the +Power Source cluster representing the device’s battery using the appropriate supported attributes +and events. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 209 +``` + +**2.11.6.5. DeviceMuted Attribute** + +This attribute SHALL indicate the whether the audible expression of the device is currently muted. +Audible expression is typically a horn or speaker pattern. + +**2.11.6.6. TestInProgress Attribute** + +This attribute SHALL indicate whether the device self-test is currently activated. If the device self- +test is activated, this attribute SHALL be set to True, otherwise it SHALL be set to False. + +**2.11.6.7. HardwareFaultAlert Attribute** + +This attribute SHALL indicate whether the hardware fault detection mechanism is currently trig­ +gered. If the detection mechanism is triggered, this attribute SHALL be set to True, otherwise it +SHALL be set to False. + +**2.11.6.8. EndOfServiceAlert Attribute** + +This attribute SHALL indicate whether the end-of-service has been triggered at the device. This +attribute SHALL be set to Expired when the device reaches the end-of-service. + +**2.11.6.9. InterconnectSmokeAlarm Attribute** + +This attribute SHALL indicate whether the interconnected smoke alarm is currently triggering by +branching devices. When the interconnected smoke alarm is being triggered, this attribute SHALL +be set to Warning or Critical, otherwise it SHALL be set to Normal. + +**2.11.6.10. InterconnectCOAlarm Attribute** + +This attribute SHALL indicate whether the interconnected CO alarm is currently triggering by +branching devices. When the interconnected CO alarm is being triggered, this attribute SHALL be +set to Warning or Critical, otherwise it SHALL be set to Normal. + +**2.11.6.11. ContaminationState Attribute** + +This attribute SHALL indicate the contamination level of the smoke sensor. + +**2.11.6.12. SmokeSensitivityLevel Attribute** + +This attribute SHALL indicate the sensitivity level of the smoke sensor configured on the device. + +**2.11.6.13. ExpiryDate Attribute** + +This attribute SHALL indicate the date when the device reaches its stated expiry date. After the +ExpiryDate has been reached, the EndOfServiceAlert SHALL start to be triggered. To account for +better customer experience across time zones, the EndOfServiceAlert MAY be delayed by up to 24 +hours after the ExpiryDate. Similarly, clients MAY delay any actions based on the ExpiryDate by up +to 24 hours to best align with the local time zone. + +``` +Page 210 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.11.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 SelfTestRe­ +quest +``` +``` +client ⇒ server Y O O +``` +**2.11.7.1. SelfTestRequest Command** + +This command SHALL initiate a device self-test. The return status SHALL indicate whether the test +was successfully initiated. Only one SelfTestRequest may be processed at a time. When the value of +the ExpressedState attribute is any of SmokeAlarm, COAlarm, Testing, InterconnectSmoke, Inter­ +connectCO, the device SHALL NOT execute the self-test, and SHALL return status code BUSY. + +Upon successful acceptance of SelfTestRequest, the TestInProgress attribute SHALL be set to True +and ExpressedState attribute SHALL be set to Testing. Any faults identified during the test SHALL +be reflected in the appropriate attributes and events. Upon completion of the self test procedure, +the SelfTestComplete event SHALL be generated, the TestInProgress attribute SHALL be set to False +and ExpressedState attribute SHALL be updated to reflect the current state of the server. + +**2.11.8. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 SmokeAlarm CRITICAL V SMOKE +0x01 COAlarm CRITICAL V CO +0x02 LowBattery INFO V M +0x03 Hardware­ +Fault +``` +### INFO V M + +``` +0x04 EndOfService INFO V M +0x05 SelfTestCom­ +plete +``` +### INFO V M + +``` +0x06 AlarmMuted INFO V O +0x07 MuteEnded INFO V O +0x08 Intercon­ +nectSmokeAla +rm +``` +### CRITICAL V [SMOKE] + +``` +0x09 Interconnect­ +COAlarm +``` +### CRITICAL V [CO] + +``` +0x0A AllClear INFO V M +``` +**2.11.8.1. SmokeAlarm Event** + +This event SHALL be generated when SmokeState attribute changes to either Warning or Critical +state. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 211 +``` + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Alarm­ +Sever­ +ityLevel +``` +``` +AlarmSta­ +teEnum +``` +``` +all M +``` +**2.11.8.1.1. AlarmSeverityLevel Field** + +This field SHALL indicate the current value of the SmokeState attribute. + +**2.11.8.2. COAlarm Event** + +This event SHALL be generated when COState attribute changes to either Warning or Critical state. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Alarm­ +Sever­ +ityLevel +``` +``` +AlarmSta­ +teEnum +``` +``` +all M +``` +**2.11.8.2.1. AlarmSeverityLevel Field** + +This field SHALL indicate the current value of the COState attribute. + +**2.11.8.3. LowBattery Event** + +This event SHALL be generated when BatteryAlert attribute changes to either Warning or Critical +state. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Alarm­ +Sever­ +ityLevel +``` +``` +AlarmSta­ +teEnum +``` +``` +all M +``` +**2.11.8.3.1. AlarmSeverityLevel Field** + +This field SHALL indicate the current value of the BatteryAlert attribute. + +**2.11.8.4. HardwareFault Event** + +This event SHALL be generated when the device detects a hardware fault that leads to setting Hard­ +wareFaultAlert to True. + +``` +Page 212 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.11.8.5. EndOfService Event** + +This event SHALL be generated when the EndOfServiceAlert is set to Expired. + +**2.11.8.6. SelfTestComplete Event** + +This event SHALL be generated when the SelfTest completes, and the attribute TestInProgress +changes to False. + +**2.11.8.7. AlarmMuted Event** + +This event SHALL be generated when the DeviceMuted attribute changes to Muted. + +**2.11.8.8. MuteEnded Event** + +This event SHALL be generated when DeviceMuted attribute changes to NotMuted. + +**2.11.8.9. InterconnectSmokeAlarm Event** + +This event SHALL be generated when the device hosting the server receives a smoke alarm from an +interconnected sensor. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Alarm­ +Sever­ +ityLevel +``` +``` +AlarmSta­ +teEnum +``` +``` +all M +``` +**2.11.8.9.1. AlarmSeverityLevel Field** + +This field SHALL indicate the current value of the InterconnectSmokeAlarm attribute. + +**2.11.8.10. InterconnectCOAlarm Event** + +This event SHALL be generated when the device hosting the server receives a CO alarm from an +interconnected sensor. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Alarm­ +Sever­ +ityLevel +``` +``` +AlarmSta­ +teEnum +``` +``` +all M +``` +**2.11.8.10.1. AlarmSeverityLevel Field** + +This field SHALL indicate the current value of the InterconnectCOAlarm attribute. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 213 +``` + +**2.11.8.11. AllClear Event** + +This event SHALL be generated when ExpressedState attribute returns to Normal state. + +**2.12. Electrical Energy Measurement Cluster** + +This cluster provides a mechanism for querying data about the electrical energy imported or pro­ +vided by the server. + +**2.12.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**2.12.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint EEM +``` +**2.12.3. Cluster ID** + +``` +ID Name +0x0091 Electrical Energy Measurement +``` +**2.12.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 IMPE ImportedEnergy O.a+ Measurement of +energy imported +by the server +1 EXPE ExportedEnergy O.a+ Measurement of +energy provided +by the server +2 CUME CumulativeEnergy O.b+ Measurements are +cumulative +3 PERE PeriodicEnergy O.b+ Measurements are +periodic +``` +``` +Page 214 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.12.4.1. ImportedEnergy Feature** + +The feature indicates the server is capable of measuring how much energy is imported by the +server. + +**2.12.4.2. ExportedEnergy Feature** + +The feature indicates the server is capable of measuring how much energy is exported by the +server. + +**2.12.4.3. CumulativeEnergy Feature** + +The feature indicates the server is capable of measuring how much energy has been imported or +exported by the server over the device’s lifetime. This measurement MAY start from when a +device’s firmware is updated to include this feature, when a device’s firmware is updated to correct +measurement errors, or when a device is factory reset. + +**2.12.4.4. PeriodicEnergy Feature** + +The feature indicates the server is capable of measuring how much energy has been imported or +exported by the server during a certain period of time. The start and end times for measurement +periods SHALL be determined by the server, and MAY represent overlapping periods. + +**2.12.5. Data Types** + +**2.12.5.1. EnergyMeasurementStruct Type** + +This struct SHALL indicate the amount of energy measured during a given measurement period. + +A server which does not have the ability to determine the time in UTC, or has not yet done so, +SHALL use the system time fields to specify the measurement period and observation times. + +A server which has determined the time in UTC SHALL use the timestamp fields to specify the mea­ +surement period. Such a server MAY also include the systime fields to indicate how many seconds +had passed since boot for a given timestamp; this allows for client-side resolution of UTC time for +previous reports that only included systime. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Energy energy- +mWh +``` +``` +0 to 2^62 M +``` +``` +1 StartTime­ +stamp +``` +``` +epoch-s desc +``` +``` +2 EndTime­ +stamp +``` +``` +epoch-s min (Start­ +Timestamp ++ 1) +``` +``` +desc +``` +``` +3 StartSys­ +time +``` +``` +systime-ms desc +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 215 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +4 EndSys­ +time +``` +``` +systime-ms min (Start­ +Systime + +1) +``` +``` +desc +``` +**2.12.5.1.1. Energy Field** + +This field SHALL be the reported energy. + +If the EnergyMeasurementStruct represents cumulative energy, then this SHALL represent the +cumulative energy recorded at either the value of the EndTimestamp field or the value of the +EndSystime field, or both. + +If the EnergyMeasurementStruct represents periodic energy, then this SHALL represent the energy +recorded during the period specified by either the StartTimestamp and EndTimestamp fields, the +period specified by the StartSystime and EndSystime fields, or both. + +**2.12.5.1.2. StartTimestamp Field** + +This field SHALL indicate the timestamp in UTC of the beginning of the period during which the +value of the Energy field was measured. + +If this EnergyMeasurementStruct represents cumulative energy, this field SHALL be omitted. + +Otherwise, if the server had determined the time in UTC at or before the beginning of the measure­ +ment period, this field SHALL be indicated. + +Otherwise, if the server had not yet determined the time in UTC at or before the beginning of the +measurement period, or does not have the capability of determining the time in UTC, this field +SHALL be omitted. + +**2.12.5.1.3. EndTimestamp Field** + +This field SHALL indicate the timestamp in UTC of the end of the period during which the value of +the Energy field was measured. + +If the server had determined the time in UTC by the end of the measurement period, this field +SHALL be indicated. + +Otherwise, if the server had not yet determined the time in UTC by the end of the measurement +period, or does not have the capability of determining the time in UTC, this field SHALL be omitted. + +**2.12.5.1.4. StartSystime Field** + +This field SHALL indicate the time elapsed since boot at the beginning of the period during which +the value of the Energy field was measured. + +If this EnergyMeasurementStruct represents cumulative energy, this field SHALL be omitted. + +Otherwise, if the server had not yet determined the time in UTC at the start of the measurement + +``` +Page 216 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +period, or does not have the capability of determining the time in UTC, this field SHALL be indi­ +cated. + +Otherwise, if the server had determined the time in UTC at or before the beginning of the measure­ +ment period, this field MAY be omitted; if it is indicated, its value SHALL be the time elapsed since +boot at the UTC time indicated in StartTimestamp. + +**2.12.5.1.5. EndSystime Field** + +This field SHALL indicate the time elapsed since boot at the end of the period during which the +value of the Energy field was measured. + +If the server had not yet determined the time in UTC by the end of the measurement period, or does +not have the capability of determining the time in UTC, this field SHALL be indicated. + +Otherwise, if the server had determined the time in UTC by the end of the measurement period, this +field MAY be omitted; if it is indicated, its value SHALL be the time elapsed since boot at the UTC +time indicated in EndTimestamp. + +**2.12.5.2. CumulativeEnergyResetStruct Type** + +This struct SHALL represent the times at which cumulative measurements were last zero, either +due to initialization of the device, or an internal reset of the cumulative value. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Importe­ +dReset­ +Time­ +stamp +``` +``` +epoch-s X null [IMPE] +``` +``` +1 Exporte­ +dReset­ +Time­ +stamp +``` +``` +epoch-s X null [EXPE] +``` +``` +2 Importe­ +dResetSys­ +time +``` +``` +systime-ms X null [IMPE] +``` +``` +3 Exporte­ +dResetSys­ +time +``` +``` +systime-ms X null [EXPE] +``` +**2.12.5.2.1. ImportedResetTimestamp Field** + +This field SHALL indicate the timestamp in UTC when the value of the Energy field on the Cumula­ +tiveEnergyImported attribute was most recently zero. + +If the server had determined the time in UTC when the value of the Energy field on the Cumula­ +tiveEnergyImported attribute was most recently zero, this field SHALL be indicated. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 217 +``` + +Otherwise, if the server had not yet determined the time in UTC when the value of the Energy field +on the CumulativeEnergyImported attribute was most recently zero, or does not have the capability +of determining the time in UTC, this field SHALL be omitted. + +If the timestamp in UTC when the value of the Energy field on the CumulativeEnergyImported +attribute was most recently zero cannot currently be determined, a value of null SHALL be +returned. + +**2.12.5.2.2. ExportedResetTimestamp Field** + +This field SHALL indicate the timestamp in UTC when the value of the Energy field on the Cumula­ +tiveEnergyExported attribute was most recently zero. + +If the server had determined the time in UTC when the value of the Energy field on the Cumula­ +tiveEnergyExported attribute was most recently zero, this field SHALL be indicated. + +Otherwise, if the server had not yet determined the time in UTC when the value of the Energy field +on the CumulativeEnergyExported attribute was most recently zero, or does not have the capability +of determining the time in UTC, this field SHALL be omitted. + +If the timestamp in UTC when the value of the Energy field on the CumulativeEnergyExported +attribute was most recently zero cannot currently be determined, a value of null SHALL be +returned. + +**2.12.5.2.3. ImportedResetSystime Field** + +This field SHALL indicate the time elapsed since boot when the value of the Energy field on the +CumulativeEnergyImported attribute was most recently zero. + +If the server had not yet determined the time in UTC when the value of the Energy field on the +CumulativeEnergyImported attribute was most recently zero, or does not have the capability of +determining the time in UTC, this field SHALL be indicated. + +Otherwise, if the server had determined the time in UTC when the value of the Energy field on the +CumulativeEnergyImported attribute was most recently zero, this field MAY be omitted; if it is indi­ +cated, its value SHALL be the time elapsed since boot at the UTC time indicated in ImportedReset­ +Timestamp. + +**2.12.5.2.4. ExportedResetSystime Field** + +This field SHALL indicate the time elapsed since boot when the value of the Energy field on the +CumulativeEnergyExported attribute was most recently zero. + +If the server had not yet determined the time in UTC when the value of the Energy field on the +CumulativeEnergyExported attribute was most recently zero, or does not have the capability of +determining the time in UTC, this field SHALL be indicated. + +Otherwise, if the server had determined the time in UTC when the value of the Energy field on the +CumulativeEnergyExported attribute was most recently zero, this field MAY be omitted; if it is indi­ +cated, its value SHALL be the time elapsed since boot at the UTC time indicated in ImportedReset­ +Timestamp. + +``` +Page 218 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.12.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Accuracy Measure­ +mentAccu­ +racyStruct +``` +### F R V M + +``` +0x0001 Cumula­ +tiveEner­ +gyIm­ +ported +``` +``` +Ener­ +gyMea­ +sure­ +mentStruct +``` +``` +X Q null R V IMPE & +CUME +``` +``` +0x0002 Cumula­ +tiveEner­ +gyEx­ +ported +``` +``` +Ener­ +gyMea­ +sure­ +mentStruct +``` +``` +X Q null R V EXPE & +CUME +``` +``` +0x0003 Peri­ +odicEner­ +gyIm­ +ported +``` +``` +Ener­ +gyMea­ +sure­ +mentStruct +``` +``` +X Q null R V IMPE & +PERE +``` +``` +0x0004 Peri­ +odicEner­ +gyEx­ +ported +``` +``` +Ener­ +gyMea­ +sure­ +mentStruct +``` +``` +X Q null R V EXPE & +PERE +``` +``` +0x0005 Cumula­ +tiveEner­ +gyReset +``` +``` +Cumula­ +tiveEner­ +gyReset­ +Struct +``` +``` +X null R V [CUME] +``` +**2.12.6.1. Accuracy Attribute** + +This attribute SHALL indicate the accuracy of energy measurement by this server. The value of the +MeasurementType field on this MeasurementAccuracyStruct SHALL be ElectricalEnergy. + +**2.12.6.2. CumulativeEnergyImported Attribute** + +This attribute SHALL indicate the most recent measurement of cumulative energy imported by the +server over the lifetime of the device, and the timestamp of when the measurement was recorded. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 219 +``` + +If the cumulative energy imported cannot currently be determined, a value of null SHALL be +returned. + +**2.12.6.3. CumulativeEnergyExported Attribute** + +This attribute SHALL indicate the most recent measurement of cumulative energy exported by the +server over the lifetime of the device, and the timestamp of when the measurement was recorded. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the cumulative energy exported cannot currently be determined, a value of null SHALL be +returned. + +**2.12.6.4. PeriodicEnergyImported Attribute** + +This attribute SHALL indicate the most recent measurement of energy imported by the server and +the period during which it was measured. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the periodic energy imported cannot currently be determined, a value of null SHALL be returned. + +**2.12.6.5. PeriodicEnergyExported Attribute** + +This attribute SHALL indicate the most recent measurement of energy exported by the server and +the period during which it was measured. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the periodic energy exported cannot currently be determined, a value of null SHALL be returned. + +``` +Page 220 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.12.6.6. CumulativeEnergyReset Attribute** + +This attribute SHALL indicate when cumulative measurements were most recently zero. + +**2.12.7. Events** + +This cluster SHALL support these events: + +``` +ID Name Priority Quality Access Conformance +0 CumulativeEn­ +ergyMeasured +``` +### INFO V CUME + +``` +1 PeriodicEner­ +gyMeasured +``` +### INFO V PERE + +**2.12.7.1. CumulativeEnergyMeasured Event** + +This event SHALL be generated when the server takes a snapshot of the cumulative energy +imported by the server, exported from the server, or both, but not more frequently than the rate +mentioned in the description above of the related attribute. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 EnergyIm­ +ported +``` +``` +EnergyMea­ +sure­ +mentStruct +``` +### CUME & + +### IMPE + +``` +1 EnergyEx­ +ported +``` +``` +EnergyMea­ +sure­ +mentStruct +``` +### CUME & + +### EXPE + +**2.12.7.1.1. EnergyImported Field** + +This field SHALL be the value of CumulativeEnergyImported attribute at the timestamp indicated in +its EndTimestamp field, EndSystime field, or both. + +**2.12.7.1.2. EnergyExported Field** + +This field SHALL be the value of CumulativeEnergyExported attribute at the timestamp indicated in +its EndTimestamp field, EndSystime field, or both. + +**2.12.7.2. PeriodicEnergyMeasured Event** + +This event SHALL be generated when the server reaches the end of a reporting period for imported +energy, exported energy, or both. + +The data of this event SHALL contain the following information: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 221 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 EnergyIm­ +ported +``` +``` +EnergyMea­ +sure­ +mentStruct +``` +### PERE & IMPE + +``` +1 EnergyEx­ +ported +``` +``` +EnergyMea­ +sure­ +mentStruct +``` +### PERE & EXPE + +**2.12.7.2.1. EnergyImported Field** + +This field SHALL be the value of PeriodicEnergyImported attribute at the timestamp indicated in its +EndTimestamp field, EndSystime field, or both. + +**2.12.7.2.2. EnergyExported Field** + +This field SHALL be the value of PeriodicEnergyExported attribute at the timestamp indicated in its +EndTimestamp field, EndSystime field, or both. + +**2.13. Electrical Power Measurement Cluster** + +This cluster provides a mechanism for querying data about electrical power as measured by the +server. + +**2.13.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**2.13.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint EPM +``` +**2.13.3. Cluster ID** + +``` +ID Name +0x0090 Electrical Power Measurement +``` +**2.13.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Page 222 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Conformance Summary +0 DIRC DirectCurrent O.a+ Supports measure­ +ment of direct cur­ +rent +1 ALTC AlternatingCur­ +rent +``` +``` +O.a+ Supports measure­ +ment of alternat­ +ing current +2 POLY PolyphasePower [ALTC] Supports +polyphase mea­ +surements +3 HARM Harmonics [ALTC] Supports measure­ +ment of AC har­ +monics +4 PWRQ PowerQuality [ALTC] Supports measure­ +ment of AC har­ +monic phases +``` +**2.13.4.1. DirectCurrent Feature** + +This feature indicates the cluster can measure a direct current. + +**2.13.4.2. AlternatingCurrent Feature** + +This feature indicates the cluster can measure an alternating current. + +**2.13.4.3. PolyphasePower Feature** + +This feature indicates the cluster represents the collective measurements for a Polyphase power +supply. + +**2.13.4.4. Harmonics Feature** + +This feature indicates the cluster can measure the harmonics of an alternating current. + +**2.13.4.5. PowerQuality Feature** + +This feature indicates the cluster can measure the harmonic phases of an alternating current. + +**2.13.5. Data Types** + +**2.13.5.1. PowerModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 223 +``` + +``` +Value Name Summary Conformance +1 DC Direct current M +2 AC Alternating current, +either single-phase or +polyphase +``` +### M + +**2.13.5.2. MeasurementRangeStruct Type** + +This struct SHALL indicate the maximum and minimum values of a given measurement type dur­ +ing a measurement period, along with the observation times of these values. + +A server which does not have the ability to determine the time in UTC, or has not yet done so, +SHALL use the system time fields to specify the measurement period and observation times. + +A server which has determined the time in UTC SHALL use the timestamp fields to specify the mea­ +surement period and observation times. Such a server MAY also include the systime fields to indi­ +cate how many seconds had passed since boot for a given timestamp; this allows for client-side res­ +olution of UTC time for previous reports that only included systime. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Measure­ +mentType +``` +``` +Measure­ +mentType­ +Enum +``` +### M + +``` +1 Min int64 -2^62 to 2^62 M +2 Max int64 -2^62 to 2^62 M +3 StartTime­ +stamp +``` +``` +epoch-s EndTime­ +stamp +4 EndTime­ +stamp +``` +``` +epoch-s min (Start­ +Timestamp ++ 1) +``` +``` +desc +``` +``` +5 MinTime­ +stamp +``` +``` +epoch-s EndTime­ +stamp +6 MaxTime­ +stamp +``` +``` +epoch-s min +(MinTime­ +stamp + 1) +``` +``` +EndTime­ +stamp +``` +``` +7 StartSys­ +time +``` +``` +systime-ms EndSys­ +time +8 EndSys­ +time +``` +``` +systime-ms min (Start­ +Systime + +1) +``` +``` +desc +``` +``` +9 MinSys­ +time +``` +``` +systime-ms EndSys­ +time +``` +``` +Page 224 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +10 MaxSys­ +time +``` +``` +systime-ms min (Min­ +Systime + +1) +``` +``` +EndSys­ +time +``` +**2.13.5.2.1. MeasurementType Field** + +This field SHALL be the type of measurement for the range provided. + +**2.13.5.2.2. Min Field** + +This field SHALL be the smallest measured value for the associated measurement over either the +period between StartTimestamp and EndTimestamp, or the period between StartSystime and +EndSystime, or both. + +**2.13.5.2.3. Max Field** + +This field SHALL be the largest measured value for the associated measurement over the period +between either StartTimestamp and EndTimestamp or the period between StartSystime and +EndSystime, or both. + +**2.13.5.2.4. StartTimestamp Field** + +This field SHALL be the timestamp in UTC of the beginning of the measurement period. + +If the server had not yet determined the time in UTC at or before the beginning of the measurement +period, or does not have the capability of determining the time in UTC, this field SHALL be omitted. + +**2.13.5.2.5. EndTimestamp Field** + +This field SHALL be the timestamp in UTC of the end of the measurement period. + +If the server had not yet determined the time in UTC at or before the beginning of the measurement +period, or does not have the capability of determining the time in UTC, this field SHALL be omitted. + +**2.13.5.2.6. MinTimestamp Field** + +This field SHALL be the most recent timestamp in UTC that the value in the Min field was mea­ +sured. + +This field SHALL be greater than or equal to the value of the StartTimestamp field. + +This field SHALL be less than or equal to the value of the EndTimestamp field. + +**2.13.5.2.7. MaxTimestamp Field** + +This field SHALL be the most recent timestamp in UTC of the value in the Max field. + +This field SHALL be greater than or equal to the value of the StartTimestamp field. + +This field SHALL be less than or equal to the value of the EndTimestamp field. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 225 +``` + +**2.13.5.2.8. StartSystime Field** + +This field SHALL be the time since boot of the beginning of the measurement period. + +If the server had determined the time in UTC at or before the start of the measurement period, this +field MAY be omitted along with the EndSystime, MinSystime, and MaxSystime fields. + +**2.13.5.2.9. EndSystime Field** + +This field SHALL be the time since boot of the end of the measurement period. + +If the server had determined the time in UTC at the end of the measurement period, this field MAY +be omitted along with the StartSystime field, MinSystime, and MaxSystime fields. + +**2.13.5.2.10. MinSystime Field** + +This field SHALL be the measurement time since boot of the value in the Min field was measured. + +This field SHALL be greater than or equal to the value of the StartSystime field. + +This field SHALL be less than or equal to the value of the EndSystime field. + +**2.13.5.2.11. MaxSystime Field** + +This field SHALL be the measurement time since boot of the value in the Max field. + +This field SHALL be greater than or equal to the value of the StartSystime field. + +This field SHALL be less than or equal to the value of the EndSystime field. + +**2.13.5.3. HarmonicMeasurementStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Order uint8 min 1 1 M +1 Measure­ +ment +``` +``` +int64 -2^62 to 2^62 X null M +``` +**2.13.5.3.1. Order Field** + +This field SHALL be the order of the harmonic being measured. Typically this is an odd number, +but servers may choose to report even harmonics. + +**2.13.5.3.2. Measurement Field** + +This field SHALL be the measured value for the given harmonic order. + +For the Harmonic Currents attribute, this value is the most recently measured harmonic current +reading in milliamps (mA). A positive value indicates that the measured harmonic current is posi­ +tive, and a negative value indicates that the measured harmonic current is negative. + +For the Harmonic Phases attribute, this value is the most recent phase of the given harmonic order + +``` +Page 226 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +in millidegrees (mDeg). A positive value indicates that the measured phase is leading, and a nega­ +tive value indicates that the measured phase is lagging. + +If this measurement is not currently available, a value of null SHALL be returned. + +**2.13.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Power­ +Mode +``` +``` +Power­ +Mod­ +eEnum +``` +### R V M + +``` +0x0001 Num­ +berOfMea­ +surement­ +Types +``` +``` +uint8 min 1 F R V M +``` +``` +0x0002 Accuracy list[Mea­ +suremen­ +tAccura­ +cyStruct] +``` +``` +1 to Num­ +berOfMea­ +surement­ +Types +``` +### F R V M + +``` +0x0003 Ranges list[Mea­ +suremen­ +tRangeStru +ct] +``` +``` +0 to Num­ +berOfMea­ +surement­ +Types +``` +``` +Q empty R V O +``` +``` +0x0004 Voltage voltage-mV-2^62 to 2^62 X Q null R V O +0x0005 ActiveCur­ +rent +``` +``` +amperage- +mA +``` +``` +-2^62 to 2^62 X Q null R V O +``` +``` +0x0006 Reactive­ +Current +``` +``` +amperage- +mA +``` +``` +-2^62 to 2^62 X Q null R V [ALTC] +``` +``` +0x0007 Appar­ +entCur­ +rent +``` +``` +amperage- +mA +``` +``` +0 to 2^62 X Q null R V [ALTC] +``` +``` +0x0008 Active­ +Power +``` +``` +power-mW -2^62 to 2^62 X Q null R V M +``` +``` +0x0009 Reactive­ +Power +``` +``` +power-mW -2^62 to 2^62 X Q null R V [ALTC] +``` +``` +0x000A Apparent­ +Power +``` +``` +power-mW -2^62 to 2^62 X Q null R V [ALTC] +``` +``` +0x000B RMSVolt­ +age +``` +``` +voltage-mV-2^62 to 2^62 X Q null R V [ALTC] +``` +``` +0x000C RMSCur­ +rent +``` +``` +amperage- +mA +``` +``` +-2^62 to 2^62 X Q null R V [ALTC] +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 227 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x000D RMSPower power-mW -2^62 to 2^62 X Q null R V [ALTC] +0x000E Frequency int64 0 to +1000000 +``` +``` +X Q null R V [ALTC] +``` +``` +0x000F Harmonic­ +Currents +``` +``` +list[Har­ +monicMea­ +sure­ +mentStruct +] +``` +``` +desc X Q null R V HARM +``` +``` +0x0010 Harmon­ +icPhases +``` +``` +list[Har­ +monicMea­ +sure­ +mentStruct +] +``` +``` +desc X Q null R V PWRQ +``` +``` +0x0011 PowerFac­ +tor +``` +``` +int64 -10000 to +10000 +``` +``` +X Q null R V [ALTC] +``` +``` +0x0012 Neutral­ +Current +``` +``` +amperage- +mA +``` +``` +-2^62 to 2^62 X Q null R V [POLY] +``` +**2.13.6.1. PowerMode Attribute** + +This SHALL indicate the current mode of the server. For some servers, such as an EV, this may +change depending on the mode of charging or discharging. + +**2.13.6.2. NumberOfMeasurementTypes Attribute** + +This SHALL indicate the maximum number of measurement types the server is capable of report­ +ing. + +**2.13.6.3. Accuracy Attribute** + +This SHALL indicate a list of accuracy specifications for the measurement types supported by the +server. There SHALL be an entry for ActivePower, as well as any other measurement types imple­ +mented by this server. + +**2.13.6.4. Ranges Attribute** + +This SHALL indicate a list of measured ranges for different measurement types. Each measurement +type SHALL have at most one entry in this list, representing the range of measurements in the most +recent measurement period. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +``` +Page 228 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +**2.13.6.5. Voltage Attribute** + +This SHALL indicate the most recent Voltage reading in millivolts (mV). + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the voltage cannot be measured, a value of null SHALL be returned. + +**2.13.6.6. ActiveCurrent Attribute** + +This SHALL indicate the most recent ActiveCurrent reading in milliamps (mA). + +A positive value represents current flowing into the server, while a negative value represents cur­ +rent flowing out of the server. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the current cannot be measured, a value of null SHALL be returned. + +**2.13.6.7. ReactiveCurrent Attribute** + +This SHALL indicate the most recent ReactiveCurrent reading in milliamps (mA). + +A positive value represents current flowing into the server, while a negative value represents cur­ +rent flowing out of the server. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 229 +``` + +If the current cannot be measured, a value of null SHALL be returned. + +**2.13.6.8. ApparentCurrent Attribute** + +This SHALL indicate the most recent ApparentCurrent (square root sum of the squares of active +and reactive currents) reading in milliamps (mA). + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the active or reactive currents cannot be measured, a value of null SHALL be returned. + +**2.13.6.9. ActivePower Attribute** + +This SHALL indicate the most recent ActivePower reading in milliwatts (mW). If the power cannot +be measured, a value of null SHALL be returned. + +A positive value represents power imported, while a negative value represents power exported. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the Polyphase Power feature is set, this value represents the combined active power imported or +exported. + +**2.13.6.10. ReactivePower Attribute** + +This SHALL indicate the most recent ReactivePower reading in millivolt-amps reactive (mVAR). + +A positive value represents power imported, while a negative value represents power exported. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +``` +Page 230 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +If the reactive power cannot be measured, a value of null SHALL be returned. + +If the Polyphase Power feature is supported, this value represents the combined reactive power +imported or exported. + +**2.13.6.11. ApparentPower Attribute** + +This SHALL indicate the most recent ApparentPower reading in millivolt-amps (mVA). + +A positive value represents power imported, while a negative value represents power exported. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the apparent power cannot be measured, a value of null SHALL be returned. + +**2.13.6.12. RMSVoltage Attribute** + +This SHALL indicate the most recent RMSVoltage reading in millivolts (mV). + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the RMS voltage cannot be measured, a value of null SHALL be returned. + +**2.13.6.13. RMSCurrent Attribute** + +This SHALL indicate the most recent RMSCurrent reading in milliamps (mA). + +A positive value represents current flowing into the server, while a negative value represents cur­ +rent flowing out of the server. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 231 +``` + +If the RMS current cannot be measured, a value of null SHALL be returned. + +**2.13.6.14. RMSPower Attribute** + +This SHALL indicate the most recent RMSPower reading in milliwatts (mW). + +A positive value represents power imported, while a negative value represents power exported. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the RMS power cannot be measured, a value of null SHALL be returned. + +**2.13.6.15. Frequency Attribute** + +This SHALL indicate the most recent Frequency reading in millihertz (mHz). + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +If the frequency cannot be measured, a value of null SHALL be returned. + +**2.13.6.16. HarmonicCurrents Attribute** + +This SHALL indicate a list of HarmonicMeasurementStruct values, with each HarmonicMeasure­ +mentStruct representing the harmonic current reading for the harmonic order specified by Order. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +**2.13.6.17. HarmonicPhases Attribute** + +This SHALL indicate a list of HarmonicMeasurementStruct values, with each HarmonicMeasure­ +mentStruct representing the most recent phase of the harmonic current reading for the harmonic + +``` +Page 232 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +order specified by Order. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +**2.13.6.18. PowerFactor Attribute** + +This SHALL indicate the Power Factor ratio in +/- 1/100ths of a percent. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +**2.13.6.19. NeutralCurrent Attribute** + +This SHALL indicate the most recent NeutralCurrent reading in milliamps (mA). Typically this is a +derived value, taking the magnitude of the vector sum of phase currents. + +If the neutral current cannot be measured or derived, a value of null SHALL be returned. + +A positive value represents an imbalance between the phase currents when power is imported. + +A negative value represents an imbalance between the phase currents when power is exported. + +The reporting interval of this attribute SHALL be manufacturer dependent. The server MAY choose +to omit publication of deltas considered not meaningful. + +The server SHALL NOT mark this attribute ready for report if the last time this was done was more +recently than 1 second ago. + +The server MAY delay marking this attribute ready for report for longer periods if needed, however +the server SHALL NOT delay marking this attribute as ready for report for longer than 60 seconds. + +**2.13.7. Events** + +This cluster SHALL support the following event: + +``` +ID Name Priority Quality Access Conformance +0 Measurement­ +PeriodRanges +``` +``` +INFO V Ranges +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 233 +``` + +**2.13.7.1. MeasurementPeriodRanges Event** + +If supported, this event SHALL be generated at the end of a measurement period. The start and end +times for measurement periods SHALL be determined by the server, and MAY represent overlap­ +ping periods. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Ranges list[Measure­ +men­ +tRangeStruct +] +``` +### R V M + +**2.13.7.1.1. Ranges Field** + +This SHALL indicate the value of the Ranges attribute at the time of event generation. + +``` +Page 234 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 3. Lighting** + +The Cluster Library is made of individual chapters such as this one. See Document Control in the +Cluster Library for a list of all chapters and documents. References between chapters are made +using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. References +to external documents are contained in Chapter 1 and are made using [ _Rn_ ] notation. + +**3.1. General Description** + +**3.1.1. Introduction** + +The clusters specified in this document are for use typically in lighting applications, but MAY be +used in any application domain. + +**3.1.2. Terms** + +**Ballast Factor:** A measure of the light output (lumens) of a ballast and lamp combination in com­ +parison to an ANSI standard ballast operated with the same lamp. Multiply the ballast factor by the +rated lumens of the lamp to get the light output of the lamp/ballast combination. + +**HSV:** Hue, Saturation, Value. A color space, also known as HSB (Hue, Saturation, Brightness). This is +a well-known transformation of the RGB (Red, Green, Blue) color space. For more information see +e.g., [http://en.wikipedia.org/wiki/HSV_color_space.](http://en.wikipedia.org/wiki/HSV_color_space.) + +**Illuminance:** The density of incident luminous flux on a surface. Illuminance is the standard met­ +ric for lighting levels, and is measured in lux (lx). + +**3.1.3. Cluster List** + +This section lists the lighting specific clusters as specified in this chapter. + +_Table 6. Overview of the Lighting Clusters_ + +``` +Cluster ID Cluster Name Description +0x0300 Color Control Attributes and commands for +controlling the color of a color- +capable light. +0x0301 Ballast Configuration Attributes and commands for +configuring a lighting ballast +``` +**3.2. Color Control Cluster** + +This cluster provides an interface for changing the color of a light. Color is specified according to +the CIE 1931 Color space. Color control is carried out in terms of x,y values, as defined by this speci­ +fication. + +Additionally, color MAY optionally be controlled in terms of color temperature, or as hue and satu­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 235 +``` + +ration values based on optionally variable RGB and W color points. It is recommended that the hue +and saturation are interpreted according to the HSV (a.k.a. HSB) color model. + +Control over luminance is not included, as this is provided by means of the Level Control for Light­ +ing cluster. It is recommended that the level provided by this cluster be interpreted as representing +a proportion of the maximum intensity achievable at the current color. + +**3.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added; CCB 2028 +2 Added Options attribute, CCB 2085 2104 2124 +2230; ZLO 1.0 +3 CCB 2501 2814 2839 2840 2843 2861 +4 All Hubs changes +5 New data model format and notation, Fea­ +tureMap support +6 Added clarifications to Scenes support for Mat­ +ter +7 Added Q quality for CurrentHue, CurrentSatura­ +tion, CurrentX, CurrentY, ColorTempera­ +tureMireds, EnhancedCurrentHue and Remain­ +ingTime attributes. Added clarifications for +behavior related to Step values. Added con­ +straints on minimum acceptable color tempera­ +ture values in mireds. +``` +**3.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint CC +``` +**3.2.3. Cluster ID** + +``` +ID Name +0x0300 Color Control +``` +**3.2.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Page 236 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Conformance Summary +0 HS HueSaturation EHUE, O Supports color +specification via +hue/saturation. +1 EHUE EnhancedHue CL, O Enhanced hue is +supported. +2 CL ColorLoop O Color loop is sup­ +ported. +3 XY XY O Supports color +specification via +XY. +4 CT ColorTemperature O Supports specifica­ +tion of color tem­ +perature. +``` +**3.2.5. Dependencies** + +**3.2.5.1. Coupling color temperature to Level Control** + +If the Level Control for Lighting cluster identifier 0x0008 is supported on the same endpoint as the +Color Control cluster and color temperature is supported, it is possible to couple changes in the cur­ +rent level to the color temperature. + +The CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster indicates +whether the color temperature is to be linked with the CurrentLevel attribute in the Level Control +cluster. + +If the CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster is equal to 1 +and the ColorMode or EnhancedColorMode attribute is set to 2 (ColorTemperatureMireds) then a +change in the CurrentLevel attribute SHALL affect the ColorTemperatureMireds attribute. This rela­ +tionship is manufacturer specific, with the qualification that the maximum value of the Cur­ +rentLevel attribute SHALL correspond to a ColorTemperatureMired attribute value equal to the +CoupleColorTempToLevelMinMireds attribute. This relationship is one-way so a change to the Col­ +orTemperatureMireds attribute SHALL NOT have any effect on the CurrentLevel attribute. + +In order to simulate the behavior of an incandescent bulb, a low value of the CurrentLevel attribute +SHALL be associated with a high value of the ColorTemperatureMireds attribute (i.e., a low value of +color temperature in kelvins). + +If the CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster is equal to 0, +there SHALL be no link between color temperature and current level. + +**3.2.5.2. Independent transition in hue and saturation** + +Various commands in this cluster can be used to start transitions in hue and/or saturation. + +- When a transition in hue is in progress, and a command to change saturation (MoveSaturation + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 237 +``` + +``` +(with MoveMode!=Stop), StepSaturation, MoveToSaturation) is received by the server, this latter +command SHALL NOT interrupt the ongoing transition in hue. +``` +- When a transition in saturation is in progress, and a command to change hue (MoveHue (with + MoveMode!=Stop), EnhancedMoveHue (with MoveMode!=Stop) StepHue, EnhancedStepHue, + MoveToHue, EnhancedMoveToHue) is received by the server, this latter command SHALL NOT + interrupt the ongoing transition in saturation. + +**3.2.6. Data Types** + +**3.2.6.1. ColorCapabilitiesBitmap** + +This data type is derived from map16. + +``` +Bit Name Summary Conformance +0 HueSaturation Supports color specifi­ +cation via hue/satura­ +tion. +``` +### HS + +``` +1 EnhancedHue Enhanced hue is sup­ +ported. +``` +### EHUE + +``` +2 ColorLoop Color loop is supported. CL +3 XY Supports color specifi­ +cation via XY. +``` +### XY + +``` +4 ColorTemperature Supports color specifi­ +cation via color temper­ +ature. +``` +### CT + +**3.2.6.2. OptionsBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 ExecuteIfOff Dependency on On/Off +cluster +``` +### M + +**3.2.6.2.1. ExecuteIfOff Bit** + +This bit SHALL indicate if this cluster server instance has a dependency with the On/Off cluster. + +**3.2.6.3. UpdateFlagsBitmap Type** + +This data type is derived from map8 and is used in the ColorLoopSet command. + +``` +Bit Name Summary Conformance +0 UpdateAction Device adheres to the +associated action field. +``` +### M + +``` +Page 238 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary Conformance +1 UpdateDirection Device updates the +associated direction +attribute. +``` +### M + +``` +2 UpdateTime Device updates the +associated time +attribute. +``` +### M + +``` +3 UpdateStartHue Device updates the +associated start hue +attribute. +``` +### M + +**3.2.6.3.1. UpdateAction Bit** + +This bit SHALL indicate whether the server adheres to the Action field in order to process the com­ +mand. + +- 0 = Device SHALL ignore the Action field. +- 1 = Device SHALL adhere to the Action field. + +**3.2.6.3.2. UpdateDirection Bit** + +This bit SHALL indicate whether the device updates the ColorLoopDirection attribute with the +Direction field. + +- 0 = Device SHALL ignore the Direction field. +- 1 = Device SHALL update the ColorLoopDirection attribute with the value of the Direction field. + +**3.2.6.3.3. UpdateTime Bit** + +This bit SHALL indicate whether the device updates the ColorLoopTime attribute with the Time +field. + +- 0 = Device SHALL ignore the Time field. +- 1 = Device SHALL update the value of the ColorLoopTime attribute with the value of the Time + field. + +**3.2.6.3.4. UpdateStartHue Bit** + +This bit SHALL indicate whether the device updates the ColorLoopStartEnhancedHue attribute with +the value of the StartHue field. + +- 0 = Device SHALL ignore the StartHue field. +- 1 = Device SHALL update the value of the ColorLoopStartEnhancedHue attribute with the value + of the StartHue field. + +**3.2.6.4. DriftCompensationEnum Type** + +This data type is derived from enum8. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 239 +``` + +``` +Value Name Summary Conformance +0 None There is no compensa­ +tion. +``` +### M + +``` +1 OtherOrUnknown The compensation is +based on other or +unknown mechanism. +``` +### M + +``` +2 TemperatureMonitor­ +ing +``` +``` +The compensation is +based on temperature +monitoring. +``` +### M + +``` +3 OpticalLuminance­ +MonitoringAndFeed­ +back +``` +``` +The compensation is +based on optical lumi­ +nance monitoring and +feedback. +``` +### M + +``` +4 OpticalColorMoni­ +toringAndFeedback +``` +``` +The compensation is +based on optical color +monitoring and feed­ +back. +``` +### M + +**3.2.6.5. ColorModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 CurrentHueAndCur­ +rentSaturation +``` +``` +The current hue and +saturation attributes +determine the color. +``` +### M + +``` +1 CurrentXAndCur­ +rentY +``` +``` +The current X and Y +attributes determine +the color. +``` +### M + +``` +2 ColorTempera­ +tureMireds +``` +``` +The color temperature +attribute determines +the color. +``` +### M + +**3.2.6.6. EnhancedColorModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 CurrentHueAndCur­ +rentSaturation +``` +``` +The current hue and +saturation attributes +determine the color. +``` +### M + +``` +1 CurrentXAndCur­ +rentY +``` +``` +The current X and Y +attributes determine +the color. +``` +### M + +``` +Page 240 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +2 ColorTempera­ +tureMireds +``` +``` +The color temperature +attribute determines +the color. +``` +### M + +``` +3 EnhancedCurrentHue­ +AndCurrentSatura­ +tion +``` +``` +The enhanced current +hue and saturation +attributes determine +the color. +``` +### M + +**3.2.6.7. DirectionEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Shortest Shortest distance M +1 Longest Longest distance M +2 Up Up M +3 Down Down M +``` +**3.2.6.8. MoveModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Stop Stop the movement M +1 Up Move in an upwards +direction +``` +### M + +``` +3 Down Move in a downwards +direction +``` +### M + +**3.2.6.9. StepModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +1 Up Step in an upwards +direction +``` +### M + +``` +3 Down Step in a downwards +direction +``` +### M + +**3.2.6.10. ColorLoopActionEnum Type** + +This data type is derived from enum8. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 241 +``` + +``` +Value Name Summary Conformance +0 Deactivate De-activate the color +loop. +``` +### M + +``` +1 ActivateFromColor­ +LoopStartEnhanced­ +Hue +``` +``` +Activate the color loop +from the value in the +ColorLoopStartEn­ +hancedHue field. +``` +### M + +``` +2 ActivateFromEn­ +hancedCurrentHue +``` +``` +Activate the color loop +from the value of the +EnhancedCurrentHue +attribute. +``` +### M + +**3.2.6.11. ColorLoopDirectionEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Decrement Decrement the hue in +the color loop. +``` +### M + +``` +1 Increment Increment the hue in +the color loop. +``` +### M + +**3.2.7. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Curren­ +tHue +``` +``` +uint8 max 254 P N Q 0 R V HS +``` +``` +0x0001 Cur­ +rentSatu­ +ration +``` +``` +uint8 max 254 P S N Q 0 R V HS +``` +``` +0x0002 Remain­ +ingTime +``` +``` +uint16 max 65534 Q 0 R V O +``` +``` +0x0003 CurrentX uint16 max 65279 P S N Q 24939 +(0.381) +``` +### R V XY + +``` +0x0004 CurrentY uint16 max 65279 P S N Q 24701 +(0.377) +``` +### R V XY + +``` +0x0005 DriftCom­ +pensation +``` +``` +DriftCom­ +pensatio­ +nEnum +``` +``` +all - R V O +``` +``` +0x0006 Compen­ +sationText +``` +``` +string max 254 - R V O +``` +``` +Page 242 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**ID Name Type Constraint Quality Default Access Confor­ +mance** + +0x0007 **ColorTem­ +pera­ +tureMired +s** + +``` +uint16 max 65279 P S N Q 250 +(4000K) +``` +### R V CT + +0x0008 **Color­ +Mode** + +``` +ColorMod­ +eEnum +``` +``` +all N 1 R V M +``` +0x000F **Options** Options­ +Bitmap + +``` +desc 0 RW VO M +``` +0x0010 **Num­ +berOfPri­ +maries** + +``` +uint8 max 6 F X R V M +``` +0x0011 **Prima­ +ry1X** + +``` +uint16 max 65279 F R V NumberOf­ +Primaries +> 0, O +``` +0x0012 **Primary1Y** uint16 max 65279 F R V NumberOf­ +Primaries +> 0, O + +0x0013 **Prima­ +ry1Inten­ +sity** + +``` +uint8 all F X R V NumberOf­ +Primaries +> 0, O +``` +0x0015 **Prima­ +ry2X** + +``` +uint16 max 65279 F R V NumberOf­ +Primaries +> 1, O +``` +0x0016 **Primary2Y** uint16 max 65279 F R V NumberOf­ +Primaries +> 1, O + +0x0017 **Prima­ +ry2Inten­ +sity** + +``` +uint8 all F X R V NumberOf­ +Primaries +> 1, O +``` +0x0019 **Prima­ +ry3X** + +``` +uint16 max 65279 F R V NumberOf­ +Primaries +> 2, O +``` +0x001A **Primary3Y** uint16 max 65279 F R V NumberOf­ +Primaries +> 2, O + +0x001B **Prima­ +ry3Inten­ +sity** + +``` +uint8 all F X R V NumberOf­ +Primaries +> 2, O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 243 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0020 Prima­ +ry4X +``` +``` +uint16 max 65279 F R V NumberOf­ +Primaries +> 3, O +0x0021 Primary4Y uint16 max 65279 F R V NumberOf­ +Primaries +> 3, O +0x0022 Prima­ +ry4Inten­ +sity +``` +``` +uint8 all F X R V NumberOf­ +Primaries +> 3, O +0x0024 Prima­ +ry5X +``` +``` +uint16 max 65279 F R V NumberOf­ +Primaries +> 4, O +0x0025 Primary5Y uint16 max 65279 F R V NumberOf­ +Primaries +> 4, O +0x0026 Prima­ +ry5Inten­ +sity +``` +``` +uint8 all F X R V NumberOf­ +Primaries +> 4, O +0x0028 Prima­ +ry6X +``` +``` +uint16 max 65279 F R V NumberOf­ +Primaries +> 5, O +0x0029 Primary6Y uint16 max 65279 F R V NumberOf­ +Primaries +> 5, O +0x002A Prima­ +ry6Inten­ +sity +``` +``` +uint8 all F X R V NumberOf­ +Primaries +> 5, O +0x0030 White­ +PointX +``` +``` +uint16 max 65279 RW VM O +``` +``` +0x0031 White­ +PointY +``` +``` +uint16 max 65279 RW VM O +``` +``` +0x0032 Color­ +PointRX +``` +``` +uint16 max 65279 RW VM O +``` +``` +0x0033 Color­ +PointRY +``` +``` +uint16 max 65279 RW VM O +``` +``` +0x0034 Color­ +PointRIn­ +tensity +``` +``` +uint8 all X RW VM O +``` +Page 244 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**ID Name Type Constraint Quality Default Access Confor­ +mance** + +0x0036 **Color­ +PointGX** + +``` +uint16 max 65279 RW VM O +``` +0x0037 **Color­ +PointGY** + +``` +uint16 max 65279 RW VM O +``` +0x0038 **Color­ +PointGIn­ +tensity** + +``` +uint8 all X RW VM O +``` +0x003A **Color­ +PointBX** + +``` +uint16 max 65279 RW VM O +``` +0x003B **Color­ +PointBY** + +``` +uint16 max 65279 RW VM O +``` +0x003C **Color­ +PointBIn­ +tensity** + +``` +uint8 all X RW VM O +``` +0x4000 **Enhanced­ +Curren­ +tHue** + +``` +uint16 all S N Q 0 R V EHUE +``` +0x4001 **Enhanced­ +Color­ +Mode** + +``` +Enhanced­ +ColorMod­ +eEnum +``` +``` +all S N 1 R V M +``` +0x4002 **Color­ +LoopActiv +e** + +``` +uint8 max 1 S N 0 R V CL +``` +0x4003 **Color­ +LoopDi­ +rection** + +``` +uint8 max 1 S N 0 R V CL +``` +0x4004 **Color­ +LoopTime** + +``` +uint16 all S N 25 R V CL +``` +0x4005 **Color­ +Loop­ +StartEn­ +hanced­ +Hue** + +``` +uint16 all 8960 R V CL +``` +0x4006 **Color­ +Loop­ +StoredEn­ +hanced­ +Hue** + +``` +uint16 all 0 R V CL +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 245 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x400A ColorCa­ +pabilities +``` +``` +ColorCapa­ +bilities­ +Bitmap +``` +``` +max +0x001F +``` +### 0 R V M + +``` +0x400B Col­ +orTemp­ +Physi­ +calMin­ +Mireds +``` +``` +uint16 1 to 65279 R V CT +``` +``` +0x400C Col­ +orTemp­ +Physical­ +MaxMired +s +``` +``` +uint16 max 65279 R V CT +``` +``` +0x400D CoupleCol­ +orTemp­ +ToLevelMi +nMireds +``` +``` +uint16 Col­ +orTemp­ +Physi­ +calMin­ +Mireds to +ColorTem­ +pera­ +tureMireds +``` +``` +MS R V CT | Col­ +orTemper­ +a­ +tureMireds +``` +``` +0x4010 StartUp­ +ColorTem­ +pera­ +tureMired +s +``` +``` +uint16 1 to 65279 N X MS RW VM CT | Col­ +orTemper­ +a­ +tureMireds +``` +**3.2.7.1. Scene Table Extensions** + +If the Scenes Management server cluster is implemented on the same endpoint, the following +attributes SHALL be part of the ExtensionFieldSetStruct of the Scene Table. If an attribute is not +implemented, the value that will be used for it in the AttributeValuePairStruct is given in parenthe­ +ses. If the implicit form of the ExtensionFieldSetStruct is used, the order of the attributes in the +AttributeValueList is in the given order, i.e., the attribute listed as 1 is added first: + +1. CurrentX (0) +2. CurrentY (0) +3. EnhancedCurrentHue (null) +4. CurrentSaturation (null) +5. ColorLoopActive (0) +6. ColorLoopDirection (0) +7. ColorLoopTime (0) + +``` +Page 246 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +8. ColorTemperatureMireds (null) +9. EnhancedColorMode + +Since there is a direct relation between ColorTemperatureMireds and XY, color temperature, if sup­ +ported, is stored as XY in the scenes table. + +Attributes in the scene table that are not supported by the device (according to the FeatureMap +attribute) SHALL be present in the scene table but ignored. + +If the Scenes Management cluster server is implemented on the same endpoint, and the cluster +revision is 6 or above, then all extension fields in the list above, including up to EnhancedColor­ +Mode (item 9), SHALL be present in the extension fields set for a Scene to be considered valid. This +disambiguates the color mode used within the Scene. + +**3.2.7.2. CurrentHue Attribute** + +The CurrentHue attribute contains the current hue value of the light. It is updated as fast as practi­ +cal during commands that change the hue. + +The hue in degrees SHALL be related to the CurrentHue attribute by the relationship: + +``` +Hue = "CurrentHue" * 360 / 254 +``` +where CurrentHue is in the range from 0 to 254 inclusive. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once per second or +- At the end of the movement/transition. + +**3.2.7.3. CurrentSaturation Attribute** + +This attribute SHALL indicate the current saturation value of the light. It is updated as fast as prac­ +tical during commands that change the saturation. + +The saturation (on a scale from 0.0 to 1.0) SHALL be related to the CurrentSaturation attribute by +the relationship: + +``` +Saturation = "CurrentSaturation" / 254 +``` +where CurrentSaturation is in the range from 0 to 254 inclusive. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once per second or +- At the end of the movement/transition. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 247 +``` + +**3.2.7.4. RemainingTime Attribute** + +This attribute SHALL indicate the time remaining, in 1/10ths of a second, until transitions due to the +currently active command will be complete. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- When it changes from 0 to any value higher than 10, or +- When it changes, with a delta larger than 10, caused by the invoke of a command, or +- When it changes to 0. + +For commands with a transition time or changes to the transition time less than 1 second, changes +to this attribute SHALL NOT be reported. + +As this attribute is not being reported during a regular countdown, clients SHOULD NOT rely on the +reporting of this attribute in order to keep track of the remaining duration. + +**3.2.7.5. CurrentX Attribute** + +This attribute SHALL indicate the current value of the normalized chromaticity value x, as defined +in the CIE xyY Color Space. It is updated as fast as practical during commands that change the color. + +The value of x SHALL be related to the CurrentX attribute by the relationship + +``` +x = "CurrentX" / 65536 +``` +where CurrentX is in the range from 0 to 65279 inclusive. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once per second or +- At the end of the movement/transition. + +**3.2.7.6. CurrentY Attribute** + +This attribute SHALL indicate the current value of the normalized chromaticity value y, as defined +in the CIE xyY Color Space. It is updated as fast as practical during commands that change the color. + +The value of y SHALL be related to the CurrentY attribute by the relationship + +``` +y = "CurrentY" / 65536 +``` +where CurrentY is in the range from 0 to 65279 inclusive. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once per second or +- At the end of the movement/transition. + +``` +Page 248 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**3.2.7.7. DriftCompensation Attribute** + +This attribute SHALL indicate what mechanism, if any, is in use for compensation for color/inten­ +sity drift over time. + +**3.2.7.8. CompensationText Attribute** + +This attribute SHALL contain a textual indication of what mechanism, if any, is in use to compen­ +sate for color/intensity drift over time. + +**3.2.7.9. ColorTemperatureMireds Attribute** + +This attribute SHALL indicate **a scaled inverse** of the current value of the color temperature. The +unit of ColorTemperatureMireds is the mired (micro reciprocal degree), a.k.a. mirek (micro recipro­ +cal kelvin). It is updated as fast as practical during commands that change the color. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once per second or +- At the end of the movement/transition. + +The color temperature value in kelvins SHALL be related to the ColorTemperatureMireds attribute +in mired by the relationship + +``` +"Color temperature [K]" = "1,000,000" / "ColorTemperatureMireds" +``` +where ColorTemperatureMireds is in the range from 1 to 65279 inclusive, giving a color tempera­ +ture range from 1,000,000 K to 15.32 K. + +If this attribute is implemented then the ColorMode attribute SHALL also be implemented. + +**3.2.7.10. ColorMode Attribute** + +This attribute SHALL indicate which attributes are currently determining the color of the device. + +The value of the ColorMode attribute cannot be written directly - it is set upon reception of any +command in section Commands to the appropriate mode for that command. + +**3.2.7.11. Options Attribute** + +This attribute SHALL indicate a bitmap that determines the default behavior of some cluster com­ +mands. Each command that is dependent on the Options attribute SHALL first construct a tempo­ +rary Options bitmap that is in effect during the command processing. The temporary Options +bitmap has the same format and meaning as the Options attribute, but includes any bits that may +be overridden by command fields. + +This attribute is meant to be changed only during commissioning. + +Below is the format and description of the Options attribute and temporary Options bitmap and the +effect on dependent commands. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 249 +``` + +Command execution SHALL NOT continue beyond the Options processing if all of these criteria are +true: + +- The On/Off cluster exists on the same endpoint as this cluster. +- The OnOff attribute of the On/Off cluster, on this endpoint, is FALSE. +- The value of the ExecuteIfOff bit is 0. + +**3.2.7.11.1. ExecuteIfOff Bit** + +- 0 = Do not execute command if the OnOff attribute in the On/Off cluster is FALSE. +- 1 = Execute command if the OnOff attribute in the On/Off cluster is FALSE. + +**3.2.7.12. EnhancedCurrentHue Attribute** + +This attribute SHALL indicate the non-equidistant steps along the CIE 1931 color triangle, and it +provides 16-bits precision. + +The upper 8 bits of this attribute SHALL be used as an index in the implementation specific XY +lookup table to provide the non-equidistant steps. The lower 8 bits SHALL be used to interpolate +between these steps in a linear way in order to provide color zoom for the user. + +To provide compatibility with clients not supporting EHUE, the CurrentHue attribute SHALL con­ +tain a hue value in the range 0 to 254, calculated from the EnhancedCurrentHue attribute. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once per second or +- At the end of the movement/transition. + +**3.2.7.13. EnhancedColorMode Attribute** + +This attribute SHALL indicate which attributes are currently determining the color of the device. + +To provide compatibility with clients not supporting EHUE, the original ColorMode attribute SHALL +indicate CurrentHue and CurrentSaturation when the light uses the EnhancedCurrentHue attribute. +If the ColorMode attribute is changed, its new value SHALL be copied to the EnhancedColorMode +attribute. + +**3.2.7.14. ColorLoopActive Attribute** + +This attribute SHALL indicate the current active status of the color loop. If this attribute has the +value 0, the color loop SHALL NOT be active. If this attribute has the value 1, the color loop SHALL +be active. + +**3.2.7.15. ColorLoopDirection Attribute** + +This attribute SHALL indicate the current direction of the color loop. If this attribute has the value +0, the EnhancedCurrentHue attribute SHALL be decremented. If this attribute has the value 1, the +EnhancedCurrentHue attribute SHALL be incremented. + +``` +Page 250 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**3.2.7.16. ColorLoopTime Attribute** + +This attribute SHALL indicate the number of seconds it SHALL take to perform a full color loop, i.e., +to cycle all values of the EnhancedCurrentHue attribute (between 0 and 65534). + +**3.2.7.17. ColorLoopStartEnhancedHue Attribute** + +This attribute SHALL indicate the value of the EnhancedCurrentHue attribute from which the color +loop SHALL be started. + +**3.2.7.18. ColorLoopStoredEnhancedHue Attribute** + +This attribute SHALL indicate the value of the EnhancedCurrentHue attribute before the color loop +was started. Once the color loop is complete, the EnhancedCurrentHue attribute SHALL be restored +to this value. + +**3.2.7.19. ColorCapabilities Attribute** + +This attribute SHALL indicate the color control capabilities of the device. + +Bits 0-4 of the ColorCapabilities attribute SHALL have the same values as the corresponding bits of +the FeatureMap attribute. All other bits in ColorCapabilities SHALL be 0. + +**3.2.7.20. ColorTempPhysicalMinMireds Attribute** + +This attribute SHALL indicate the minimum mired value supported by the hardware. ColorTemp­ +PhysicalMinMireds corresponds to the maximum color temperature in kelvins supported by the +hardware. +ColorTempPhysicalMinMireds <= ColorTemperatureMireds. + +**3.2.7.21. ColorTempPhysicalMaxMireds Attribute** + +This attribute SHALL indicate the maximum mired value supported by the hardware. ColorTemp­ +PhysicalMaxMireds corresponds to the minimum color temperature in kelvins supported by the +hardware. +ColorTemperatureMireds <= ColorTempPhysicalMaxMireds. + +**3.2.7.22. CoupleColorTempToLevelMinMireds Attribute** + +This attribute SHALL indicate a lower bound on the value of the ColorTemperatureMireds attribute +for the purposes of coupling the ColorTemperatureMireds attribute to the CurrentLevel attribute +when the CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster is equal +to 1. When coupling the ColorTemperatureMireds attribute to the CurrentLevel attribute, this value +SHALL correspond to a CurrentLevel value of 254 (100%). + +This attribute SHALL be set such that the following relationship exists: +ColorTempPhysicalMinMireds <= CoupleColorTempToLevelMinMireds <= ColorTemperatureMireds + +Note that since this attribute is stored as a micro reciprocal degree (mired) value (i.e. color temper­ +ature in kelvins = 1,000,000 / CoupleColorTempToLevelMinMireds), the CoupleColorTemp­ +ToLevelMinMireds attribute corresponds to an upper bound on the value of the color temperature + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 251 +``` + +in kelvins supported by the device. + +**3.2.7.23. StartUpColorTemperatureMireds Attribute** + +This attribute SHALL indicate the desired startup color temperature value the light SHALL use +when it is supplied with power and this value SHALL be reflected in the ColorTemperatureMireds +attribute. In addition, the ColorMode and EnhancedColorMode attributes SHALL be set to 2 (Col­ +orTemperatureMireds). The values of the StartUpColorTemperatureMireds attribute are listed in +the table below, + +``` +Value Action on power up +1 to 65279 Set the ColorTemperatureMireds attribute to this +value. +null Set the ColorTemperatureMireds attribute to its +previous value. +``` +**3.2.7.24. NumberOfPrimaries Attribute** + +This attribute SHALL indicate the number of color primaries implemented on this device. A value +of null SHALL indicate that the number of primaries is unknown. + +Where this attribute is implemented, the attributes below for indicating the “x” and “y” color values +of the primaries SHALL also be implemented for each of the primaries from 1 to NumberOfPri­ +maries, without leaving gaps. Implementation of the Primary1Intensity attribute and subsequent +intensity attributes is optional. + +**3.2.7.25. Primary1X Attribute** + +This attribute SHALL indicate the normalized chromaticity value x for this primary, as defined in +the CIE xyY Color Space. + +The value of x SHALL be related to the Primary1X attribute by the relationship + +x = Primary1X / 65536 (Primary1X in the range 0 to 65279 inclusive) + +**3.2.7.26. Primary1Y Attribute** + +This attribute SHALL indicate the normalized chromaticity value y for this primary, as defined in +the CIE xyY Color Space. + +The value of y SHALL be related to the Primary1Y attribute by the relationship + +y = Primary1Y / 65536 (Primary1Y in the range 0 to 65279 inclusive) + +**3.2.7.27. Primary1Intensity Attribute** + +This attribute SHALL indicate a representation of the maximum intensity of this primary as defined +in the Dimming Light Curve in the Ballast Configuration cluster (see Ballast Configuration Cluster), +normalized such that the primary with the highest maximum intensity contains the value 254. + +``` +Page 252 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +A value of null SHALL indicate that this primary is not available. + +**3.2.7.28. Primary2X, Primary2Y, Primary2Intensity, Primary3X, Primary3Y, Primary3Intensity, +Primary4X, Primary4Y, Primary4Intensity, Primary5X, Primary5Y, Primary5Intensity, +Primary6X, Primary6Y and Primary6Intensity Attributes** + +These attributes SHALL represent the capabilities of the 2nd, 3rd, 4th, 5th and 6th primaries, where +present, in the same way as for the Primary1X, Primary1Y and Primary1Intensity attributes. + +**3.2.7.29. WhitePointX Attribute** + +This attribute SHALL indicate the normalized chromaticity value x, as defined in the CIE xyY Color +Space, of the current white point of the device. + +The value of x SHALL be related to the WhitePointX attribute by the relationship + +x = WhitePointX / 65536 (WhitePointX in the range 0 to 65279 inclusive) + +**3.2.7.30. WhitePointY Attribute** + +This attribute SHALL indicate the normalized chromaticity value y, as defined in the CIE xyY Color +Space, of the current white point of the device. + +The value of y SHALL be related to the WhitePointY attribute by the relationship + +y = WhitePointY / 65536 (WhitePointY in the range 0 to 65279 inclusive) + +**3.2.7.31. ColorPointRX Attribute** + +This attribute SHALL indicate the normalized chromaticity value x, as defined in the CIE xyY Color +Space, of the red color point of the device. + +The value of x SHALL be related to the ColorPointRX attribute by the relationship + +x = ColorPointRX / 65536 (ColorPointRX in the range 0 to 65279 inclusive) + +**3.2.7.32. ColorPointRY Attribute** + +This attribute SHALL indicate the normalized chromaticity value y, as defined in the CIE xyY Color +Space, of the red color point of the device. + +The value of y SHALL be related to the ColorPointRY attribute by the relationship + +y = ColorPointRY / 65536 (ColorPointRY in the range 0 to 65279 inclusive) + +**3.2.7.33. ColorPointRIntensity Attribute** + +This attribute SHALL indicate a representation of the relative intensity of the red color point as +defined in the Dimming Light Curve in the Ballast Configuration cluster (see Ballast Configuration +Cluster), normalized such that the color point with the highest relative intensity contains the value +254. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 253 +``` + +A value of null SHALL indicate an invalid value. + +**3.2.7.34. ColorPointGX, ColorPointGY, ColorPointGIntensity, ColorPointBX, ColorPointBY and +ColorPointBIntensity Attributes** + +These attributes SHALL represent the chromaticity values and intensities of the green and blue +color points, in the same way as for the ColorPointRX, ColorPointRY and ColorPointRIntensity +attributes. + +If any one of these red, green or blue color point attributes is implemented then they SHALL all be +implemented. + +**3.2.8. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 MoveToHue client ⇒ server Y O HS +0x01 MoveHue client ⇒ server Y O HS +0x02 StepHue client ⇒ server Y O HS +0x03 MoveToSatu­ +ration +``` +``` +client ⇒ server Y O HS +``` +``` +0x04 MoveSatura­ +tion +``` +``` +client ⇒ server Y O HS +``` +``` +0x05 StepSatura­ +tion +``` +``` +client ⇒ server Y O HS +``` +``` +0x06 MoveToHue­ +AndSatura­ +tion +``` +``` +client ⇒ server Y O HS +``` +``` +0x07 MoveToColor client ⇒ server Y O XY +0x08 MoveColor client ⇒ server Y O XY +0x09 StepColor client ⇒ server Y O XY +0x0A MoveToCol­ +orTempera­ +ture +``` +``` +client ⇒ server Y O CT +``` +``` +0x40 Enhanced­ +MoveToHue +``` +``` +client ⇒ server Y O EHUE +``` +``` +0x41 Enhanced­ +MoveHue +``` +``` +client ⇒ server Y O EHUE +``` +``` +0x42 EnhancedSte­ +pHue +``` +``` +client ⇒ server Y O EHUE +``` +``` +Page 254 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Direction Response Access Conformance +0x43 Enhanced­ +MoveToHue­ +AndSatura­ +tion +``` +``` +client ⇒ server Y O EHUE +``` +``` +0x44 ColorLoopSet client ⇒ server Y O CL +0x47 StopMoveStep client ⇒ server Y O HS | XY | CT +0x4B MoveCol­ +orTempera­ +ture +``` +``` +client ⇒ server Y O CT +``` +``` +0x4C StepCol­ +orTempera­ +ture +``` +``` +client ⇒ server Y O CT +``` +**3.2.8.1. Generic Usage Notes** + +When asked to change color via one of these commands, the implementation SHALL select a color, +within the limits of the hardware of the device, which is as close as possible to that requested. The +determination as to the true representations of color is out of the scope of this specification. How­ +ever, as long as the color data fields of the received command are within the permitted range of this +specification and no error condition applies, the resulting status code SHALL be SUCCESS. + +For example the MoveToColorTemperature command: if the target color temperature is not achiev­ +able by the hardware then the color temperature SHALL be clipped at the physical minimum or +maximum achievable (depending on the direction of the color temperature transition) when the +device reaches that color temperature (which MAY be before the requested transition time). + +If a color loop is active (i.e., the ColorLoopActive attribute is equal to 1), it SHALL only be stopped +by sending a specific ColorLoopSet command frame with a request to deactivate the color loop (i.e., +the color loop SHALL NOT be stopped on receipt of another command which has a 'stop' semantic +such as the EnhancedMoveToHue command with MoveMode==Stop, or the StopMoveStep com­ +mand). In addition, while a color loop is active, a manufacturer MAY choose to ignore incoming +color commands which affect a change in hue. + +**3.2.8.2. Note on Change of ColorMode** + +The first action taken when any one of these commands is received is to change the ColorMode +attribute to the appropriate value for the command (see individual commands). Note that, when +moving from one color mode to another (e.g., CurrentX/CurrentY to CurrentHue/CurrentSatura­ +tion), the starting color for the command is formed by calculating the values of the new attributes +(in this case CurrentHue, CurrentSaturation) from those of the old attributes (in this case CurrentX +and CurrentY). + +When moving from a mode to another mode that has a more restricted color range (e.g., Cur­ +rentX/CurrentY to CurrentHue/CurrentSaturation, or CurrentHue/CurrentSaturation to ColorTem­ +peratureMireds) it is possible for the current color value to have no equivalent in the new mode. +The behavior in such cases is manufacturer dependent, and therefore it is recommended to avoid + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 255 +``` + +color mode changes of this kind during use. + +**3.2.8.3. Use of the OptionsMask and OptionsOverride Fields** + +The OptionsMask and OptionsOverride Fields SHALL both be present. Default values are provided +to interpret missing fields from legacy devices. A temporary Options bitmap SHALL be created from +the Options attribute, using the OptionsMask and OptionsOverride Fields. Each bit of the temporary +Options bitmap SHALL be determined as follows: + +Each bit in the Options attribute SHALL determine the corresponding bit in the temporary Options +bitmap, unless the OptionsMask field is present and has the corresponding bit set to 1, in which +case the corresponding bit in the OptionsOverride field SHALL determine the corresponding bit in +the temporary Options bitmap. + +The resulting temporary Options bitmap SHALL then be processed as defined in section Options. + +**3.2.8.4. MoveToHue Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Hue uint8 max 254 M +1 Direction Directio­ +nEnum +``` +``` +all M +``` +``` +2 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.4.1. Hue Field** + +This field SHALL indicate the hue to be moved to. + +**3.2.8.4.2. Direction Field** + +This field SHALL indicate the movement direction. + +**3.2.8.4.3. TransitionTime Field** + +This field SHALL indicate, in 1/10ths of a second, the time that SHALL be taken to move to the new +hue. + +**3.2.8.4.4. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +``` +Page 256 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**3.2.8.4.5. Effect on Receipt** + +On receipt of this command, a device SHALL also set the ColorMode attribute to the value 0 and +then SHALL move from its current hue to the value given in the Hue field. + +The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the +new hue SHALL be equal to the TransitionTime field. + +As hue is effectively measured on a circle, the new hue MAY be moved to in either direction. The +direction of hue change is given by the Direction field. If Direction is 'Shortest distance', the direc­ +tion is taken that involves the shortest path round the circle. This case corresponds to expected nor­ +mal usage. If Direction is 'Longest distance', the direction is taken that involves the longest path +round the circle. This case can be used for 'rainbow effects'. In both cases, if both distances are the +same, the Up direction SHALL be taken. + +**3.2.8.5. MoveHue Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 MoveMode MoveMod­ +eEnum +``` +``` +all M +``` +``` +1 Rate uint8 all M +2 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +3 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.5.1. MoveMode Field** + +This field SHALL indicate the mode of movement. + +**3.2.8.5.2. Rate Field** + +This field SHALL indicate the rate of movement in steps per second. A step is a change in the +device’s hue of one unit. + +**3.2.8.5.3. OptionsMask and OptionsOverride field** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.5.4. Effect on Receipt** + +On receipt of this command, + +- If the MoveMode field is set to 1 (Up) or 3 (Down): + ◦ If the Rate field has a value of zero, the command has no effect and a response SHALL be + returned with the status code set to INVALID_COMMAND. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 257 +``` + +``` +◦ Otherwise, a device SHALL set the ColorMode attribute to the value 0 (CurrentHueAndCur­ +rentSaturation) and SHALL then move from its current hue in an up or down direction in a +continuous fashion, as detailed in the table. +``` +- If the MoveMode field is set to 0 (Stop), the Rate field SHALL be completely ignored. + +``` +MoveMode Action on Receipt +Stop If moving, stop, else ignore the command (i.e., +the command is accepted but has no effect). This +SHALL stop any ongoing hue and/or saturation +transition. +Up Increase the device’s hue at the rate given in the +Rate field. If the hue reaches the maximum +allowed for the device, then wraparound and +proceed from its minimum allowed value. +Down Decrease the device’s hue at the rate given in the +Rate field. If the hue reaches the minimum +allowed for the device, then wraparound and +proceed from its maximum allowed value. +``` +**3.2.8.6. StepHue Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StepMode StepMod­ +eEnum +``` +``` +all M +``` +``` +1 StepSize uint8 all M +2 Transition­ +Time +``` +``` +uint8 all M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.6.1. StepMode Field** + +This field SHALL indicate the mode of the step to be performed. + +**3.2.8.6.2. StepSize Field** + +This field SHALL indicate the change to be added to (or subtracted from) the current value of the +device’s hue. + +**3.2.8.6.3. TransitionTime Field** + +This field SHALL indicate, in 1/10ths of a second, the time that SHALL be taken to perform the step. + +``` +Page 258 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +A step is a change in the device’s hue of Step size units. + +### NOTE + +``` +Here the TransitionTime data field is of data type uint8, where uint16 is more com­ +mon for TransitionTime data fields in other clusters / commands. +``` +**3.2.8.6.4. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.6.5. Effect on Receipt** + +On receipt of this command, if the StepSize field has a value of zero, the command has no effect and +a response SHALL be returned with the status code set to INVALID_COMMAND. + +Otherwise, a device SHALL set the ColorMode attribute to the value 0 (CurrentHueAndCurrentSatu­ +ration) and SHALL then move from its current hue in an up or down direction by one step, as +detailed in the table. + +``` +StepMode Action on Receipt +Up Increase the device’s hue by one step, in a con­ +tinuous fashion. If the hue value reaches the +maximum value then wraparound and proceed +from the minimum allowed value. +Down Decrease the device’s hue by one step, in a con­ +tinuous fashion. If the hue value reaches the +minimum value then wraparound and proceed +from the maximum allowed value. +``` +**3.2.8.7. MoveToSaturation Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Saturation uint8 max 254 M +1 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +2 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +3 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.7.1. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 259 +``` + +**3.2.8.7.2. Effect on Receipt** + +On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 (Curren­ +tHueAndCurrentSaturation) and SHALL then move from its current saturation to the value given in +the Saturation field. + +The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the +new saturation SHALL be equal to the TransitionTime field, in 1/10ths of a second. + +**3.2.8.8. MoveSaturation Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 MoveMode MoveMod­ +eEnum +``` +``` +all M +``` +``` +1 Rate uint8 all M +2 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +3 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.8.1. MoveMode Field** + +This field SHALL indicate the mode of movement, as described in the MoveHue command. + +**3.2.8.8.2. Rate Field** + +This field SHALL indicate the rate of movement in steps per second. A step is a change in the +device’s saturation of one unit. + +**3.2.8.8.3. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.8.4. Effect on Receipt** + +On receipt of this command, + +- If the MoveMode field is set to 1 (Up) or 3 (Down) + ◦ If the Rate field has a value of zero, the command has no effect and a response SHALL be + returned with the status code set to INVALID_COMMAND. + ◦ Otherwise, a device SHALL set the ColorMode attribute to the value 0 (CurrentHueAndCur­ + rentSaturation) and SHALL then move from its current saturation in an up or down direc­ + tion in a continuous fashion, as detailed in the table. +- If the MoveMode field is set to 0 (Stop), the Rate field SHALL be completely ignored. + +``` +Page 260 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +MoveMode Action on Receipt +Stop If moving, stop, else ignore the command (i.e., +the command is accepted but has no effect). This +SHALL stop any ongoing hue and/or saturation +transition. +Up Increase the device’s saturation at the rate given +in the Rate field. If the saturation reaches the +maximum allowed for the device, stop. +Down Decrease the device’s saturation at the rate given +in the Rate field. If the saturation reaches the +minimum allowed for the device, stop. +``` +**3.2.8.9. StepSaturation Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StepMode StepMod­ +eEnum +``` +``` +all M +``` +``` +1 StepSize uint8 all M +2 Transition­ +Time +``` +``` +uint8 all M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.9.1. StepMode Field** + +This field SHALL indicate the mode of the step to be performed, as described in the StepHue com­ +mand. + +**3.2.8.9.2. StepSize Field** + +This field SHALL indicate the change to be added to (or subtracted from) the current value of the +device’s saturation. + +**3.2.8.9.3. TransitionTime Field** + +This field SHALL indicate, in 1/10ths of a second, the time that SHALL be taken to perform the step. +A step is a change in the device’s saturation of Step size units. + +### NOTE + +``` +Here the TransitionTime data field is of data type uint8, where uint16 is more com­ +mon for TransitionTime data fields in other clusters / commands. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 261 +``` + +**3.2.8.9.4. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.9.5. Effect on Receipt** + +On receipt of this command, if the StepSize field has a value of zero, the command has no effect and +a response SHALL be returned with the status code set to INVALID_COMMAND. + +Otherwise, a device SHALL set the ColorMode attribute to the value 0 (CurrentHueAndCurrentSatu­ +ration) and SHALL then move from its current saturation in an up or down direction by one step. + +``` +StepMode Action on Receipt +Up Increase the device’s saturation by one step, in a +continuous fashion. However, if the saturation +value is already the maximum value then do +nothing. +Down Decrease the device’s saturation by one step, in a +continuous fashion. However, if the saturation +value is already the minimum value then do +nothing. +``` +**3.2.8.10. MoveToHueAndSaturation Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Hue uint8 max 254 M +1 Saturation uint8 max 254 M +2 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.10.1. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.10.2. Effect on Receipt** + +On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 (Curren­ +tHueAndCurrentSaturation) and SHALL then move from its current hue and saturation to the val­ +ues given in the Hue and Saturation fields. + +``` +Page 262 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the +new color SHALL be equal to the TransitionTime field, in 1/10ths of a second. + +The path through color space taken during the transition is not specified, but it is recommended +that the shortest path is taken through color space, i.e., movement is 'in a straight line' across the +CIE xyY Color Space. + +**3.2.8.11. MoveToColor Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ColorX uint16 max 65279 M +1 ColorY uint16 max 65279 M +2 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.11.1. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.11.2. Effect on Receipt** + +On receipt of this command, a device SHALL set the value of the ColorMode attribute, where imple­ +mented, to 1 (CurrentXAndCurrentY), and SHALL then move from its current color to the color +given in the ColorX and ColorY fields. + +The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the +new color SHALL be equal to the TransitionTime field, in 1/10ths of a second. + +The path through color space taken during the transition is not specified, but it is recommended +that the shortest path is taken through color space, i.e., movement is 'in a straight line' across the +CIE xyY Color Space. + +**3.2.8.12. MoveColor Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 RateX int16 all M +1 RateY int16 all M +2 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 263 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +3 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.12.1. RateX Field** + +This field SHALL indicate the rate of movement in steps per second. A step is a change in the +device’s CurrentX attribute of one unit. + +**3.2.8.12.2. RateY Field** + +This field SHALL indicate the rate of movement in steps per second. A step is a change in the +device’s CurrentY attribute of one unit. + +**3.2.8.12.3. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.12.4. Effect on Receipt** + +On receipt of this command, if both the RateX and RateY fields contain a value of zero, no move­ +ment SHALL be carried out, and the command execution SHALL have no effect other than stopping +the operation of any previously received command of this cluster. While this command (when used +with both the RateX and RateY fields set to zero) can be used to stop any operation of this cluster, it +is recommended to instead use the StopMoveStep command to achieve this goal. + +Otherwise, a device SHALL set the value of the ColorMode attribute, where implemented, to 1 (Cur­ +rentXAndCurrentY), and SHALL then move from its current color in a continuous fashion according +to the rates specified. This movement SHALL continue until the target color for the next step cannot +be implemented on this device. + +**3.2.8.13. StepColor Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StepX int16 all M +1 StepY int16 all M +2 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +Page 264 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**3.2.8.13.1. StepX and StepY Fields** + +These fields SHALL indicate the change to be added to the device’s CurrentX attribute and CurrentY +attribute respectively. + +**3.2.8.13.2. TransitionTime Field** + +The field SHALL indicate, in 1/10ths of a second, the time that SHALL be taken to perform the color +change. + +**3.2.8.13.3. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.13.4. Effect on Receipt** + +On receipt of this command, if both the StepX and StepY fields contain a value of zero, the com­ +mand has no effect and a response SHALL be returned with the status code set to INVALID_COM­ +MAND. + +Otherwise, a device SHALL set the value of the ColorMode attribute, where implemented, to 1 (Cur­ +rentXAndCurrentY), and SHALL then move from its current color by the color step indicated. + +The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the +new color SHALL be equal to the TransitionTime field, in 1/10ths of a second. + +The path through color space taken during the transition is not specified, but it is recommended +that the shortest path is taken through color space, i.e., movement is 'in a straight line' across the +CIE xyY Color Space. + +Note also that if the required step is larger than can be represented by signed 16-bit integers then +more than one step command SHOULD be issued. + +**3.2.8.14. MoveToColorTemperature Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ColorTem­ +pera­ +tureMireds +``` +``` +uint16 max 65279 M +``` +``` +1 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +2 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +3 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 265 +``` + +**3.2.8.14.1. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.14.2. Effect on Receipt** + +On receipt of this command, a device SHALL set the value of the ColorMode attribute, where imple­ +mented, to 2 (ColorTemperatureMireds), and SHALL then move from its current color to the color +given by the ColorTemperatureMired field. + +The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the +new color SHALL be equal to the TransitionTime field, in 1/10ths of a second. + +By definition of this color mode, the path through color space taken during the transition is along +the 'Black Body Line'. + +If the ColorTemperatureMireds field is less than the value of the ColorTempPhysicalMinMireds +attribute, the value of the ColorTempPhysicalMinMireds attribute SHALL be used as the final target +for the ColorTemperatureMireds attribute. + +If the ColorTemperatureMireds field is greater than the value of the ColorTempPhysicalMaxMireds +attribute, the value of the ColorTempPhysicalMaxMireds attribute SHALL be used as the final target +for the ColorTemperatureMireds attribute. + +**3.2.8.15. EnhancedMoveToHue Command** + +This command allows the light to be moved in a smooth continuous transition from their current +hue to a target hue. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Enhanced­ +Hue +``` +``` +uint16 all M +``` +``` +1 Direction Directio­ +nEnum +``` +``` +all M +``` +``` +2 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.15.1. EnhancedHue Field** + +This field SHALL indicate the target extended hue for the light. + +``` +Page 266 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**3.2.8.15.2. Direction Field** + +This field SHALL indicate the movement direction. + +**3.2.8.15.3. TransitionTime Field** + +This field SHALL indicate the transition time, as described in the MoveToHue command. + +**3.2.8.15.4. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.15.5. Effect on Receipt** + +On receipt of this command, a device SHALL set the ColorMode attribute to 0 (CurrentHueAndCur­ +rentSaturation) and set the EnhancedColorMode attribute to the value 3 (EnhancedCurrentHueAnd­ +CurrentSaturation). The device SHALL then move from its current enhanced hue to the value given +in the EnhancedHue field. + +The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the +new enhanced hue SHALL be equal to the TransitionTime field. + +**3.2.8.16. EnhancedMoveHue Command** + +This command allows the light to start a continuous transition starting from their current hue. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 MoveMode MoveMod­ +eEnum +``` +``` +desc M +``` +``` +1 Rate uint16 all M +2 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +3 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.16.1. MoveMode Field** + +This field SHALL indicate the mode of movement, as described in the MoveHue command. + +**3.2.8.16.2. Rate field** + +This field SHALL indicate the rate of movement in steps per second. A step is a change in the +extended hue of a device by one unit. + +**3.2.8.16.3. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 267 +``` + +**3.2.8.16.4. Effect on receipt** + +On receipt of this command, + +- If the MoveMode field is set to 1 (Up) or 3 (Down) + ◦ If the Rate field has a value of zero, the command has no effect and a response SHALL be + returned with the status code set to INVALID_COMMAND. + ◦ Otherwise, a device SHALL set the ColorMode attribute to 0 (CurrentHueAndCurrentSatura­ + tion) and set the EnhancedColorMode attribute to the value 3 (EnhancedCurrentHueAndCur­ + rentSaturation). The device SHALL then move from its current enhanced hue in an up or + down direction in a continuous fashion, as detailed in the table. +- If the MoveMode field is set to 0 (Stop), the Rate field SHALL be completely ignored. + +``` +MoveMode Action on Receipt +Stop If moving, stop, else ignore the command (i.e., +the command is accepted but has no effect). This +SHALL stop any ongoing hue and/or saturation +transition. +Up Increase the device’s enhanced hue at the rate +given in the Rate field. If the enhanced hue +reaches the maximum allowed for the device, +wraparound and proceed from its minimum +allowed value. +Down Decrease the device’s enhanced hue at the rate +given in the Rate field. If the hue reaches the +minimum allowed for the device, wraparound +and proceed from its maximum allowed value. +``` +**3.2.8.17. EnhancedStepHue Command** + +This command allows the light to be moved in a stepped transition from their current hue, resulting +in a linear transition through XY space. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StepMode StepMod­ +eEnum +``` +``` +desc M +``` +``` +1 StepSize uint16 all M +2 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +Page 268 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**3.2.8.17.1. StepMode Field** + +This field SHALL indicate the mode of the step to be performed, as described in the StepHue com­ +mand. + +**3.2.8.17.2. StepSize Field** + +This field SHALL indicate the change to be added to (or subtracted from) the current value of the +device’s enhanced hue. + +**3.2.8.17.3. TransitionTime Field** + +The field SHALL indicate, in units of 1/10ths of a second, the time that SHALL be taken to perform +the step. A step is a change to the device’s enhanced hue of a magnitude corresponding to the Step­ +Size field. + +### NOTE + +``` +Here TransitionTime data field is of data type uint16, while the TransitionTime data +field of the StepHue command is of data type uint8. +``` +**3.2.8.17.4. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.17.5. Effect on Receipt** + +On receipt of this command, if the StepSize field has a value of zero, the command has no effect and +a response SHALL be returned with the status code set to INVALID_COMMAND. + +Otherwise, a device SHALL set the ColorMode attribute to 0 (CurrentHueAndCurrentSaturation) +and the EnhancedColorMode attribute to the value 3 (EnhancedCurrentHueAndCurrentSaturation). +The device SHALL then move from its current enhanced hue in an up or down direction by one +step, as detailed in the table. + +``` +StepMode Action on Receipt +Up Increase the device’s enhanced hue by one step. +If the enhanced hue reaches the maximum +allowed for the device, wraparound and proceed +from its minimum allowed value. +Down Decrease the device’s enhanced hue by one step. +If the hue reaches the minimum allowed for the +device, wraparound and proceed from its maxi­ +mum allowed value. +``` +**3.2.8.18. EnhancedMoveToHueAndSaturation Command** + +This command allows the light to be moved in a smooth continuous transition from their current +hue to a target hue and from their current saturation to a target saturation. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 269 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Enhanced­ +Hue +``` +``` +uint16 all M +``` +``` +1 Saturation uint8 max 254 M +2 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +3 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +4 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.18.1. EnhancedHue Field** + +This field SHALL indicate the target extended hue for the light. + +**3.2.8.18.2. Saturation Field** + +This field SHALL indicate the saturation, as described in the MoveToHueAndSaturation command. + +**3.2.8.18.3. TransitionTime Field** + +This field SHALL indicate the transition time, as described in the MoveToHue command. + +**3.2.8.18.4. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.18.5. Effect on Receipt** + +On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 (Curren­ +tHueAndCurrentSaturation) and set the EnhancedColorMode attribute to the value 3 (Enhanced­ +CurrentHueAndCurrentSaturation). The device SHALL then move from its current enhanced hue +and saturation to the values given in the EnhancedHue and Saturation fields. + +The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the +new color SHALL be equal to the TransitionTime field, in 1/10ths of a second. + +The path through color space taken during the transition is not specified, but it is recommended +that the shortest path is taken through color space, i.e., movement is 'in a straight line' across the +CIE xyY Color Space. + +**3.2.8.19. ColorLoopSet Command** + +This command allows a color loop to be activated such that the color light cycles through its range +of hues. + +``` +Page 270 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UpdateFlags UpdateFlags­ +Bitmap +``` +``` +all M +``` +``` +1 Action Color­ +LoopActio­ +nEnum +``` +``` +all M +``` +``` +2 Direction ColorLoopDi­ +rectionEnum +``` +``` +all M +``` +``` +3 Time uint16 all M +4 StartHue uint16 all M +5 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +6 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.19.1. UpdateFlags Field** + +This field SHALL indicate which color loop attributes to update (from the values supplied in the +other fields, see field descriptions below) before the color loop is started. + +**3.2.8.19.2. Action Field** + +This field SHALL indicate the action to take for the color loop. + +**3.2.8.19.3. Direction Field** + +This field SHALL indicate the direction for the color loop. + +**3.2.8.19.4. Time Field** + +This field SHALL indicate the number of seconds over which to perform a full color loop. + +**3.2.8.19.5. Start Hue Field** + +This field SHALL indicate the starting hue to use for the color loop. + +**3.2.8.19.6. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.19.7. Effect on Receipt** + +On receipt of this command, the device SHALL first update its color loop attributes according to the +value of the UpdateFlags field, as follows. + +- If the UpdateDirection sub-field is set to 1, the device SHALL set the ColorLoopDirection + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 271 +``` + +``` +attribute to the value of the Direction field. +``` +- If the UpdateTime sub-field is set to 1, the device SHALL set the ColorLoopTime attribute to the + value of the Time field. +- If the UpdateStartHue sub-field is set to 1, the device SHALL set the ColorLoopStartEnhanced­ + Hue attribute to the value of the StartHue field. +- If the UpdateAction sub-field of the UpdateFlags field is set to 1, the device SHALL adhere to the + action specified in the Action field, as follows. + ◦ If the value of the Action field is set to 0 and the color loop is active, i.e. the ColorLoopActive + attribute is set to 1, the device SHALL de-active the color loop, set the ColorLoopActive + attribute to 0 and set the EnhancedCurrentHue attribute to the value of the ColorLoopStore­ + dEnhancedHue attribute. + ◦ If the value of the Action field is set to 0 and the color loop is inactive, i.e. the Color­ + LoopActive attribute is set to 0, the device SHALL ignore the action update component of the + command, i.e. the EnhancedCurrentHue attribute SHALL NOT be updated (contrasting with + the case described in the previous bullet). + ◦ If the value of the Action field is set to 1, the device SHALL set the ColorLoopStoredEn­ + hancedHue attribute to the value of the EnhancedCurrentHue attribute, set the Color­ + LoopActive attribute to 1 and activate the color loop, starting from the value of the Color­ + LoopStartEnhancedHue attribute. + ◦ If the value of the Action field is set to 2, the device SHALL set the ColorLoopStoredEn­ + hancedHue attribute to the value of the EnhancedCurrentHue attribute, set the Color­ + LoopActive attribute to 1 and activate the color loop, starting from the value of the + EnhancedCurrentHue attribute. + +If the color loop is active, the device SHALL cycle over the complete range of values of the +EnhancedCurrentHue attribute in the direction of the ColorLoopDirection attribute over the time +specified in the ColorLoopTime attribute. The level of increments/decrements is application spe­ +cific. + +If the color loop is active (and stays active), the device SHALL immediately react on updates of the +ColorLoopDirection and ColorLoopTime attributes. + +**3.2.8.20. StopMoveStep Command** + +This command is provided to allow MoveTo and Step commands to be stopped. + +``` +NOTE This automatically provides symmetry to the Level Control cluster. +``` +``` +NOTE The StopMoveStep command has no effect on an active color loop. +``` +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +Page 272 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.20.1. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.20.2. Effect on Receipt** + +Upon receipt of this command, any MoveTo, Move or Step command currently in process SHALL be +terminated. The values of the CurrentHue, EnhancedCurrentHue and CurrentSaturation attributes +SHALL be left at their present value upon receipt of the StopMoveStep command, and the Remain­ +ingTime attribute SHALL be set to zero. + +**3.2.8.21. MoveColorTemperature Command** + +This command allows the color temperature of the light to be moved at a specified rate. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 MoveMode MoveMod­ +eEnum +``` +``` +all M +``` +``` +1 Rate uint16 all M +2 ColorTem­ +peratureMi­ +nimum­ +Mireds +``` +``` +uint16 max 65279 M +``` +``` +3 ColorTem­ +perature­ +Maximum­ +Mireds +``` +``` +uint16 max 65279 M +``` +``` +4 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +5 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +**3.2.8.21.1. MoveMode Field** + +This field SHALL indicate the mode of movement, as described in the MoveHue command. + +**3.2.8.21.2. Rate Field** + +This field SHALL indicate the rate of movement in steps per second. A step is a change in the color +temperature of a device by one unit. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 273 +``` + +**3.2.8.21.3. ColorTemperatureMinimumMireds Field** + +This field SHALL indicate a lower bound on the ColorTemperatureMireds attribute (≡ an upper +bound on the color temperature in kelvins) for the current move operation such that: + +ColorTempPhysicalMinMireds <= ColorTemperatureMinimumMireds field <= ColorTempera­ +tureMireds + +As such if the move operation takes the ColorTemperatureMireds attribute towards the value of the +ColorTemperatureMinimumMireds field it SHALL be clipped so that the above invariant is satisfied. +If the ColorTemperatureMinimumMireds field is set to 0, ColorTempPhysicalMinMireds SHALL be +used as the lower bound for the ColorTemperatureMireds attribute. + +**3.2.8.21.4. ColorTemperatureMaximumMireds Field** + +This field SHALL indicate an upper bound on the ColorTemperatureMireds attribute (≡ a lower +bound on the color temperature in kelvins) for the current move operation such that: + +ColorTemperatureMireds <= ColorTemperatureMaximumMireds field <= ColorTempPhysical­ +MaxMireds + +As such if the move operation takes the ColorTemperatureMireds attribute towards the value of the +ColorTemperatureMaximumMireds field it SHALL be clipped so that the above invariant is satis­ +fied. If the ColorTemperatureMaximumMireds field is set to 0, ColorTempPhysicalMaxMireds +SHALL be used as the upper bound for the ColorTemperatureMireds attribute. + +**3.2.8.21.5. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.21.6. Effect on Receipt** + +On receipt of this command, + +- If the MoveMode field is set to 1 (Up) or 3 (Down) + ◦ If the Rate field has a value of zero, the command has no effect and a response SHALL be + returned with the status code set to INVALID_COMMAND. + ◦ Otherwise, a device SHALL set both the ColorMode and EnhancedColorMode attributes to 2 + (ColorTemperatureMireds) The device SHALL then move from its current color temperature + in an up or down direction in a continuous fashion, as detailed in the table. +- If the MoveMode field is set to 0 (Stop), the Rate field SHALL be completely ignored. + +``` +MoveMode Action on Receipt +Stop If moving, stop the operation, else ignore the +command (i.e., the command is accepted but has +no effect). +``` +``` +Page 274 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +MoveMode Action on Receipt +Up Increase the ColorTemperatureMireds attribute +(≡ decrease the color temperature in kelvins) at +the rate given in the Rate field. If the ColorTem­ +peratureMireds attribute reaches the maximum +allowed for the device (via either the ColorTem­ +peratureMaximumMireds field or the Col­ +orTempPhysicalMaxMireds attribute), the move +operation SHALL be stopped. +Down Decrease the ColorTemperatureMireds attribute +(≡ increase the color temperature in kelvins) at +the rate given in the Rate field. If the ColorTem­ +peratureMireds attribute reaches the minimum +allowed for the device (via either the ColorTem­ +peratureMinimumMireds field or the Col­ +orTempPhysicalMinMireds attribute), the move +operation SHALL be stopped. +``` +**3.2.8.22. StepColorTemperature Command** + +This command allows the color temperature of the light to be stepped with a specified step size. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StepMode StepMod­ +eEnum +``` +``` +all M +``` +``` +1 StepSize uint16 all M +2 Transition­ +Time +``` +``` +uint16 max 65534 M +``` +``` +3 ColorTem­ +peratureMi­ +nimum­ +Mireds +``` +``` +uint16 max 65279 M +``` +``` +4 ColorTem­ +perature­ +Maximum­ +Mireds +``` +``` +uint16 max 65279 M +``` +``` +5 Options­ +Mask +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +6 OptionsOve +rride +``` +``` +Options­ +Bitmap +``` +``` +desc 0 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 275 +``` + +**3.2.8.22.1. StepMode Field** + +This field SHALL indicate the mode of the step to be performed, as described in the StepHue com­ +mand. + +**3.2.8.22.2. StepSize Field** + +This field SHALL indicate the change to be added to (or subtracted from) the current value of the +device’s color temperature. + +**3.2.8.22.3. TransitionTime Field** + +This field SHALL indicate, in units of 1/10ths of a second, the time that SHALL be taken to perform +the step. A step is a change to the device’s color temperature of a magnitude corresponding to the +StepSize field. + +**3.2.8.22.4. ColorTemperatureMinimumMireds Field** + +This field SHALL indicate a lower bound on the ColorTemperatureMireds attribute (≡ an upper +bound on the color temperature in kelvins) for the current step operation such that: + +ColorTempPhysicalMinMireds <= ColorTemperatureMinimumMireds field <= ColorTempera­ +tureMireds + +As such if the step operation takes the ColorTemperatureMireds attribute towards the value of the +ColorTemperatureMinimumMireds field it SHALL be clipped so that the above invariant is satisfied. +If the ColorTemperatureMinimumMireds field is set to 0, ColorTempPhysicalMinMireds SHALL be +used as the lower bound for the ColorTemperatureMireds attribute. + +**3.2.8.22.5. ColorTemperatureMaximumMireds Field** + +This field SHALL indicate an upper bound on the ColorTemperatureMireds attribute (≡ a lower +bound on the color temperature in kelvins) for the current step operation such that: + +ColorTemperatureMireds ≤ ColorTemperatureMaximumMireds field ≤ ColorTempPhysical­ +MaxMireds + +As such if the step operation takes the ColorTemperatureMireds attribute towards the value of the +ColorTemperatureMaximumMireds field it SHALL be clipped so that the above invariant is satis­ +fied. If the ColorTemperatureMaximumMireds field is set to 0, ColorTempPhysicalMaxMireds +SHALL be used as the upper bound for the ColorTemperatureMireds attribute. + +**3.2.8.22.6. OptionsMask and OptionsOverride Fields** + +These fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride +Fields. + +**3.2.8.22.7. Effect on Receipt** + +On receipt of this command, if the StepSize field has a value of zero, the command has no effect and +a response SHALL be returned with the status code set to INVALID_COMMAND. + +``` +Page 276 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Otherwise, a device SHALL set both the ColorMode and EnhancedColorMode attributes to 2 (Col­ +orTemperatureMireds). The device SHALL then move from its current color temperature in an up +or down direction by one step, as detailed in the table. + +``` +StepMode Action on Receipt +Up Increase the ColorTemperatureMireds attribute +(≡ decrease the color temperature in kelvins) by +one step. If the ColorTemperatureMireds +attribute reaches the maximum allowed for the +device (via either the ColorTemperatureMaxi­ +mumMireds field or the ColorTempPhysical­ +MaxMireds attribute), the step operation SHALL +be stopped. +Down Decrease the ColorTemperatureMireds attribute +(≡ increase the color temperature in kelvins) by +one step. If the ColorTemperatureMireds +attribute reaches the minimum allowed for the +device (via either the ColorTemperatureMini­ +mumMireds field or the ColorTempPhysicalMin­ +Mireds attribute), the step operation SHALL be +stopped. +``` +**3.3. Ballast Configuration Cluster** + +This cluster is used for configuring a lighting ballast. + +``` +NOTE Support for Ballast Configuration cluster is provisional. +``` +**3.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 CCB 2104 2193 2230 2393 Deprecated some +attributes +3 CCB 2881 +4 New data model format and notation +``` +**3.3.2. Classification** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 277 +``` + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint BC +``` +**3.3.3. Cluster ID** + +``` +ID Name Conformance +0x0301 Ballast Configuration P +``` +**3.3.4. Dependencies** + +If the Alarms server cluster is supported on the same endpoint then the Alarms functionality is +enabled and the LampAlarmMode attribute SHALL be supported. + +**3.3.5. Data Types** + +**3.3.5.1. BallastStatusBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 BallastNonOpera­ +tional +``` +``` +Operational state of the +ballast. +``` +### M + +``` +1 LampFailure Operational state of the +lamps. +``` +### M + +**3.3.5.1.1. BallastNonOperational Bit** + +This bit SHALL indicate whether the ballast is operational. + +- 0 = The ballast is fully operational +- 1 = The ballast is not fully operational + +**3.3.5.1.2. LampFailure Bit** + +This bit SHALL indicate whether all lamps is operational. + +- 0 = All lamps are operational +- 1 = One or more lamp is not in its socket or is faulty + +**3.3.5.2. LampAlarmModeBitmap Type** + +This data type is derived from map8. + +``` +Page 278 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary Conformance +0 LampBurnHours State of LampBurn­ +Hours alarm genera­ +tion +``` +### M + +**3.3.5.2.1. LampBurnHours Bit** + +This bit SHALL indicate that the LampBurnHours attribute MAY generate an alarm. + +**3.3.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Physi­ +calMin­ +Level +``` +``` +uint8 1 to 254 1 R V M +``` +``` +0x0001 Physical­ +MaxLevel +``` +``` +uint8 1 to 254 254 R V M +``` +``` +0x0002 BallastSta­ +tus +``` +``` +BallastSta­ +tusBitmap +``` +``` +all 0 R V O +``` +``` +0x0010 MinLevel uint8 Physi­ +calMin­ +Level to +MaxLevel +``` +``` +Physi­ +calMin­ +Level +``` +### RW VM M + +``` +0x0011 MaxLevel uint8 MinLevel +to Physical­ +MaxLevel +``` +``` +Physical­ +MaxLevel +``` +### RW VM M + +``` +0x0012 PowerOn­ +Level +``` +### D + +``` +0x0013 PowerOn­ +FadeTime +``` +### D + +``` +0x0014 Intrin­ +sicBallast­ +Factor +``` +``` +uint8 all X RW VM O +``` +``` +0x0015 Ballast­ +FactorAd­ +justment +``` +``` +uint8 100 to MS X null RW VM O +``` +``` +0x0020 Lam­ +pQuantity +``` +``` +uint8 all R V M +``` +``` +0x0030 LampType string max 16 "" RW VM O +0x0031 LampMan­ +ufacturer +``` +``` +string max 16 "" RW VM O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 279 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0032 LampRat­ +edHours +``` +``` +uint24 all X null RW VM O +``` +``` +0x0033 Lamp­ +Burn­ +Hours +``` +``` +uint24 all X 0 RW VM O +``` +``` +0x0034 LampAlar­ +mMode +``` +``` +LampAlar­ +mModeB­ +itmap +``` +``` +all 0 RW VM O +``` +``` +0x0035 Lamp­ +Burn­ +HoursTrip +Point +``` +``` +uint24 all X null RW VM O +``` +**3.3.6.1. PhysicalMinLevel Attribute** + +This attribute SHALL specify the minimum light output the ballast can achieve according to the +dimming light curve (see Dimming Curve). + +**3.3.6.2. PhysicalMaxLevel Attribute** + +This attribute SHALL specify the maximum light output the ballast can achieve according to the +dimming light curve (see Dimming Curve). + +**3.3.6.3. BallastStatus Attribute** + +This attribute SHALL specify the status of various aspects of the ballast or the connected lights, see +BallastStatusBitmap. + +**3.3.6.4. MinLevel Attribute** + +This attribute SHALL specify the light output of the ballast according to the dimming light curve +(see Dimming Curve) when the Level Control Cluster’s CurrentLevel attribute equals to 1 (and the +On/Off Cluster’s OnOff attribute equals to TRUE). + +The value of this attribute SHALL be both greater than or equal to PhysicalMinLevel and less than +or equal to MaxLevel. If an attempt is made to set this attribute to a level where these conditions +are not met, a response SHALL be returned with status code set to CONSTRAINT_ERROR, and the +level SHALL NOT be set. + +**3.3.6.5. MaxLevel Attribute** + +This attribute SHALL specify the light output of the ballast according to the dimming light curve +(see Dimming Curve) when the Level Control Cluster’s CurrentLevel attribute equals to 254 (and the +On/Off Cluster’s OnOff attribute equals to TRUE). + +The value of this attribute SHALL be both less than or equal to PhysicalMaxLevel and greater than + +``` +Page 280 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +or equal to MinLevel. If an attempt is made to set this attribute to a level where these conditions are +not met, a response SHALL be returned with status code set to CONSTRAINT_ERROR, and the level +SHALL NOT be set. + +**3.3.6.6. IntrinsicBallastFactor Attribute** + +This attribute SHALL specify the ballast factor, as a percentage, of the ballast/lamp combination, +prior to any adjustment. + +A value of null indicates in invalid value. + +**3.3.6.7. BallastFactorAdjustment Attribute** + +This attribute SHALL specify the multiplication factor, as a percentage, to be applied to the config­ +ured light output of the lamps. A typical use for this attribute is to compensate for reduction in effi­ +ciency over the lifetime of a lamp. + +The light output is given by + +actual light output = configured light output x BallastFactorAdjustment / 100% + +The range for this attribute is manufacturer dependent. If an attempt is made to set this attribute to +a level that cannot be supported, a response SHALL be returned with status code set to CONSTRAIN­ +T_ERROR, and the level SHALL NOT be changed. The value of null indicates that ballast factor scal­ +ing is not in use. + +**3.3.6.8. LampQuantity Attribute** + +This attribute SHALL specify the number of lamps connected to this ballast. ( **Note 1:** this number +does not take into account whether lamps are actually in their sockets or not). + +**3.3.6.9. LampType Attribute** + +This attribute SHALL specify the type of lamps (including their wattage) connected to the ballast. + +**3.3.6.10. LampManufacturer Attribute** + +This attribute SHALL specify the name of the manufacturer of the currently connected lamps. + +**3.3.6.11. LampRatedHours Attribute** + +This attribute SHALL specify the number of hours of use the lamps are rated for by the manufac­ +turer. + +A value of null indicates an invalid or unknown time. + +**3.3.6.12. LampBurnHours Attribute** + +This attribute SHALL specify the length of time, in hours, the currently connected lamps have been +operated, cumulative since the last re-lamping. Burn hours SHALL NOT be accumulated if the +lamps are off. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 281 +``` + +This attribute SHOULD be reset to zero (e.g., remotely) when the lamps are changed. If partially +used lamps are connected, LampBurnHours SHOULD be updated to reflect the burn hours of the +lamps. + +A value of null indicates an invalid or unknown time. + +**3.3.6.13. LampAlarmMode Attribute** + +This attribute SHALL specify which attributes MAY cause an alarm notification to be generated. A 1 +in each bit position means that its associated attribute is able to generate an alarm. + +``` +NOTE All alarms are also logged in the alarm table – see Alarms cluster. +``` +**3.3.6.14. LampBurnHoursTripPoint Attribute** + +This attribute SHALL specify the number of hours the LampBurnHours attribute MAY reach before +an alarm is generated. + +If the Alarms cluster is not present on the same device this attribute is not used and thus MAY be +omitted (see Dependencies). + +The Alarm Code field included in the generated alarm SHALL be 0x01. + +If this attribute has the value of null, then this alarm SHALL NOT be generated. + +**3.3.7. The Dimming Light Curve** + +The dimming curve is recommended to be logarithmic, as defined by the following equation: + +Where: %Light is the percent light output of the ballast and + +``` +Level is an 8-bit integer between 1 (0.1% light output) and 254 (100% output) that is adjusted for +MinLevel and MaxLevel using the following equation: +``` +Level = (MaxLevel – MinLevel) * CurrentLevel / 253 + (254 * MinLevel – MaxLevel) / 253. + +**Note 1:** Value 255 is not used. + +**Note 2:** The light output is determined by this curve together with the IntrinsicBallastFactor and +BallastFactorAdjustment attributes. + +The table below gives a couple of examples of the dimming light curve for different values of Min­ +Level, MaxLevel and CurrentLevel. + +_Table 7. Examples of The Dimming Light Curve_ + +``` +Page 282 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**MinLevel MaxLevel CurrentLevel Level %Light** + +1 254 1 1 0.10% + +1 254 10 10 0.13% + +1 254 100 100 1.49% + +1 254 254 254 100% + +170 254 1 170 10.1% + +170 254 10 173 11.0% + +170 254 100 203 24.8% + +170 254 254 254 100% + +170 230 1 170 10.1% + +170 230 10 172 10.7% + +170 230 100 193 19.2% + +170 230 254 230 51.9% + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 283 +``` + +Page 284 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 4. HVAC** + +The Cluster Library is made of individual chapters such as this one. References between chapters +are made using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. + +**4.1. General Description** + +**4.1.1. Introduction** + +The clusters specified in this document are for use typically in HVAC applications, but MAY be used +in any application domain. + +**4.1.2. Terms** + +**Precooling:** Cooling a building in the early (cooler) part of the day, so that the thermal mass of the +building decreases cooling needs in the later (hotter) part of the day. + +**4.1.3. Cluster List** + +This section lists the HVAC specific clusters as specified in this chapter. + +_Table 8. Overview of the HVAC Clusters_ + +``` +Cluster ID Cluster Name Description +0x0200 Pump Configuration and Con­ +trol +``` +``` +An interface for configuring +and controlling pumps. +0x0201 Thermostat An interface for configuring +and controlling the functional­ +ity of a thermostat +0x0202 Fan Control An interface for controlling a +fan +0x0204 Thermostat User Interface Con­ +figuration +``` +``` +An interface for configuring the +user interface of a thermostat +(which MAY be remote from the +thermostat) +0x0081 Valve Configuration and Control An interface for configuring +and controlling the functional­ +ity of a valve +``` +**4.2. Pump Configuration and Control Cluster** + +The Pump Configuration and Control cluster provides an interface for the setup and control of +pump devices, and the automatic reporting of pump status information. Note that control of pump +speed is not included – speed is controlled by the On/Off and Level Control clusters. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 285 +``` + +``` +C +``` +``` +C +``` +``` +C +``` +``` +S +``` +``` +S +``` +``` +S +``` +``` +Pump configuration and control +``` +``` +Level control +``` +``` +On/Off +``` +``` +Pump controller Pump +``` +``` += Client = Server +``` +``` +Note: Device names are examples for illustration purposes only +``` +``` +C S +``` +_Figure 14. Typical Usage of Pump Configuration and Control Cluster_ + +**4.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 All Hubs changes +3 New data model format and notation, added +additional events +4 Added feature map +``` +**4.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint PCC +``` +**4.2.3. Cluster ID** + +``` +ID Name +0x0200 Pump Configuration and Control +``` +**4.2.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Page 286 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Conformance Summary +0 PRSCONST ConstantPressure O.a+ Supports operat­ +ing in constant +pressure mode +1 PRSCOMP CompensatedPres­ +sure +``` +``` +O.a+ Supports operat­ +ing in compen­ +sated pressure +mode +2 FLW ConstantFlow O.a+ Supports operat­ +ing in constant +flow mode +3 SPD ConstantSpeed O.a+ Supports operat­ +ing in constant +speed mode +4 TEMP ConstantTempera­ +ture +``` +``` +O.a+ Supports operat­ +ing in constant +temperature mode +5 AUTO Automatic O Supports operat­ +ing in automatic +mode +6 LOCAL LocalOperation O Supports operat­ +ing using local set­ +tings +``` +**4.2.5. Dependencies** + +Where external pressure, flow, and temperature measurements are processed by this cluster (see +ControlMode attribute), these are provided by a Pressure Measurement cluster, a Flow Measure­ +ment cluster, and a Temperature Measurement client cluster, respectively. These 3 client clusters +are used for connection to a remote sensor device. The pump is able to use the sensor measurement +provided by a remote sensor for regulation of the pump speed. + +Note that control of the pump setpoint is not included in this cluster – the On/Off and Level Control +clusters (see Typical Usage of Pump Configuration and Control Cluster) MAY be used by a pump +device to turn it on and off and control its setpoint. Note that the Pump Configuration and Control +cluster MAY override on/off/setpoint settings for specific operation modes (See OperationMode +attribute for detailed description of the operation and control of the pump.). + +**4.2.6. Data Types** + +**4.2.6.1. PumpStatusBitmap Type** + +This data type is derived from map16. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 287 +``` + +``` +Bit Name Summary Conformance +0 DeviceFault A fault related to the +system or pump device +is detected. +``` +### M + +``` +1 SupplyFault A fault related to the +supply to the pump is +detected. +``` +### M + +``` +2 SpeedLow Setpoint is too low to +achieve. +``` +### M + +``` +3 SpeedHigh Setpoint is too high to +achieve. +``` +### M + +``` +4 LocalOverride Device control is over­ +ridden by hardware, +such as an external +STOP button or via a +local HMI. +``` +### M + +``` +5 Running Pump is currently run­ +ning +``` +### M + +``` +6 RemotePressure A remote pressure sen­ +sor is used as the sen­ +sor for the regulation of +the pump. +``` +### M + +``` +7 RemoteFlow A remote flow sensor is +used as the sensor for +the regulation of the +pump. +``` +### M + +``` +8 RemoteTemperature A remote temperature +sensor is used as the +sensor for the regula­ +tion of the pump. +``` +### M + +**4.2.6.1.1. DeviceFault Bit** + +If this bit is set, it MAY correspond to an event in the range 2-16, see Events. + +**4.2.6.1.2. SupplyFault Bit** + +If this bit is set, it MAY correspond to an event in the range 0-1 or 13, see Events. + +**4.2.6.1.3. LocalOverride Bit** + +While this bit is set, the EffectiveOperationMode is adjusted to Local. Any request changing Opera­ +tionMode SHALL generate a FAILURE error status until LocalOverride is cleared on the physical +device. When LocalOverride is cleared, the device SHALL return to the operation mode set in Oper­ +ationMode. + +``` +Page 288 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.2.6.1.4. RemotePressure Bit** + +If this bit is set, EffectiveControlMode is ConstantPressure and the setpoint for the pump is inter­ +preted as a percentage of the range of the remote sensor ([MinMeasuredValue – MaxMeasured­ +Value]). + +**4.2.6.1.5. RemoteFlow Bit** + +If this bit is set, EffectiveControlMode is ConstantFlow, and the setpoint for the pump is interpreted +as a percentage of the range of the remote sensor ([MinMeasuredValue – MaxMeasuredValue]). + +**4.2.6.1.6. RemoteTemperature Bit** + +If this bit is set, EffectiveControlMode is ConstantTemperature, and the setpoint for the pump is +interpreted as a percentage of the range of the remote sensor ([MinMeasuredValue – MaxMeasured­ +Value]) + +**4.2.6.2. OperationModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Normal The pump is controlled +by a setpoint, as +defined by a connected +remote sensor or by the +ControlMode attribute. +``` +### M + +``` +1 Minimum This value sets the +pump to run at the +minimum possible +speed it can without +being stopped. +``` +### SPD + +``` +2 Maximum This value sets the +pump to run at its max­ +imum possible speed. +``` +### SPD + +``` +3 Local This value sets the +pump to run with the +local settings of the +pump, regardless of +what these are. +``` +### LOCAL + +**4.2.6.2.1. Normal Value** + +If the pump is running in this operation mode the setpoint is an internal variable which MAY be +controlled between 0% and 100%, e.g., by means of the Level Control cluster + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 289 +``` + +**4.2.6.3. ControlModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 ConstantSpeed The pump is running at +a constant speed. +``` +### SPD + +``` +1 ConstantPressure The pump will regulate +its speed to maintain a +constant differential +pressure over its +flanges. +``` +### PRSCONST + +``` +2 ProportionalPressure The pump will regulate +its speed to maintain a +constant differential +pressure over its +flanges. +``` +### PRSCOMP + +``` +3 ConstantFlow The pump will regulate +its speed to maintain a +constant flow through +the pump. +``` +### FLW + +``` +5 ConstantTemperature The pump will regulate +its speed to maintain a +constant temperature. +``` +### TEMP + +``` +7 Automatic The operation of the +pump is automatically +optimized to provide +the most suitable per­ +formance with respect +to comfort and energy +savings. +``` +### AUTO + +**4.2.6.3.1. ConstantSpeed Value** + +The setpoint is interpreted as a percentage of the range derived from the [MinConstSpeed – Max­ +ConstSpeed] attributes. + +**4.2.6.3.2. ConstantPressure Value** + +The setpoint is interpreted as a percentage of the range of the sensor used for this control mode. In +case of the internal pressure sensor, this will be the range derived from the [MinConstPressure – +MaxConstPressure] attributes. In case of a remote pressure sensor, this will be the range derived +from the [MinMeasuredValue – MaxMeasuredValue] attributes of the remote pressure sensor. + +**4.2.6.3.3. ProportionalPressure Value** + +The setpoint is interpreted as a percentage of the range derived of the [MinCompPressure – Max­ + +``` +Page 290 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +CompPressure] attributes. The internal setpoint will be lowered (compensated) dependent on the +flow in the pump (lower flow ⇒ lower internal setpoint). + +**4.2.6.3.4. ConstantFlow Value** + +The setpoint is interpreted as a percentage of the range of the sensor used for this control mode. In +case of the internal flow sensor, this will be the range derived from the [MinConstFlow – MaxConst­ +Flow] attributes. In case of a remote flow sensor, this will be the range derived from the [MinMea­ +suredValue – MaxMeasuredValue] attributes of the remote flow sensor. + +**4.2.6.3.5. ConstantTemperature Value** + +The setpoint is interpreted as a percentage of the range of the sensor used for this control mode. In +case of the internal temperature sensor, this will be the range derived from the [MinConstTemp – +MaxConstTemp] attributes. In case of a remote temperature sensor, this will be the range derived +from the [MinMeasuredValue – MaxMeasuredValue] attributes of the remote temperature sensor. + +**4.2.6.3.6. Automatic Value** + +This behavior is manufacturer defined. The pump can be stopped by setting the setpoint of the level +control cluster to 0, or by using the On/Off cluster. If the pump is started (at any setpoint), the speed +of the pump is entirely determined by the pump. + +**4.2.7. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 MaxPres­ +sure +``` +``` +int16 all X F null R V M +``` +``` +0x0001 MaxSpeed uint16 all X F null R V M +0x0002 MaxFlow uint16 all X F null R V M +0x0003 MinConst­ +Pressure +``` +``` +int16 all X F null R V PRSCONST, +[AUTO] +0x0004 MaxConst­ +Pressure +``` +``` +int16 all X F null R V PRSCONST, +[AUTO] +0x0005 MinComp­ +Pressure +``` +``` +int16 all X F null R V PRSCOMP, +[AUTO] +0x0006 MaxComp­ +Pressure +``` +``` +int16 all X F null R V PRSCOMP, +[AUTO] +0x0007 MinConst­ +Speed +``` +``` +uint16 all X F null R V SPD, +[AUTO] +0x0008 MaxConst­ +Speed +``` +``` +uint16 all X F null R V SPD, +[AUTO] +0x0009 MinConst­ +Flow +``` +``` +uint16 all X F null R V FLW, +[AUTO] +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 291 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x000A MaxConst­ +Flow +``` +``` +uint16 all X F null R V FLW, +[AUTO] +0x000B MinConst­ +Temp +``` +``` +int16 min -27315 X F null R V TEMP, +[AUTO] +0x000C MaxConst­ +Temp +``` +``` +int16 min -27315 X F null R V TEMP, +[AUTO] +0x0010 PumpSta­ +tus +``` +``` +PumpSta­ +tusBitmap +``` +``` +desc P 0 R V O +``` +``` +0x0011 Effective­ +Opera­ +tionMode +``` +``` +Operation­ +Mod­ +eEnum +``` +``` +desc N desc R V M +``` +``` +0x0012 Effective­ +Con­ +trolMode +``` +``` +Con­ +trolMod­ +eEnum +``` +``` +desc N desc R V M +``` +``` +0x0013 Capacity int16 all X P null R V M +0x0014 Speed uint16 all X null R V O +0x0015 Life­ +timeRun­ +ningHours +``` +``` +uint24 all X N 0 RW VM O +``` +``` +0x0016 Power uint24 all X null R V O +0x0017 Life­ +timeEner­ +gyCon­ +sumed +``` +``` +uint32 all X N 0 RW VM O +``` +``` +0x0020 Opera­ +tionMode +``` +``` +Operation­ +Mod­ +eEnum +``` +``` +desc N 0 RW VM M +``` +``` +0x0021 Con­ +trolMode +``` +``` +Con­ +trolMod­ +eEnum +``` +``` +desc N 0 RW VM O +``` +``` +0x0022 Alarm­ +Mask +``` +### D + +**4.2.7.1. MaxPressure Attribute** + +This attribute specifies the maximum pressure the pump can achieve. It is a physical limit, and does +not apply to any specific control mode or operation mode. + +Valid range is -3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa). +This attribute SHALL be null if the value is invalid. + +``` +Page 292 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.2.7.2. MaxSpeed Attribute** + +This attribute specifies the maximum speed the pump can achieve. It is a physical limit, and does +not apply to any specific control mode or operation mode. + +Valid range is 0 to 65,534 RPM (steps of 1 RPM). +This attribute SHALL be null if the value is invalid. + +**4.2.7.3. MaxFlow Attribute** + +This attribute specifies the maximum flow the pump can achieve. It is a physical limit, and does not +apply to any specific control mode or operation mode. + +Valid range is 0 m^3 /h to 6,553.4 m^3 /h (steps of 0.1 m^3 /h). +This attribute SHALL be null if the value is invalid. + +**4.2.7.4. MinConstPressure Attribute** + +This attribute specifies the minimum pressure the pump can achieve when it is working with the +ControlMode attribute set to ConstantPressure. + +Valid range is –3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa). +This attribute SHALL be null if the value is invalid. + +**4.2.7.5. MaxConstPressure Attribute** + +This attribute specifies the maximum pressure the pump can achieve when it is working with the +ControlMode attribute set to ConstantPressure. + +Valid range is –3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa). +This attribute SHALL be null if the value is invalid. + +**4.2.7.6. MinCompPressure Attribute** + +This attribute specifies the minimum compensated pressure the pump can achieve when it is work­ +ing with the ControlMode attribute set to ProportionalPressure. + +Valid range is –3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa). +This attribute SHALL be null if the value is invalid. + +**4.2.7.7. MaxCompPressure Attribute** + +This attribute specifies the maximum compensated pressure the pump can achieve when it is work­ +ing with the ControlMode attribute set to ProportionalPressure. + +Valid range is –3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa). +This attribute SHALL be null if the value is invalid. + +**4.2.7.8. MinConstSpeed Attribute** + +This attribute specifies the minimum speed the pump can achieve when it is working with the Con­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 293 +``` + +trolMode attribute set to ConstantSpeed. + +Valid range is 0 to 65,534 RPM (steps of 1 RPM). +This attribute SHALL be null if the value is invalid. + +**4.2.7.9. MaxConstSpeed Attribute** + +This attribute specifies the maximum speed the pump can achieve when it is working with the Con­ +trolMode attribute set to ConstantSpeed. + +Valid range is 0 to 65,534 RPM (steps of 1 RPM). +This attribute SHALL be null if the value is invalid. + +**4.2.7.10. MinConstFlow Attribute** + +This attribute specifies the minimum flow the pump can achieve when it is working with the Con­ +trolMode attribute set to ConstantFlow. + +Valid range is 0 m^3 /h to 6,553.4 m^3 /h (steps of 0.1 m^3 /h). +This attribute SHALL be null if the value is invalid. + +**4.2.7.11. MaxConstFlow Attribute** + +This attribute specifies the maximum flow the pump can achieve when it is working with the Con­ +trolMode attribute set to ConstantFlow. + +Valid range is 0 m^3 /h to 6,553.4 m^3 /h (steps of 0.1 m^3 /h). +This attribute SHALL be null if the value is invalid. + +**4.2.7.12. MinConstTemp Attribute** + +This attribute specifies the minimum temperature the pump can maintain in the system when it is +working with the ControlMode attribute set to ConstantTemperature. + +Valid range is –273.15 °C to 327.67 °C (steps of 0.01 °C). +This attribute SHALL be null if the value is invalid. + +**4.2.7.13. MaxConstTemp Attribute** + +This attribute specifies the maximum temperature the pump can maintain in the system when it is +working with the ControlMode attribute set to ConstantTemperature. + +MaxConstTemp SHALL be greater than or equal to MinConstTemp + +Valid range is –273.15 °C to 327.67 °C (steps of 0.01 °C). +This attribute SHALL be null if the value is invalid. + +**4.2.7.14. PumpStatus Attribute** + +This attribute specifies the activity status of the pump functions as listed in PumpStatusBitmap. +Where a pump controller function is active, the corresponding bit SHALL be set to 1. Where a pump + +``` +Page 294 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +controller function is not active, the corresponding bit SHALL be set to 0. + +**4.2.7.15. EffectiveOperationMode Attribute** + +This attribute specifies current effective operation mode of the pump as defined in OperationMod­ +eEnum. + +The value of the EffectiveOperationMode attribute is the same as the OperationMode attribute, +unless one of the following points are true: + +- The pump is physically set to run with the local settings +- The LocalOverride bit in the PumpStatus attribute is set, + +See OperationMode and ControlMode attributes for a detailed description of the operation and con­ +trol of the pump. + +**4.2.7.16. EffectiveControlMode Attribute** + +This attribute specifies the current effective control mode of the pump as defined in ControlMod­ +eEnum. + +This attribute contains the control mode that currently applies to the pump. It will have the value of +the ControlMode attribute, unless one of the following points are true: + +- The ControlMode attribute is set to Automatic. In this case, the value of the EffectiveCon­ + trolMode SHALL match the behavior of the pump. +- A remote sensor is used as the sensor for regulation of the pump. In this case, EffectiveCon­ + trolMode will display ConstantPressure, ConstantFlow or ConstantTemperature if the remote + sensor is a pressure sensor, a flow sensor or a temperature sensor respectively, regardless of the + value of the ControlMode attribute. + +In case the ControlMode attribute is not included on the device and no remote sensors are con­ +nected, the value of the EffectiveControlMode SHALL match the vendor-specific behavior of the +pump. + +See OperationMode and ControlMode attributes for detailed a description of the operation and con­ +trol of the pump. + +**4.2.7.17. Capacity Attribute** + +This attribute specifies the actual capacity of the pump as a percentage of the effective maximum +setpoint value. It is updated dynamically as the speed of the pump changes. + +If the value is not available (the measurement or estimation of the speed is done in the pump), this +attribute will indicate the null value. + +Valid range is 0 % to 163.835% (0.005 % granularity). Although this attribute is a signed value, val­ +ues of capacity less than zero have no physical meaning. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 295 +``` + +**4.2.7.18. Speed Attribute** + +This attribute specifies the actual speed of the pump measured in RPM. It is updated dynamically as +the speed of the pump changes. + +If the value is not available (the measurement or estimation of the speed is done in the pump), this +attribute will indicate the null value. + +Valid range is 0 to 65,534 RPM. + +**4.2.7.19. LifetimeRunningHours Attribute** + +This attribute specifies the accumulated number of hours that the pump has been powered and the +motor has been running. It is updated dynamically as it increases. It is preserved over power cycles +of the pump. If LifeTimeRunningHours rises above maximum value it “rolls over” and starts at 0 +(zero). + +This attribute is writeable, in order to allow setting to an appropriate value after maintenance. If +the value is not available, this attribute will indicate the null value. + +Valid range is 0 to 16,777,214 hrs. + +**4.2.7.20. Power Attribute** + +This attribute specifies the actual power consumption of the pump in Watts. The value of this +attribute is updated dynamically as the power consumption of the pump changes. + +This attribute is read only. If the value is not available (the measurement of power consumption is +not done in the pump), this attribute will indicate the null value. + +Valid range is 0 to 16,777,214 Watts. + +**4.2.7.21. LifetimeEnergyConsumed Attribute** + +This attribute specifies the accumulated energy consumption of the pump through the entire life­ +time of the pump in kWh. The value of the LifetimeEnergyConsumed attribute is updated dynami­ +cally as the energy consumption of the pump increases. If LifetimeEnergyConsumed rises above +maximum value it “rolls over” and starts at 0 (zero). + +This attribute is writeable, in order to allow setting to an appropriate value after maintenance. + +Valid range is 0 kWh to 4,294,967,294 kWh. +This attribute SHALL be null if the value is unknown. + +**4.2.7.22. OperationMode Attribute** + +This attribute specifies the operation mode of the pump as defined in OperationModeEnum. + +The actual operating mode of the pump is a result of the setting of the attributes OperationMode, +ControlMode and the optional connection of a remote sensor. The operation and control is priori­ +tized as shown in the scheme below: + +``` +Page 296 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Priority Scheme of Pump Operation and Control_ + +If this attribute is Maximum, Minimum or Local, the OperationMode attribute decides how the +pump is operated. + +If this attribute is Normal and a remote sensor is connected to the pump, the type of the remote sen­ +sor decides the control mode of the pump. A connected remote pressure sensor will make the pump +run in control mode Constant pressure and vice versa for flow and temperature type sensors. This +is regardless of the setting of the ControlMode attribute. + +If this attribute is Normal and no remote sensor is connected, the control mode of the pump is +decided by the ControlMode attribute. + +OperationMode MAY be changed at any time, even when the pump is running. The behavior of the +pump at the point of changing the value of this attribute is vendor-specific. + +In the case a device does not support a specific operation mode, the write interaction to this +attribute with an unsupported operation mode value SHALL be ignored and a response containing +the status of CONSTRAINT_ERROR SHALL be returned. + +**4.2.7.23. ControlMode Attribute** + +This attribute specifies the control mode of the pump as defined in ControlModeEnum. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 297 +``` + +See the OperationMode attribute for a detailed description of the operation and control of the +pump. + +ControlMode MAY be changed at any time, even when the pump is running. The behavior of the +pump at the point of changing is vendor-specific. + +In the case a device does not support a specific control mode, the write interaction to this attribute +with an unsupported control mode value SHALL be ignored and a response containing the status of +CONSTRAINT_ERROR SHALL be returned. + +**4.2.8. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 SupplyVolt­ +ageLow +``` +### INFO V O + +``` +0x01 SupplyVolt­ +ageHigh +``` +### INFO V O + +``` +0x02 PowerMissing­ +Phase +``` +### INFO V O + +``` +0x03 SystemPres­ +sureLow +``` +### INFO V O + +``` +0x04 SystemPres­ +sureHigh +``` +### INFO V O + +``` +0x05 DryRunning CRITICAL V O +0x06 MotorTemper­ +atureHigh +``` +### INFO V O + +``` +0x07 PumpMotor­ +FatalFailure +``` +### CRITICAL V O + +``` +0x08 Electron­ +icTempera­ +tureHigh +``` +### INFO V O + +``` +0x09 PumpBlocked CRITICAL V O +0x0A SensorFailure INFO V O +0x0B Electronic­ +NonFatalFail­ +ure +``` +### INFO V O + +``` +0x0C ElectronicFa­ +talFailure +``` +### CRITICAL V O + +``` +0x0D GeneralFault INFO V O +0x0E Leakage INFO V O +0x0F AirDetection INFO V O +``` +``` +Page 298 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Priority Quality Access Conformance +0x10 TurbineOper­ +ation +``` +### INFO V O + +**4.3. Thermostat Cluster** + +This cluster provides an interface to the functionality of a thermostat. + +``` +C +``` +``` +C +``` +``` +C +``` +``` +S +``` +``` +S +``` +``` +Thermostat +``` +``` +Fan control +``` +``` +Thermostat +notification +``` +``` +Heating / cooling +control panel +``` +``` +Heating / cooling device +(e.g. indoor air handler) +``` +``` += Client = Server +``` +``` +Note: Device names are examples for illustration purposes only +``` +``` +C S +``` +``` +S +``` +``` +S +``` +``` +S C +``` +``` +Dehumidification +notification +``` +``` +C +``` +``` +Optional temperature, +humidity and occupancy +sensors +``` +``` +Thermostat +configuration +``` +``` +Dehumidification +configuration +Thermostat +user interface +configuration +``` +``` +Configuration +tool +``` +_Figure 15. Example Usage of the Thermostat and Related Clusters"_ + +**4.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added; fixed some defaults; CCB 1823, 1480 +2 CCB 1981 2186 2249 2250 2251; NFR Thermostat +Setback +3 CCB 2477 2560 2773 2777 2815 2816 3029 +4 All Hubs changes +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 299 +``` + +``` +Revision Description +5 New data model format and notation, added +FeatureMap, collapsed attribute sets, clarified +edge cases around limits, default value of +xxxSetpointLimit now respects AbsxxxSet­ +pointLimit +6 Introduced the LTNE feature and adapted text +(spec issue #5778) +7 Update constraints on local temperature calibra­ +tion and minimum setpoint deadband and intro­ +duced Presets and MatterScheduleConfiguration +features +8 Added comment regarding writing to ControlSe­ +quenceOfOperation. +``` +**4.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint TSTAT +``` +**4.3.3. Cluster ID** + +``` +ID Name +0x0201 Thermostat +``` +**4.3.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 HEAT Heating AUTO, O.a+ Thermostat is +capable of manag­ +ing a heating +device +1 COOL Cooling AUTO, O.a+ Thermostat is +capable of manag­ +ing a cooling +device +2 OCC Occupancy O Supports Occupied +and Unoccupied +setpoints +``` +``` +Page 300 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Conformance Summary +3 SCH ScheduleConfigu­ +ration +``` +``` +[Zigbee], D Supports remote +configuration of a +weekly schedule +of setpoint transi­ +tions +4 SB Setback O Supports config­ +urable setback (or +span) +5 AUTO AutoMode O Supports a System +Mode of Auto +6 LTNE LocalTempera­ +tureNotExposed +``` +``` +O Thermostat does +not expose the +LocalTemperature +Value in the Local­ +Temperature +attribute +7 MSCH MatterSchedule­ +Configuration +``` +``` +O Supports +enhanced sched­ +ules +8 PRES Presets O Thermostat sup­ +ports setpoint pre­ +sets +``` +**4.3.4.1. LocalTemperatureNotExposed Feature** + +This feature indicates that the Calculated Local Temperature used internally is unavailable to +report externally, for example due to the temperature control being done by a separate subsystem +which does not offer a view into the currently measured temperature, but allows setpoints to be +provided. + +**4.3.5. Units of Temperature** + +Temperatures within this cluster are represented by types using units of degree Celsius. + +The temperature data type used throughout this cluster is defined in the Derived Data Types section +of the Data Model. + +The following temperature-related data types are also defined in and used throughout this cluster: + +- TemperatureDifference +- SignedTemperature +- UnsignedTemperature + +While temperature values MUST be transferred over the air using these types, this does not limit +how Thermostats may display or store temperature values. Thermostats which display temperature + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 301 +``` + +values SHOULD follow the recommendations in Conversion of Temperature Values for Display. + +### CAUTION + +``` +Calculations with temperature attributes +Where calculations or comparisons are performed, attribute values must be +converted to a common type. In many cases, it is not sufficient to simply use the +integer representation as the scaling from °C to integer value differs. +``` +**4.3.6. Setpoint Limits** + +There are a number of attributes which impose limits on setpoint values. This imposes constraints +which MUST be maintained by any mechanism which modifies a limit or setpoint. Individual +attribute descriptions detail the actions to be taken should a conflict arise while modifying the +value. + +User configurable limits must be within device limits: + +- AbsMinHeatSetpointLimit <= MinHeatSetpointLimit <= MaxHeatSetpointLimit <= AbsMaxHeat­ + SetpointLimit +- AbsMinCoolSetpointLimit <= MinCoolSetpointLimit <= MaxCoolSetpointLimit <= AbsMaxCoolSet­ + pointLimit + +Setpoints must be within user configurable limits: + +- MinHeatSetpointLimit <= OccupiedHeatingSetpoint <= MaxHeatSetpointLimit +- MinCoolSetpointLimit <= OccupiedCoolingSetpoint <= MaxCoolSetpointLimit +- MinHeatSetpointLimit <= UnoccupiedHeatingSetpoint <= MaxHeatSetpointLimit +- MinCoolSetpointLimit <= UnoccupiedCoolingSetpoint <= MaxCoolSetpointLimit + +If, and only if, the AUTO feature is supported, a deadband must be maintained between Heating +and Cooling setpoints and limits: + +- AbsMinHeatSetpointLimit <= (AbsMinCoolSetpointLimit - MinSetpointDeadBand) +- AbsMaxHeatSetpointLimit <= (AbsMaxCoolSetpointLimit - MinSetpointDeadBand) +- MinHeatSetpointLimit <= (MinCoolSetpointLimit - MinSetpointDeadBand) +- MaxHeatSetpointLimit <= (MaxCoolSetpointLimit - MinSetpointDeadBand) +- OccupiedHeatingSetpoint <= (OccupiedCoolingSetpoint - MinSetpointDeadBand) +- UnoccupiedHeatingSetpoint <= (UnoccupiedCoolingSetpoint - MinSetpointDeadBand) + +**4.3.7. Dependencies** + +If the Alarms server cluster is supported on the same endpoint then the Alarms functionality is +enabled and the AlarmMask attribute SHALL be supported. + +For remote temperature sensing, the Temperature Measurement client cluster MAY be included on +the same endpoint. + +``` +Page 302 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +For occupancy sensing, the Occupancy Sensing client cluster MAY be included on the same end­ +point. + +**4.3.8. Data Types** + +**4.3.8.1. TemperatureDifference Type** + +This data type is derived from int16 and represents a temperature difference with a resolution of +0.01°C. + +- _value_ = ( _temperature in °C_ ) x 100 + +### • -4°C ⇒ -400 + +### • 123.45°C ⇒ 12345 + +The full (non-null) range of -327.67°C to 327.67°C may be used. + +**4.3.8.2. SignedTemperature Type** + +This data type is derived from int8 and represents a temperature from -12.7°C to 12.7°C with a reso­ +lution of 0.1°C. + +- _value_ = ( _temperature in °C_ ) x 10 + +### • -4°C ⇒ -40 + +### • 12.3°C ⇒ 123 + +This type is employed where compactness of representation is important and where the resolution +and range are still satisfactory. + +**4.3.8.3. UnsignedTemperature Type** + +This data type is derived from uint8 and represents a temperature from 0°C to 25.5°C with a resolu­ +tion of 0.1°C. + +- _value_ = ( _temperature in °C_ ) x 10 + +### • 4°C ⇒ 40 + +### • 12.3°C ⇒ 123 + +This type is employed where compactness of representation is important and where the resolution +and range are still satisfactory. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 303 +``` + +**4.3.8.4. ACErrorCodeBitmap Type** + +This data type is derived from map32. + +``` +Bit Name Summary Conformance +0 CompressorFail Compressor Failure or +Refrigerant Leakage +``` +### M + +``` +1 RoomSensorFail Room Temperature +Sensor Failure +``` +### M + +``` +2 OutdoorSensorFail Outdoor Temperature +Sensor Failure +``` +### M + +``` +3 CoilSensorFail Indoor Coil Tempera­ +ture Sensor Failure +``` +### M + +``` +4 FanFail Fan Failure M +``` +**4.3.8.5. AlarmCodeBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 Initialization Initialization failure. +The device failed to +complete initialization +at power-up. +``` +### M + +``` +1 Hardware Hardware failure M +2 SelfCalibration Self-calibration failure M +``` +**4.3.8.6. HVACSystemTypeBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +1..0 CoolingStage Stage of cooling the +HVAC system is using. +``` +### M + +``` +3..2 HeatingStage Stage of heating the +HVAC system is using. +``` +### M + +``` +4 HeatingIsHeatPump Is the heating type Heat +Pump. +``` +### M + +``` +5 HeatingUsesFuel Does the HVAC system +use fuel. +``` +### M + +**4.3.8.6.1. CoolingStage Bits** + +These bits SHALL indicate what stage of cooling the HVAC system is using. + +``` +Page 304 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- 00 = Cool Stage 1 +- 01 = Cool Stage 2 +- 10 = Cool Stage 3 +- 11 = Reserved + +**4.3.8.6.2. HeatingStage Bits** + +These bits SHALL indicate what stage of heating the HVAC system is using. + +- 00 = Heat Stage 1 +- 01 = Heat Stage 2 +- 10 = Heat Stage 3 +- 11 = Reserved + +**4.3.8.6.3. HeatingIsHeatPump Bit** + +This bit SHALL indicate whether the HVAC system is conventional or a heat pump. + +- 0 = Conventional +- 1 = Heat Pump + +**4.3.8.6.4. HeatingUsesFuel Bit** + +This bit SHALL indicate whether the HVAC system uses fuel. + +- 0 = Does not use fuel +- 1 = Uses fuel + +**4.3.8.7. OccupancyBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 Occupied Indicates the occu­ +pancy state +``` +### M + +**4.3.8.7.1. Occupied Bit** + +If this bit is set, it SHALL indicate the occupied state else if the bit if not set, it SHALL indicate the +unoccupied state. + +**4.3.8.8. PresetTypeFeaturesBitmap Type** + +This data type is derived from map16. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 305 +``` + +``` +Bit Name Summary Conformance +0 Automatic Preset may be automat­ +ically activated by the +thermostat +``` +### M + +``` +1 SupportsNames Preset supports user- +provided names +``` +### M + +**4.3.8.9. ProgrammingOperationModeBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 ScheduleActive Schedule programming +mode. This enables any +programmed weekly +schedule configura­ +tions. +``` +### M + +``` +1 AutoRecovery Auto/recovery mode M +2 Economy Economy/EnergyStar +mode +``` +### M + +**4.3.8.10. RelayStateBitmap Type** + +This data type is derived from map16. + +``` +Bit Name Summary Conformance +0 Heat Heat Stage On M +1 Cool Cool Stage On M +2 Fan Fan Stage On M +3 HeatStage2 Heat 2nd Stage On M +4 CoolStage2 Cool 2nd Stage On M +5 FanStage2 Fan 2nd Stage On M +6 FanStage3 Fan 3rd Stage On M +``` +**4.3.8.11. RemoteSensingBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 LocalTemperature Calculated Local Tem­ +perature is derived +from a remote node +``` +### M + +``` +Page 306 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary Conformance +1 OutdoorTemperature OutdoorTemperature is +derived from a remote +node +``` +``` +desc +``` +``` +2 Occupancy Occupancy is derived +from a remote node +``` +### OCC + +**4.3.8.11.1. OutdoorTemperature Bit** + +This bit SHALL be supported if the OutdoorTemperature attribute is supported. + +**4.3.8.12. ScheduleTypeFeaturesBitmap Type** + +This data type is derived from map16. + +``` +Bit Name Summary Conformance +0 SupportsPresets Supports presets [PRES].b+ +1 SupportsSetpoints Supports setpoints O.b+ +2 SupportsNames Supports user-provided +names +``` +### O + +``` +3 SupportsOff Supports transitioning +to SystemModeOff +``` +### O + +**4.3.8.12.1. SupportsPresets Bit** + +This bit SHALL indicate that any ScheduleStruct with a SystemMode field whose value matches the +SystemMode field on the encompassing ScheduleTypeStruct supports specifying presets on Sched­ +uleTransitionStructs contained in its Transitions field. + +**4.3.8.12.2. SupportsSetpoints Bit** + +This bit SHALL indicate that any ScheduleStruct with a SystemMode field whose value matches the +SystemMode field on the encompassing ScheduleTypeStruct supports specifying setpoints on Sched­ +uleTransitionStructs contained in its Transitions field. + +**4.3.8.12.3. SupportsNames Bit** + +This bit SHALL indicate that any ScheduleStruct with a SystemMode field whose value matches the +SystemMode field on the encompassing ScheduleTypeStruct supports setting the value of the Name +field. + +**4.3.8.12.4. SupportsOff Bit** + +This bit SHALL indicate that any ScheduleStruct with a SystemMode field whose value matches the +SystemMode field on the encompassing ScheduleTypeStruct supports setting its SystemMode field +to Off. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 307 +``` + +**4.3.8.13. ScheduleDayOfWeekBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 Sunday Sunday M +1 Monday Monday M +2 Tuesday Tuesday M +3 Wednesday Wednesday M +4 Thursday Thursday M +5 Friday Friday M +6 Saturday Saturday M +7 Away Away or Vacation M +``` +**4.3.8.14. ScheduleModeBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 HeatSetpointPresent Adjust Heat Setpoint M +1 CoolSetpointPresent Adjust Cool Setpoint M +``` +**4.3.8.15. ACCapacityFormatEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 BTUh British Thermal Unit +per Hour +``` +### O + +**4.3.8.16. ACCompressorTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown Unknown compressor +type +``` +### O + +``` +1 T1 Max working ambient +43 °C +``` +### O + +``` +2 T2 Max working ambient +35 °C +``` +### O + +``` +3 T3 Max working ambient +52 °C +``` +### O + +``` +Page 308 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.8.17. ACLouverPositionEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +1 Closed Fully Closed O +2 Open Fully Open O +3 Quarter Quarter Open O +4 Half Half Open O +5 ThreeQuarters Three Quarters Open O +``` +**4.3.8.18. ACRefrigerantTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown Unknown Refrigerant +Type +``` +### O + +``` +1 R22 R22 Refrigerant O +2 R410a R410a Refrigerant O +3 R407c R407c Refrigerant O +``` +**4.3.8.19. ACTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown Unknown AC Type O +1 CoolingFixed Cooling and Fixed +Speed +``` +### O + +``` +2 HeatPumpFixed Heat Pump and Fixed +Speed +``` +### O + +``` +3 CoolingInverter Cooling and Inverter O +4 HeatPumpInverter Heat Pump and +Inverter +``` +### O + +**4.3.8.20. SetpointRaiseLowerModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Heat Adjust Heat Setpoint HEAT +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 309 +``` + +``` +Value Name Summary Conformance +1 Cool Adjust Cool Setpoint COOL +2 Both Adjust Heat Setpoint +and Cool Setpoint +``` +### HEAT | COOL + +**4.3.8.21. ControlSequenceOfOperationEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 CoolingOnly Heat and Emergency +are not possible +``` +### [COOL] + +``` +1 CoolingWithReheat Heat and Emergency +are not possible +``` +### [COOL] + +``` +2 HeatingOnly Cool and precooling +(see Terms) are not pos­ +sible +``` +### [HEAT] + +``` +3 HeatingWithReheat Cool and precooling are +not possible +``` +### [HEAT] + +``` +4 CoolingAndHeating All modes are possible [HEAT & COOL] +5 CoolingAndHeating­ +WithReheat +``` +``` +All modes are possible [HEAT & COOL] +``` +### NOTE + +``` +CoolingAndHeating +A thermostat indicating it supports CoolingAndHeating (or CoolingAndHeatingWith­ +Reheat) SHOULD be able to request heating or cooling on demand and will usually +support the Auto SystemMode. +``` +``` +Systems which support cooling or heating, requiring external intervention to +change modes or where the whole building must be in the same mode, SHOULD +report CoolingOnly or HeatingOnly based on the current capability. +``` +**4.3.8.22. PresetScenarioEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +1 Occupied The thermostat-con­ +trolled area is occupied +``` +### M + +``` +2 Unoccupied The thermostat-con­ +trolled area is unoccu­ +pied +``` +### M + +``` +Page 310 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +3 Sleep Users are likely to be +sleeping +``` +### M + +``` +4 Wake Users are likely to be +waking up +``` +### M + +``` +5 Vacation Users are on vacation M +6 GoingToSleep Users are likely to be +going to sleep +``` +### M + +``` +254 UserDefined Custom presets M +``` +**4.3.8.22.1. Undefined Value** + +This value SHALL have no specified scenario. + +**4.3.8.22.2. Occupied Value** + +This value SHALL indicate the preset for periods when the thermostat’s temperature-controlled +area is occupied. It is intended for thermostats that can automatically determine occupancy. + +**4.3.8.22.3. Unoccupied Value** + +This value SHALL indicate the preset for periods when the thermostat’s temperature-controlled +area is unoccupied. It is intended for thermostats that can automatically determine occupancy. + +**4.3.8.22.4. Sleep Value** + +This value SHALL indicate the preset for periods when users are likely to be asleep. + +**4.3.8.22.5. Wake Value** + +This value SHALL indicate the preset for periods when users are likely to be waking up. + +**4.3.8.22.6. Vacation Value** + +This value SHALL indicate the preset for periods when users are on vacation, or otherwise out-of- +home for extended periods of time. + +**4.3.8.22.7. GoingToSleep Value** + +This value SHALL indicate the preset for periods when users are likely to be going to sleep. + +**4.3.8.22.8. UserDefined Value** + +This value SHALL indicate a free-form preset; when set, the Name field on PresetStruct SHALL NOT +be null. + +**4.3.8.23. SetpointChangeSourceEnum Type** + +This data type is derived from enum8. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 311 +``` + +``` +Value Name Summary Conformance +0 Manual Manual, user-initiated +setpoint change via the +thermostat +``` +### O + +``` +1 Schedule Schedule/internal pro­ +gramming-initiated set­ +point change +``` +### [SCH | MSCH] + +``` +2 External Externally-initiated set­ +point change (e.g., +DRLC cluster com­ +mand, attribute write) +``` +### O + +**4.3.8.24. StartOfWeekEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Sunday M +1 Monday M +2 Tuesday M +3 Wednesday M +4 Thursday M +5 Friday M +6 Saturday M +``` +**4.3.8.25. SystemModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Off The Thermostat does +not generate demand +for Cooling or Heating +``` +### O + +``` +1 Auto Demand is generated +for either Cooling or +Heating, as required +``` +### AUTO + +``` +3 Cool Demand is only gener­ +ated for Cooling +``` +### [COOL] + +``` +4 Heat Demand is only gener­ +ated for Heating +``` +### [HEAT] + +``` +Page 312 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +5 EmergencyHeat 2 nd stage heating is in +use to achieve desired +temperature +``` +### [HEAT] + +``` +6 Precooling (see Terms) [COOL] +7 FanOnly O +8 Dry O +9 Sleep O +``` +_Table 9. Interpretation of Heat, Cool and Auto SystemModeEnum Values_ + +``` +Attribute Values Temperature Below +Heat Setpoint +``` +``` +Temperature Between +Heat Setpoint and +Cool Setpoint +``` +``` +Temperature Above +Cool Setpoint +``` +``` +Heat Temperature below tar­ +get +``` +``` +Temperature on target Temperature on target +``` +``` +Cool Temperature on target Temperature on target Temperature above tar­ +get +Auto Temperature below tar­ +get +``` +``` +Temperature on target Temperature above tar­ +get +``` +**4.3.8.26. ThermostatRunningModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Off The Thermostat does +not generate demand +for Cooling or Heating +``` +### O + +``` +3 Cool Demand is only gener­ +ated for Cooling +``` +### [COOL] + +``` +4 Heat Demand is only gener­ +ated for Heating +``` +### [HEAT] + +**4.3.8.27. TemperatureSetpointHoldEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 SetpointHoldOff Follow scheduling pro­ +gram +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 313 +``` + +``` +Value Name Summary Conformance +1 SetpointHoldOn Maintain current set­ +point, regardless of +schedule transitions +``` +### M + +**4.3.8.28. PresetStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Pre­ +setHandle +``` +``` +octstr max 16 X M +``` +``` +1 PresetSce­ +nario +``` +``` +PresetSce­ +narioEnum +``` +``` +all M +``` +``` +2 Name string max 64 X null O +3 Cool­ +ingSet­ +point +``` +``` +tempera­ +ture +``` +``` +desc 26°C COOL +``` +``` +4 Heat­ +ingSet­ +point +``` +``` +tempera­ +ture +``` +``` +desc 20°C HEAT +``` +``` +5 BuiltIn bool all X false M +``` +**4.3.8.28.1. PresetHandle Field** + +This field SHALL indicate a device generated identifier for this preset. It SHALL be unique on the +device, and SHALL NOT be reused after the associated preset has been deleted. + +This field SHALL only be null when the encompassing PresetStruct is appended to the Presets +attribute for the purpose of creating a new Preset. Refer to Presets for the creation of Preset han­ +dles. + +**4.3.8.28.2. PresetScenario Field** + +This field SHALL indicate the associated PresetScenarioEnum value for this preset. + +**4.3.8.28.3. Name Field** + +This field SHALL indicate a name provided by a user. The null value SHALL indicate no name. + +Within each subset of presets sharing the same PresetScenario field value, there SHALL NOT be any +presets with the same value, including null as a value, in the Name field. + +**4.3.8.28.4. CoolingSetpoint Field** + +This field SHALL indicate the cooling setpoint for the preset. Refer to Setpoint Limits for value con­ +straints. + +``` +Page 314 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.8.28.5. HeatingSetpoint Field** + +This field SHALL indicate the heating setpoint for the preset. Refer to Setpoint Limits for value con­ +straints. + +**4.3.8.28.6. BuiltIn Field** + +This field SHALL indicate whether the preset is marked as "built-in", meaning that it can be modi­ +fied, but it cannot be deleted. + +**4.3.8.29. PresetTypeStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 PresetSce­ +nario +``` +``` +PresetSce­ +narioEnum +``` +``` +all M +``` +``` +1 Num­ +berOfPre­ +sets +``` +``` +uint8 all 0 M +``` +``` +2 Preset­ +TypeFea­ +tures +``` +``` +Preset­ +TypeFea­ +tures­ +Bitmap +``` +``` +all 0 M +``` +**4.3.8.29.1. PresetScenario Field** + +This field SHALL specify a PresetScenarioEnum value supported by this thermostat. + +**4.3.8.29.2. NumberOfPresets Field** + +This field SHALL specify a limit for the number of presets for this PresetScenarioEnum. + +**4.3.8.29.3. PresetTypeFeatures Field** + +This field SHALL specify a bitmap of features for this PresetTypeStruct. + +**4.3.8.30. WeeklyScheduleTransitionStruct Type** + +This represents a single transition in a Thermostat schedule + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Transi­ +tionTime +``` +``` +uint16 max 1439 M +``` +``` +1 HeatSet­ +point +``` +``` +tempera­ +ture +``` +``` +all X M +``` +``` +2 CoolSet­ +point +``` +``` +tempera­ +ture +``` +``` +all X M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 315 +``` + +**4.3.8.30.1. TransitionTime Field** + +This field SHALL represent the start time of the schedule transition during the associated day. The +time will be represented by a 16 bits unsigned integer to designate the minutes since midnight. For +example, 6am will be represented by 360 minutes since midnight and 11:30pm will be represented +by 1410 minutes since midnight. + +**4.3.8.30.2. HeatSetpoint Field** + +This field SHALL represent the heat setpoint to be applied at this associated transition start time. + +**4.3.8.30.3. CoolSetpoint Field** + +This field SHALL represent the cool setpoint to be applied at this associated transition start time. + +**4.3.8.31. ScheduleStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Schedule­ +Handle +``` +``` +octstr max 16 X M +``` +``` +1 System­ +Mode +``` +``` +System­ +Mod­ +eEnum +``` +``` +desc M +``` +``` +2 Name string max 64 O +3 Pre­ +setHandle +``` +``` +octstr max 16 O +``` +``` +4 Transi­ +tions +``` +``` +list[Sched­ +uleTransi­ +tionStruct] +``` +``` +1 to Num­ +berOf­ +Schedule­ +Transitions +``` +``` +empty M +``` +``` +5 BuiltIn bool all X false M +``` +**4.3.8.31.1. ScheduleHandle Field** + +This field SHALL indicate a device generated identifier for this schedule. It SHALL be unique on the +device, and SHALL NOT be reused after the associated schedule has been deleted. + +This field SHALL only be null when the encompassing ScheduleStruct is appended to the Schedules +attribute for the purpose of creating a new Schedule. Refer to Schedules for the creation of Sched­ +ule handles. + +**4.3.8.31.2. SystemMode Field** + +This field SHALL specify the default thermostat system mode for transitions in this schedule. The +only valid values for this field SHALL be Auto, Heat, and Cool. + +``` +Page 316 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.8.31.3. Name Field** + +This field SHALL specify a name for the ScheduleStruct. + +**4.3.8.31.4. PresetHandle Field** + +This field SHALL indicate the default PresetHandle value for transitions in this schedule. + +**4.3.8.31.5. Transitions Field** + +This field SHALL specify a list of transitions for the schedule. + +This field SHALL NOT contain more than one ScheduleStruct with the same TransitionTime field +and overlapping DayOfWeek fields; i.e. there SHALL be no duplicate transitions. + +If the NumberOfScheduleTransitionsPerDay attribute is not null, then for each bit in ScheduleDay­ +OfWeekBitmap, the number of transitions with that bit set in DayOfWeek SHALL NOT be greater +than the value of the NumberOfScheduleTransitionsPerDay attribute. + +For the purposes of determining which ScheduleStruct in this list is currently active, the current +time SHALL be the number of minutes past midnight in the display value of the current time, not +the actual number of minutes that have elapsed since midnight. On days which transition into or +out of daylight saving time, certain values may repeat or not occur during the transition period. + +A ScheduleTransitionStruct in this list SHALL be active if the current day of the week matches its +DayOfWeek field and the current time is greater than or equal to the TransitionTime, but less than +the TransitionTime on any other ScheduleTransitionStruct in the Transitions field whose Day­ +OfWeek field also matches the current day of the week. + +If the current time is less than every ScheduleTransitionStruct whose DayOfWeek field also matches +the current day of the week, the server SHALL attempt the same process to identify the active +ScheduleTransitionStruct for the day preceding the previously attempted day of the week, repeat­ +ing until an active ScheduleTransitionStruct is found or the attempted day is the current day of the +week again. If no active ScheduleTransitionStruct is found, then the active ScheduleTransition­ +Struct SHALL be the ScheduleTransitionStruct with the largest TransitionTime field from the set of +ScheduleTransitionStructs whose DayOfWeek field matches the current day of the week. + +**4.3.8.31.6. BuiltIn Field** + +This field SHALL indicate whether the schedule is marked as "built-in", meaning that it can be mod­ +ified, but it cannot be deleted. + +**4.3.8.32. ScheduleTransitionStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Day­ +OfWeek +``` +``` +Schedule­ +Day­ +OfWeek­ +Bitmap +``` +``` +desc M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 317 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +1 Transi­ +tionTime +``` +``` +uint16 max 1439 M +``` +``` +2 Pre­ +setHandle +``` +``` +octstr max 16 [PRES] +``` +``` +3 System­ +Mode +``` +``` +System­ +Mod­ +eEnum +``` +``` +desc O +``` +``` +4 Cool­ +ingSet­ +point +``` +``` +tempera­ +ture +``` +``` +desc [COOL] +``` +``` +5 Heat­ +ingSet­ +point +``` +``` +tempera­ +ture +``` +``` +desc [HEAT] +``` +This struct provides a time of day and a set of days of the week for a state transition within a sched­ +ule. The thermostat SHALL use the following order of precedence for determining a new setpoint at +the time of transition: + +1. If the PresetHandle field is provided, then the setpoint for the PresetStruct in the Presets + attribute with that identifier SHALL be used +2. If either the HeatingSetpoint or CoolingSetpoint is provided, then it SHALL be used + a.If the SystemMode field is provided, the HeatingSetpoint and CoolingSetpoint fields SHALL + be interpreted using the SystemMode field +b. If the SystemMode field is not provided, the HeatingSetpoint and CoolingSetpoint fields +SHALL be interpreted using the SystemMode field on the parent ScheduleStruct +3. If neither the PresetHandle field or any Setpoint field is provided, then the PresetHandle field + on the parent ScheduleStruct SHALL be used to determine the active PresetStruct +4. If the PresetHandle is not indicated and no setpoint is provided for the current SystemMode, the + server SHALL use a default value for the current SystemMode. + +If the setpoint was derived from a preset, then the ActivePresetHandle SHALL be set to the Pre­ +setHandle of that preset. + +If a CoolingSetpoint was used to determine the cooling setpoint: + +- If the server supports the OCC feature, and the Occupied bit is not set on the Occupancy + attribute, then the UnoccupiedCoolingSetpoint attribute SHALL be set to the CoolingSetpoint +- Otherwise, the OccupiedCoolingSetpoint attribute SHALL be set to the CoolingSetpoint + +If a HeatingSetpoint was used to determine the heating setpoint: + +- If the server supports the OCC feature, and the Occupied bit is not set on the Occupancy + attribute, then the UnoccupiedHeatingSetpoint attribute SHALL be set to the HeatingSetpoint + +``` +Page 318 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Otherwise, the OccupiedHeatingSetpoint attribute SHALL be set to the HeatingSetpoint + +The ScheduleTransitionStruct SHALL be invalid if all the following are true: + +- The HeatingSetpoint field is not provided +- The PresetHandle field is not provided +- The PresetHandle field on the encompassing ScheduleStruct is not provided +- The SystemMode field is provided and has the value Heat or Auto, or the SystemMode field on + the parent ScheduleStruct has the value Heat or Auto + +The ScheduleTransitionStruct SHALL be invalid if all the following are true: + +- The CoolingSetpoint field is not provided +- The PresetHandle field is not provided +- The PresetHandle field on the encompassing ScheduleStruct is not provided +- The SystemMode field is provided and has the value Cool or Auto, or the SystemMode field on + the parent ScheduleStruct has the value Cool or Auto + +**4.3.8.32.1. DayOfWeek Field** + +This field SHALL specify a bitmask of days of the week that the transition applies to. The Vacation +bit SHALL NOT be set; vacation schedules SHALL be set via the vacation preset. + +**4.3.8.32.2. TransitionTime Field** + +This SHALL specify the time of day at which the transition becomes active, in terms of minutes +within the day representing the wall clock, where 0 is 00:00:00, 1 is 00:01:00 and 1439 is 23:59:00. + +Handling of transitions during the changeover of Daylight Saving Time is implementation-depen­ +dent. + +**4.3.8.32.3. PresetHandle Field** + +This field SHALL specify the preset used at the TransitionTime. If this field is provided, then the Sys­ +temMode, CoolingSetpoint and HeatingSetpoint fields SHALL NOT be provided. + +**4.3.8.32.4. SystemMode Field** + +This SHALL specify the default mode to which the thermostat will switch for this transition, over­ +riding the default for the schedule. The only valid values for this field SHALL be Auto, Heat, Cool +and Off. This field SHALL only be included when the required system mode differs from the sched­ +ule’s default SystemMode. + +**4.3.8.32.5. CoolingSetpoint Field** + +This field SHALL specify the cooling setpoint for the transition. If PresetHandle is set, this field +SHALL NOT be included. Refer to Setpoint Limits for value constraints. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 319 +``` + +**4.3.8.32.6. HeatingSetpoint Field** + +This field SHALL specify the cooling setpoint for the transition. If PresetHandle is set, this field +SHALL NOT be included. Refer to Setpoint Limits for value constraints. + +**4.3.8.33. ScheduleTypeStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 System­ +Mode +``` +``` +System­ +Mod­ +eEnum +``` +``` +desc M +``` +``` +1 Num­ +berOf­ +Schedules +``` +``` +uint8 max Num­ +berOf­ +Schedules +``` +### 0 M + +``` +2 Schedule­ +TypeFea­ +tures +``` +``` +Schedule­ +TypeFea­ +tures­ +Bitmap +``` +``` +desc 0 M +``` +**4.3.8.33.1. SystemMode Field** + +This field SHALL specify a SystemModeEnum supported by this thermostat for Schedules. The only +valid values for this field SHALL be Auto, Heat, and Cool. + +**4.3.8.33.2. NumberOfSchedules Field** + +This field SHALL specify a limit for the number of Schedules for this SystemMode. + +**4.3.8.33.3. ScheduleTypeFeatures Field** + +This field SHALL specify a bitmap of features for this schedule entry. At least one of SupportsPresets +and SupportsSetpoints SHALL be set. + +**4.3.9. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 LocalTem­ +perature +``` +``` +tempera­ +ture +``` +``` +all X P null R V M +``` +``` +0x0001 Out­ +doorTem­ +perature +``` +``` +tempera­ +ture +``` +``` +all X null R V O +``` +``` +0x0002 Occu­ +pancy +``` +``` +Occupan­ +cyBitmap +``` +``` +all 1 R V OCC +``` +``` +Page 320 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**ID Name Type Constraint Quality Default Access Confor­ +mance** + +0x0003 **AbsMin­ +HeatSet­ +pointLimit** + +``` +tempera­ +ture +``` +``` +desc F 7°C R V [HEAT] +``` +0x0004 **AbsMax­ +HeatSet­ +pointLimit** + +``` +tempera­ +ture +``` +``` +desc F 30°C R V [HEAT] +``` +0x0005 **AbsMin­ +CoolSet­ +pointLimit** + +``` +tempera­ +ture +``` +``` +desc F 16°C R V [COOL] +``` +0x0006 **AbsMax­ +CoolSet­ +pointLimit** + +``` +tempera­ +ture +``` +``` +desc F 32°C R V [COOL] +``` +0x0007 **PICool­ +ingDe­ +mand** + +``` +uint8 0% to +100% +``` +### P - R V [COOL] + +0x0008 **PIHeat­ +ingDe­ +mand** + +``` +uint8 0% to +100% +``` +### P - R V [HEAT] + +0x0009 **HVACSys­ +temType­ +Configura­ +tion** + +``` +HVACSys­ +tem­ +TypeBitma +p +``` +``` +desc N 0 R[W] VM D +``` +0x0010 **LocalTem­ +perature­ +Calibra­ +tion** + +``` +SignedTem +perature +``` +``` +all N 0°C RW VM [!LTNE] +``` +0x0011 **Occupied­ +Cool­ +ingSet­ +point** + +``` +tempera­ +ture +``` +``` +desc N 26°C RW VO COOL +``` +0x0012 **Occupied­ +Heat­ +ingSet­ +point** + +``` +tempera­ +ture +``` +``` +desc N 20°C RW VO HEAT +``` +0x0013 **Unoccu­ +piedCool­ +ingSet­ +point** + +``` +tempera­ +ture +``` +``` +desc N 26°C RW VO COOL & +OCC +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 321 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0014 Unoccu­ +piedHeat­ +ingSet­ +point +``` +``` +tempera­ +ture +``` +``` +desc N 20°C RW VO HEAT & +OCC +``` +``` +0x0015 MinHeat­ +Set­ +pointLimit +``` +``` +tempera­ +ture +``` +``` +desc N AbsMin­ +HeatSet­ +pointLimit +``` +### RW VM [HEAT] + +``` +0x0016 MaxHeat­ +Set­ +pointLimit +``` +``` +tempera­ +ture +``` +``` +desc N AbsMax­ +HeatSet­ +pointLimit +``` +### RW VM [HEAT] + +``` +0x0017 Min­ +CoolSet­ +pointLimit +``` +``` +tempera­ +ture +``` +``` +desc N AbsMin­ +CoolSet­ +pointLimit +``` +### RW VM [COOL] + +``` +0x0018 Max­ +CoolSet­ +pointLimit +``` +``` +tempera­ +ture +``` +``` +desc N AbsMax­ +CoolSet­ +pointLimit +``` +### RW VM [COOL] + +``` +0x0019 MinSet­ +point­ +DeadBand +``` +``` +SignedTem +perature +``` +``` +0 to 12.7°C N 2.5°C R[W] VM AUTO +``` +``` +0x001A Remote­ +Sensing +``` +``` +Remote­ +Sensing­ +Bitmap +``` +``` +00000xxx N 0 RW VM O +``` +``` +0x001B ControlSe­ +quenceOf­ +Operation +``` +``` +ControlSe­ +quenceOf­ +Operatio­ +nEnum +``` +``` +desc N 4 RW VM M +``` +``` +0x001C System­ +Mode +``` +``` +System­ +Mod­ +eEnum +``` +``` +desc N 1 RW VM M +``` +``` +0x001D Alarm­ +Mask +``` +``` +Alarm­ +CodeB­ +itmap +``` +``` +desc 0 R V [Zigbee] +``` +``` +0x001E Ther­ +mosta­ +tRunning­ +Mode +``` +``` +Thermosta­ +tRunning­ +Mod­ +eEnum +``` +``` +desc 0 R V [AUTO] +``` +``` +0x0020 StartOfWe +ek +``` +``` +StartOfWe +ekEnum +``` +``` +desc F – R V SCH +``` +Page 322 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**ID Name Type Constraint Quality Default Access Confor­ +mance** + +0x0021 **Num­ +berOfWee +klyTransi­ +tions** + +``` +uint8 all F 0 R V SCH +``` +0x0022 **Num­ +berOfDai­ +lyTransi­ +tions** + +``` +uint8 all F 0 R V SCH +``` +0x0023 **Tempera­ +tureSet­ +pointHold** + +``` +Tempera­ +tureSet­ +pointHold­ +Enum +``` +``` +desc N 0 RW VM O +``` +0x0024 **Tempera­ +tureSet­ +pointHold­ +Duration** + +``` +uint16 max 1440 NX null RW VM O +``` +0x0025 **Ther­ +mostat­ +Program­ +mingOper­ +ationMode** + +``` +Program­ +mingOper­ +ation­ +ModeB­ +itmap +``` +``` +desc P 0 RW VM O +``` +0x0029 **Ther­ +mosta­ +tRun­ +ningState** + +``` +RelayState +Bitmap +``` +``` +desc - R V O +``` +0x0030 **Set­ +pointChan +geSource** + +``` +Set­ +pointChan +ge­ +SourceEnu +m +``` +``` +desc 0 R V O +``` +0x0031 **Set­ +pointChan +geAmount** + +``` +Tempera­ +tureDiffer­ +ence +``` +``` +all X null R V O +``` +0x0032 **Set­ +pointChan +geSource­ +Time­ +stamp** + +``` +utc all 0 R V O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 323 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0034 Occupied­ +Setback +``` +``` +UnsignedT +empera­ +ture +``` +``` +Occupied­ +Setback­ +Min to +Occupied­ +Setback­ +Max +``` +``` +XN null RW VM SB +``` +``` +0x0035 Occupied­ +Setback­ +Min +``` +``` +UnsignedT +empera­ +ture +``` +``` +max Occu­ +piedSet­ +backMax +``` +``` +XF null R V SB +``` +``` +0x0036 Occupied­ +Setback­ +Max +``` +``` +UnsignedT +empera­ +ture +``` +``` +Occupied­ +Setback­ +Min to +25.4°C +``` +``` +XF null R V SB +``` +``` +0x0037 Unoccu­ +piedSet­ +back +``` +``` +UnsignedT +empera­ +ture +``` +``` +Unoccu­ +piedSet­ +backMin to +Unoccu­ +piedSet­ +backMax +``` +``` +XN null RW VM SB & OCC +``` +``` +0x0038 Unoccu­ +piedSet­ +backMin +``` +``` +UnsignedT +empera­ +ture +``` +``` +max Unoc­ +cupiedSet­ +backMax +``` +``` +XF null R V SB & OCC +``` +``` +0x0039 Unoccu­ +piedSet­ +backMax +``` +``` +UnsignedT +empera­ +ture +``` +``` +Unoccu­ +piedSet­ +backMin to +25.4°C +``` +``` +XF null R V SB & OCC +``` +``` +0x003A Emergen­ +cyHeat­ +Delta +``` +``` +UnsignedT +empera­ +ture +``` +``` +all N 25.5°C RW VM O +``` +``` +0x0040 ACType ACType­ +Enum +``` +``` +desc N 0 RW VM O +``` +``` +0x0041 ACCapac­ +ity +``` +``` +uint16 all N 0 RW VM O +``` +``` +0x0042 ACRefrig­ +erantType +``` +``` +ACRefrig­ +erantType­ +Enum +``` +``` +desc N 0 RW VM O +``` +``` +0x0043 ACCom­ +pres­ +sorType +``` +``` +ACCom­ +pres­ +sorType­ +Enum +``` +``` +desc N 0 RW VM O +``` +Page 324 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**ID Name Type Constraint Quality Default Access Confor­ +mance** + +0x0044 **ACError­ +Code** + +``` +ACError­ +CodeB­ +itmap +``` +``` +all 0 RW VM O +``` +0x0045 **ACLouver­ +Position** + +``` +ACLouver­ +Positio­ +nEnum +``` +``` +desc N 0 RW VM O +``` +0x0046 **ACCoil­ +Tempera­ +ture** + +``` +tempera­ +ture +``` +``` +all X null R V O +``` +0x0047 **ACCapaci­ +tyFormat** + +``` +ACCapaci­ +tyFor­ +matEnum +``` +``` +desc N 0 RW VM O +``` +0x0048 **Preset­ +Types** + +``` +list[Preset­ +Type­ +Struct] +``` +``` +desc F MS R V PRES +``` +0x0049 **Schedule­ +Types** + +``` +list[Sched­ +uleType­ +Struct] +``` +``` +desc F MS R V MSCH +``` +0x004A **Num­ +berOfPre­ +sets** + +``` +uint8 all F 0 R V PRES +``` +0x004B **Num­ +berOf­ +Schedules** + +``` +uint8 all F 0 R V MSCH +``` +0x004C **Num­ +berOf­ +Schedule­ +Transi­ +tions** + +``` +uint8 all F 0 R V MSCH +``` +0x004D **Num­ +berOf­ +Schedule­ +Transi­ +tionPer­ +Day** + +``` +uint8 all XF null R V MSCH +``` +0x004E **ActivePre­ +setHandle** + +``` +octstr max 16 XN null R V PRES +``` +0x004F **ActiveSch +eduleHan­ +dle** + +``` +octstr max 16 XN null R V MSCH +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 325 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0050 Presets list[Preset­ +Struct] +``` +``` +max Num­ +berOfPre­ +sets +``` +``` +NT empty RW VM PRES +``` +``` +0x0051 Schedules list[Sched­ +uleStruct] +``` +``` +desc NT empty RW VM MSCH +``` +``` +0x0052 Set­ +pointHold­ +Expiry­ +Time­ +stamp +``` +``` +epoch-s all XN null R V O +``` +**4.3.9.1. Calculated Local Temperature** + +The local temperature SHALL be calculated from the _measured temperature_ , including any adjust­ +ments applied by LocalTemperatureCalibration attribute (if any) as follows: + +``` +Calculated Local Temperature = ( measured temperature ) + LocalTemperatureCalibration +``` +The _measured temperature_ value may be local, or remote, depending on the value of the Remote­ +Sensing attribute when supported. + +All setpoint attributes in the Thermostat cluster SHALL be triggered based off this calculated value +(i.e., measured temperature and any calibration offset). + +If the LocalTemperatureNotExposed feature is present, the behavior of the thermostat SHALL be +that the equipment’s temperature control uses the calculated local temperature even if that value is +not reported in the LocalTemperature attribute. + +**4.3.9.2. LocalTemperature Attribute** + +This attribute SHALL indicate the current Calculated Local Temperature, when available. + +- If the LTNE feature is not supported: + ◦ If the LocalTemperatureCalibration is invalid or currently unavailable, the attribute SHALL + report null. + ◦ If the LocalTemperatureCalibration is valid, the attribute SHALL report that value. +- Otherwise, if the LTNE feature is supported, there is no feedback externally available for the + LocalTemperatureCalibration. In that case, the LocalTemperature attribute SHALL always + report null. + +**4.3.9.3. OutdoorTemperature Attribute** + +This attribute SHALL indicate the outdoor temperature, as measured locally or remotely (over the +network). + +``` +Page 326 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.9.4. Occupancy Attribute** + +This attribute SHALL indicate whether the heated/cooled space is occupied or not, as measured +locally or remotely (over the network). + +**4.3.9.5. AbsMinHeatSetpointLimit Attribute** + +This attribute SHALL indicate the absolute minimum level that the heating setpoint MAY be set to. +This is a limitation imposed by the manufacturer. + +Refer to Setpoint Limits for constraints + +**4.3.9.6. AbsMaxHeatSetpointLimit Attribute** + +This attribute SHALL indicate the absolute maximum level that the heating setpoint MAY be set to. +This is a limitation imposed by the manufacturer. + +Refer to Setpoint Limits for constraints + +**4.3.9.7. AbsMinCoolSetpointLimit Attribute** + +This attribute SHALL indicate the absolute minimum level that the cooling setpoint MAY be set to. +This is a limitation imposed by the manufacturer. + +Refer to Setpoint Limits for constraints + +**4.3.9.8. AbsMaxCoolSetpointLimit Attribute** + +This attribute SHALL indicate the absolute maximum level that the cooling setpoint MAY be set to. +This is a limitation imposed by the manufacturer. + +Refer to Setpoint Limits for constraints + +**4.3.9.9. PICoolingDemand Attribute** + +This attribute SHALL indicate the level of cooling demanded by the PI (proportional integral) con­ +trol loop in use by the thermostat (if any), in percent. This value is 0 when the thermostat is in “off ” +or “heating” mode. + +This attribute is reported regularly and MAY be used to control a cooling device. + +**4.3.9.10. PIHeatingDemand Attribute** + +This attribute SHALL indicate the level of heating demanded by the PI loop in percent. This value is +0 when the thermostat is in “off ” or “cooling” mode. + +This attribute is reported regularly and MAY be used to control a heating device. + +**4.3.9.11. HVACSystemTypeConfiguration Attribute** + +This attribute SHALL indicate the HVAC system type controlled by the thermostat. If the thermostat +uses physical DIP switches to set these parameters, this information SHALL be available read-only + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 327 +``` + +from the DIP switches. If these parameters are set via software, there SHALL be read/write access in +order to provide remote programming capability. + +**4.3.9.12. LocalTemperatureCalibration Attribute** + +This attribute SHALL indicate the offset the Thermostat server SHALL make to the measured tem­ +perature (locally or remotely) to adjust the Calculated Local Temperature prior to using, displaying +or reporting it. + +The purpose of this attribute is to adjust the calibration of the Thermostat server per the user’s +preferences (e.g., to match if there are multiple servers displaying different values for the same +HVAC area) or compensate for variability amongst temperature sensors. + +If a Thermostat client attempts to write LocalTemperatureCalibration attribute to an unsupported +value (e.g., out of the range supported by the Thermostat server), the Thermostat server SHALL +respond with a status of SUCCESS and set the value of LocalTemperatureCalibration to the upper or +lower limit reached. + +### NOTE + +``` +Prior to revision 8 of this cluster specification the value of this attribute was con­ +strained to a range of -2.5°C to 2.5°C. +``` +**4.3.9.13. OccupiedCoolingSetpoint Attribute** + +This attribute SHALL indicate the cooling mode setpoint when the room is occupied. + +Refer to Setpoint Limits for constraints. + +If an attempt is made to set this attribute to a value greater than MaxCoolSetpointLimit or less than +MinCoolSetpointLimit, a response with the status code CONSTRAINT_ERROR SHALL be returned. + +If this attribute is set to a value that is less than (OccupiedHeatingSetpoint + MinSetpointDeadBand), +the value of OccupiedHeatingSetpoint SHALL be adjusted to (OccupiedCoolingSetpoint - MinSet­ +pointDeadBand). + +If the occupancy status of the room is unknown, this attribute SHALL be used as the cooling mode +setpoint. + +If a client changes the value of this attribute, the server supports the PRES feature, and the server +either does not support the OCC feature or the Occupied bit is set on the Occupancy attribute, the +value of the ActivePresetHandle attribute SHALL be set to null. + +**4.3.9.14. OccupiedHeatingSetpoint Attribute** + +This attribute SHALL indicate the heating mode setpoint when the room is occupied. + +Refer to Setpoint Limits for constraints. + +If an attempt is made to set this attribute to a value greater than MaxHeatSetpointLimit or less than +MinHeatSetpointLimit, a response with the status code CONSTRAINT_ERROR SHALL be returned. + +If this attribute is set to a value that is greater than (OccupiedCoolingSetpoint - MinSetpointDead­ + +``` +Page 328 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Band), the value of OccupiedCoolingSetpoint SHALL be adjusted to (OccupiedHeatingSetpoint + +MinSetpointDeadBand). + +If the occupancy status of the room is unknown, this attribute SHALL be used as the heating mode +setpoint. + +If a client changes the value of this attribute, the server supports the PRES feature, and the server +either does not support the OCC feature or the Occupied bit is set on the Occupancy attribute, the +value of the ActivePresetHandle attribute SHALL be set to null. + +**4.3.9.15. UnoccupiedCoolingSetpoint Attribute** + +This attribute SHALL indicate the cooling mode setpoint when the room is unoccupied. + +Refer to Setpoint Limits for constraints. + +If an attempt is made to set this attribute to a value greater than MaxCoolSetpointLimit or less than +MinCoolSetpointLimit, a response with the status code CONSTRAINT_ERROR SHALL be returned. + +If this attribute is set to a value that is less than (UnoccupiedHeatingSetpoint + MinSetpointDead­ +Band), the value of UnoccupiedHeatingSetpoint SHALL be adjusted to (UnoccupiedCoolingSetpoint - +MinSetpointDeadBand). + +If the occupancy status of the room is unknown, this attribute SHALL NOT be used. + +If a client changes the value of this attribute, the server supports the PRES and OCC features, and +the Occupied bit is not set on the Occupancy attribute, the value of the ActivePresetHandle attribute +SHALL be set to null. + +**4.3.9.16. UnoccupiedHeatingSetpoint Attribute** + +This attribute SHALL indicate the heating mode setpoint when the room is unoccupied. + +Refer to Setpoint Limits for constraints. + +If an attempt is made to set this attribute to a value greater than MaxHeatSetpointLimit or less than +MinHeatSetpointLimit, a response with the status code CONSTRAINT_ERROR SHALL be returned. + +If this attribute is set to a value that is greater than (UnoccupiedCoolingSetpoint - MinSetpointDead­ +Band), the value of UnoccupiedCoolingSetpoint SHALL be adjusted to (UnoccupiedHeatingSetpoint ++ MinSetpointDeadBand). + +If the occupancy status of the room is unknown, this attribute SHALL NOT be used. + +If a client changes the value of this attribute, the server supports the PRES and OCC features, and +the Occupied bit is not set on the Occupancy attribute, the value of the ActivePresetHandle attribute +SHALL be set to null. + +**4.3.9.17. MinHeatSetpointLimit Attribute** + +This attribute SHALL indicate the minimum level that the heating setpoint MAY be set to. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 329 +``` + +This attribute, and the following three attributes, allow the user to define setpoint limits more con­ +strictive than the manufacturer imposed ones. Limiting users (e.g., in a commercial building) to +such setpoint limits can help conserve power. + +Refer to Setpoint Limits for constraints. If an attempt is made to set this attribute to a value which +conflicts with setpoint values then those setpoints SHALL be adjusted by the minimum amount to +permit this attribute to be set to the desired value. If an attempt is made to set this attribute to a +value which is not consistent with the constraints and cannot be resolved by modifying setpoints +then a response with the status code CONSTRAINT_ERROR SHALL be returned. + +**4.3.9.18. MaxHeatSetpointLimit Attribute** + +This attribute SHALL indicate the maximum level that the heating setpoint MAY be set to. + +Refer to Setpoint Limits for constraints. If an attempt is made to set this attribute to a value which +conflicts with setpoint values then those setpoints SHALL be adjusted by the minimum amount to +permit this attribute to be set to the desired value. If an attempt is made to set this attribute to a +value which is not consistent with the constraints and cannot be resolved by modifying setpoints +then a response with the status code CONSTRAINT_ERROR SHALL be returned. + +**4.3.9.19. MinCoolSetpointLimit Attribute** + +This attribute SHALL indicate the minimum level that the cooling setpoint MAY be set to. + +Refer to Setpoint Limits for constraints. If an attempt is made to set this attribute to a value which +conflicts with setpoint values then those setpoints SHALL be adjusted by the minimum amount to +permit this attribute to be set to the desired value. If an attempt is made to set this attribute to a +value which is not consistent with the constraints and cannot be resolved by modifying setpoints +then a response with the status code CONSTRAINT_ERROR SHALL be returned. + +**4.3.9.20. MaxCoolSetpointLimit Attribute** + +This attribute SHALL indicate the maximum level that the cooling setpoint MAY be set to. + +Refer to Setpoint Limits for constraints. If an attempt is made to set this attribute to a value which +conflicts with setpoint values then those setpoints SHALL be adjusted by the minimum amount to +permit this attribute to be set to the desired value. If an attempt is made to set this attribute to a +value which is not consistent with the constraints and cannot be resolved by modifying setpoints +then a response with the status code CONSTRAINT_ERROR SHALL be returned. + +**4.3.9.21. MinSetpointDeadBand Attribute** + +On devices which support the AUTO feature, this attribute SHALL indicate the minimum difference +between the Heat Setpoint and the Cool Setpoint. + +Refer to Setpoint Limits for constraints. + +### NOTE + +``` +Prior to revision 8 of this cluster specification the value of this attribute was con­ +strained to a range of 0°C to 2.5°C. +``` +``` +Page 330 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### NOTE + +``` +For backwards compatibility, this attribute is optionally writeable. However any +writes to this attribute SHALL be silently ignored. +``` +**4.3.9.22. RemoteSensing Attribute** + +This attribute SHALL indicate when the local temperature, outdoor temperature and occupancy are +being sensed by remote networked sensors, rather than internal sensors. + +If the LTNE feature is present in the server, the LocalTemperature RemoteSensing bit value SHALL +always report a value of 0. + +If the LocalTemperature RemoteSensing bit is written with a value of 1 when the LTNE feature is +present, the write SHALL fail and the server SHALL report a CONSTRAINT_ERROR. + +**4.3.9.23. ControlSequenceOfOperation Attribute** + +This attribute SHALL indicate the overall operating environment of the thermostat, and thus the +possible system modes that the thermostat can operate in. + +If an attempt is made to write to this attribute, the server SHALL silently ignore the write and the +value of this attribute SHALL remain unchanged. This behavior is in place for backwards compati­ +bility with existing thermostats. + +**4.3.9.24. SystemMode Attribute** + +This attribute SHALL indicate the current operating mode of the thermostat. Its value SHALL be +limited by the ControlSequenceOfOperation attribute. + +**4.3.9.25. AlarmMask Attribute** + +This attribute SHALL indicate whether each of the alarms in AlarmCodeBitmap is enabled. + +When the Alarms cluster is implemented on a device, and one of the alarm conditions included in +AlarmCodeBitmap occurs, an alarm notification is generated, with the alarm code field set as listed +in AlarmCodeBitmap. + +**4.3.9.26. ThermostatRunningMode Attribute** + +This attribute SHALL indicate the running mode of the thermostat. This attribute uses the same val­ +ues as SystemModeEnum but can only be Off, Cool or Heat. This attribute is intended to provide +additional information when the thermostat’s system mode is in auto mode. + +**4.3.9.27. StartOfWeek Attribute** + +This attribute SHALL indicate the day of the week that this thermostat considers to be the start of +week for weekly setpoint scheduling. + +This attribute MAY be able to be used as the base to determine if the device supports weekly sched­ +uling by reading the attribute. Successful response means that the weekly scheduling is supported. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 331 +``` + +**4.3.9.28. NumberOfWeeklyTransitions Attribute** + +This attribute SHALL indicate how many weekly schedule transitions the thermostat is capable of +handling. + +**4.3.9.29. NumberOfDailyTransitions Attribute** + +This attribute SHALL indicate how many daily schedule transitions the thermostat is capable of +handling. + +**4.3.9.30. TemperatureSetpointHold Attribute** + +This attribute SHALL indicate the temperature hold status on the thermostat. If hold status is on, +the thermostat SHOULD maintain the temperature setpoint for the current mode until a system +mode change. If hold status is off, the thermostat SHOULD follow the setpoint transitions specified +by its internal scheduling program. If the thermostat supports setpoint hold for a specific duration, +it SHOULD also implement the TemperatureSetpointHoldDuration attribute. + +If the server supports a setpoint hold for a specific duration, it SHOULD also implement the Set­ +pointHoldExpiryTimestamp attribute. + +If this attribute is updated to SetpointHoldOn and the TemperatureSetpointHoldDuration has a non- +null value and the SetpointHoldExpiryTimestamp is supported, the server SHALL update the Set­ +pointHoldExpiryTimestamp with a value of current UTC timestamp, in seconds, plus the value in +TemperatureSetpointHoldDuration multiplied by 60. + +If this attribute is updated to SetpointHoldOff and the SetpointHoldExpiryTimestamp is supported, +the server SHALL set the SetpointHoldExpiryTimestamp to null. + +**4.3.9.31. TemperatureSetpointHoldDuration Attribute** + +This attribute SHALL indicate the period in minutes for which a setpoint hold is active. Thermostats +that support hold for a specified duration SHOULD implement this attribute. The null value indi­ +cates the field is unused. All other values are reserved. + +If this attribute is updated to a non-null value and the TemperatureSetpointHold is set to Set­ +pointHoldOn and the SetpointHoldExpiryTimestamp is supported, the server SHALL update Set­ +pointHoldExpiryTimestamp with a value of current UTC timestamp, in seconds, plus the new value +of this attribute multiplied by 60. + +If this attribute is set to null and the SetpointHoldExpiryTimestamp is supported, the server SHALL +set the SetpointHoldExpiryTimestamp to null. + +**4.3.9.32. ThermostatProgrammingOperationMode Attribute** + +This attribute SHALL indicate the operational state of the thermostat’s programming. The thermo­ +stat SHALL modify its programming operation when this attribute is modified by a client and +update this attribute when its programming operation is modified locally by a user. The thermostat +MAY support more than one active ProgrammingOperationModeBitmap. For example, the thermo­ +stat MAY operate simultaneously in Schedule Programming Mode and Recovery Mode. + +``` +Page 332 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Thermostats which contain a schedule MAY use this attribute to control how that schedule is used, +even if they do not support the ScheduleConfiguration feature. + +When ScheduleActive is not set, the setpoint is altered only by manual up/down changes at the ther­ +mostat or remotely, not by internal schedule programming. + +### NOTE + +``` +Modifying the ScheduleActive bit does not clear or delete previous weekly schedule +programming configurations. +``` +**4.3.9.33. ThermostatRunningState Attribute** + +This attribute SHALL indicate the current relay state of the heat, cool, and fan relays. + +Unimplemented outputs SHALL be treated as if they were Off. + +**4.3.9.34. SetpointChangeSource Attribute** + +This attribute SHALL indicate the source of the current active OccupiedCoolingSetpoint or Occu­ +piedHeatingSetpoint (i.e., who or what determined the current setpoint). + +This attribute enables service providers to determine whether changes to setpoints were initiated +due to occupant comfort, scheduled programming or some other source (e.g., electric utility or +other service provider). Because automation services MAY initiate frequent setpoint changes, this +attribute clearly differentiates the source of setpoint changes made at the thermostat. + +**4.3.9.35. SetpointChangeAmount Attribute** + +This attribute SHALL indicate the delta between the current active OccupiedCoolingSetpoint or +OccupiedHeatingSetpoint and the previous active setpoint. This attribute is meant to accompany +the SetpointChangeSource attribute; devices implementing SetpointChangeAmount SHOULD also +implement SetpointChangeSource. + +The null value indicates that the previous setpoint was unknown. + +**4.3.9.36. SetpointChangeSourceTimestamp Attribute** + +This attribute SHALL indicate the time in UTC at which the SetpointChangeAmount attribute +change was recorded. + +**4.3.9.37. OccupiedSetback Attribute** + +This attribute SHALL indicate the amount that the Thermostat server will allow the Calculated +Local Temperature to float above the OccupiedCoolingSetpoint (i.e., OccupiedCoolingSetpoint + +OccupiedSetback) or below the OccupiedHeatingSetpoint setpoint (i.e., OccupiedHeatingSetpoint – +OccupiedSetback) before initiating a state change to bring the temperature back to the user’s +desired setpoint. This attribute is sometimes also referred to as the “span.” + +The purpose of this attribute is to allow remote configuration of the span between the desired set­ +point and the measured temperature to help prevent over-cycling and reduce energy bills, though +this may result in lower comfort on the part of some users. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 333 +``` + +The null value indicates the attribute is unused. + +If the Thermostat client attempts to write OccupiedSetback to a value greater than OccupiedSet­ +backMax, the Thermostat server SHALL set its OccupiedSetback value to OccupiedSetbackMax and +SHALL send a Write Attribute Response command with a Status Code field enumeration of SUCCESS +response. + +If the Thermostat client attempts to write OccupiedSetback to a value less than OccupiedSetback­ +Min, the Thermostat server SHALL set its OccupiedSetback value to OccupiedSetbackMin and +SHALL send a Write Attribute Response command with a Status Code field enumeration of SUCCESS +response. + +**4.3.9.38. OccupiedSetbackMin Attribute** + +This attribute SHALL indicate the minimum value that the Thermostat server will allow the Occu­ +piedSetback attribute to be configured by a user. + +The null value indicates the attribute is unused. + +**4.3.9.39. OccupiedSetbackMax Attribute** + +This attribute SHALL indicate the maximum value that the Thermostat server will allow the Occu­ +piedSetback attribute to be configured by a user. + +The null value indicates the attribute is unused. + +**4.3.9.40. UnoccupiedSetback Attribute** + +This attribute SHALL indicate the amount that the Thermostat server will allow the Calculated +Local Temperature to float above the UnoccupiedCoolingSetpoint (i.e., UnoccupiedCoolingSetpoint + +UnoccupiedSetback) or below the UnoccupiedHeatingSetpoint setpoint (i.e., UnoccupiedHeatingSet­ +point - UnoccupiedSetback) before initiating a state change to bring the temperature back to the +user’s desired setpoint. This attribute is sometimes also referred to as the “span.” + +The purpose of this attribute is to allow remote configuration of the span between the desired set­ +point and the measured temperature to help prevent over-cycling and reduce energy bills, though +this may result in lower comfort on the part of some users. + +The null value indicates the attribute is unused. + +If the Thermostat client attempts to write UnoccupiedSetback to a value greater than Unoccupied­ +SetbackMax, the Thermostat server SHALL set its UnoccupiedSetback value to UnoccupiedSetback­ +Max and SHALL send a Write Attribute Response command with a Status Code field enumeration of +SUCCESS response. + +If the Thermostat client attempts to write UnoccupiedSetback to a value less than UnoccupiedSet­ +backMin, the Thermostat server SHALL set its UnoccupiedSetback value to UnoccupiedSetbackMin +and SHALL send a Write Attribute Response command with a Status Code field enumeration of +SUCCESS response. + +``` +Page 334 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.9.41. UnoccupiedSetbackMin Attribute** + +This attribute SHALL indicate the minimum value that the Thermostat server will allow the Unoc­ +cupiedSetback attribute to be configured by a user. + +The null value indicates the attribute is unused. + +**4.3.9.42. UnoccupiedSetbackMax Attribute** + +This attribute SHALL indicate the maximum value that the Thermostat server will allow the Unoc­ +cupiedSetback attribute to be configured by a user. + +The null value indicates the attribute is unused. + +**4.3.9.43. EmergencyHeatDelta Attribute** + +This attribute SHALL indicate the delta between the Calculated Local Temperature and the Occu­ +piedHeatingSetpoint or UnoccupiedHeatingSetpoint attributes at which the Thermostat server will +operate in emergency heat mode. + +If the difference between the Calculated Local Temperature and OccupiedCoolingSetpoint or Unoc­ +cupiedCoolingSetpoint is greater than or equal to the EmergencyHeatDelta and the Thermostat +server’s SystemMode attribute is in a heating-related mode, then the Thermostat server SHALL +immediately switch to the SystemMode attribute value that provides the highest stage of heating +(e.g., emergency heat) and continue operating in that running state until the OccupiedHeatingSet­ +point value is reached. For example: + +- Calculated Local Temperature = 10.0°C +- OccupiedHeatingSetpoint = 16.0°C +- EmergencyHeatDelta = 2.0°C + +``` +⇒ OccupiedHeatingSetpoint - Calculated Local Temperature ≥? EmergencyHeatDelta +``` +``` +⇒ 16°C - 10°C ≥? 2°C +``` +``` +⇒ TRUE >>> Thermostat server changes its SystemMode to operate in 2nd stage or emergency +heat mode +``` +The purpose of this attribute is to provide Thermostat clients the ability to configure rapid heating +when a setpoint is of a specified amount greater than the measured temperature. This allows the +heated space to be quickly heated to the desired level set by the user. + +**4.3.9.44. ACType Attribute** + +This attribute SHALL indicate the type of Mini Split ACTypeEnum of Mini Split AC is defined +depending on how Cooling and Heating condition is achieved by Mini Split AC. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 335 +``` + +**4.3.9.45. ACCapacity Attribute** + +This attribute SHALL indicate capacity of Mini Split AC in terms of the format defined by the ACCa­ +pacityFormat attribute + +**4.3.9.46. ACRefrigerantType Attribute** + +This attribute SHALL indicate type of refrigerant used within the Mini Split AC. + +**4.3.9.47. ACCompressorType Attribute** + +This attribute SHALL indicate the type of compressor used within the Mini Split AC. + +**4.3.9.48. ACErrorCode Attribute** + +This attribute SHALL indicate the type of errors encountered within the Mini Split AC. + +**4.3.9.49. ACLouverPosition Attribute** + +This attribute SHALL indicate the position of Louver on the AC. + +**4.3.9.50. ACCoilTemperature Attribute** + +This attribute SHALL indicate the temperature of the AC coil, as measured locally or remotely (over +the network). + +**4.3.9.51. ACCapacityFormat Attribute** + +This attribute SHALL indicate the format for the ACCapacity attribute. + +**4.3.9.52. PresetTypes Attribute** + +This attribute SHALL indicate the supported PresetScenarioEnum values, limits on how many pre­ +sets can be created for each PresetScenarioEnum, and whether or not a thermostat can transition +automatically to a given scenario. + +**4.3.9.53. ScheduleTypes Attribute** + +This attribute SHALL indicate the supported SystemMode values for Schedules, limits on how many +schedules can be created for each SystemMode value, and whether or not a given SystemMode +value supports transitions to Presets, target setpoints, or both. + +**4.3.9.54. NumberOfPresets Attribute** + +This attribute SHALL indicate the maximum number of entries supported by the Presets attribute. + +**4.3.9.55. NumberOfSchedules Attribute** + +This attribute SHALL indicate the maximum number of entries supported by the Schedules +attribute. + +``` +Page 336 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.9.56. NumberOfScheduleTransitions Attribute** + +This attribute SHALL indicate the maximum number of transitions per Schedules attribute entry. + +**4.3.9.57. NumberOfScheduleTransitionsPerDay Attribute** + +This attribute SHALL indicate the maximum number of transitions per day of the week supported +by each Schedules attribute entry. If this value is null, there is no limit on the number of transitions +per day. + +**4.3.9.58. ActivePresetHandle Attribute** + +This attribute SHALL indicate the PresetHandle of the active preset. If this attribute is null, then +there is no active preset. + +**4.3.9.59. ActiveScheduleHandle Attribute** + +This attribute SHALL indicate the ScheduleHandle of the active schedule. A null value in this +attribute indicates that there is no active schedule. + +**4.3.9.60. Presets Attribute** + +This attribute SHALL contain the current list of configured presets. + +On receipt of a write request: + +1. If the PresetHandle field is null, the PresetStruct SHALL be treated as an added preset, and the + device SHALL create a new unique value for the PresetHandle field. + a. If the BuiltIn field is true, a response with the status code CONSTRAINT_ERROR SHALL be + returned. +2. If the PresetHandle field is not null, the PresetStruct SHALL be treated as a modification of an + existing preset. + a. If the value of the PresetHandle field does not match any of the existing presets, a response + with the status code NOT_FOUND SHALL be returned. + b. If the value of the PresetHandle field is duplicated on multiple presets in the updated list, a + response with the status code CONSTRAINT_ERROR SHALL be returned. +c. If the BuiltIn field is true, and the PresetStruct in the current value with a matching Pre­ +setHandle field has a BuiltIn field set to false, a response with the status code CONSTRAIN­ +T_ERROR SHALL be returned. + d. If the BuiltIn field is false, and the PresetStruct in the current value with a matching Pre­ + setHandle field has a BuiltIn field set to true, a response with the status code CONSTRAIN­ + T_ERROR SHALL be returned. +3. If the specified PresetScenarioEnum value does not exist in PresetTypes, a response with the + status code CONSTRAINT_ERROR SHALL be returned. +4. If the Name is set, but the associated PresetTypeStruct does not have the SupportsNames bit set, + a response with the status code CONSTRAINT_ERROR SHALL be returned. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 337 +``` + +5. If appending the received PresetStruct to the pending list of Presets would cause the total num­ + ber of pending presets to exceed the value of the NumberOfPresets attribute, a response with + the status code RESOURCE_EXHAUSTED SHALL be returned. +6. If appending the received PresetStruct to the pending list of Presets would cause the total num­ + ber of pending presets whose PresetScenario field matches the appended preset’s PresetSce­ + nario field to exceed the value of the NumberOfPresets field on the PresetTypeStruct whose Pre­ + setScenario matches the appended preset’s PresetScenario field, a response with the status code + RESOURCE_EXHAUSTED SHALL be returned. +7. Otherwise, the write SHALL be pended until receipt of a commit request, and the status code + SUCCESS SHALL be returned. + a.If the BuiltIn field is null: + i. If there is a PresetStruct in the current value with a matching PresetHandle field, the + BuiltIn field on the pending PresetStruct SHALL be set to the value of the BuiltIn on the + matching PresetStruct. +ii.Otherwise, the BuiltIn field on the pending PresetStruct SHALL be set to false. + +On an attempt to commit, the status of this attribute SHALL be determined as follows: + +1. For all existing presets: + a.If, after applying all pending changes, the updated value of the Presets attribute would not + contain a PresetStruct with a matching PresetHandle field, indicating the removal of the Pre­ + setStruct, the server SHALL check for invalid removal of the PresetStruct: + i. If the BuiltIn field is true on the removed PresetStruct, the attribute status SHALL be + CONSTRAINT_ERROR. +ii.If the MSCH feature is supported and the removed PresetHandle would be referenced by +any PresetHandle on any ScheduleTransitionStruct on any ScheduleStruct in the updated +value of the Schedules attribute, the attribute status SHALL be INVALID_IN_STATE. +iii.If the removed PresetHandle is equal to the value of the ActivePresetHandle attribute, +the attribute status SHALL be INVALID_IN_STATE. +2. Otherwise, the attribute status SHALL be SUCCESS. + +**4.3.9.61. Schedules Attribute** + +This attribute SHALL contain a list of ScheduleStructs. + +On receipt of a write request: + +1. For all schedules in the write request: + a.If the ScheduleHandle field is null, the ScheduleStruct SHALL be treated as an added sched­ + ule, and the device SHALL create a new unique value for the ScheduleHandle field. + i. If the BuiltIn field is true, a response with the status code CONSTRAINT_ERROR SHALL + be returned. +b. Otherwise, if the ScheduleHandle field is not null, the ScheduleStruct SHALL be treated as a +modification of an existing schedule. + +``` +Page 338 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +i. If the value of the ScheduleHandle field does not match any of the existing schedules, a +response with the status code NOT_FOUND SHALL be returned. +ii. If the BuiltIn field is true, and the ScheduleStruct in the current value with a matching +ScheduleHandle field has a BuiltIn field set to false, a response with the status code CON­ +STRAINT_ERROR SHALL be returned. +iii. If the BuiltIn field is false, and the ScheduleStruct in the current value with a matching +ScheduleHandle field has a BuiltIn field set to true, a response with the status code CON­ +STRAINT_ERROR SHALL be returned. +c. If the specified SystemMode does not exist in ScheduleTypes, a response with the status code +CONSTRAINT_ERROR SHALL be returned. +``` +d. If the number of transitions exceeds the NumberOfScheduleTransitions value, a response +with the status code RESOURCE_EXHAUSTED SHALL be returned. +e. If the value of the NumberOfScheduleTransitionsPerDay attribute is not null, and the num­ +ber of transitions on any single day of the week exceeds the NumberOfScheduleTransition­ +sPerDay value, a response with the status code RESOURCE_EXHAUSTED SHALL be returned. +f. If the PresetHandle field is present, but the associated ScheduleTypeStruct does not have the +SupportsPresets bit set, a response with the status code CONSTRAINT_ERROR SHALL be +returned. +g. If the PresetHandle field is present, but after applying all pending changes, the Presets +attribute would not contain a PresetStruct whose PresetHandle field matches the value of +the PresetHandle field, a response with the status code CONSTRAINT_ERROR SHALL be +returned. + +h. If the Name is set, but the associated ScheduleTypeStruct does not have the SupportsNames +bit set, a response with the status code CONSTRAINT_ERROR SHALL be returned. +i. For all transitions in all schedules in the write request: +i. If the PresetHandle field is present, but the ScheduleTypeStruct matching the value of +the SystemMode field on the encompassing ScheduleStruct does not have the SupportsP­ +resets bit set, a response with the status code CONSTRAINT_ERROR SHALL be returned. +j. If the PresetHandle field is present, but after applying all pending changes, the Presets +attribute would not contain a PresetStruct whose PresetHandle field matches the value of +the PresetHandle field, a response with the status code CONSTRAINT_ERROR SHALL be +returned. +i. If the SystemMode field is present, but the ScheduleTypeStruct matching the value of the +SystemMode field on the encompassing ScheduleStruct does not have the SupportsSet­ +points bit set, a response with the status code CONSTRAINT_ERROR SHALL be returned. +ii. If the SystemMode field is has a value of SystemModeOff, but the ScheduleTypeStruct +matching the value of the SystemMode field on the encompassing ScheduleStruct does +not have the SupportsOff bit set, a response with the status code CONSTRAINT_ERROR +SHALL be returned. + +k. If the HeatingSetpoint field is present, but the ScheduleTypeStruct matching the value of the +SystemMode field on the encompassing ScheduleStruct does not have the SupportsSetpoints +bit set, a response with the status code CONSTRAINT_ERROR SHALL be returned. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 339 +``` + +``` +l.If the CoolingSetpoint field is present, but the ScheduleTypeStruct matching the value of the +SystemMode field on the encompassing ScheduleStruct does not have the SupportsSetpoints +bit set, a response with the status code CONSTRAINT_ERROR SHALL be returned. +``` +2. If appending the received ScheduleStruct to the pending list of Schedules would cause the total + number of pending schedules to exceed the value of the NumberOfSchedules attribute, a + response with the status code RESOURCE_EXHAUSTED SHALL be returned. +3. If appending the received ScheduleStruct to the pending list of Schedules would cause the total + number of pending schedules whose SystemMode field matches the appended schedule’s Sys­ + temMode field to exceed the value of the NumberOfSchedules field on the ScheduleTypeStruct + whose SystemMode field matches the appended schedule’s SystemMode field, a response with + the status code RESOURCE_EXHAUSTED SHALL be returned. +4. Otherwise, the write SHALL be pended until receipt of a commit request, and the attribute sta­ + tus SHALL be SUCCESS. + a.If the BuiltIn field is null: + i. If there is a ScheduleStruct in the current value with a matching ScheduleHandle field, + the BuiltIn field on the pending ScheduleStruct SHALL be set to the value of the BuiltIn + on the matching ScheduleStruct. +ii.Otherwise, the BuiltIn field on the pending ScheduleStruct SHALL be set to false. + +On an attempt to commit, the status of this attribute SHALL be determined as follows: + +1. For all existing schedules: + a.If, after applying all pending changes, the updated value of the Schedules attribute would + not contain a ScheduleStruct with a matching ScheduleHandle field, indicating the removal + of the ScheduleStruct, the server SHALL check for invalid removal of the ScheduleStruct: + i. If the BuiltIn field is true on the removed ScheduleStruct, the attribute status SHALL be + CONSTRAINT_ERROR. +ii.If the removed ScheduleHandle is equal to the value of the ActiveScheduleHandle +attribute, the attribute status SHALL be INVALID_IN_STATE. +2. Otherwise, the attribute status SHALL be SUCCESS. + +**4.3.9.62. SetpointHoldExpiryTimestamp Attribute** + +If there is a known time when the TemperatureSetpointHold SHALL be cleared, this attribute +SHALL contain the timestamp in UTC indicating when that will happen. If there is no such known +time, this attribute SHALL be null. + +If the TemperatureSetpointHold is set to SetpointHoldOff or the TemperatureSetpointHoldDuration +is set to null, this attribute SHALL be set to null indicating there is no hold on the Thermostat either +with or without a duration. + +**4.3.10. Commands** + +``` +Page 340 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Direction Response Access Conformance +0x00 Set­ +pointRaiseLo +wer +``` +``` +client ⇒ server Y O M +``` +``` +0x01 SetWeeklySch +edule +``` +``` +client ⇒ server Y M SCH +``` +``` +0x02 GetWeeklySch +edule +``` +``` +client ⇒ server GetWeeklySche +duleResponse +``` +### O SCH + +``` +0x00 GetWeeklySch +eduleRe­ +sponse +``` +``` +client ⇐ server N SCH +``` +``` +0x03 Clear­ +WeeklySched­ +ule +``` +``` +client ⇒ server Y M SCH +``` +``` +0x04 GetRelaySta­ +tusLog +``` +``` +client ⇒ server GetRelayStatus­ +LogResponse +``` +``` +O [Zigbee] +``` +``` +0x01 GetRelaySta­ +tusLogRe­ +sponse +``` +``` +client ⇐ server N GetRelayStatus­ +Log +``` +``` +0x05 SetAc­ +tiveSched­ +uleRequest +``` +``` +client ⇒ server Y O MSCH +``` +``` +0x06 SetActivePre­ +setRequest +``` +``` +client ⇒ server Y O PRES +``` +**4.3.10.1. SetpointRaiseLower Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Mode Set­ +pointRaiseLo +werMod­ +eEnum +``` +``` +desc M +``` +``` +1 Amount int8 all M +``` +**4.3.10.1.1. Mode Field** + +The field SHALL specify which setpoints are to be adjusted. + +**4.3.10.1.1.1. Heat Value** + +If the server does not support the HEAT feature then it SHALL respond with INVALID_COMMAND. If +the server supports the AUTO feature and the resulting setpoint would be invalid solely due to Min­ +SetpointDeadBand then the Cooling setpoint SHALL be increased sufficiently to maintain the dead­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 341 +``` + +band. + +**4.3.10.1.1.2. Cool Value** + +If the server does not support the COOL feature then it SHALL respond with INVALID_COMMAND. +If the server supports the AUTO feature and the resulting setpoint would be invalid solely due to +MinSetpointDeadBand then the Heating setpoint SHALL be decreased sufficiently to maintain the +deadband. + +**4.3.10.1.1.3. Both Value** + +The client MAY indicate Both regardless of the server feature support. The server SHALL only +adjust the setpoint that it supports and not respond with an error. + +**4.3.10.1.2. Amount Field** + +This field SHALL indicate the amount (possibly negative) that should be added to the setpoint(s), in +steps of 0.1°C. + +**4.3.10.1.3. Effect on Receipt** + +Upon receipt, the attributes for the indicated setpoint(s) SHALL have the amount specified in the +Amount field added to them. If the resulting value is outside the limits imposed by MinCoolSet­ +pointLimit, MaxCoolSetpointLimit, MinHeatSetpointLimit and MaxHeatSetpointLimit, the value is +clamped to those limits. This is not considered an error condition. + +**4.3.10.2. SetWeeklySchedule Command** + +This command is used to update the thermostat weekly setpoint schedule from a management sys­ +tem. If the thermostat already has a weekly setpoint schedule programmed, then it SHOULD replace +each daily setpoint set as it receives the updates from the management system. For example, if the +thermostat has 4 setpoints for every day of the week and is sent a SetWeeklySchedule command +with one setpoint for Saturday then the thermostat SHOULD remove all 4 setpoints for Saturday +and replace those with the updated setpoint but leave all other days unchanged. If the schedule is +larger than what fits in one frame or contains more than 10 transitions, the schedule SHALL then +be sent using multiple SetWeeklySchedule Commands. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NumberOf­ +Transitions­ +ForSe­ +quence +``` +``` +uint8 all M +``` +``` +1 DayOfWeek­ +ForSe­ +quence +``` +``` +Schedule­ +DayOfWeek­ +Bitmap +``` +``` +desc M +``` +``` +2 ModeForSe­ +quence +``` +``` +Schedule­ +ModeBitmap +``` +``` +desc M +``` +``` +Page 342 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +3 Transitions list[WeeklyS +chedule­ +Transition­ +Struct] +``` +``` +max 10 M +``` +**4.3.10.2.1. NumberOfTransitionsForSequence Field** + +This field SHALL indicate how many individual transitions to expect for this sequence of com­ +mands. If a device supports more than 10 transitions in its schedule they can send this by sending +more than 1 “Set Weekly Schedule” command, each containing the separate information that the +device needs to set. + +**4.3.10.2.2. DayOfWeekForSequence Field** + +This field SHALL represent the day of the week at which all the transitions within the payload of +the command SHOULD be associated to. This field is a bitmap and therefore the associated setpoint +could overlap onto multiple days (you could set one transition time for all “week days” or whatever +combination of days the implementation requests). + +Each setpoint transition will begin with the day of week for this transition. There can be up to 10 +transitions for each command. + +**4.3.10.2.3. ModeForSequence Field** + +This field SHALL indicate how the application decodes the setpoint fields of each transition in the +Transitions list. + +If the HeatSetpointPresent bit is On, the HeatSetpoint field SHALL NOT be null in **every** entry of the +Transitions list. + +If the HeatSetpointPresent bit is Off, the HeatSetpoint field SHALL be null in **every** entry of the +Transitions list. + +If the CoolSetpointPresent bit is On, the CoolSetpoint field SHALL NOT be null in **every** entry of the +Transitions list. + +If the CoolSetpointPresent bit is Off, the CoolSetpoint field SHALL be null in **every** entry of the Tran­ +sitions list. + +At least one of the bits in the Mode For Sequence byte SHALL be on. + +Both bits must be respected, even if the HEAT or COOL feature is not supported, to ensure the com­ +mand is decoded and handled correctly. + +**4.3.10.2.4. Transitions Field** + +This field SHALL contain the list of setpoint transitions used to update the specified daily schedules + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 343 +``` + +**4.3.10.2.5. Effect on Receipt** + +Upon receipt, the weekly schedule for updating setpoints SHALL be stored in the thermostat and +SHOULD begin at the time of receipt. A status code SHALL be sent in response. + +When a command is received that requires a total number of transitions greater than the device +supports, the status of the response SHALL be INSUFFICIENT_SPACE. + +When any of the setpoints sent in the sequence is out of range (AbsMin/MaxSetPointLimit), or when +the Mode for Sequence field includes a mode not supported by the device, the status of the response +SHALL be CONSTRAINT_ERROR and no setpoints from the entire sequence SHOULD be used. + +When an overlapping transition is detected, the status of the response SHALL be FAILURE. + +When a device which does not support multiple days in a command receives a command with more +than one bit set in the DayOfWeekForSequence field, or when a device which does not support mul­ +tiple modes in a command receives a command with more than one bit set in the ModeForSequence +field, or when the contents of the Transitions field does not agree with NumberOfTransitionsForSe­ +quence, DayOfWeekForSequence or ModeForSequence, the status of the response SHALL be +INVALID_COMMAND. + +When the transitions could be added successfully, the status of the response SHALL be SUCCESS. + +**4.3.10.3. GetWeeklySchedule Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 DaysToRe­ +turn +``` +``` +Schedule­ +DayOfWeek­ +Bitmap +``` +``` +desc M +``` +``` +1 ModeToRe­ +turn +``` +``` +Schedule­ +ModeBitmap +``` +``` +desc M +``` +**4.3.10.3.1. DaysToReturn Field** + +This field SHALL indicate the number of days the client would like to return the setpoint values for +and could be any combination of single days or the entire week. + +**4.3.10.3.2. ModeToReturn Field** + +This field SHALL indicate the mode the client would like to return the set point values for and could +be any combination of heat only, cool only or heat & cool. + +**4.3.10.3.3. Effect on Receipt** + +Upon receipt, the unit SHOULD send in return the Get Weekly Schedule Response command. The +Days to Return and Mode to Return fields are defined as bitmask for the flexibility to support multi­ +ple days and multiple modes within one command. If thermostat cannot handle incoming com­ +mand with multiple days and/or multiple modes within one command, it SHALL send default +response of INVALID_COMMAND in return. + +``` +Page 344 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.10.4. GetWeeklyScheduleResponse Command** + +This command has the same payload format as the Set Weekly Schedule. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NumberOf­ +Transitions­ +ForSe­ +quence +``` +``` +uint8 all M +``` +``` +1 DayOfWeek­ +ForSe­ +quence +``` +``` +Schedule­ +DayOfWeek­ +Bitmap +``` +``` +desc M +``` +``` +2 ModeForSe­ +quence +``` +``` +Schedule­ +ModeBitmap +``` +``` +desc M +``` +``` +3 Transitions list[WeeklyS +chedule­ +Transition­ +Struct] +``` +``` +max 10 M +``` +**4.3.10.5. ClearWeeklySchedule Command** + +This command is used to clear the weekly schedule. The Clear weekly schedule has no payload. + +Upon receipt, all transitions currently stored SHALL be cleared and a default response of SUCCESS +SHALL be sent in response. There are no error responses to this command. + +**4.3.10.6. GetRelayStatusLog Command** + +This command is used to query the thermostat internal relay status log. This command has no pay­ +load. + +Upon receipt, the unit SHALL respond with Relay Status Log command if the relay status log feature +is supported on the unit. + +The log storing order is First in First Out (FIFO) when the log is generated and stored into the +Queue. + +The first record in the log (i.e., the oldest) one, is the first to be replaced when there is a new record +and there is no more space in the log. Thus, the newest record will overwrite the oldest one if there +is no space left. + +The log storing order is Last In First Out (LIFO) when the log is being retrieved from the Queue by a +client device. + +Once the "Get Relay Status Log Response" frame is sent by the Server, the "Unread Entries" attribute +SHOULD be decremented to indicate the number of unread records that remain in the queue. + +If the "Unread Entries" attribute reaches zero and the Client sends a new "Get Relay Status Log + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 345 +``` + +Request", the Server MAY send one of the following items as a response: + +``` +i. Resend the last Get Relay Status Log Response +``` +``` +or +``` +``` +ii.Generate new log record at the time of request and send Get Relay Status Log Response with the +new data +``` +For both cases, the "Unread Entries" attribute will remain zero. + +**4.3.10.7. GetRelayStatusLogResponse Command** + +This command is sent from the thermostat cluster server in response to the Get Relay Status Log. +After the Relay Status Entry is sent over the air to the requesting client, the specific entry will be +cleared from the thermostat internal log. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TimeOfDay uint16 max 1439 M +1 RelayStatus RelayStateBit +map +``` +``` +desc M +``` +``` +2 LocalTem­ +perature +``` +``` +temperature all X M +``` +``` +3 HumidityIn­ +Percentage +``` +``` +uint8 0% to 100% X M +``` +``` +4 SetPoint temperature all M +5 UnreadEn­ +tries +``` +``` +uint16 all M +``` +**4.3.10.7.1. TimeOfDay Field** + +This field SHALL indicate the sample time of the day, in minutes since midnight, when the relay sta­ +tus was captured for this associated log entry. For example, 6am will be represented by 360 minutes +since midnight and 11:30pm will be represented by 1410 minutes since midnight. + +**4.3.10.7.2. RelayStatus Field** + +This field SHALL indicate the relay status for thermostat when the log is captured. Each bit repre­ +sents one relay used by the thermostat. If the bit is on, the associated relay is on and active. Each +thermostat manufacturer can create its own mapping between the bitmap and the associated relay. + +**4.3.10.7.3. LocalTemperature Field** + +This field SHALL indicate the LocalTemperature when the log is captured. The null value indicates +that LocalTemperature was invalid or unavailable. + +``` +Page 346 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.10.7.4. Humidity Field** + +This field SHALL indicate the humidity as a percentage when the log was captured. The null value +indicates that the humidity value was invalid or unknown. + +**4.3.10.7.5. Setpoint Field** + +This field SHALL indicate the target setpoint temperature when the log is captured. + +**4.3.10.7.6. UnreadEntries Field** + +This field SHALL indicate the number of unread entries within the thermostat internal log system. + +**4.3.10.8. SetActiveScheduleRequest Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Schedule­ +Handle +``` +``` +octstr max 16 M +``` +**4.3.10.8.1. ScheduleHandle Field** + +This field SHALL specify the value of the ScheduleHandle field on the ScheduleStruct to be made +active. + +**4.3.10.8.2. Effect on Receipt** + +Upon receipt, if the Schedules attribute contains a ScheduleStruct whose ScheduleHandle field +matches the value of the ScheduleHandle field, the server SHALL set the thermostat’s ActiveSched­ +uleHandle attribute to the value of the ScheduleHandle field. + +Otherwise, the server SHALL return a status code of INVALID_COMMAND. + +**4.3.10.9. SetActivePresetRequest Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Pre­ +setHandle +``` +``` +octstr max 16 X M +``` +**4.3.10.9.1. PresetHandle Field** + +This field SHALL specify the value of the PresetHandle field on the PresetStruct to be made active. If +the field is set to null, that indicates there should be no active preset. + +**4.3.10.9.2. Effect on Receipt** + +Upon receipt of this command, + +1. If the PresetHandle field is null, the server SHALL clear the ActivePresetHandle attribute by set­ + ting it to null. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 347 +``` + +2. Otherwise, + a.If this command is received with a PresetHandle such that the Presets attribute does not + contain a PresetStruct whose PresetHandle field matches the value of the PresetHandle, the + server SHALL return a status code of INVALID_COMMAND. +b. The server SHALL set the ActivePresetHandle attribute to the value of the PresetHandle +field. +3. The server SHALL return a status code of SUCCESS. + +**4.4. Fan Control Cluster** + +This cluster specifies an interface to control the speed of a fan. + +**4.4.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 New data model format and notation; Percent, +speed and motion settings; General cleanup +3 Addition of AirflowDirection and Step command +4 Change conformance for FanModeSe­ +quenceEnum +``` +**4.4.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint FAN +``` +**4.4.3. Cluster ID** + +``` +ID Name +0x0202 Fan Control +``` +**4.4.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 SPD MultiSpeed 0-SpeedMax Fan Speeds +``` +``` +Page 348 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Summary +1 AUT Auto Automatic mode sup­ +ported for fan speed +2 RCK Rocking Rocking movement +supported +3 WND Wind Wind emulation sup­ +ported +4 STEP Step Step command sup­ +ported +5 DIR AirflowDirection Airflow Direction +attribute is supported +``` +**4.4.4.1. MultiSpeed Feature** + +Legacy Fan Control cluster revision 0-1 defined 3 speeds (low, medium and high) plus automatic +speed control but left it up to the implementer to decide what was supported. Therefore, it is +assumed that legacy client implementations are capable of determining, from the server, the num­ +ber of speeds supported between 1, 2, or 3, and whether automatic speed control is supported. + +The MultiSpeed feature includes new attributes that support a running fan speed value from 0 to +SpeedMax, which has a maximum of 100. + +See Section 4.4.6.6.1 for more details. + +**4.4.5. Data Types** + +**4.4.5.1. RockBitmap Type** + +``` +Bit Name Summary Conformance +0 RockLeftRight Indicate rock left to +right +``` +### M + +``` +1 RockUpDown Indicate rock up and +down +``` +### M + +``` +2 RockRound Indicate rock around M +``` +**4.4.5.2. WindBitmap Type** + +``` +Bit Name Summary Conformance +0 SleepWind Indicate sleep wind M +1 NaturalWind Indicate natural wind M +``` +**4.4.5.2.1. SleepWind Value** + +The fan speed, based on current settings, SHALL gradually slow down to a final minimum speed. +For this process, the sequence, speeds and duration are MS. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 349 +``` + +**4.4.5.2.2. NaturalWind Value** + +The fan speed SHALL vary to emulate natural wind. For this setting, the sequence, speeds and dura­ +tion are MS. + +**4.4.5.3. StepDirectionEnum Type** + +``` +Value Name Summary Conformance +0 Increase Step moves in increas­ +ing direction +``` +### M + +``` +1 Decrease Step moves in decreas­ +ing direction +``` +### M + +**4.4.5.4. AirflowDirectionEnum Type** + +``` +Value Name Summary Conformance +0 Forward Airflow is in the for­ +ward direction +``` +### M + +``` +1 Reverse Airflow is in the +reverse direction +``` +### M + +**4.4.5.5. FanModeEnum Type** + +``` +Value Name Summary Conformance +0 Off Fan is off M +1 Low Fan using low speed desc +2 Medium Fan using medium +speed +``` +``` +desc +``` +``` +3 High Fan using high speed M +4 On D +5 Auto Fan is using auto mode AUT +6 Smart Fan is using smart +mode +``` +### D + +**4.4.5.5.1. Low Value** + +If the fan supports 2 or more speeds, the Low value SHALL be supported. + +The Low value SHALL be supported if and only if the FanModeSequence attribute value is less than +4. + +**4.4.5.5.2. Medium Value** + +If the fan supports 3 or more speeds, the Medium value SHALL be supported. + +``` +Page 350 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The Medium value SHALL be supported if and only if the FanModeSequence attribute value is 0 or +2. + +**4.4.5.6. FanModeSequenceEnum Type** + +``` +Value Name Summary Conformance +0 OffLowMedHigh Fan is capable of off, +low, medium and high +modes +``` +``` +[!AUT].a +``` +``` +1 OffLowHigh Fan is capable of off, +low and high modes +``` +``` +[!AUT].a +``` +``` +2 OffLowMedHighAuto Fan is capable of off, +low, medium, high and +auto modes +``` +``` +[AUT].a +``` +``` +3 OffLowHighAuto Fan is capable of off, +low, high and auto +modes +``` +``` +[AUT].a +``` +``` +4 OffHighAuto Fan is capable of off, +high and auto modes +``` +``` +[AUT].a +``` +``` +5 OffHigh Fan is capable of off +and high modes +``` +``` +[!AUT].a +``` +**4.4.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 FanMode FanMod­ +eEnum +``` +``` +all N 0 RW VO M +``` +``` +0x0001 FanMode­ +Sequence +``` +``` +FanMode­ +Se­ +quenceEnu +m +``` +``` +all N MS R[W] VO Zigbee +``` +``` +0x0001 FanMode­ +Sequence +``` +``` +FanMode­ +Se­ +quenceEnu +m +``` +``` +all F MS R V M +``` +``` +0x0002 Per­ +centSet­ +ting +``` +``` +percent max 100 X 0 RW VO M +``` +``` +0x0003 Per­ +centCur­ +rent +``` +``` +percent max 100 desc R V M +``` +``` +0x0004 SpeedMax uint8 1 to 100 F MS R V SPD +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 351 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0005 SpeedSet­ +ting +``` +``` +uint8 max +SpeedMax +``` +### X 0 RW VO SPD + +``` +0x0006 SpeedCur­ +rent +``` +``` +uint8 max +SpeedMax +``` +``` +P desc R V SPD +``` +``` +0x0007 RockSup­ +port +``` +``` +Rock­ +Bitmap +``` +``` +desc F 0 R V RCK +``` +``` +0x0008 RockSet­ +ting +``` +``` +Rock­ +Bitmap +``` +``` +desc P 0 RW VO RCK +``` +``` +0x0009 WindSup­ +port +``` +``` +Wind­ +Bitmap +``` +``` +desc F 0 R V WND +``` +``` +0x000A WindSet­ +ting +``` +``` +Wind­ +Bitmap +``` +``` +desc P 0 RW VO WND +``` +``` +0x000B AirflowDi­ +rection +``` +``` +AirflowDi­ +rectio­ +nEnum +``` +``` +desc P 0 RW VO DIR +``` +**4.4.6.1. FanMode Attribute** + +This attribute SHALL indicate the current speed mode of the fan. This attribute MAY be written by +the client to request a different fan mode. A server SHALL return INVALID_IN_STATE to indicate +that the fan is not in a state where the FanMode can be changed to the requested value. A server +MAY have FanMode values that it can never be set to. For example, where this cluster appears on +the same or another endpoint as other clusters with a system dependency, for example the Thermo­ +stat cluster, attempting to set the FanMode attribute of this cluster to Off may not be allowed by the +system. + +This attribute SHALL be set to one of the values in FanModeEnum. + +When the FanMode attribute is successfully written to, the PercentSetting and SpeedSetting (if +present) attributes SHALL be set to appropriate values, as defined by the Section 4.4.6.3.1 and Sec­ +tion 4.4.6.6.1 respectively, unless otherwise specified below. + +When the FanMode attribute is set to any given mode, the PercentCurrent and SpeedCurrent (if +present) SHALL indicate the actual currently operating fan speed, unless otherwise specified below. + +**4.4.6.1.1. Off Value** + +Setting the attribute value to Off SHALL set the values of these attributes to 0 (zero): + +- PercentSetting +- PercentCurrent +- SpeedSetting (if present) +- SpeedCurrent (if present) + +``` +Page 352 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.4.6.1.2. Auto Value** + +Setting the attribute value to Auto SHALL set the values of these attributes to null: + +- PercentSetting +- SpeedSetting (if present) + +These attributes SHALL continue to indicate the current state of the fan while this attribute value is +Auto: + +- PercentCurrent +- SpeedCurrent (if present) + +**4.4.6.1.3. On Value** + +If a client attempts to write a value of On, the attribute SHALL be set to High. + +**4.4.6.1.4. Smart Value** + +If a client attempts to write a value of Smart and the AUT feature is supported, the attribute SHALL +be set to Auto, otherwise the attribute SHALL be set to High. + +**4.4.6.2. FanModeSequence Attribute** + +This attribute indicates the fan speed ranges that SHALL be supported. + +**4.4.6.3. PercentSetting Attribute** + +This attribute SHALL indicate the speed setting for the fan. This attribute MAY be written by the +client to indicate a new fan speed. If the client writes null to this attribute, the attribute value +SHALL NOT change. A server SHALL return INVALID_IN_STATE to indicate that the fan is not in a +state where the PercentSetting can be changed to the requested value. + +If this is successfully written to 0, the server SHALL set the FanMode attribute value to Off. + +**4.4.6.3.1. Percent Rules** + +It is up to the server implementation to map between ranges of the PercentSetting attribute and +FanMode attribute enumerated values. Percent values are split into ranges, each range correspond­ +ing to a supported FanMode attribute value. Percent ranges SHALL NOT overlap. All percent values +in the High speed range SHALL be higher than all percent values in the Medium and Low speed +ranges, if supported. All percent values in the Medium speed range SHALL be higher than all per­ +cent values in the Low speed range. If the client sets the FanMode attribute to Low, Medium or +High, the server SHALL set the PercentSetting attribute to a value within the corresponding range. +If the client sets the PercentSetting attribute, the server SHALL set the FanMode attribute to Low, +Medium or High, based on the percent value being in the corresponding range. + +If the MultiSpeed feature is supported, the calculation of SpeedSetting or SpeedCurrent (speed) +from a percent value change for PercentSetting or PercentCurrent respectively (percent) SHALL +hold true: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 353 +``` + +- speed = ceil( SpeedMax * (percent * 0.01) ) + +``` +For example: If the SpeedMax attribute is 42 (42 speed fan) and PercentSetting is changed to +25, then SpeedSetting and SpeedCurrent become 11 (rounding up 10.5). +``` +**4.4.6.4. PercentCurrent Attribute** + +This attribute SHALL indicate the actual currently operating fan speed, or zero to indicate that the +fan is off. There MAY be a temporary mismatch between the value of this attribute and the value of +the PercentSetting attribute due to other system requirements that would not allow the fan to oper­ +ate at the requested setting. See Section 4.4.6.3.1 for more details. + +**4.4.6.5. SpeedMax Attribute** + +This attribute SHALL indicate that the fan has one speed (value of 1) or the maximum speed, if the +fan is capable of multiple speeds. + +**4.4.6.6. SpeedSetting Attribute** + +This attribute SHALL indicate the speed setting for the fan. This attribute MAY be written by the +client to indicate a new fan speed. If the client writes null to this attribute, the attribute value +SHALL NOT change. A server SHALL return INVALID_IN_STATE to indicate that the fan is not in a +state where the SpeedSetting can be changed to the requested value. + +If this is successfully written to 0, the server SHALL set the FanMode attribute value to Off. Please +see the Section 4.4.6.6.1 for details on other values. + +**4.4.6.6.1. Speed Rules** + +It is up to the server implementation to map between ranges of the SpeedSetting attribute and Fan­ +Mode attribute enumerated values. Speed values are split into ranges, each range corresponding to +a FanMode attribute value. Speed ranges SHALL NOT overlap. All speed values in the High speed +range SHALL be higher than all speed values in the Medium and Low speed ranges, if supported. +All speed values in the Medium speed range SHALL be higher than all speed values in the Low +speed range. If the client sets the FanMode attribute to Low, Medium or High, the server SHALL set +the SpeedSetting attribute to a value within the corresponding range. If the client sets the SpeedSet­ +ting attribute, the server SHALL set the FanMode attribute to Low, Medium or High, based on the +speed value being in the corresponding range. + +This calculation for the value of PercentSetting or PercentCurrent (percent) from a speed value +change for SpeedSetting or SpeedCurrent respectively (speed) SHALL hold true: + +- percent = floor( speed/SpeedMax * 100 ) + +``` +For example: If the SpeedMax attribute is 42 (42 speed fan) and SpeedSetting attribute is +changed to 11, then PercentSetting and PercentCurrent become 26. +``` +``` +Page 354 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.4.6.7. SpeedCurrent Attribute** + +This attribute SHALL indicate the actual currently operating fan speed, or zero to indicate that the +fan is off. There MAY be a temporary mismatch between the value of this attribute and the value of +the SpeedSetting attribute due to other system requirements that would not allow the fan to oper­ +ate at the requested setting. + +**4.4.6.8. RockSupport Attribute** + +This attribute is a bitmap that indicates what rocking motions the server supports. + +**4.4.6.9. RockSetting Attribute** + +This attribute is a bitmap that indicates the current active fan rocking motion settings. Each bit +SHALL only be set to 1, if the corresponding bit in the RockSupport attribute is set to 1, otherwise a +status code of CONSTRAINT_ERROR SHALL be returned. + +If a combination of supported bits is set by the client, and the server does not support the combina­ +tion, the lowest supported single bit in the combination SHALL be set and active, and all other bits +SHALL indicate zero. + +``` +For example: If RockUpDown and RockRound are both set, but this combination is not possi­ +ble, then only RockUpDown becomes active. +``` +**4.4.6.10. WindSupport Attribute** + +This attribute is a bitmap that indicates what wind modes the server supports. At least one wind +mode bit SHALL be set. + +**4.4.6.11. WindSetting Attribute** + +This attribute is a bitmap that indicates the current active fan wind feature settings. Each bit SHALL +only be set to 1, if the corresponding bit in the WindSupport attribute is set to 1, otherwise a status +code of CONSTRAINT_ERROR SHALL be returned. + +If a combination of supported bits is set by the client, and the server does not support the combina­ +tion, the lowest supported single bit in the combination SHALL be set and active, and all other bits +SHALL indicate zero. + +``` +For example: If Sleep Wind and Natural Wind are set, but this combination is not possible, +then only Sleep Wind becomes active. +``` +**4.4.6.12. AirflowDirection Attribute** + +This attribute SHALL indicate the current airflow direction of the fan. This attribute MAY be writ­ +ten by the client to indicate a new airflow direction for the fan. This attribute SHALL be set to one +of the values in the AirflowDirectionEnum table. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 355 +``` + +**4.4.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Step client ⇒ server Y O STEP +``` +**4.4.7.1. Step Command** + +This command speeds up or slows down the fan, in steps, without the client having to know the fan +speed. This command supports, for example, a user operated wall switch, where the user provides +the feedback or control to stop sending this command when the proper speed is reached. The step +speed values are implementation specific. How many step speeds are implemented is implementa­ +tion specific. + +This command supports these fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Direction StepDirectio­ +nEnum +``` +``` +Increase M +``` +``` +1 Wrap bool false O +2 LowestOff bool true O +``` +**4.4.7.1.1. Direction Field** + +This field SHALL indicate whether the fan speed increases or decreases to the next step value. + +**4.4.7.1.2. Wrap Field** + +This field SHALL indicate if the fan speed wraps between highest and lowest step value. + +**4.4.7.1.3. LowestOff Field** + +This field SHALL indicate that the fan being off (speed value 0) is included as a step value. + +**4.4.7.1.4. When Generated** + +The client sends this command to speed the fan up or down in a step by step fashion. + +**4.4.7.1.5. Effect Upon Receipt** + +- This command SHALL be executed even if the fan speed is not currently at an implemented step + value. +- If the Direction field is Increase, + ◦ If the fan speed is lower than the highest step value, the fan speed SHALL change to the low­ + est step value that is higher than the current fan speed. + ◦ Else if Wrap is TRUE, the fan speed SHALL change to the lowest step value. + ◦ Else the fan speed SHALL change to (or remain at) the highest step value. + +``` +Page 356 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- If the Direction field is Decrease, + ◦ If the fan speed is higher than the lowest step value, the fan speed SHALL change to the + highest step value that is lower than the current fan speed. + ◦ Else if Wrap is TRUE, the fan speed SHALL change to the highest step value. + ◦ Else the fan speed SHALL change to (or remain at) the lowest step value. +- Although the effect of the Step command is implementation specific, the effect on receipt of the + Step command SHALL adhere to the conformance of the affected attributes. + +**4.5. Thermostat User Interface Configuration Cluster** + +This cluster provides an interface to allow configuration of the user interface for a thermostat, or a +thermostat controller device, that supports a keypad and LCD screen. + +**4.5.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added +2 New data model format and notation, added +"Conversion of Temperature Values for Display" +section +``` +**4.5.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint TSUIC +``` +**4.5.3. Cluster ID** + +``` +ID Name +0x0204 Thermostat User Interface Configuration +``` +**4.5.4. Conversion of Temperature Values for Display** + +See the Temperature Conversion section in the Data Model for unit conversion between Fahrenheit +and Celsius. + +**4.5.5. Data Types** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 357 +``` + +**4.5.5.1. TemperatureDisplayModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Celsius Temperature displayed +in °C +``` +### M + +``` +1 Fahrenheit Temperature displayed +in °F +``` +### M + +**4.5.5.2. KeypadLockoutEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 NoLockout All functionality avail­ +able to the user +``` +### M + +``` +1 Lockout1 Level 1 reduced func­ +tionality +``` +### M + +``` +2 Lockout2 Level 2 reduced func­ +tionality +``` +### M + +``` +3 Lockout3 Level 3 reduced func­ +tionality +``` +### M + +``` +4 Lockout4 Level 4 reduced func­ +tionality +``` +### M + +``` +5 Lockout5 Least functionality +available to the user +``` +### M + +The interpretation of the various levels is device-dependent. + +**4.5.5.3. ScheduleProgrammingVisibilityEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 ScheduleProgram­ +mingPermitted +``` +``` +Local schedule pro­ +gramming functionality +is enabled at the ther­ +mostat +``` +### M + +``` +1 ScheduleProgram­ +mingDenied +``` +``` +Local schedule pro­ +gramming functionality +is disabled at the ther­ +mostat +``` +### M + +``` +Page 358 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.5.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Tempera­ +tureDis­ +playMode +``` +``` +Tempera­ +tureDis­ +playMod­ +eEnum +``` +``` +all Celsius RW VO M +``` +``` +0x0001 Keypad­ +Lockout +``` +``` +Keypad­ +Lock­ +outEnum +``` +``` +all NoLockout RW VM M +``` +``` +0x0002 Sched­ +ulePro­ +gram­ +mingVisi­ +bility +``` +``` +Sched­ +ulePro­ +gram­ +mingVisi­ +bilityEnum +``` +``` +all Sched­ +ulePro­ +gramming­ +Permitted +``` +### RW VM O + +**4.5.6.1. TemperatureDisplayMode Attribute** + +This attribute SHALL indicate the units of the temperature displayed on the thermostat screen. + +**4.5.6.2. KeypadLockout Attribute** + +This attribute SHALL indicate the level of functionality that is available to the user via the keypad. + +**4.5.6.3. ScheduleProgrammingVisibility Attribute** + +This attribute is used to hide the weekly schedule programming functionality or menu on a thermo­ +stat from a user to prevent local user programming of the weekly schedule. The schedule program­ +ming MAY still be performed via a remote interface, and the thermostat MAY operate in schedule +programming mode. + +This attribute is designed to prevent local tampering with or disabling of schedules that MAY have +been programmed by users or service providers via a more capable remote interface. The program­ +ming schedule SHALL continue to run even though it is not visible to the user locally at the thermo­ +stat. + +**4.6. Valve Configuration and Control Cluster** + +This cluster is used to configure a valve. + +**4.6.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 359 +``` + +``` +Revision Description +1 Initial revision +``` +**4.6.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint VALCC +``` +**4.6.3. Cluster ID** + +``` +ID Name +0x0081 Valve Configuration and Control +``` +**4.6.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 TS TimeSync desc UTC time is used +for time indica­ +tions +1 LVL Level O Device supports +setting the specific +position of the +valve +``` +**4.6.4.1. TimeSync Feature** + +This feature SHALL indicate that the valve uses Time Synchronization and UTC time to indicate +duration and auto close time. + +This feature SHALL NOT be supported unless the device supports the Time Synchronization cluster. + +**4.6.4.2. Level Feature** + +This feature SHALL indicate that the valve is capable of being adjusted to a specific position, as a +percentage, of its full range of motion. + +**4.6.5. Data Types** + +**4.6.5.1. ValveFaultBitmap Type** + +This data type is derived from map16. + +``` +Page 360 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary Conformance +0 GeneralFault Unspecified fault +detected +``` +### M + +``` +1 Blocked Valve is blocked M +2 Leaking Valve has detected a +leak +``` +### M + +``` +3 NotConnected No valve is connected +to controller +``` +### M + +``` +4 ShortCircuit Short circuit is detected M +5 CurrentExceeded The available current +has been exceeded +``` +### M + +**4.6.5.2. ValveStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Closed Valve is in closed posi­ +tion +``` +### M + +``` +1 Open Valve is in open posi­ +tion +``` +### M + +``` +2 Transitioning Valve is transitioning +between closed and +open positions or +between levels +``` +### M + +**4.6.6. Status Codes** + +**4.6.6.1. StatusCodeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x02 FailureDueToFault The requested action +could not be performed +due to a fault on the +valve. +``` +### M + +**4.6.7. Attributes** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 361 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Open­ +Duration +``` +``` +elapsed-s min 1 X null R V M +``` +``` +0x0001 Default­ +Open­ +Duration +``` +``` +elapsed-s min 1 XN null RW VO M +``` +``` +0x0002 AutoClose­ +Time +``` +``` +epoch-us all X null R V TS +``` +``` +0x0003 Remain­ +ingDura­ +tion +``` +``` +elapsed-s all X Q null R V M +``` +``` +0x0004 Cur­ +rentState +``` +``` +ValveSta­ +teEnum +``` +``` +all X null R V M +``` +``` +0x0005 Target­ +State +``` +``` +ValveSta­ +teEnum +``` +``` +all X null R V M +``` +``` +0x0006 Cur­ +rentLevel +``` +``` +percent all X null R V LVL +``` +``` +0x0007 Tar­ +getLevel +``` +``` +percent all X null R V LVL +``` +``` +0x0008 Default­ +OpenLevel +``` +``` +percent 1 to 100 N 100 RW VO [LVL] +``` +``` +0x0009 ValveFault ValveFault­ +Bitmap +``` +``` +all 0 R V O +``` +``` +0x000A LevelStep uint8 1 to 50 F 1 R V [LVL] +``` +**4.6.7.1. OpenDuration Attribute** + +This attribute SHALL indicate the total duration, in seconds, for which the valve will remain open +for this current opening. + +A value of null SHALL indicate the duration is not set, meaning that the valve will remain open +until closed by the user or some other automation. + +**4.6.7.2. DefaultOpenDuration Attribute** + +This attribute SHALL indicate the default duration, in seconds, for which the valve will remain +open, if the OpenDuration field is not present in the Open command. + +A value of null SHALL indicate the duration is not set, meaning that the valve will remain open +until closed by the user or some other automation. + +``` +Page 362 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.6.7.3. AutoCloseTime Attribute** + +This attribute SHALL indicate the UTC time when the valve will close, depending on value of the +OpenDuration attribute. + +This attribute SHALL be null: + +- When OpenDuration is null, or +- When the valve does not have a synchronized UTCTime in the Time Synchronization cluster, or +- When the valve is closed. + +When the value of this attribute is earlier or equal to the current UTC time, the valve SHALL auto­ +matically transition to its closed position. The behavior of transitioning to the closed position, +SHALL match the behavior described in the Close command. + +If this attribute is not null and the Time Synchronization cluster receives a SetUTCTime command, +modifying the current UTC time of the device, the value of this attribute SHALL be adjusted to +match the new UTC time plus the value of the RemainingDuration attribute. + +**4.6.7.4. RemainingDuration Attribute** + +This attribute SHALL indicate the remaining duration, in seconds, until the valve closes. + +This attribute SHALL be null: + +- When OpenDuration is null, or +- When the valve is closed. + +The value of this attribute SHALL only be reported in the following cases: + +- When it changes from null to any other value and vice versa, or +- When it changes to 0, or +- When it increases, or +- When the closing time changes. + +Meaning that clients SHOULD NOT rely on the reporting of this attribute in order to keep track of +the remaining duration, due to this attribute not being reported during regular countdown. + +When reading this attribute it SHALL return the remaining duration, in seconds, until the valve +closes. + +When the value of this attribute counts down to 0, the valve SHALL automatically transition to its +closed position. The behavior of transitioning to the closed position SHALL match the behavior +described in the Close command. + +**4.6.7.5. CurrentState Attribute** + +This attribute SHALL indicate the current state of the valve. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 363 +``` + +A value of null SHALL indicate that the current state is not known. + +**4.6.7.6. TargetState Attribute** + +This attribute SHALL indicate the target state, while changing the state, of the valve. + +A value of null SHALL indicate that no target position is set, since the change in state is either done +or failed. + +**4.6.7.7. CurrentLevel Attribute** + +This attribute SHALL indicate the current level of the valve as a percentage value, between fully +closed and fully open. During a transition from one level to another level, the valve SHOULD keep +this attribute updated to the best of its ability, in order to represent the actual level of the valve dur­ +ing the movement. + +A value of 100 percent SHALL indicate the fully open position. + +A value of 0 percent SHALL indicate the fully closed position. + +A value of null SHALL indicate that the current state is not known. + +**4.6.7.8. TargetLevel Attribute** + +This attribute SHALL indicate the target level of the valve as a percentage value, between fully +closed and fully open. + +The interpretation of the percentage value is the same as for the CurrentLevel attribute. + +A value of null SHALL indicate that no target position is set, since the change of level is either done +or failed. + +**4.6.7.9. DefaultOpenLevel Attribute** + +This attribute SHALL indicate the default value used for the TargetLevel attribute, when a valve +transitions from the closed to the open state, caused by an Open command, if a TargetLevel field is +not present in the Open command. + +If the LevelStep attribute is present and the value of a write interaction to this attribute field is not +100, the value SHALL be a supported value as defined by the LevelStep attribute, such that (Value +received in the write interaction) % (Value of LevelStep attribute) equals 0. If the resulting value is +not 0, the requested DefaultOpenLevel value is considered an unsupported value and a CON­ +STRAINT_ERROR status SHALL be returned. + +**4.6.7.10. ValveFault Attribute** + +This attribute SHALL indicate any faults registered by the valve. + +**4.6.7.11. LevelStep Attribute** + +This attribute SHALL indicate the step size the valve can support. + +``` +Page 364 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The step size defined by this attribute is counted from 0 and the final step towards 100 MAY be dif­ +ferent than what is defined in this attribute. For example, if the value of this attribute is 15, it +results in these target values being supported; 0, 15, 30, 45, 60, 75, 90 and 100. + +The values of 0 and 100 SHALL always be supported, regardless of the value of this attribute. + +**4.6.8. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Open client ⇒ server Y O M +0x01 Close client ⇒ server Y O M +``` +**4.6.8.1. Open Command** + +This command is used to set the valve to its open position. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 OpenDura­ +tion +``` +``` +elapsed-s min 1 X O +``` +``` +1 TargetLevel percent min 1 [LVL] +``` +**4.6.8.1.1. OpenDuration Field** + +This field SHALL indicate the duration that the valve will remain open for this specific Open com­ +mand. + +A value of null SHALL indicate the duration is not set, meaning that the valve will remain open +until closed by the user or some other automation. + +**4.6.8.1.2. TargetLevel Field** + +This field SHALL indicate the target level used for this specific Open command. + +**4.6.8.1.3. Effect on Receipt** + +If the device has registered a fault, that prevents it from performing the requested action, the com­ +mand SHALL be ignored and a FailureDueToFault status SHALL be returned. + +The device SHALL set the TargetState attribute to the Open value and set the CurrentState attribute +to the Transitioning value. + +If the OpenDuration field is present, the value of the OpenDuration attribute SHALL be set to the +value of the OpenDuration field. +If the OpenDuration field is not present, the value of OpenDuration attribute SHALL be set to the +value of the DefaultOpenDuration attribute. + +If the OpenDuration attribute is null, it SHALL indicate that there is no auto close defined for the +current Open action and the device SHALL set the RemainingDuration attribute to null. If the + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 365 +``` + +device supports the TimeSync feature, the device SHALL set the AutoCloseTime attribute to null. +If the OpenDuration attribute is not null, it indicates that an auto close duration is defined for the +current open action and the device SHALL set the value of the RemainingDuration attribute equal +to the value of the OpenDuration attribute. If the device supports the TimeSync feature, the device +SHALL set the AutoCloseTime attribute to the UTC value of the time when command was received +plus the value of the OpenDuration attribute. + +If the LevelStep attribute and the TargetLevel field are both present and the value of the Tar­ +getLevel field is not 100, the value of the TargetLevel field SHALL be a supported value as defined +by the LevelStep attribute, such that (Value of TargetLevel field) % (Value of LevelStep attribute) +equals 0. If the resulting value is not 0, the requested TargetLevel value is considered an unsup­ +ported value and a CONSTRAINT_ERROR status SHALL be returned. + +If the device supports the Level feature, the TargetLevel attribute SHALL be set to the value of the +TargetLevel field, if present. If the TargetLevel field is not present, the TargetLevel attribute SHALL +be set to the value of the DefaultOpenLevel attribute, if implemented. If the DefaultOpenLevel +attribute is not present, the TargetLevel attribute SHALL be set to 100. + +When the relevant target and duration attributes have been set, the device SHALL start the move­ +ment towards the target value and start the countdown of the RemainingDuration attribute. If the +device supports the Level feature, the device SHALL update the CurrentLevel attribute at the start +of the movement, and SHOULD update it as appropriate during movement, especially if it is slow. +When the movement is complete, the device SHALL set the CurrentState attribute to the Open +value. + +**4.6.8.2. Close Command** + +This command is used to set the valve to its closed position. + +**4.6.8.2.1. Effect on Receipt** + +If the device has registered a fault that causes it to prevent the valve to perform the requested +action, the command SHALL be ignored and a FailureDueToFault status SHALL be returned. + +The OpenDuration and RemainingDuration attribute SHALL be set to null. + +If the device supports the TimeSync feature, the AutoCloseTime attribute SHALL be set to null. + +The device SHALL set the TargetState attribute to the Closed value and set the CurrentState +attribute to the Transitioning value. + +If the device supports the Level feature, it SHALL set the TargetLevel attribute to 0. + +When the relevant target attributes have been set, the device SHALL start the movement towards +the target value. If the device supports the Level feature, the device SHALL update the CurrentLevel +attribute, accordingly during the movement. When the movement is complete, the device SHALL +set the CurrentState attribute to the Closed value. + +``` +Page 366 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.6.9. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 ValveState­ +Changed +``` +### INFO V O + +``` +0x01 ValveFault INFO V O +``` +**4.6.9.1. ValveStateChanged Event** + +This event SHALL be generated when the valve state changed. For level changes, after the end of +movement, for state changes when the new state has been reached. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ValveState ValveSta­ +teEnum +``` +``` +all M +``` +``` +1 ValveLevel percent all LVL +``` +**4.6.9.1.1. ValveState Field** + +This field SHALL indicate the new state of the valve. + +**4.6.9.1.2. ValveLevel Field** + +This field SHALL indicate the new level of the valve. + +**4.6.9.2. ValveFault Event** + +This event SHALL be generated when the valve registers or clears a fault, e.g. not being able to tran­ +sition to the requested target level or state. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ValveFault ValveFault­ +Bitmap +``` +``` +all M +``` +**4.6.9.2.1. ValveFault Field** + +This field SHALL indicate the value of the ValveFault attribute, at the time this event is generated. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 367 +``` + +Page 368 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 5. Closures** + +The Cluster Library is made of individual chapters such as this one. References between chapters +are made using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. + +**5.1. General Description** + +**5.1.1. Introduction** + +The clusters specified in this document are for use typically in applications involving closures (e.g., +shades, windows, doors), but MAY be used in any application domain. + +**5.1.2. Cluster List** + +This section lists the closures specific clusters as specified in this chapter. + +_Table 10. Overview of the Closures Clusters_ + +``` +Cluster ID Cluster Name Description +0x0101 Door Lock An interface to a generic way to +secure a door +0x0102 Window Covering Commands and attributes for +controlling a window covering +``` +**5.2. Door Lock Cluster** + +The door lock cluster provides an interface to a generic way to secure a door. The physical object +that provides the locking functionality is abstracted from the cluster. The cluster has a small list of +mandatory attributes and functions and a list of optional features. + +_Figure 16. Typical Usage of the Door Lock Cluster_ + +**5.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 369 +``` + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added; CCB 1811 1812 1821 +2 CCB 2430 +3 CCB 2629 2630 +4 All Hubs changes and added feature map +5 CCB 3472 3474 3338 +6 New data model format and notation. Added +User features. General cleanup of functionality +7 Added support for European door locks (unbolt +feature) +8 Removed LOG and NOT feature, fixed con­ +straints on NumberOf *Schedules attributes. and +added support for Aliro credential provisioning +``` +**5.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint DRLK +``` +**5.2.3. Cluster ID** + +``` +ID Name +0x0101 Door Lock +``` +**5.2.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 PIN PINCredential O Lock supports PIN +credentials (via +keypad, or over- +the-air) +1 RID RFIDCredential O Lock supports +RFID credentials +2 FGP FingerCredentials P, O Lock supports fin­ +ger related cre­ +dentials (finger­ +print, finger vein) +``` +``` +Page 370 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Conformance Summary +4 WDSCH WeekDayAccessS­ +chedules +``` +``` +O Lock supports +week day user +access schedules +5 DPS DoorPositionSen­ +sor +``` +``` +O Lock supports a +door position sen­ +sor that indicates +door’s state +6 FACE FaceCredentials P, O Lock supports face +related credentials +(face, iris, retina) +7 COTA Creden­ +tialOverTheAirAc­ +cess +``` +``` +O PIN codes over- +the-air supported +for lock/unlock +operations +8 USR User ALIRO, [ PIN | RID +| FGP | FACE ] +``` +``` +Lock supports the +user commands +and database +10 YDSCH YearDayAccessS­ +chedules +``` +``` +O Lock supports +year day user +access schedules +11 HDSCH HolidaySchedules O Lock supports hol­ +iday schedules +12 UBOLT Unbolting O Lock supports +unbolting +13 ALIRO AliroProvisioning O Lock supports +Aliro credential +provisioning as +defined in [Aliro] +14 ALBU AliroBLEUWB [ALIRO] Lock supports the +Bluetooth LE + +UWB Access Con­ +trol Flow as +defined in [Aliro] +``` +**5.2.4.1. PINCredential Feature** + +If the User Feature is also supported then any PIN Code stored in the lock SHALL be associated with +a User. + +A lock MAY support multiple credential types so if the User feature is supported the UserType, User­ +Status and Schedules are all associated with a User index and not directly with a PIN index. A User +index may have several credentials associated with it. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 371 +``` + +**5.2.4.2. RFIDCredential Feature** + +If the User Feature is also supported then any RFID credential stored in the lock SHALL be associ­ +ated with a User. + +A lock MAY support multiple credential types so if the User feature is supported the UserType, User­ +Status and Schedules are all associated with a User index and not directly with a RFID index. A User +Index may have several credentials associated with it. + +**5.2.4.3. FingerCredentials Feature** + +Currently the cluster only defines the metadata format for notifications when a fingerprint/ finger +vein credential is used to access the lock and doesn’t describe how to create fingerprint/finger vein +credentials. If the Users feature is also supported then the User that a fingerprint/finger vein is +associated with can also have its UserType, UserStatus and Schedule modified. + +A lock MAY support multiple credential types so if the User feature is supported the UserType, User­ +Status and Schedules are all associated with a User index and not directly with a Finger index. A +User Index may have several credentials associated with it. + +**5.2.4.4. WeekDayAccessSchedules Feature** + +If the User feature is supported then Week Day Schedules are applied to a User and not a credential. + +Week Day Schedules are used to restrict access to a specified time window on certain days of the +week. The schedule is repeated each week. + +The lock MAY automatically adjust the UserType when a schedule is created or cleared. + +Support for WeekDayAccessSchedules requires that the lock has the capability of keeping track of +local time. + +**5.2.4.5. DoorPositionSensor Feature** + +If this feature is supported this indicates that the lock has the ability to determine the position of +the door which is separate from the state of the lock. + +**5.2.4.6. FaceCredentials Feature** + +Currently the cluster only defines the metadata format for notifications when a face recognition, +iris, or retina credential is used to access the lock and doesn’t describe how to create face recogni­ +tion, iris, or retina credentials. If the Users feature is also supported then the User that a face recog­ +nition, iris, or retina credential is associated with can also have its UserType, UserStatus and Sched­ +ule modified. + +A lock MAY support multiple credential types so if the User feature is supported the UserType, User­ +Status and Schedules are all associated with a User and not directly with a credential. + +**5.2.4.7. CredentialOverTheAirAccess Feature** + +If this feature is supported then the lock supports the ability to verify a credential provided in a + +``` +Page 372 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +lock/unlock command. Currently the cluster only supports providing the PIN credential to the +lock/unlock commands. If this feature is supported then the PIN Credential feature SHALL also be +supported. + +**5.2.4.8. User Feature** + +If the User Feature is supported then a lock employs a User database. A User within the User data­ +base is used to associate credentials and schedules to single user record within the lock. This also +means the UserType and UserStatus fields are associated with a User and not a credential. + +**5.2.4.9. YearDayAccessSchedules Feature** + +If the User feature is supported then Year Day Schedules are applied to a User and not a credential. + +Year Day Schedules are used to restrict access to a specified date and time window. + +The lock MAY automatically adjust the UserType when a schedule is created or cleared. + +Support for YearDayAccessSchedules requires that the lock has the capability of keeping track of +local time. + +**5.2.4.10. HolidaySchedules Feature** + +This feature is used to setup Holiday Schedule in the lock device. A Holiday Schedule sets a start +and stop end date/time for the lock to use the specified operating mode set by the Holiday Schedule. + +Support for HolidaySchedules requires that the lock has the capability of keeping track of local +time. + +**5.2.4.11. Unbolting Feature** + +Locks that support this feature differentiate between unbolting and unlocking. The Unbolt Door +command retracts the bolt without pulling the latch. The Unlock Door command fully unlocks the +door by retracting the bolt and briefly pulling the latch. While the latch is pulled, the lock state +changes to Unlatched. Locks without unbolting support don’t differentiate between unbolting and +unlocking and perform the same operation for both commands. + +**5.2.4.12. AliroProvisioning Feature** + +Locks that support this feature implement the Aliro specification as defined in [Aliro] and support +Matter as a method for provisioning Aliro credentials. + +**5.2.4.13. AliroBLEUWB Feature** + +Locks that support this feature implement the Bluetooth LE + UWB Access Control Flow as defined +in [Aliro]. + +**5.2.5. Recommended steps for creating a new User** + +It is RECOMMENDED that the Administrator query the door lock for what users already exist in its +database to find an available UserIndex for creating a new User (see GetUser command). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 373 +``` + +1. Use SetUser command with an available UserIndex to set the user record fields as applicable. +2. Use SetCredential command with same UserIndex to add one or more credentials as applicable. +3. Use SetWeekDaySchedule command or SetYearDaySchedule command with same UserIndex to + add one or more schedule restrictions as applicable. + +**5.2.6. Data Types** + +**5.2.6.1. DaysMaskBitmap Type** + +This data type is derived from map8. + +This bitmap SHALL indicate the days of the week the Week Day schedule applies for. + +``` +Bit Name Summary Conformance +0 Sunday Schedule is applied on +Sunday +``` +### M + +``` +1 Monday Schedule is applied on +Monday +``` +### M + +``` +2 Tuesday Schedule is applied on +Tuesday +``` +### M + +``` +3 Wednesday Schedule is applied on +Wednesday +``` +### M + +``` +4 Thursday Schedule is applied on +Thursday +``` +### M + +``` +5 Friday Schedule is applied on +Friday +``` +### M + +``` +6 Saturday Schedule is applied on +Saturday +``` +### M + +**5.2.6.2. CredentialRulesBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 Single Only one credential is +required for lock oper­ +ation +``` +### M + +``` +1 Dual Any two credentials are +required for lock oper­ +ation +``` +### M + +``` +2 Tri Any three credentials +are required for lock +operation +``` +### M + +``` +Page 374 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.6.3. OperatingModesBitmap Type** + +This data type is derived from map16. + +``` +Bit Name Summary Conformance +0 Normal Normal operation +mode +``` +### M + +``` +1 Vacation Vacation operation +mode +``` +### O + +``` +2 Privacy Privacy operation +mode +``` +### O + +``` +3 NoRemoteLockUnlock No remote lock and +unlock operation mode +``` +### M + +``` +4 Passage Passage operation +mode +``` +### O + +**5.2.6.4. ConfigurationRegisterBitmap Type** + +This data type is derived from map16. + +``` +Bit Name Summary Conformance +0 LocalProgramming The state of local pro­ +gramming functionality +``` +### M + +``` +1 KeypadInterface The state of the keypad +interface +``` +### M + +``` +2 RemoteInterface The state of the remote +interface +``` +### M + +``` +5 SoundVolume Sound volume is set to +Silent value +``` +### M + +``` +6 AutoRelockTime Auto relock time it set +to 0 +``` +### M + +``` +7 LEDSettings LEDs is disabled M +``` +**5.2.6.4.1. LocalProgramming Bit** + +This bit SHALL indicate the state related to local programming: + +- 0 = Local programming is disabled +- 1 = Local programming is enabled + +**5.2.6.4.2. KeypadInterface Bit** + +This bit SHALL indicate the state related to keypad interface: + +- 0 = Keypad interface is disabled + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 375 +``` + +- 1 = Keypad interface is enabled + +**5.2.6.4.3. RemoteInterface Bit** + +This bit SHALL indicate the state related to remote interface: + +- 0 = Remote interface is disabled +- 1 = Remote interface is enabled + +**5.2.6.4.4. SoundVolume Bit** + +This bit SHALL indicate the state related to sound volume: + +- 0 = Sound volume value is 0 (Silent) +- 1 = Sound volume value is equal to something other than 0 + +**5.2.6.4.5. AutoRelockTime Bit** + +This bit SHALL indicate the state related to auto relock time: + +- 0 = Auto relock time value is 0 +- 1 = Auto relock time value is equal to something other than 0 + +**5.2.6.4.6. LEDSettings Bit** + +This bit SHALL indicate the state related to LED settings: + +- 0 = LED settings value is 0 (NoLEDSignal) +- 1 = LED settings value is equal to something other than 0 + +**5.2.6.5. LocalProgrammingFeaturesBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 AddUsersCreden­ +tialsSchedules +``` +``` +The state of the ability +to add users, creden­ +tials or schedules on +the device +``` +### M + +``` +1 ModifyUsersCreden­ +tialsSchedules +``` +``` +The state of the ability +to modify users, cre­ +dentials or schedules +on the device +``` +### M + +``` +2 ClearUsersCreden­ +tialsSchedules +``` +``` +The state of the ability +to clear users, creden­ +tials or schedules on +the device +``` +### M + +``` +Page 376 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary Conformance +3 AdjustSettings The state of the ability +to adjust settings on the +device +``` +### M + +**5.2.6.5.1. AddUsersCredentialsSchedules Bit** + +This bit SHALL indicate whether the door lock is able to add Users/Credentials/Schedules locally: + +- 0 = This ability is disabled +- 1 = This ability is enabled + +**5.2.6.5.2. ModifyUsersCredentialsSchedules Bit** + +This bit SHALL indicate whether the door lock is able to modify Users/Credentials/Schedules locally: + +- 0 = This ability is disabled +- 1 = This ability is enabled + +**5.2.6.5.3. ClearUsersCredentialsSchedules Bit** + +This bit SHALL indicate whether the door lock is able to clear Users/Credentials/Schedules locally: + +- 0 = This ability is disabled +- 1 = This ability is enabled + +**5.2.6.5.4. AdjustSettings Bit** + +This bit SHALL indicate whether the door lock is able to adjust lock settings locally: + +- 0 = This ability is disabled +- 1 = This ability is enabled + +**5.2.6.6. AlarmMaskBitmap Type** + +This data type is derived from map16. + +``` +Bit Name Summary Conformance +0 LockJammed Locking Mechanism +Jammed +``` +### M + +``` +1 LockFactoryReset Lock Reset to Factory +Defaults +``` +### O + +``` +3 LockRadioPowerCy­ +cled +``` +``` +RF Module Power +Cycled +``` +### O + +``` +4 WrongCodeEn­ +tryLimit +``` +``` +Tamper Alarm - wrong +code entry limit +``` +### PIN | RID + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 377 +``` + +``` +Bit Name Summary Conformance +5 FrontEscutcheonRe­ +moved +``` +``` +Tamper Alarm - front +escutcheon removed +from main +``` +### O + +``` +6 DoorForcedOpen Forced Door Open +under Door Locked +Condition +``` +### O + +**5.2.6.7. AlarmCodeEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate the alarm type. + +``` +Value Name Summary Conformance +0 LockJammed Locking Mechanism +Jammed +``` +### M + +``` +1 LockFactoryReset Lock Reset to Factory +Defaults +``` +### O + +``` +3 LockRadioPowerCy­ +cled +``` +``` +Lock Radio Power +Cycled +``` +### O + +``` +4 WrongCodeEn­ +tryLimit +``` +``` +Tamper Alarm - wrong +code entry limit +``` +### [USR] + +``` +5 FrontEsceutcheonRe­ +moved +``` +``` +Tamper Alarm - front +escutcheon removed +from main +``` +### O + +``` +6 DoorForcedOpen Forced Door Open +under Door Locked +Condition +``` +### [DPS] + +``` +7 DoorAjar Door ajar [DPS] +8 ForcedUser Force User SOS alarm [USR] +``` +**5.2.6.8. CredentialRuleEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate the credential rule that can be applied to a particular user. + +``` +Value Name Summary Conformance +0 Single Only one credential is +required for lock oper­ +ation +``` +### USR + +``` +Page 378 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +1 Dual Any two credentials are +required for lock oper­ +ation +``` +### [USR] + +``` +2 Tri Any three credentials +are required for lock +operation +``` +### [USR] + +**5.2.6.9. CredentialTypeEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate the credential type. + +``` +Value Name Summary Conformance +0 ProgrammingPIN Programming PIN code +credential type +``` +### O + +``` +1 PIN PIN code credential +type +``` +### PIN + +``` +2 RFID RFID identifier creden­ +tial type +``` +### RID + +``` +3 Fingerprint Fingerprint identifier +credential type +``` +### FGP + +``` +4 FingerVein Finger vein identifier +credential type +``` +### FGP + +``` +5 Face Face identifier creden­ +tial type +``` +### FACE + +``` +6 AliroCredentialIs­ +suerKey +``` +``` +A Credential Issuer +public key as defined in +[Aliro] +``` +### ALIRO + +``` +7 AliroEvictableEnd­ +pointKey +``` +``` +An Endpoint public key +as defined in [Aliro] +which can be evicted if +space is needed for +another endpoint key +``` +### ALIRO + +``` +8 AliroNonEvictableEnd +pointKey +``` +``` +An Endpoint public key +as defined in [Aliro] +which cannot be +evicted if space is +needed for another +endpoint key +``` +### ALIRO + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 379 +``` + +**5.2.6.9.1. AliroCredentialIssuerKey Value** + +Credentials of this type SHALL be 65-byte uncompressed elliptic curve public keys as defined in sec­ +tion 2.3.3 of SEC 1. + +Credentials of this type SHALL NOT be used to allow operating the lock. They SHALL be used, as +defined in [Aliro], to create new credentials of type AliroEvictableEndpointKey via a step-up trans­ +action. + +When performing the step-up transaction, the lock SHALL request the data element with identifier +"matter1", and SHALL attempt to create a new credential of type AliroEvictableEndpointKey if and +only if the data element is returned and the Access Credential can be validated using the AliroCre­ +dentialIssuerKey. + +When a new credential of type AliroEvictableEndpointKey is added in this manner, it SHALL be +associated with the same user record as the AliroCredentialIssuerKey credential that allowed the +new credential to be added. + +If there are no available credential slots to add a new AliroEvictableEndpointKey credential (i.e. +either the NumberOfCredentialsSupportedPerUser or the NumberOfAliroEndpointKeysSupported +limit has been reached) but there exist credentials of type AliroEvictableEndpointKey associated +with the user record, the server SHALL remove one of those credentials using the same procedure +it would follow for the ClearCredential command before adding the new credential. + +If there are no available credential slots to add a new AliroEvictableEndpointKey credential (i.e. +either the NumberOfCredentialsSupportedPerUser or the NumberOfAliroEndpointKeysSupported +limit has been reached) and there do not exist credentials of type AliroEvictableEndpointKey asso­ +ciated with the user record, a new AliroEvictableEndpointKey credential SHALL NOT be created. + +If the step-up process results in addition of new credentials, the corresponding LockUserChange +event SHALL have OperationSource set to Aliro. + +If the step-up process results in the lock state changing (e.g. locking or unlocking), the credential +associated with those changes in the LockOperation events SHALL be the newly provisioned AliroE­ +victableEndpointKey credential if one was created. If no new AliroEvictableEndpointKey credential +was created, the credential associated with the changes in the LockOperation events SHALL be the +AliroCredentialIssuerKey credential used for the step-up. + +**5.2.6.9.2. AliroEvictableEndpointKey Value** + +Credentials of this type SHALL be 65-byte uncompressed elliptic curve public keys as defined in sec­ +tion 2.3.3 of SEC 1. + +**5.2.6.9.3. AliroNonEvictableEndpointKey Value** + +Credentials of this type SHALL be 65-byte uncompressed elliptic curve public keys as defined in sec­ +tion 2.3.3 of SEC 1. + +**5.2.6.10. DataOperationTypeEnum Type** + +This data type is derived from enum8. + +``` +Page 380 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +This enumeration SHALL indicate the data operation performed. + +``` +Value Name Summary Conformance +0 Add Data is being added or +was added +``` +### M + +``` +1 Clear Data is being cleared or +was cleared +``` +### M + +``` +2 Modify Data is being modified +or was modified +``` +### M + +**5.2.6.11. DoorStateEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate the current door state. + +``` +Value Name Summary Conformance +0 DoorOpen Door state is open DPS +1 DoorClosed Door state is closed DPS +2 DoorJammed Door state is jammed [DPS] +3 DoorForcedOpen Door state is currently +forced open +``` +### [DPS] + +``` +4 DoorUnspecifiedError Door state is invalid for +unspecified reason +``` +### [DPS] + +``` +5 DoorAjar Door state is ajar [DPS] +``` +**5.2.6.12. LockDataTypeEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate the data type that is being or has changed. + +``` +Value Name Summary Conformance +0 Unspecified Unspecified or manu­ +facturer specific lock +user data added, +cleared, or modified. +``` +### O + +``` +1 ProgrammingCode Lock programming PIN +code was added, +cleared, or modified. +``` +### O + +``` +2 UserIndex Lock user index was +added, cleared, or mod­ +ified. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 381 +``` + +``` +Value Name Summary Conformance +3 WeekDaySchedule Lock user week day +schedule was added, +cleared, or modified. +``` +### WDSCH + +``` +4 YearDaySchedule Lock user year day +schedule was added, +cleared, or modified. +``` +### YDSCH + +``` +5 HolidaySchedule Lock holiday schedule +was added, cleared, or +modified. +``` +### HDSCH + +``` +6 PIN Lock user PIN code was +added, cleared, or mod­ +ified. +``` +### PIN + +``` +7 RFID Lock user RFID code +was added, cleared, or +modified. +``` +### RID + +``` +8 Fingerprint Lock user fingerprint +was added, cleared, or +modified. +``` +### FGP + +``` +9 FingerVein Lock user finger-vein +information was added, +cleared, or modified. +``` +### FGP + +``` +10 Face Lock user face informa­ +tion was added, +cleared, or modified. +``` +### FACE + +``` +11 AliroCredentialIs­ +suerKey +``` +``` +An Aliro credential +issuer key credential +was added, cleared, or +modified. +``` +### ALIRO + +``` +12 AliroEvictableEnd­ +pointKey +``` +``` +An Aliro endpoint key +credential which can be +evicted credential was +added, cleared, or mod­ +ified. +``` +### ALIRO + +``` +13 AliroNonEvictableEnd +pointKey +``` +``` +An Aliro endpoint key +credential which can­ +not be evicted was +added, cleared, or mod­ +ified. +``` +### ALIRO + +**5.2.6.13. LockOperationTypeEnum Type** + +This data type is derived from enum8. + +``` +Page 382 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +This enumeration SHALL indicate the type of Lock operation performed. + +``` +Value Name Summary Conformance +0 Lock Lock operation M +1 Unlock Unlock operation M +2 NonAccessUserEvent Triggered by keypad +entry for user with +User Type set to Non +Access User +``` +### O + +``` +3 ForcedUserEvent Triggered by using a +user with UserType set +to Forced User +``` +### O + +``` +4 Unlatch Unlatch operation M +``` +**5.2.6.14. OperationErrorEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate the error cause of the Lock/Unlock operation performed. + +``` +Value Name Summary Conformance +0 Unspecified Lock/unlock error +caused by unknown or +unspecified source +``` +### O + +``` +1 InvalidCredential Lock/unlock error +caused by invalid PIN, +RFID, fingerprint or +other credential +``` +### USR + +``` +2 DisabledUserDenied Lock/unlock error +caused by disabled +USER or credential +``` +### M + +``` +3 Restricted Lock/unlock error +caused by schedule +restriction +``` +### WDSCH | YDSCH + +``` +4 InsufficientBattery Lock/unlock error +caused by insufficient +battery power left to +safely actuate the lock +``` +### O + +**5.2.6.15. OperatingModeEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate the lock operating mode. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 383 +``` + +``` +Value Name Summary Conformance +0 Normal M +1 Vacation O +2 Privacy O +3 NoRemoteLockUnlock M +4 Passage O +``` +The table below shows the operating mode and which interfaces are enabled, if supported, for each +mode. + +``` +Name Keypad* Remote* RFID* +Normal Y Y Y +Vacation N Y N +Privacy N N N +NoRemoteLockUnlock Y N Y +Passage N/A N/A N/A +``` +* Interface Operational: Yes, No or N/A + +### NOTE + +``` +For modes that disable the remote interface, the door lock SHALL respond to Lock, +Unlock, Toggle, and Unlock with Timeout commands with a response status Failure +and not take the action requested by those commands. The door lock SHALL NOT +disable the radio or otherwise unbind or leave the network. It SHALL still respond +to all other commands and requests. +``` +**5.2.6.15.1. Normal Value** + +The lock operates normally. All interfaces are enabled. + +**5.2.6.15.2. Vacation Value** + +Only remote interaction is enabled. The keypad SHALL only be operable by the master user. + +**5.2.6.15.3. Privacy Value** + +This mode is only possible if the door is locked. Manual unlocking changes the mode to Normal +operating mode. All external interaction with the door lock is disabled. This mode is intended to be +used so that users, presumably inside the property, will have control over the entrance. + +**5.2.6.15.4. NoRemoteLockUnlock Value** + +This mode only disables remote interaction with the lock. This does not apply to any remote propri­ +etary means of communication. It specifically applies to the Lock, Unlock, Toggle, and Unlock with +Timeout Commands. + +``` +Page 384 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.6.15.5. Passage Value** + +The lock is open or can be opened or closed at will without the use of a Keypad or other means of +user validation (e.g. a lock for a business during work hours). + +**5.2.6.16. OperationSourceEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate the source of the Lock/Unlock or user change operation per­ +formed. + +``` +Value Name Summary Conformance +0 Unspecified Lock/unlock operation +came from unspecified +source +``` +### O + +``` +1 Manual Lock/unlock operation +came from manual +operation (key, thumb­ +turn, handle, etc). +``` +### O + +``` +2 ProprietaryRemote Lock/unlock operation +came from proprietary +remote source (e.g. ven­ +dor app/cloud) +``` +### O + +``` +3 Keypad Lock/unlock operation +came from keypad +``` +### O + +``` +4 Auto Lock/unlock operation +came from lock auto­ +matically (e.g. relock +timer) +``` +### O + +``` +5 Button Lock/unlock operation +came from lock button +(e.g. one touch or but­ +ton) +``` +### O + +``` +6 Schedule Lock/unlock operation +came from lock due to +a schedule +``` +### HDSCH + +``` +7 Remote Lock/unlock operation +came from remote +node +``` +### M + +``` +8 RFID Lock/unlock operation +came from RFID card +``` +### RID + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 385 +``` + +``` +Value Name Summary Conformance +9 Biometric Lock/unlock operation +came from biometric +source (e.g. face, finger­ +print/fingervein) +``` +### [USR] + +``` +10 Aliro Lock/unlock operation +came from an interac­ +tion defined in [Aliro], +or user change opera­ +tion was a step-up cre­ +dential provisioning as +defined in [Aliro] +``` +### ALIRO + +**5.2.6.17. UserStatusEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate what the status is for a specific user ID. + +``` +Value Name Summary Conformance +0 Available The user ID is available M +1 OccupiedEnabled The user ID is occupied +and enabled +``` +### M + +``` +3 OccupiedDisabled The user ID is occupied +and disabled +``` +### O + +**5.2.6.18. UserTypeEnum Type** + +This data type is derived from enum8. + +This enumeration SHALL indicate what the type is for a specific user ID. + +``` +Value Name Summary Conformance +0 UnrestrictedUser The user ID type is +unrestricted +``` +### M + +``` +1 YearDayScheduleUser The user ID type is +schedule +``` +### O + +``` +2 WeekDaySched­ +uleUser +``` +``` +The user ID type is +schedule +``` +### O + +``` +3 ProgrammingUser The user ID type is pro­ +gramming +``` +### O + +``` +4 NonAccessUser The user ID type is non +access +``` +### O + +``` +Page 386 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +5 ForcedUser The user ID type is +forced +``` +### [USR] + +``` +6 DisposableUser The user ID type is dis­ +posable +``` +### [USR] + +``` +7 ExpiringUser The user ID type is +expiring +``` +### [USR] + +``` +8 ScheduleRestricte­ +dUser +``` +``` +The user ID type is +schedule restricted +``` +### WDSCH | YDSCH + +``` +9 RemoteOnlyUser The user ID type is +remote only +``` +### USR & COTA & PIN + +**5.2.6.18.1. UnrestrictedUser Value** + +This value SHALL indicate the user has access 24/7 provided proper PIN or RFID is supplied (e.g., +owner). + +**5.2.6.18.2. YearDayScheduleUser Value** + +This value SHALL indicate the user has the ability to open lock within a specific time period (e.g., +guest). + +When UserType is set to YearDayScheduleUser, user access SHALL be restricted as follows: + +- If no YearDaySchedules are set for the user, then access SHALL be denied +- If one or more YearDaySchedules are set, user access SHALL be granted if and only if the cur­ + rent time falls within at least one of the YearDaySchedules. If current time is not known, user + access SHALL NOT be granted. + +**5.2.6.18.3. WeekDayScheduleUser Value** + +This value SHALL indicate the user has the ability to open lock based on specific time period within +a reoccurring weekly schedule (e.g., cleaning worker). + +When UserType is set to WeekDayScheduleUser, user access SHALL be restricted as follows: + +- If no WeekDaySchedules are set for the user, then access SHALL be denied +- If one or more WeekDaySchedules are set, user access SHALL be granted if and only if the cur­ + rent time falls within at least one of the WeekDaySchedules. If current time is not known, user + access SHALL NOT be granted. + +**5.2.6.18.4. ProgrammingUser Value** + +This value SHALL indicate the user has the ability to both program and operate the door lock. This +user can manage the users and user schedules. In all other respects this user matches the unre­ +stricted (default) user. ProgrammingUser is the only user that can disable the user interface (key­ +pad, remote, etc...). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 387 +``` + +**5.2.6.18.5. NonAccessUser Value** + +This value SHALL indicate the user is recognized by the lock but does not have the ability to open +the lock. This user will only cause the lock to generate the appropriate event notification to any +bound devices. + +**5.2.6.18.6. ForcedUser Value** + +This value SHALL indicate the user has the ability to open lock but a ForcedUser LockOpera­ +tionType and ForcedUser silent alarm will be emitted to allow a notified Node to alert emergency +services or contacts on the user account when used. + +**5.2.6.18.7. DisposableUser Value** + +This value SHALL indicate the user has the ability to open lock once after which the lock SHALL +change the corresponding user record UserStatus value to OccupiedDisabled automatically. + +**5.2.6.18.8. ExpiringUser Value** + +This value SHALL indicate the user has the ability to open lock for ExpiringUserTimeout attribute +minutes after the first use of the PIN code, RFID code, Fingerprint, or other credential. After +ExpiringUserTimeout minutes the corresponding user record UserStatus value SHALL be set to +OccupiedDisabled automatically by the lock. The lock SHALL persist the timeout across reboots +such that the ExpiringUserTimeout is honored. + +**5.2.6.18.9. ScheduleRestrictedUser Value** + +This value SHALL indicate the user access is restricted by Week Day and/or Year Day schedule. + +When UserType is set to ScheduleRestrictedUser, user access SHALL be restricted as follows: + +- If no WeekDaySchedules and no YearDaySchedules are set for the user, then access SHALL be + denied +- If one or more WeekDaySchedules are set, but no YearDaySchedules are set for the user, then + user access SHALL be equivalent to the WeekDayScheduleUser UserType +- If one or more YearDaySchedules are set, but no WeekDaySchedules are set for the user, then + user access SHALL be equivalent to the YearDayScheduleUser UserType +- If one or WeekDaySchedules are set AND one or more YearDaySchedules are set, then user + access SHALL be granted if and only if the current time falls within at least one of the Week­ + DaySchedules AND the current time falls within at least one of the YearDaySchedules. + +**5.2.6.18.10. RemoteOnlyUser Value** + +This value SHALL indicate the user access and PIN code is restricted to remote lock/unlock com­ +mands only. This type of user might be useful for regular delivery services or voice assistant +unlocking operations to prevent a PIN code credential created for them from being used at the key­ +pad. The PIN code credential would only be provided over-the-air for the lock/unlock commands. + +``` +Page 388 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.6.19. LockStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 NotFullyLocked Lock state is not fully +locked +``` +### M + +``` +1 Locked Lock state is fully +locked +``` +### M + +``` +2 Unlocked Lock state is fully +unlocked +``` +### M + +``` +3 Unlatched Lock state is fully +unlocked and the latch +is pulled +``` +### O + +**5.2.6.20. LockTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 DeadBolt Physical lock type is +dead bolt +``` +### M + +``` +1 Magnetic Physical lock type is +magnetic +``` +### M + +``` +2 Other Physical lock type is +other +``` +### M + +``` +3 Mortise Physical lock type is +mortise +``` +### M + +``` +4 Rim Physical lock type is +rim +``` +### M + +``` +5 LatchBolt Physical lock type is +latch bolt +``` +### M + +``` +6 CylindricalLock Physical lock type is +cylindrical lock +``` +### M + +``` +7 TubularLock Physical lock type is +tubular lock +``` +### M + +``` +8 InterconnectedLock Physical lock type is +interconnected lock +``` +### M + +``` +9 DeadLatch Physical lock type is +dead latch +``` +### M + +``` +10 DoorFurniture Physical lock type is +door furniture +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 389 +``` + +``` +Value Name Summary Conformance +11 Eurocylinder Physical lock type is +euro cylinder +``` +### M + +**5.2.6.21. LEDSettingEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 NoLEDSignal Never use LED for sig­ +nalization +``` +### M + +``` +1 NoLEDSignalAccessAl­ +lowed +``` +``` +Use LED signalization +except for access +allowed events +``` +### M + +``` +2 LEDSignalAll Use LED signalization +for all events +``` +### M + +**5.2.6.22. SoundVolumeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Silent Silent Mode M +1 Low Low Volume M +2 High High Volume M +3 Medium Medium Volume M +``` +**5.2.6.23. EventTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Operation Event type is operation M +1 Programming Event type is program­ +ming +``` +### M + +``` +2 Alarm Event type is alarm M +``` +**5.2.6.24. CredentialStruct Type** + +This struct SHALL indicate the credential types and their corresponding indices (if any) for the +event or user record. + +``` +Page 390 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Creden­ +tialType +``` +``` +Credential­ +TypeEnum +``` +``` +all M +``` +``` +1 Creden­ +tialIndex +``` +``` +uint16 all 0 M +``` +**5.2.6.24.1. CredentialType Field** + +This field SHALL indicate the credential field used to authorize the lock operation. + +**5.2.6.24.2. CredentialIndex Field** + +This field SHALL indicate the index of the specific credential used to authorize the lock operation in +the list of credentials identified by CredentialType (e.g. PIN, RFID, etc.). This field SHALL be set to 0 +if CredentialType is ProgrammingPIN or does not correspond to a list that can be indexed into. + +**5.2.7. Status Codes** + +**5.2.7.1. StatusCodeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x02 DUPLICATE Entry would cause a +duplicate credential/ID. +``` +### M + +``` +0x03 OCCUPIED Entry would replace an +occupied slot. +``` +### M + +**5.2.7.2. DUPLICATE Code** + +The provided User ID, PIN or RFID code or other credential is a duplicate of an existing entry. + +**5.2.7.3. OCCUPIED Code** + +The provided User ID, Credential ID, or entry location is already occupied. The entry might need to +be deleted or a different ID or location chosen. + +**5.2.8. PIN/RFID Code Format** + +The PIN/RFID codes defined in this specification are all octet strings. + +All value in the PIN/RFID code SHALL be ASCII encoded regardless if the PIN/RFID codes are num­ +ber or characters. For example, code of “1, 2, 3, 4” SHALL be represented as 0x31, 0x32, 0x33, 0x34. + +**5.2.9. Attributes** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 391 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 LockState LockSta­ +teEnum +``` +``` +desc X P R V M +``` +``` +0x0001 LockType LockType­ +Enum +``` +``` +desc R V M +``` +``` +0x0002 Actua­ +torEn­ +abled +``` +``` +bool all R V M +``` +``` +0x0003 DoorState DoorSta­ +teEnum +``` +``` +desc X P R V DPS +``` +``` +0x0004 DoorOpen +Events +``` +``` +uint32 all RW VM [DPS] +``` +``` +0x0005 Door­ +ClosedE­ +vents +``` +``` +uint32 all RW VM [DPS] +``` +``` +0x0006 OpenPe­ +riod +``` +``` +uint16 all RW VM [DPS] +``` +``` +0x0011 Num­ +berOfTo­ +talUsersSu +pported +``` +``` +uint16 all F 0 R V USR +``` +``` +0x0012 Num­ +berOfPI­ +NUsersSu +pported +``` +``` +uint16 all F 0 R V PIN +``` +``` +0x0013 Num­ +berOfR­ +FIDUsersS +upported +``` +``` +uint16 all F 0 R V RID +``` +``` +0x0014 Num­ +berOfWee +k­ +DaySched­ +ulesSup­ +portedPe­ +rUser +``` +``` +uint8 max 0xFD F 0 R V WDSCH +``` +``` +0x0015 NumberO­ +fYear­ +DaySched­ +ulesSup­ +portedPe­ +rUser +``` +``` +uint8 max 0xFD F 0 R V YDSCH +``` +Page 392 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**ID Name Type Constraint Quality Default Access Confor­ +mance** + +0x0016 **Num­ +berOfHoli­ +daySched­ +ulesSup­ +ported** + +``` +uint8 max 0xFD F 0 R V HDSCH +``` +0x0017 **MaxPIN­ +Code­ +Length** + +``` +uint8 all F MS R V PIN +``` +0x0018 **MinPIN­ +Code­ +Length** + +``` +uint8 all F MS R V PIN +``` +0x0019 **MaxRFID­ +Code­ +Length** + +``` +uint8 all F MS R V RID +``` +0x001A **MinRFID­ +Code­ +Length** + +``` +uint8 all F MS R V RID +``` +0x001B **Creden­ +tialRu­ +lesSup­ +port** + +``` +Credential­ +Rules­ +Bitmap +``` +``` +all F 1 R V USR +``` +0x001C **Num­ +berOfCre­ +den­ +tialsSup­ +portedPe­ +rUser** + +``` +uint8 all F 0 R V USR +``` +0x0021 **Language** string max 3 P MS R[W] VM O + +0x0022 **LEDSet­ +tings** + +``` +LEDSettin­ +gEnum +``` +``` +all P 0 R[W] VM O +``` +0x0023 **AutoRe­ +lockTime** + +``` +uint32 all P MS R[W] VM O +``` +0x0024 **SoundVol­ +ume** + +``` +SoundVol­ +umeEnum +``` +``` +all P 0 R[W] VM O +``` +0x0025 **Operating­ +Mode** + +``` +Operating­ +Mod­ +eEnum +``` +``` +desc P 0 R[W] VM M +``` +0x0026 **Supporte­ +dOperat­ +ingModes** + +``` +Operating­ +Modes­ +Bitmap +``` +``` +all F 0xFFF6 R V M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 393 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0027 Default­ +Configura­ +tionRegis­ +ter +``` +``` +Configura­ +tionRegis­ +terBitmap +``` +``` +all P 0 R V O +``` +``` +0x0028 EnableLo­ +calPro­ +gramming +``` +``` +bool all P 1 R[W] VA O +``` +``` +0x0029 EnableOn +e­ +TouchLoc +king +``` +``` +bool all P 0 RW VM O +``` +``` +0x002A EnableIn­ +sideSta­ +tusLED +``` +``` +bool all P 0 RW VM O +``` +``` +0x002B EnablePri­ +vacyMode­ +Button +``` +``` +bool all P 0 RW VM O +``` +``` +0x002C LocalPro­ +gram­ +mingFea­ +tures +``` +``` +LocalPro­ +gram­ +mingFea­ +tures­ +Bitmap +``` +``` +all P 0 R[W] VA O +``` +``` +0x0030 Wrong­ +CodeEn­ +tryLimit +``` +``` +uint8 1 to 255 P MS R[W] VA PIN | RID +``` +``` +0x0031 UserCode­ +Tempo­ +raryDis­ +ableTime +``` +``` +uint8 1 to 255 P MS R[W] VA PIN | RID +``` +``` +0x0032 Send­ +PINOverT +heAir +``` +``` +bool all P 0 R[W] VA [!USR & +PIN] +``` +``` +0x0033 Require­ +PINforRe­ +moteOper­ +ation +``` +``` +bool all P 0 R[W] VA COTA & +PIN +``` +``` +0x0034 Secu­ +rityLevel +``` +### 0 R V D + +``` +0x0035 ExpiringU +serTime­ +out +``` +``` +uint16 1 to 2880 P MS R[W] VA [USR] +``` +Page 394 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**ID Name Type Constraint Quality Default Access Confor­ +mance** + +0x0040 **Alarm­ +Mask** + +``` +Alarm­ +MaskBitma +p +``` +``` +all P 0xFFFF RW VA O +``` +0x0080 **AliroRead­ +erVerifica­ +tionKey** + +``` +octstr 65 X null R A ALIRO +``` +0x0081 **AliroRead­ +erGroupI­ +dentifier** + +``` +octstr 16 X null R A ALIRO +``` +0x0082 **AliroRead­ +erGroup­ +SubIdenti­ +fier** + +``` +octstr 16 F R A ALIRO +``` +0x0083 **AliroExpe­ +dited­ +Transac­ +tionSup­ +ported­ +Proto­ +colVer­ +sions** + +``` +list[octstr] max 16[2] F empty R A ALIRO +``` +0x0084 **AliroGrou +pResolv­ +ingKey** + +``` +octstr 16 X null R A ALBU +``` +0x0085 **AliroSup­ +ported­ +BLEUWBP +roto­ +colVer­ +sions** + +``` +list[octstr] max 16[2] F empty R A ALBU +``` +0x0086 **AliroB­ +LEAdver­ +tisingVer­ +sion** + +``` +uint8 all F 0 R A ALBU +``` +0x0087 **NumberO­ +fAliroCre­ +dentialIs­ +suerKeysS +upported** + +``` +uint16 all F 0 R V ALIRO +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 395 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0088 NumberO­ +fAliroEnd­ +pointKeys +Supported +``` +``` +uint16 all F 0 R V ALIRO +``` +**5.2.9.1. LockState Attribute** + +This attribute may be NULL if the lock hardware does not currently know the status of the locking +mechanism. For example, a lock may not know the LockState status after a power cycle until the +first lock actuation is completed. + +The Not Fully Locked value is used by a lock to indicate that the state of the lock is somewhere +between Locked and Unlocked so it is only partially secured. For example, a deadbolt could be par­ +tially extended and not in a dead latched state. + +**5.2.9.2. LockType Attribute** + +This attribute SHALL indicate the type of door lock as defined in LockTypeEnum. + +**5.2.9.3. ActuatorEnabled Attribute** + +This attribute SHALL indicate if the lock is currently able to (Enabled) or not able to (Disabled) +process remote Lock, Unlock, or Unlock with Timeout commands. + +This attribute has the following possible values: + +``` +Boolean Value Summary +0 Disabled +1 Enabled +``` +**5.2.9.4. DoorState Attribute** + +This attribute SHALL indicate the current door state as defined in DoorStateEnum. + +This attribute SHALL be null only if an internal error prevents the retrieval of the current door +state. + +**5.2.9.5. DoorOpenEvents Attribute** + +This attribute SHALL hold the number of door open events that have occurred since it was last +zeroed. + +**5.2.9.6. DoorClosedEvents Attribute** + +This attribute SHALL hold the number of door closed events that have occurred since it was last +zeroed. + +``` +Page 396 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.9.7. OpenPeriod Attribute** + +This attribute SHALL hold the number of minutes the door has been open since the last time it tran­ +sitioned from closed to open. + +**5.2.9.8. NumberOfTotalUsersSupported Attribute** + +This attribute SHALL indicate the number of total users supported by the lock. + +**5.2.9.9. NumberOfPINUsersSupported Attribute** + +This attribute SHALL indicate the number of PIN users supported. + +**5.2.9.10. NumberOfRFIDUsersSupported Attribute** + +This attribute SHALL indicate the number of RFID users supported. + +**5.2.9.11. NumberOfWeekDaySchedulesSupportedPerUser Attribute** + +This attribute SHALL indicate the number of configurable week day schedule supported per user. + +**5.2.9.12. NumberOfYearDaySchedulesSupportedPerUser Attribute** + +This attribute SHALL indicate the number of configurable year day schedule supported per user. + +**5.2.9.13. NumberOfHolidaySchedulesSupported Attribute** + +This attribute SHALL indicate the number of holiday schedules supported for the entire door lock +device. + +**5.2.9.14. MaxPINCodeLength Attribute** + +This attribute SHALL indicate the maximum length in bytes of a PIN Code on this device. + +**5.2.9.15. MinPINCodeLength Attribute** + +This attribute SHALL indicate the minimum length in bytes of a PIN Code on this device. + +**5.2.9.16. MaxRFIDCodeLength Attribute** + +This attribute SHALL indicate the maximum length in bytes of a RFID Code on this device. The +value depends on the RFID code range specified by the manufacturer, if media anti-collision identi­ +fiers (UID) are used as RFID code, a value of 20 (equals 10 Byte ISO 14443A UID) is recommended. + +**5.2.9.17. MinRFIDCodeLength Attribute** + +This attribute SHALL indicate the minimum length in bytes of a RFID Code on this device. The value +depends on the RFID code range specified by the manufacturer, if media anti-collision identifiers +(UID) are used as RFID code, a value of 8 (equals 4 Byte ISO 14443A UID) is recommended. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 397 +``` + +**5.2.9.18. CredentialRulesSupport Attribute** + +This attribute SHALL contain a bitmap with the bits set for the values of CredentialRuleEnum sup­ +ported on this device. + +**5.2.9.19. NumberOfCredentialsSupportedPerUser Attribute** + +This attribute SHALL indicate the number of credentials that could be assigned for each user. + +Depending on the value of NumberOfRFIDUsersSupported and NumberOfPINUsersSupported it +may not be possible to assign that number of credentials for a user. + +For example, if the device supports only PIN and RFID credential types, NumberOfCredentialsSup­ +portedPerUser is set to 10, NumberOfPINUsersSupported is set to 5 and NumberOfRFIDUsersSup­ +ported is set to 3, it will not be possible to actually assign 10 credentials for a user because maxi­ +mum number of credentials in the database is 8. + +**5.2.9.20. Language Attribute** + +This attribute SHALL indicate the language for the on-screen or audible user interface using a 2- +byte language code from ISO-639-1. + +**5.2.9.21. LEDSettings Attribute** + +This attribute SHALL indicate the settings for the LED support, as defined by LEDSettingEnum. + +**5.2.9.22. AutoRelockTime Attribute** + +This attribute SHALL indicate the number of seconds to wait after unlocking a lock before it auto­ +matically locks again. 0=disabled. If set, unlock operations from any source will be timed. For one +time unlock with timeout use the specific command. + +**5.2.9.23. SoundVolume Attribute** + +This attribute SHALL indicate the sound volume on a door lock as defined by SoundVolumeEnum. + +**5.2.9.24. OperatingMode Attribute** + +This attribute SHALL indicate the current operating mode of the lock as defined in OperatingMod­ +eEnum. + +**5.2.9.25. SupportedOperatingModes Attribute** + +This attribute SHALL contain a bitmap with all operating bits of the OperatingMode attribute sup­ +ported by the lock. All operating modes NOT supported by a lock SHALL be set to one. The value of +the OperatingMode enumeration defines the related bit to be set. + +**5.2.9.26. DefaultConfigurationRegister Attribute** + +This attribute SHALL represent the default configurations as they are physically set on the device +(example: hardware dip switch setting, etc...) and represents the default setting for some of the + +``` +Page 398 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +attributes within this cluster (for example: LED, Auto Lock, Sound Volume, and Operating Mode +attributes). + +This is a read-only attribute and is intended to allow clients to determine what changes MAY need +to be made without having to query all the included attributes. It MAY be beneficial for the clients +to know what the device’s original settings were in the event that the device needs to be restored to +factory default settings. + +If the Client device would like to query and modify the door lock server’s operating settings, it +SHOULD send read and write attribute requests to the specific attributes. + +For example, the Sound Volume attribute default value is Silent Mode. However, it is possible that +the current Sound Volume is High Volume. Therefore, if the client wants to query/modify the cur­ +rent Sound Volume setting on the server, the client SHOULD read/write to the Sound Volume +attribute. + +**5.2.9.26.1. LocalProgramming Bit** + +This bit SHALL indicate the default value of the EnableLocalProgramming attribute. + +**5.2.9.26.2. KeypadInterface Bit** + +This bit SHALL indicate the default state of the keypad interface. + +**5.2.9.26.3. RemoteInterface Bit** + +This bit SHALL indicate the default state of the remote interface. + +**5.2.9.26.4. SoundVolume Bit** + +This bit SHALL indicate the default value of SoundVolume attribute. + +**5.2.9.26.5. AutoRelockTime Bit** + +This bit SHALL indicate the default value of AutoRelockTime attribute. + +**5.2.9.26.6. LEDSettings Bit** + +This bit SHALL indicate the default value of LEDSettings attribute. + +**5.2.9.27. EnableLocalProgramming Attribute** + +This attribute SHALL enable/disable local programming on the door lock of certain features (see +LocalProgrammingFeatures attribute). If this value is set to TRUE then local programming is +enabled on the door lock for all features. If it is set to FALSE then local programming is disabled on +the door lock for those features whose bit is set to 0 in the LocalProgrammingFeatures attribute. +Local programming SHALL be enabled by default. + +**5.2.9.28. EnableOneTouchLocking Attribute** + +This attribute SHALL enable/disable the ability to lock the door lock with a single touch on the door +lock. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 399 +``` + +**5.2.9.29. EnableInsideStatusLED Attribute** + +This attribute SHALL enable/disable an inside LED that allows the user to see at a glance if the door +is locked. + +**5.2.9.30. EnablePrivacyModeButton Attribute** + +This attribute SHALL enable/disable a button inside the door that is used to put the lock into pri­ +vacy mode. When the lock is in privacy mode it cannot be manipulated from the outside. + +**5.2.9.31. LocalProgrammingFeatures Attribute** + +This attribute SHALL indicate the local programming features that will be disabled when EnableLo­ +calProgramming attribute is set to False. If a door lock doesn’t support disabling one aspect of local +programming it SHALL return CONSTRAINT_ERROR during a write operation of this attribute. If +the EnableLocalProgramming attribute is set to True then all local programming features SHALL be +enabled regardless of the bits set to 0 in this attribute. + +The features that can be disabled from local programming are defined in LocalProgrammingFea­ +turesBitmap. + +**5.2.9.32. WrongCodeEntryLimit Attribute** + +This attribute SHALL indicate the number of incorrect Pin codes or RFID presentment attempts a +user is allowed to enter before the lock will enter a lockout state. The value of this attribute is com­ +pared to all failing forms of credential presentation, including Pin codes used in an Unlock Com­ +mand when RequirePINforRemoteOperation is set to true. Valid range is 1-255 incorrect attempts. +The lockout state will be for the duration of UserCodeTemporaryDisableTime. If the attribute +accepts writes and an attempt to write the value 0 is made, the device SHALL respond with CON­ +STRAINT_ERROR. + +The lock MAY reset the counter used to track incorrect credential presentations as required by +internal logic, environmental events, or other reasons. The lock SHALL reset the counter if a valid +credential is presented. + +**5.2.9.33. UserCodeTemporaryDisableTime Attribute** + +This attribute SHALL indicate the number of seconds that the lock shuts down following wrong +code entry. Valid range is 1-255 seconds. Device can shut down to lock user out for specified amount +of time. (Makes it difficult to try and guess a PIN for the device.) If the attribute accepts writes and +an attempt to write the attribute to 0 is made, the device SHALL respond with CONSTRAINT_ERROR. + +**5.2.9.34. SendPINOverTheAir Attribute** + +This attribute SHALL indicate the door locks ability to send PINs over the air. If the attribute is True +it is ok for the door lock server to send PINs over the air. This attribute determines the behavior of +the server’s TX operation. If it is false, then it is not ok for the device to send PIN in any messages +over the air. + +The PIN field within any door lock cluster message SHALL keep the first octet unchanged and + +``` +Page 400 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +masks the actual code by replacing with 0xFF. For example (PIN "1234" ): If the attribute value is +True, 0x04 0x31 0x32 0x33 0x34 SHALL be used in the PIN field in any door lock cluster message +payload. If the attribute value is False, 0x04 0xFF 0xFF 0xFF 0xFF SHALL be used. + +**5.2.9.35. RequirePINForRemoteOperation Attribute** + +This attribute SHALL indicate if the door lock requires an optional PIN. If this attribute is set to +True, the door lock server requires that an optional PINs be included in the payload of remote lock +operation events like Lock, Unlock, Unlock with Timeout and Toggle in order to function. + +**5.2.9.36. ExpiringUserTimeout Attribute** + +This attribute SHALL indicate the number of minutes a PIN, RFID, Fingerprint, or other credential +associated with a user of type ExpiringUser SHALL remain valid after its first use before expiring. +When the credential expires the UserStatus for the corresponding user record SHALL be set to +OccupiedDisabled. + +**5.2.9.37. AlarmMask Attribute** + +This attribute is only supported if the Alarms cluster is on the same endpoint. The alarm mask is +used to turn on/off alarms for particular functions. Alarms for an alarm group are enabled if the +associated alarm mask bit is set. Each bit represents a group of alarms. Entire alarm groups can be +turned on or off by setting or clearing the associated bit in the alarm mask. + +This mask DOES NOT apply to the Events mechanism of this cluster. + +``` +Alarm Code Value AlarmMaskBitmap Bit +0 0 +1 1 +2 2 +3 3 +4 4 +5 5 +6 6 +``` +**5.2.9.38. AliroReaderVerificationKey Attribute** + +This attribute SHALL indicate the verification key component of the Reader’s key pair as defined in +[Aliro]. The value, if not null, SHALL be an uncompressed elliptic curve public key as defined in sec­ +tion 2.3.3 of SEC 1. + +This attribute SHALL be null if no Reader key pair has been configured on the lock. See SetAliroRe­ +aderConfig. + +**5.2.9.39. AliroReaderGroupIdentifier Attribute** + +This attribute SHALL indicate the reader_group_identifier as defined in [Aliro]. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 401 +``` + +This attribute SHALL be null if no reader_group_identifier has been configured on the lock. See +SetAliroReaderConfig. + +**5.2.9.40. AliroReaderGroupSubIdentifier Attribute** + +This attribute SHALL indicate the reader_group_sub_identifier as defined in [Aliro]. + +**5.2.9.41. AliroExpeditedTransactionSupportedProtocolVersions Attribute** + +This attribute SHALL indicate the list of protocol versions supported for expedited transactions as +defined in [Aliro]. + +**5.2.9.42. AliroGroupResolvingKey Attribute** + +This attribute SHALL indicate the Group Resolving Key as defined in [Aliro]. + +This attribute SHALL be null if no group resolving key has been configured on the lock. See +SetAliroReaderConfig. + +**5.2.9.43. AliroSupportedBLEUWBProtocolVersions Attribute** + +This attribute SHALL indicate the list of protocol versions supported for the Bluetooth LE + UWB +Access Control Flow as defined in [Aliro]. + +**5.2.9.44. AliroBLEAdvertisingVersion Attribute** + +This attribute SHALL indicate the version of the Bluetooth LE advertisement as defined in [Aliro]. + +**5.2.9.45. NumberOfAliroCredentialIssuerKeysSupported** + +This attribute SHALL indicate the maximum number of AliroCredentialIssuerKey credentials that +can be stored on the lock. + +**5.2.9.46. NumberOfAliroEndpointKeysSupported** + +This attribute SHALL indicate the maximum number of endpoint key credentials that can be stored +on the lock. This limit applies to the sum of the number of AliroEvictableEndpointKey credentials +and the number of AliroNonEvictableEndpointKey credentials. + +### NOTE + +``` +The credential indices used for these two credential types are independent of each +other, similar to all other credential types. As long as NumberOfAliroEnd­ +pointKeysSupported is at least 2 a client could add a credential of type AliroE­ +victableEndpointKey at any index from 1 to NumberOfAliroEndpointKeysSupported +and also add a credential of type AliroNonEvictableEndpointKey at the same index, +and both credentials would exist on the server. +``` +**5.2.10. Commands** + +``` +Page 402 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**ID Name Direction Response Access Conformance** + +0x00 **LockDoor** client ⇒ server Y O T M + +0x01 **UnlockDoor** client ⇒ server Y O T M + +0x02 **Toggle** client ⇒ server Y O T X + +0x03 **UnlockWith­ +Timeout** + +``` +client ⇒ server Y O T O +``` +0x05 **SetPINCode** client ⇒ server Y A T !USR & PIN + +0x06 **GetPINCode** client ⇒ server GetPINCodeRe­ +sponse + +### A !USR & PIN + +0x06 **GetPIN­ +CodeResponse** + +``` +client ⇐ server N !USR & PIN +``` +0x07 **ClearPINCode** client ⇒ server Y A T !USR & PIN + +0x08 **ClearAllPIN­ +Codes** + +``` +client ⇒ server Y A T !USR & PIN +``` +0x09 **SetUserStatus** client ⇒ server Y A !USR & (PIN | +RID | FGP) + +0x0A **GetUserStatus** client ⇒ server GetUserStatus­ +Response + +### A !USR & (PIN | + +### RID | FGP) + +0x0A **GetUserSta­ +tusResponse** + +``` +client ⇐ server N !USR +``` +0x0B **SetWeek­ +DaySchedule** + +``` +client ⇒ server Y A WDSCH +``` +0x0C **GetWeek­ +DaySchedule** + +``` +client ⇒ server GetWeek­ +DaySched­ +uleResponse +``` +### A WDSCH + +0x0C **GetWeek­ +DaySched­ +uleResponse** + +``` +client ⇐ server N WDSCH +``` +0x0D **ClearWeek­ +DaySchedule** + +``` +client ⇒ server Y A WDSCH +``` +0x0E **SetYear­ +DaySchedule** + +``` +client ⇒ server Y A YDSCH +``` +0x0F **GetYear­ +DaySchedule** + +``` +client ⇒ server GetYear­ +DaySched­ +uleResponse +``` +### A YDSCH + +0x0F **GetYear­ +DaySched­ +uleResponse** + +``` +client ⇐ server N YDSCH +``` +0x10 **ClearYear­ +DaySchedule** + +``` +client ⇒ server Y A YDSCH +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 403 +``` + +``` +ID Name Direction Response Access Conformance +0x11 SetHoli­ +daySchedule +``` +``` +client ⇒ server Y A HDSCH +``` +``` +0x12 GetHoli­ +daySchedule +``` +``` +client ⇒ server GetHoli­ +daySched­ +uleResponse +``` +### A HDSCH + +``` +0x12 GetHoli­ +daySched­ +uleResponse +``` +``` +client ⇐ server N HDSCH +``` +``` +0x13 ClearHoli­ +daySchedule +``` +``` +client ⇒ server Y A HDSCH +``` +``` +0x14 SetUserType client ⇒ server Y A !USR & (PIN | +RID | FGP) +0x15 GetUserType client ⇒ server GetUserTypeR­ +esponse +``` +### A !USR & (PIN | + +### RID | FGP) + +``` +0x15 GetUserType­ +Response +``` +``` +client ⇐ server N !USR +``` +``` +0x16 SetRFIDCode client ⇒ server Y A T !USR & RID +0x17 GetRFIDCode client ⇒ server GetRFID­ +CodeResponse +``` +### A !USR & RID + +``` +0x17 GetRFID­ +CodeResponse +``` +``` +client ⇐ server N !USR & RID +``` +``` +0x18 ClearRFID­ +Code +``` +``` +client ⇒ server Y A T !USR & RID +``` +``` +0x19 ClearAllRFID­ +Codes +``` +``` +client ⇒ server Y A T !USR & RID +``` +``` +0x1A SetUser client ⇒ server Y A T USR +0x1B GetUser client ⇒ server GetUserRe­ +sponse +``` +### A USR + +``` +0x1C GetUserRe­ +sponse +``` +``` +client ⇐ server N USR +``` +``` +0x1D ClearUser client ⇒ server Y A T USR +0x22 SetCredential client ⇒ server SetCredential­ +Response +``` +### A T USR + +``` +0x23 SetCredential­ +Response +``` +``` +client ⇐ server N USR +``` +``` +0x24 GetCredential­ +Status +``` +``` +client ⇒ server GetCredential­ +StatusResponse +``` +### A USR + +Page 404 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +ID Name Direction Response Access Conformance +0x25 GetCredential­ +StatusRe­ +sponse +``` +``` +client ⇐ server N USR +``` +``` +0x26 ClearCreden­ +tial +``` +``` +client ⇒ server Y A T USR +``` +``` +0x27 UnboltDoor client ⇒ server Y O T UBOLT +0x28 SetAliroRead­ +erConfig +``` +``` +client ⇒ server Y A T ALIRO +``` +``` +0x29 ClearAliroRe­ +aderConfig +``` +``` +client ⇒ server Y A T ALIRO +``` +**5.2.10.1. LockDoor Command** + +This command causes the lock device to lock the door. This command includes an optional code for +the lock. The door lock MAY require a PIN depending on the value of the RequirePINForRemoteOp­ +eration attribute. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PINCode octstr [COTA & PIN] +``` +**5.2.10.1.1. PINCode Field** + +If the RequirePINforRemoteOperation attribute is True then PINCode field SHALL be provided and +the door lock SHALL NOT grant access if it is not provided. + +If the PINCode field is provided, the door lock SHALL verify PINCode before granting access regard­ +less of the value of RequirePINForRemoteOperation attribute. + +When the PINCode field is provided an invalid PIN will count towards the WrongCodeEntryLimit +and the UserCodeTemporaryDisableTime will be triggered if the WrongCodeEntryLimit is exceeded. +The lock SHALL ignore any attempts to lock/unlock the door until the UserCodeTemporaryDisable­ +Time expires. + +**5.2.10.2. UnlockDoor Command** + +This command causes the lock device to unlock the door. This command includes an optional code +for the lock. The door lock MAY require a code depending on the value of the RequirePINForRemo­ +teOperation attribute. + +``` +NOTE If the attribute AutoRelockTime is supported the lock will transition to the locked +state when the auto relock time has expired. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 405 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PINCode octstr [COTA & PIN] +``` +**5.2.10.2.1. PINCode Field** + +See PINCode field. + +**5.2.10.3. UnlockWithTimeout Command** + +This command causes the lock device to unlock the door with a timeout parameter. After the time +in seconds specified in the timeout field, the lock device will relock itself automatically. This time­ +out parameter is only temporary for this message transition and overrides the default relock time +as specified in the AutoRelockTime attribute. If the door lock device is not capable of or does not +want to support temporary Relock Timeout, it SHOULD NOT support this optional command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Timeout uint16 M +1 PINCode octstr [COTA & PIN] +``` +**5.2.10.3.1. Timeout Field** + +This field SHALL indicate the timeout in seconds to wait before relocking the door lock. This value +is independent of the AutoRelockTime attribute value. + +**5.2.10.3.2. PINCode Field** + +See PINCode field. + +**5.2.10.4. SetPINCode Command** + +Set a PIN Code into the lock. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +1 UserStatus UserSta­ +tusEnum +``` +``` +desc X OccupiedEn­ +abled +``` +### M + +``` +2 UserType UserType­ +Enum +``` +``` +all X Unrestricte­ +dUser +``` +### M + +``` +3 PIN octstr M +``` +Return status is a global status code or a cluster-specific status code from the Status Codes table and +SHALL be one of the following values: + +``` +Page 406 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Name Summary +SUCCESS Setting PIN code was successful. +FAILURE Setting PIN code failed. +CONSTRAINT_ERROR Setting PIN code failed because User ID +requested was out of range. +DUPLICATE Setting PIN code failed because it would create a +duplicate PIN code. +``` +**5.2.10.4.1. UserID Field** + +This field SHALL indicate the user ID. The value of the UserID field SHALL be between 0 and the +value of the NumberOfPINUsersSupported attribute. + +**5.2.10.4.2. UserStatus Field** + +This field SHALL indicate the user status. Only the values 1 (Occupied/Enabled) and 3 (Occu­ +pied/Disabled) are allowed for UserStatus. + +**5.2.10.5. GetPINCode Command** + +Retrieve a PIN Code. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +``` +**5.2.10.5.1. UserID Field** + +This field SHALL indicate the user ID. The value of the UserID field SHALL be between 0 and the +value of the NumberOfPINUsersSupported attribute. + +**5.2.10.6. GetPINCodeResponse Command** + +Returns the PIN for the specified user ID. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +1 UserStatus UserSta­ +tusEnum +``` +``` +desc X Available M +``` +``` +2 UserType UserType­ +Enum +``` +``` +desc X M +``` +``` +3 PINCode octstr X empty M +``` +If the requested UserID is valid and the Code doesn’t exist, Get RFID Code Response SHALL have the +following format: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 407 +``` + +UserID = requested User ID + +UserStatus = 0 (Available) + +UserType = Null (Not supported) + +PINCode = 0 (zero length) + +If the requested UserID is invalid, send Default Response with an error status. The error status +SHALL be equal to CONSTRAINT_ERROR when User_ID is less than the max number of users sup­ +ported, and NOT_FOUND if greater than or equal to the max number of users supported. + +**5.2.10.7. ClearPINCode Command** + +Clear a PIN code or all PIN codes. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PINSlotIn­ +dex +``` +``` +uint16 1 to Num­ +berOfPI­ +NUsersSup­ +ported, +0xFFFE +``` +### M + +For each PIN Code cleared whose user doesn’t have a RFID Code or other credential type, then cor­ +responding user record’s UserStatus value SHALL be set to Available, and UserType value SHALL be +set to UnrestrictedUser and all schedules SHALL be cleared. + +**5.2.10.7.1. PINSlotIndex Field** + +This field SHALL specify a valid PIN code slot index or 0xFFFE to indicate all PIN code slots SHALL +be cleared. + +**5.2.10.8. ClearAllPINCodes Command** + +Clear out all PINs on the lock. + +### NOTE + +``` +On the server, the clear all PIN codes command SHOULD have the same effect as the +ClearPINCode command with respect to the setting of user status, user type and +schedules. +``` +**5.2.10.9. SetUserStatus Command** + +Set the status of a user ID. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +``` +``` +Page 408 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 UserStatus UserSta­ +tusEnum +``` +``` +desc M +``` +**5.2.10.9.1. UserID Field** + +This field SHALL indicate the user ID. The value of the UserID field SHALL be between 0 and the +value of the NumberOfPINUsersSupported attribute. + +**5.2.10.9.2. UserStatus Field** + +UserStatus value of Available is not allowed. In order to clear a user id, the ClearUser Command +SHALL be used. For user status value please refer to UserStatusEnum. + +**5.2.10.10. GetUserStatus Command** + +Get the status of a user. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +``` +**5.2.10.10.1. UserID Field** + +This field SHALL indicate the user ID. The value of the UserID field SHALL be between 0 and the +value of the NumberOfPINUsersSupported attribute. + +**5.2.10.11. GetUserStatusResponse Command** + +Returns the user status for the specified user ID. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +1 UserStatus UserSta­ +tusEnum +``` +``` +all M +``` +**5.2.10.11.1. UserID Field** + +This field SHALL indicate the user ID provided in the request. + +**5.2.10.11.2. UserStatus Field** + +This field SHALL indicate the current status of the requested user ID. + +**5.2.10.12. SetWeekDaySchedule Command** + +Set a weekly repeating schedule for a specified user. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 409 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 WeekDayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfWeek­ +DaySchedu­ +lesSupport­ +edPerUser +``` +### M + +``` +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +``` +2 DaysMask DaysMaskBit +map +``` +### M + +``` +3 StartHour uint8 max 23 M +4 StartMinute uint8 max 59 M +5 EndHour uint8 max 23 M +6 EndMinute uint8 max 59 M +``` +The associated UserType MAY be changed to ScheduleRestrictedUser by the lock when a Week Day +schedule is set. + +Return status SHALL be one of the following values: + +``` +Name Summary +SUCCESS Setting Week Day schedule was successful. +FAILURE Some unexpected internal error occurred setting +Week Day schedule. +INVALID_COMMAND One or more fields violates constraints or is +invalid. +``` +**5.2.10.12.1. WeekDayIndex Field** + +This field SHALL indicate the index of the Week Day schedule. + +**5.2.10.12.2. UserIndex Field** + +This field SHALL indicate the user ID. + +**5.2.10.12.3. DaysMask Field** + +This field SHALL indicate which week days the schedule is active. + +**5.2.10.12.4. StartHour Field** + +This field SHALL indicate the starting hour for the Week Day schedule. + +``` +Page 410 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.10.12.5. StartMinute Field** + +This field SHALL indicate the starting minute for the Week Day schedule. + +**5.2.10.12.6. EndHour Field** + +This field SHALL indicate the ending hour for the Week Day schedule. EndHour SHALL be equal to +or greater than StartHour. + +**5.2.10.12.7. EndMinute Field** + +This field SHALL indicate the ending minute for the Week Day schedule. If EndHour is equal to Star­ +tHour then EndMinute SHALL be greater than StartMinute. + +If the EndHour is equal to 23 and the EndMinute is equal to 59 the Lock SHALL grant access to the +user up until 23:59:59. + +**5.2.10.13. GetWeekDaySchedule Command** + +Retrieve the specific weekly schedule for the specific user. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 WeekDayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfWeek­ +DaySchedu­ +lesSupport­ +edPerUser +``` +### M + +``` +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +**5.2.10.14. GetWeekDayScheduleResponse Command** + +Returns the weekly repeating schedule data for the specified schedule index. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 WeekDayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfWeek­ +DaySchedu­ +lesSupport­ +edPerUser +``` +### M + +``` +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 411 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +2 Status enum8 desc SUCCESS M +3 DaysMask DaysMaskBit +map +``` +### O + +``` +4 StartHour uint8 max 23 O +5 StartMinute uint8 max 59 O +6 EndHour uint8 max 23 O +7 EndMinute uint8 max 59 O +``` +**5.2.10.14.1. WeekDayIndex Field** + +This field SHALL indicate the index of the Week Day schedule. + +**5.2.10.14.2. UserIndex Field** + +This field SHALL indicate the user ID. + +**5.2.10.14.3. Status Field** + +Status SHALL be one of the following values: + +- SUCCESS if both WeekDayIndex and UserIndex are valid and there is a corresponding schedule + entry. +- INVALID_COMMAND if either WeekDayIndex and/or UserIndex values are not within valid + range +- NOT_FOUND if no corresponding schedule entry found for WeekDayIndex. +- NOT_FOUND if no corresponding user entry found for UserIndex. + +If this field is SUCCESS, the optional fields for this command SHALL be present. For other (error) +status values, only the fields up to the status field SHALL be present. + +**5.2.10.14.4. StartHour Field** + +This field SHALL indicate the starting hour for the Week Day schedule. + +**5.2.10.14.5. StartMinute Field** + +This field SHALL indicate the starting minute for the Week Day schedule. + +**5.2.10.14.6. EndHour Field** + +This field SHALL indicate the ending hour for the Week Day schedule. EndHour SHALL be equal to +or greater than StartHour. + +``` +Page 412 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.10.14.7. EndMinute Field** + +This field SHALL indicate the ending minute for the Week Day schedule. If EndHour is equal to Star­ +tHour then EndMinute SHALL be greater than StartMinute. + +**5.2.10.15. ClearWeekDaySchedule Command** + +Clear the specific weekly schedule or all weekly schedules for the specific user. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 WeekDayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfWeek­ +DaySchedu­ +lesSupport­ +edPerUser, +0xFE +``` +### M + +``` +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +Return status SHALL be one of the following values: + +``` +Name Summary +SUCCESS Clearing the requested WeekDaySchedule was +successful. +FAILURE Some unexpected internal error occurred clear­ +ing Week Day schedule. +INVALID_COMMAND One or more fields violates constraints or is +invalid. +``` +**5.2.10.15.1. WeekDayIndex Field** + +This field SHALL indicate the Week Day schedule index to clear or 0xFE to clear all Week Day +schedules for the specified user. + +**5.2.10.15.2. UserIndex Field** + +This field SHALL indicate the user ID. + +**5.2.10.16. SetYearDaySchedule Command** + +Set a time-specific schedule ID for a specified user. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 413 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 YearDayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfYear­ +DaySchedu­ +lesSupport­ +edPerUser +``` +### M + +``` +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +``` +2 LocalStart­ +Time +``` +``` +epoch-s all M +``` +``` +3 LocalEnd­ +Time +``` +``` +epoch-s all M +``` +The associated UserType MAY be changed to ScheduleRestrictedUser by the lock when a Year Day +schedule is set. + +Return status SHALL be one of the following values: + +``` +Name Summary +SUCCESS Setting Year Day schedule was successful. +FAILURE Some unexpected internal error occurred setting +Year Day schedule. +INVALID_COMMAND One or more fields violates constraints or is +invalid. +``` +**5.2.10.16.1. YearDayIndex Field** + +This field SHALL indicate the index of the Year Day schedule. + +**5.2.10.16.2. UserIndex Field** + +This field SHALL indicate the user ID. + +**5.2.10.16.3. LocalStartTime Field** + +This field SHALL indicate the starting time for the Year Day schedule in Epoch Time in Seconds with +local time offset based on the local timezone and DST offset on the day represented by the value. + +**5.2.10.16.4. LocalEndTime Field** + +This field SHALL indicate the ending time for the Year Day schedule in Epoch Time in Seconds with +local time offset based on the local timezone and DST offset on the day represented by the value. +LocalEndTime SHALL be greater than LocalStartTime. + +``` +Page 414 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.10.17. GetYearDaySchedule Command** + +Retrieve the specific year day schedule for the specific schedule and user indexes. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 YearDayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfYear­ +DaySchedu­ +lesSupport­ +edPerUser +``` +### M + +``` +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +**5.2.10.18. GetYearDayScheduleResponse Command** + +Returns the year day schedule data for the specified schedule and user indexes. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 YearDayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfYear­ +DaySchedu­ +lesSupport­ +edPerUser +``` +### M + +``` +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +``` +2 Status enum8 desc SUCCESS M +2 LocalStart­ +Time +``` +``` +epoch-s all O +``` +``` +3 LocalEnd­ +Time +``` +``` +epoch-s all O +``` +**5.2.10.18.1. YearDayIndex Field** + +This field SHALL indicate the index of the Year Day schedule. + +**5.2.10.18.2. UserIndex Field** + +This field SHALL indicate the user ID. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 415 +``` + +**5.2.10.18.3. Status Field** + +Status SHALL be one of the following values: + +- SUCCESS if both YearDayIndex and UserIndex are valid and there is a corresponding schedule + entry. +- INVALID_COMMAND if either YearDayIndex and/or UserIndex values are not within valid range +- NOT_FOUND if no corresponding schedule entry found for YearDayIndex. +- NOT_FOUND if no corresponding user entry found for UserIndex. + +If this field is SUCCESS, the optional fields for this command SHALL be present. For other (error) +status values, only the fields up to the status field SHALL be present. + +**5.2.10.18.4. LocalStartTime Field** + +This field SHALL indicate the starting time for the Year Day schedule in Epoch Time in Seconds with +local time offset based on the local timezone and DST offset on the day represented by the value. +This SHALL be null if the schedule is not set for the YearDayIndex and UserIndex provided. + +**5.2.10.18.5. LocalEndTime Field** + +This field SHALL indicate the ending time for the Year Day schedule in Epoch Time in Seconds with +local time offset based on the local timezone and DST offset on the day represented by the value. +LocalEndTime SHALL be greater than LocalStartTime. This SHALL be null if the schedule is not set +for the YearDayIndex and UserIndex provided. + +**5.2.10.19. ClearYearDaySchedule Command** + +Clears the specific year day schedule or all year day schedules for the specific user. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 YearDayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfYear­ +DaySchedu­ +lesSupport­ +edPerUser, +0xFE +``` +### M + +``` +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +Return status SHALL be one of the following values: + +``` +Name Summary +SUCCESS Clearing the requested YearDaySchedule was +successful. +``` +``` +Page 416 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Name Summary +FAILURE Some unexpected internal error occurred clear­ +ing Year Day schedule. +INVALID_COMMAND One or more fields violates constraints or is +invalid. +``` +**5.2.10.19.1. YearDayIndex Field** + +This field SHALL indicate the Year Day schedule index to clear or 0xFE to clear all Year Day sched­ +ules for the specified user. + +**5.2.10.19.2. UserIndex Field** + +This field SHALL indicate the user ID. + +**5.2.10.20. SetHolidaySchedule Command** + +Set the holiday Schedule by specifying local start time and local end time with respect to any Lock +Operating Mode. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 HolidayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfHoli­ +daySchedu­ +lesSupported +``` +### M + +``` +1 LocalStart­ +Time +``` +``` +epoch-s all M +``` +``` +2 LocalEnd­ +Time +``` +``` +epoch-s all M +``` +``` +3 Operating­ +Mode +``` +``` +Operating­ +ModeEnum +``` +``` +all M +``` +Return status SHALL be one of the following values: + +``` +Name Summary +SUCCESS Setting Holiday schedule was successful. +FAILURE Some unexpected internal error occurred setting +Holiday schedule. +INVALID_COMMAND One or more fields violates constraints or is +invalid. +``` +**5.2.10.20.1. HolidayIndex Field** + +This field SHALL indicate the index of the Holiday schedule. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 417 +``` + +**5.2.10.20.2. LocalStartTime Field** + +This field SHALL indicate the starting time for the Holiday Day schedule in Epoch Time in Seconds +with local time offset based on the local timezone and DST offset on the day represented by the +value. + +**5.2.10.20.3. LocalEndTime Field** + +This field SHALL indicate the ending time for the Holiday Day schedule in Epoch Time in Seconds +with local time offset based on the local timezone and DST offset on the day represented by the +value. LocalEndTime SHALL be greater than LocalStartTime. + +**5.2.10.20.4. OperatingMode Field** + +This field SHALL indicate the operating mode to use during this Holiday schedule start/end time. + +**5.2.10.21. GetHolidaySchedule Command** + +Get the holiday schedule for the specified index. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 HolidayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfHoli­ +daySchedu­ +lesSupported +``` +### M + +**5.2.10.22. GetHolidayScheduleResponse Command** + +Returns the Holiday Schedule Entry for the specified Holiday ID. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 HolidayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfHoli­ +daySchedu­ +lesSupported +``` +### M + +``` +1 Status enum8 desc SUCCESS M +2 LocalStart­ +Time +``` +``` +epoch-s all X O +``` +``` +3 Local End +Time +``` +``` +epoch-s all X O +``` +``` +4 Operating­ +Mode +``` +``` +Operating­ +ModeEnum +``` +``` +all X O +``` +``` +Page 418 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.10.22.1. HolidayIndex Field** + +This field SHALL indicate the index of the Holiday schedule. + +**5.2.10.22.2. Status Field** + +Status SHALL be one of the following values: + +- FAILURE if the attribute NumberOfHolidaySchedulesSupported is zero. +- SUCCESS if the HolidayIndex is valid and there is a corresponding schedule entry. +- INVALID_COMMAND if the HolidayIndex is not within valid range +- NOT_FOUND if the HolidayIndex is within the valid range, however, there is not corresponding + schedule entry found. + +If this field is SUCCESS, the optional fields for this command SHALL be present. For other (error) +status values, only the fields up to the status field SHALL be present. + +**5.2.10.22.3. LocalStartTime Field** + +This field SHALL indicate the starting time for the Holiday schedule in Epoch Time in Seconds with +local time offset based on the local timezone and DST offset on the day represented by the value. +This SHALL be null if the schedule is not set for the HolidayIndex provided. + +**5.2.10.22.4. LocalEndTime Field** + +This field SHALL indicate the ending time for the Holiday schedule in Epoch Time in Seconds with +local time offset based on the local timezone and DST offset on the day represented by the value. +LocalEndTime SHALL be greater than LocalStartTime. This SHALL be null if the schedule is not set +for the HolidayIndex provided. + +**5.2.10.22.5. OperatingMode Field** + +This field SHALL indicate the operating mode to use during this Holiday schedule start/end time. +This SHALL be null if the schedule is not set for the HolidayIndex provided. + +**5.2.10.23. ClearHolidaySchedule Command** + +Clears the holiday schedule or all holiday schedules. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 HolidayIn­ +dex +``` +``` +uint8 1 to Num­ +berOfHoli­ +daySchedu­ +lesSup­ +ported, 0xFE +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 419 +``` + +**5.2.10.23.1. HolidayIndex Field** + +This field SHALL indicate the Holiday schedule index to clear or 0xFE to clear all Holiday schedules. + +**5.2.10.24. SetUserType Command** + +Set the user type for a specified user. + +For user type value please refer to User Type Value. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +1 UserType UserType­ +Enum +``` +``` +all M +``` +Return status SHALL be one of the following values: + +``` +Name Summary +SUCCESS Setting User Type was successful. +FAILURE Some unexpected internal error occurred setting +User Type. +INVALID_COMMAND One or more fields violates constraints or is +invalid. +Door lock is unable to switch from restricted to +unrestricted user (e.g. need to clear schedules to +switch). +``` +**5.2.10.24.1. UserID Field** + +This field SHALL indicate the user ID. + +**5.2.10.24.2. UserType Field** + +This field SHALL indicate the user type. + +**5.2.10.25. GetUserType Command** + +Retrieve the user type for a specific user. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +``` +**5.2.10.26. GetUserTypeResponse Command** + +Returns the user type for the specified user ID. If the requested User ID is invalid, send Default +Response with an error status equal to FAILURE. + +``` +Page 420 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +1 UserType UserType­ +Enum +``` +``` +all M +``` +**5.2.10.27. SetRFIDCode Command** + +Set an ID for RFID access into the lock. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +1 UserStatus UserSta­ +tusEnum +``` +``` +desc X OccupiedEn­ +abled +``` +### M + +``` +2 UserType UserType­ +Enum +``` +``` +desc X Unrestricte­ +dUser +``` +### M + +``` +3 RFIDCode octstr M +``` +Return status is a global status code or a cluster-specific status code from the Status Codes table and +SHALL be one of the following values: + +``` +Name Summary +SUCCESS Setting RFID code was successful. +FAILURE Setting RFID code failed. +CONSTRAINT_ERROR Setting RFID code failed because User ID +requested was out of range. +DUPLICATE Setting RFID code failed because it would create +a duplicate RFID code. +``` +**5.2.10.27.1. UserID Field** + +This field SHALL indicate the user ID. + +The value of the UserID field SHALL be between 0 and the value of the NumberOfRFIDUsersSup­ +ported attribute. + +**5.2.10.27.2. UserStatus Field** + +This field SHALL indicate what the status is for a specific user ID. The values are according to “Set +PIN” while not all are supported. + +Only the values 1 (Occupied/Enabled) and 3 (Occupied/Disabled) are allowed for UserStatus. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 421 +``` + +**5.2.10.27.3. UserType Field** + +The values are the same as used for SetPINCode command. + +**5.2.10.28. GetRFIDCode Command** + +Retrieve an RFID code. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +``` +**5.2.10.28.1. UserID Field** + +This field SHALL indicate the user ID. + +The value of the UserID field SHALL be between 0 and the value of the NumberOfRFIDUsersSup­ +ported attribute. + +**5.2.10.29. GetRFIDCodeResponse Command** + +Returns the RFID code for the specified user ID. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserID uint16 desc M +1 UserStatus UserSta­ +tusEnum +``` +``` +desc X Available M +``` +``` +2 UserType UserType­ +Enum +``` +``` +desc X M +``` +``` +3 RFIDCode octstr X empty M +``` +If the requested User ID is valid and the Code doesn’t exist, Get RFID Code Response SHALL have +the following format: + +User ID = requested User ID + +UserStatus = 0 (available) + +UserType = 0xFF (not supported) + +RFID Code = 0 (zero length) + +If requested User ID is invalid, send Default Response with an error status. The error status SHALL +be equal to CONSTRAINT_ERROR when User_ID is less than the max number of users supported, +and NOT_FOUND if greater than or equal to the max number of users supported. + +``` +Page 422 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.10.30. ClearRFIDCode Command** + +Clear an RFID code or all RFID codes. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 RFIDSlotIn­ +dex +``` +``` +uint16 1 to Num­ +berOfR­ +FIDUsersSup +ported, +0xFFFE +``` +### M + +For each RFID Code cleared whose user doesn’t have a PIN Code or other credential type, then the +corresponding user record’s UserStatus value SHALL be set to Available, and UserType value +SHALL be set to UnrestrictedUser and all schedules SHALL be cleared. + +**5.2.10.30.1. RFIDSlotIndex Field** + +This field SHALL indicate a valid RFID code slot index or 0xFFFE to indicate all RFID code slots +SHALL be cleared. + +**5.2.10.31. ClearAllRFIDCodes Command** + +Clear out all RFIDs on the lock. If you clear all RFID codes and this user didn’t have a PIN code, the +user status has to be set to "0 Available", the user type has to be set to the default value, and all +schedules which are supported have to be set to the default values. + +**5.2.10.32. SetUser Command** + +Set user into the lock. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Opera­ +tionType +``` +``` +DataOpera­ +tionType­ +Enum +``` +``` +Add, Modify M +``` +``` +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +``` +2 UserName string max 10 X empty M +3 UserUnique +ID +``` +``` +uint32 all X 0xFFFFFFFF M +``` +``` +4 UserStatus UserSta­ +tusEnum +``` +``` +OccupiedEn­ +abled, Occu­ +piedDisabled +``` +``` +X OccupiedEn­ +abled +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 423 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +5 UserType UserType­ +Enum +``` +``` +Unrestricte­ +dUser, +NonAcces­ +sUser, +ForcedUser, +Dispos­ +ableUser, +ExpiringUser +, +ScheduleRe­ +strictedUser, +RemoteOn­ +lyUser +``` +``` +X Unrestricte­ +dUser +``` +### M + +``` +6 Credential­ +Rule +``` +``` +Credential­ +RuleEnum +``` +``` +X Single M +``` +Fields used for different use cases: + +``` +Page 424 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Use Case Description** + +Create a new user record • OperationType SHALL be set to Add. + +- UserIndex value SHALL be set to a user + record with UserType set to Available. +- UserName MAY be null causing new user + record to use empty string for UserName + otherwise UserName SHALL be set to the + value provided in the new user record. +- UserUniqueID MAY be null causing new user + record to use 0xFFFFFFFF for UserUniqueID + otherwise UserUniqueID SHALL be set to the + value provided in the new user record. +- UserStatus MAY be null causing new user + record to use OccupiedEnabled for UserSta­ + tus otherwise UserStatus SHALL be set to the + value provided in the new user record. +- UserType MAY be null causing new user + record to use UnrestrictedUser for UserType + otherwise UserType SHALL be set to the + value provided in the new user record. +- CredentialRule MAY be null causing new + user record to use Single for CredentialRule + otherwise CredentialRule SHALL be set to + the value provided in the new user record. + +``` +CreatorFabricIndex and LastModifiedFabricIn­ +dex in the new user record SHALL be set to the +accessing fabric index. +``` +``` +A LockUserChange event SHALL be generated +after successfully creating a new user. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 425 +``` + +``` +Use Case Description +Modify an existing user record • OperationType SHALL be set to Modify. +``` +- UserIndex value SHALL be set for a user + record with UserType NOT set to Available. +- UserName SHALL be null if modifying a user + record that was not created by the accessing + fabric. +- INVALID_COMMAND SHALL be returned if + UserName is not null and the accessing fab­ + ric index doesn’t match the CreatorFabricIn­ + dex in the user record otherwise UserName + SHALL be set to the value provided in the + user record. +- UserUniqueID SHALL be null if modifying + the user record that was not created by the + accessing fabric. +- INVALID_COMMAND SHALL be returned if + UserUniqueID is not null and the accessing + fabric index doesn’t match the Creator­ + FabricIndex in the user record otherwise + UserUniqueID SHALL be set to the value pro­ + vided in the user record. +- UserStatus MAY be null causing no change to + UserStatus in user record otherwise UserSta­ + tus SHALL be set to the value provided in the + user record. +- UserType MAY be null causing no change to + UserType in user record otherwise UserType + SHALL be set to the value provided in the + user record. +- CredentialRule MAY be null causing no + change to CredentialRule in user record oth­ + erwise CredentialRule SHALL be set to the + value provided in the user record. + +``` +CreatorFabricIndex SHALL NOT be changed in +the user record. LastModifiedFabricIndex in the +new user record SHALL be set to the accessing +fabric index. +``` +``` +A LockUserChange event SHALL be generated +after successfully modifying a user. +``` +Return status is a global status code or a cluster-specific status code from the Status Codes table and + +``` +Page 426 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +SHALL be one of the following values: + +- SUCCESS, if setting User was successful. +- FAILURE, if some unexpected internal error occurred setting User. +- OCCUPIED, if OperationType is Add and UserIndex points to an occupied slot. +- INVALID_COMMAND, if one or more fields violate constraints or are invalid or if OperationType + is Modify and UserIndex points to an available slot. + +**5.2.10.32.1. OperationType Field** + +This field SHALL indicate the type of operation. + +**5.2.10.32.2. UserIndex Field** + +This field SHALL indicate the user ID. + +**5.2.10.32.3. UserName Field** + +This field SHALL contain a string to use as a human readable identifier for the user. + +If UserName is null then: + +- If the OperationType is Add, the UserName in the resulting user record SHALL be set to an + empty string. +- If the OperationType is Modify, the UserName in the user record SHALL NOT be changed from + the current value. + +If UserName is not null, the UserName in the user record SHALL be set to the provided value. + +**5.2.10.32.4. UserUniqueID Field** + +This field SHALL indicate the fabric assigned number to use for connecting this user to other users +on other devices from the fabric’s perspective. + +If UserUniqueID is null then: + +- If the OperationType is Add, the UserUniqueID in the resulting user record SHALL be set to + default value specified above. +- If the OperationType is Modify, the UserUniqueID in the user record SHALL NOT be changed + from the current value. + +If UserUniqueID is not null, the UserUniqueID in the user record SHALL be set to the provided +value. + +**5.2.10.32.5. UserStatus Field** + +This field SHALL indicate the UserStatus to assign to this user when created or modified. + +If UserStatus is null then: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 427 +``` + +- If the OperationType is Add, the UserStatus in the resulting user record SHALL be set to default + value specified above. +- If the OperationType is Modify, the UserStatus in the user record SHALL NOT be changed from + the current value. + +If UserStatus is not null, the UserStatus in the user record SHALL be set to the provided value. + +**5.2.10.32.6. UserType Field** + +This field SHALL indicate the UserType to assign to this user when created or modified. + +If UserType is null then: + +- If the OperationType is Add, the UserType in the resulting user record SHALL be set to default + value specified above. +- If the OperationType is Modify, the UserType in the user record SHALL NOT be changed from + the current value. + +If UserType is not null, the UserType in the user record SHALL be set to the provided value. + +**5.2.10.32.7. CredentialRule Field** + +This field SHALL indicate the CredentialRule to use for this user. + +The valid CredentialRule enumeration values depends on the bits in the CredentialRulesBitmap +map. Each bit in the map identifies a valid CredentialRule that can be used. + +If CredentialRule is null then: + +- If the OperationType is Add, the CredentialRule in the resulting user record SHALL be set to + default value specified above. +- If the OperationType is Modify, the CredentialRule in the user record SHALL NOT be changed + from the current value. + +If CredentialRule is not null, the CredentialRule in the user record SHALL be set to the provided +value. + +**5.2.10.33. GetUser Command** + +Retrieve user. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +An InvokeResponse command SHALL be sent with an appropriate error (e.g. FAILURE, INVALID_­ + +``` +Page 428 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +COMMAND, etc.) as needed otherwise the GetUserResponse Command SHALL be sent implying a +status of SUCCESS. + +**5.2.10.34. GetUserResponse Command** + +Returns the user for the specified UserIndex. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### M + +``` +1 UserName string max 10 X empty M +2 UserUnique +ID +``` +``` +uint32 all X 0 M +``` +``` +3 UserStatus UserSta­ +tusEnum +``` +``` +all X Available M +``` +``` +4 UserType UserType­ +Enum +``` +``` +all X Unrestricte­ +dUser +``` +### M + +``` +5 Credential­ +Rule +``` +``` +Credential­ +RuleEnum +``` +``` +desc X Single M +``` +``` +6 Credentials list[Creden­ +tialStruct] +``` +``` +0 to Num­ +berOfCre­ +dentialsSup­ +portedPe­ +rUser +``` +### X M + +``` +7 Creator­ +FabricIndex +``` +``` +fabric-idx all X M +``` +``` +8 LastModi­ +fied­ +FabricIndex +``` +``` +fabric-idx all X M +``` +``` +9 Nex­ +tUserIndex +``` +``` +uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### X M + +If the requested UserIndex is valid and the UserStatus is Available for the requested UserIndex then +UserName, UserUniqueID, UserStatus, UserType, CredentialRule, Credentials, CreatorFabricIndex, +and LastModifiedFabricIndex SHALL all be null in the response. + +**5.2.10.34.1. UserIndex Field** + +This field SHALL indicate the user ID. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 429 +``` + +**5.2.10.34.2. UserName Field** + +This field SHALL contain a string to use as a human readable identifier for the user. + +**5.2.10.34.3. UserUniqueID Field** + +See UserUniqueID field. + +**5.2.10.34.4. UserStatus Field** + +This field SHALL indicate the UserStatus assigned to the user when created or modified. + +**5.2.10.34.5. UserType Field** + +This field SHALL indicate the UserType assigned to this user when created or modified. + +**5.2.10.34.6. CredentialRule Field** + +This field SHALL indicate the CredentialRule set for this user. + +**5.2.10.34.7. Credentials Field** + +This field SHALL contain a list of credentials for this user. + +**5.2.10.34.8. CreatorFabricIndex Field** + +This field SHALL indicate the user’s creator fabric index. CreatorFabricIndex SHALL be null if User­ +Status is set to Available or when the creator fabric cannot be determined (for example, when user +was created outside the Interaction Model) and SHALL NOT be null otherwise. This value SHALL be +set to 0 if the original creator fabric was deleted. + +**5.2.10.34.9. LastModifiedFabricIndex Field** + +This field SHALL indicate the user’s last modifier fabric index. LastModifiedFabricIndex SHALL be +null if UserStatus is set to Available or when the modifier fabric cannot be determined (for exam­ +ple, when user was modified outside the Interaction Model) and SHALL NOT be null otherwise. This +value SHALL be set to 0 if the last modifier fabric was deleted. + +**5.2.10.34.10. NextUserIndex Field** + +This field SHALL indicate the next occupied UserIndex in the database which is useful for quickly +identifying occupied user slots in the database. This SHALL NOT be null if there is at least one occu­ +pied entry after the requested UserIndex in the User database and SHALL be null if there are no +more occupied entries. + +**5.2.10.35. ClearUser Command** + +Clears a user or all Users. + +``` +Page 430 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID name Type Constraint Quality Default Confor­ +mance +0 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported, +0xFFFE +``` +### M + +For each user to clear, all associated credentials (e.g. PIN, RFID, fingerprint, etc.) SHALL be cleared +and the user entry values SHALL be reset to their default values (e.g. UserStatus SHALL be Avail­ +able, UserType SHALL be UnrestrictedUser) and all associated schedules SHALL be cleared. + +A LockUserChange event with the provided UserIndex SHALL be generated after successfully clear­ +ing users. + +**5.2.10.35.1. UserIndex Field** + +This field SHALL specify a valid User index or 0xFFFE to indicate all user slots SHALL be cleared. + +**5.2.10.36. SetCredential Command** + +Set a credential (e.g. PIN, RFID, Fingerprint, etc.) into the lock for a new user, existing user, or Pro­ +grammingUser. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Opera­ +tionType +``` +``` +DataOpera­ +tionType­ +Enum +``` +``` +Add, Modify M +``` +``` +1 Credential Credential­ +Struct +``` +### M + +``` +2 Credential­ +Data +``` +``` +octstr desc M +``` +``` +3 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### X M + +``` +4 UserStatus UserSta­ +tusEnum +``` +``` +OccupiedEn­ +abled, Occu­ +piedDisabled +``` +``` +X OccupiedEn­ +abled +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 431 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +5 UserType UserType­ +Enum +``` +``` +Unrestricte­ +dUser, +Program­ +mingUser, +NonAcces­ +sUser, +ForcedUser, +Dispos­ +ableUser, +ExpiringUser +, +RemoteOn­ +lyUser +``` +``` +X Unrestricte­ +dUser +``` +### M + +Fields used for different use cases: + +``` +Page 432 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Use Case Description** + +Create a new credential and a new user record • OperationType SHALL be set to Add. + +- UserIndex SHALL be set to null and the lock + will find a user record with a UserStatus + value of Available and associate its + UserIndex with the CredentialIndex in Cre­ + dentialStruct provided. +- CredentialIndex in CredentialStruct SHALL + be for an unoccupied credential slot. +- UserStatus MAY be null. If it is null, the new + user record SHALL have UserStatus set to + OccupiedEnabled. Otherwise the new user + record SHALL have UserStatus set to the pro­ + vided value. +- UserType MAY be null. If it is null, the new + user record SHALL have UserType set to + UnrestrictedUser. Otherwise the new user + record SHALL have UserType set to the pro­ + vided value. +- UserType SHALL NOT be set to Programmin­ + gUser for this use case. + +``` +CreatorFabricIndex and LastModifiedFabricIn­ +dex in new user and credential records SHALL +be set to the accessing fabric index. +``` +``` +A LockUserChange event SHALL be generated +after successfully creating a new credential and +a new user. The UserIndex of this LockUser­ +Change event SHALL be the UserIndex that was +used to create the user. The DataIndex of this +LockUserChange event SHALL be the Creden­ +tialIndex that was used to create the credential. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 433 +``` + +``` +Use Case Description +Add a new credential to existing user record • OperationType SHALL be set to Add. +``` +- UserIndex SHALL NOT be null and SHALL + NOT already be associated with the Creden­ + tialIndex in CredentialStruct provided other­ + wise INVALID_COMMAND status response + SHALL be returned. +- INVALID_COMMAND SHALL be returned if + the accessing fabric index doesn’t match the + CreatorFabricIndex in the user record + pointed to by UserIndex. +- CredentialIndex in CredentialStruct pro­ + vided SHALL be for an available credential + slot. +- UserStatus SHALL be null. +- UserType SHALL be null. + +``` +CreatorFabricIndex SHALL NOT be changed in +the user record. LastModifiedFabricIndex in the +user record SHALL be set to the accessing fabric +index. +``` +``` +CreatorFabricIndex and LastModifiedFabricIn­ +dex in the new credential record SHALL be set +to the accessing fabric index. +``` +``` +A LockUserChange event SHALL be generated +after successfully adding a new credential. +``` +Page 434 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Use Case Description** + +Modify credential for an existing user record • OperationType SHALL be set to Modify. + +- UserIndex value SHALL already be associ­ + ated with the CredentialIndex in Credential­ + Struct provided otherwise INVALID_COM­ + MAND status response SHALL be returned. +- INVALID_COMMAND SHALL be returned if + the accessing fabric index doesn’t match the + CreatorFabricIndex in the user record + pointed to by UserIndex. +- INVALID_COMMAND SHALL be returned if + the accessing fabric index doesn’t match the + CreatorFabricIndex in the credential record + pointed to by the CredentialIndex field value + of the Credential parameter. +- CredentialIndex in CredentialStruct pro­ + vided SHALL be for an occupied credential + slot +- UserStatus SHALL be null. +- UserType SHALL be null. + +``` +CreatorFabricIndex SHALL NOT be changed in +user and credential records. LastModified­ +FabricIndex in user and credential records +SHALL be set to the accessing fabric index. +``` +``` +A LockUserChange event SHALL be generated +after successfully modifying a credential. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 435 +``` + +``` +Use Case Description +Modify credential for a Programming User • OperationType SHALL be set to Modify. +``` +- UserIndex SHALL be null. +- INVALID_COMMAND SHALL be returned if + the accessing fabric index doesn’t match the + CreatorFabricIndex in the credential record + pointed to by the CredentialIndex field value + of the Credential parameter. +- CredentialType in CredentialStruct SHALL + be set to ProgrammingPIN. +- CredentialIndex in CredentialStruct SHALL + be 0. +- UserStatus SHALL be null. +- UserType SHALL be set to Programmin­ + gUser. + +``` +CreatorFabricIndex SHALL NOT be changed in +the credential record. LastModifiedFabricIndex +in the credential record SHALL be set to the +accessing fabric index. +``` +``` +A LockUserChange event SHALL be generated +after successfully modifying a Programmin­ +gUser PIN code. +``` +**5.2.10.36.1. OperationType Field** + +This field SHALL indicate the set credential operation type requested. + +**5.2.10.36.2. Credential Field** + +This field SHALL contain a credential structure that contains the CredentialTypeEnum and the cre­ +dential index (if applicable or 0 if not) to set. + +**5.2.10.36.3. CredentialData Field** + +This field SHALL indicate the credential data to set for the credential being added or modified. The +length of the credential data SHALL conform to the limits of the CredentialType specified in the Cre­ +dential structure otherwise an INVALID_COMMAND status SHALL be returned in the SetCredential­ +Response command. + +**5.2.10.36.4. UserIndex Field** + +This field SHALL indicate the user index to the user record that corresponds to the credential being +added or modified. This SHALL be null if OperationType is add and a new credential and user is +being added at the same time. + +``` +Page 436 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.10.36.5. UserStatus Field** + +This field SHALL indicate the user status to use in the new user record if a new user is being cre­ +ated. This SHALL be null if OperationType is Modify. This MAY be null when adding a new creden­ +tial and user. + +**5.2.10.36.6. UserType Field** + +This field SHALL indicate the user type to use in the new user record if a new user is being created. +This SHALL be null if OperationType is Modify. This MAY be null when adding a new credential and +user. + +**5.2.10.37. SetCredentialResponse Command** + +Returns the status for setting the specified credential. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status status desc M +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### X 0 M + +``` +2 NextCre­ +dentialIn­ +dex +``` +``` +uint16 desc X O +``` +**5.2.10.37.1. Status Field** + +Status comes from the Status Codes table and SHALL be one of the following values: + +- SUCCESS, if setting user credential was successful. +- FAILURE, if some unexpected internal error occurred setting user credential. +- OCCUPIED, if OperationType is Add and CredentialIndex in Credential structure points to an + occupied slot. +- OCCUPIED, if OperationType is Modify and CredentialIndex in Credential structure does not + match the CredentialIndex that is already associated with the provided UserIndex. +- DUPLICATE, if CredentialData provided is a duplicate of another credential with the same Cre­ + dentialType (e.g. duplicate PIN code). +- RESOURCE_EXHAUSTED, if OperationType is Add and the new credential cannot be added due + to resource constraints such as: + ◦ The user referred to by UserIndex already has NumberOfCredentialsSupportedPerUser cre­ + dentials associated. + ◦ The credential is of type AliroEvictableEndpointKey or AliroNonEvictableEndpointKey, and + adding it would cause the total number of credentials of those two types to exceed Num­ + berOfAliroEndpointKeysSupported. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 437 +``` + +- INVALID_COMMAND, if one or more fields violate constraints or are invalid. +- INVALID_COMMAND, if the CredentialIndex in the Credential provided exceeds the number of + credentials of the provided CredentialType supported by the lock. +- INVALID_COMMAND, if OperationType is Modify and UserIndex points to an available slot. + +**5.2.10.37.2. UserIndex Field** + +This field SHALL indicate the user index that was created with the new credential. If the status +being returned is not success then this SHALL be null. This SHALL be null if OperationType was +Modify; if the OperationType was Add and a new User was created this SHALL NOT be null and +SHALL provide the UserIndex created. If the OperationType was Add and an existing User was asso­ +ciated with the new credential then this SHALL be null. + +**5.2.10.37.3. NextCredentialIndex Field** + +This field SHALL indicate the next available index in the database for the credential type set, which +is useful for quickly identifying available credential slots in the database. This SHALL NOT be null if +there is at least one available entry after the requested credential index in the corresponding data­ +base and SHALL be null if there are no more available entries. The NextCredentialIndex reported +SHALL NOT exceed the maximum number of credentials for a particular credential type. + +**5.2.10.38. GetCredentialStatus Command** + +Retrieve the status of a particular credential (e.g. PIN, RFID, Fingerprint, etc.) by index. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Credential Credential­ +Struct +``` +### M + +An InvokeResponse command SHALL be sent with an appropriate error (e.g. FAILURE, INVALID_­ +COMMAND, etc.) as needed otherwise the GetCredentialStatusResponse command SHALL be sent +implying a status of SUCCESS. + +**5.2.10.38.1. Credential Field** + +This field SHALL contain a credential structure that contains the CredentialTypeEnum and the cre­ +dential index (if applicable or 0 if not) to retrieve the status for. + +**5.2.10.39. GetCredentialStatusResponse Command** + +Returns the status for the specified credential. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Creden­ +tialExists +``` +``` +bool all M +``` +``` +Page 438 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 UserIndex uint16 1 to Num­ +berOfTo­ +talUsersSup­ +ported +``` +### X M + +``` +2 Creator­ +FabricIndex +``` +``` +fabric-idx all X M +``` +``` +3 LastModi­ +fied­ +FabricIndex +``` +``` +fabric-idx all X M +``` +``` +4 NextCre­ +dentialIn­ +dex +``` +``` +uint16 desc X O +``` +``` +5 Credential­ +Data +``` +``` +octstr desc X [ALIRO] +``` +**5.2.10.39.1. CredentialExists Field** + +This field SHALL indicate if the requested credential type and index exists and is populated for the +requested user index. + +**5.2.10.39.2. UserIndex Field** + +This field SHALL indicate the credential’s corresponding user index value if the credential exists. If +CredentialType requested was ProgrammingPIN then UserIndex SHALL be null; otherwise, +UserIndex SHALL be null if CredentialExists is set to False and SHALL NOT be null if CredentialEx­ +ists is set to True. + +**5.2.10.39.3. CreatorFabricIndex Field** + +This field SHALL indicate the credential’s creator fabric index. CreatorFabricIndex SHALL be null if +CredentialExists is set to False or when the creator fabric cannot be determined (for example, when +credential was created outside the Interaction Model) and SHALL NOT be null otherwise. This value +SHALL be set to 0 if the original creator fabric was deleted. + +**5.2.10.39.4. LastModifiedFabricIndex Field** + +This field SHALL indicate the credential’s last modifier fabric index. LastModifiedFabricIndex +SHALL be null if CredentialExists is set to False or when the modifier fabric cannot be determined +(for example, when credential was modified outside the Interaction Model) and SHALL NOT be null +otherwise. This value SHALL be set to 0 if the last modifier fabric was deleted. + +**5.2.10.39.5. NextCredentialIndex Field** + +This field SHALL indicate the next occupied index in the database for the credential type requested, +which is useful for quickly identifying occupied credential slots in the database. This SHALL NOT be +null if there is at least one occupied entry after the requested credential index in the corresponding + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 439 +``` + +database and SHALL be null if there are no more occupied entries. The NextCredentialIndex +reported SHALL NOT exceed the maximum number of credentials for a particular credential type. + +**5.2.10.39.6. CredentialData** + +This field SHALL indicate the credential data for the requested user index. + +If the CredentialType in the GetCredentialStatus command was not AliroCredentialIssuerKey, +AliroEvictableEndpointKey, or AliroNonEvictableEndpointKey, this field SHALL NOT be included. + +Otherwise, if CredentialExists is false this field SHALL be null. + +Otherwise, the value of this field SHALL be the value of the relevant credential, as a 65-byte uncom­ +pressed elliptic curve public key as defined in section 2.3.3 of SEC 1. + +### NOTE + +``` +Since the Aliro credentials are public keys, there is no security risk in allowing them +to be read. Possession of the credential octet string does not allow operating the +lock. +``` +**5.2.10.40. ClearCredential Command** + +Clear one, one type, or all credentials except ProgrammingPIN credential. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Credential Credential­ +Struct +``` +``` +desc X M +``` +Fields used for different use cases: + +``` +Use Case Description +Clear a single credential • CredentialType in Credential structure +SHALL be set to the credential type to be +cleared. +``` +- CredentialType in Credential structure + SHALL NOT be set to ProgrammingPIN. +- CredentialIndex in Credential structure + SHALL be set to the credential index to be + cleared. + +``` +A LockUserChange event SHALL be generated +after successfully clearing a credential. +``` +``` +Page 440 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Use Case Description +Clear all credentials of one type • CredentialType in Credential structure +SHALL be set to the credential type to be +cleared. +``` +- CredentialType in Credential structure + SHALL NOT be set to ProgrammingPIN. +- CredentialIndex in Credential structure + SHALL be set to 0xFFFE to indicate all cre­ + dentials of that type SHALL be cleared. + +``` +A single LockUserChange event SHALL be gener­ +ated after successfully clearing credentials. This +event SHALL have DataIndex set to the Creden­ +tialIndex in the Credential structure. +Clear all credentials of all types • Credential field SHALL be null. +``` +``` +The ProgrammingPIN credential SHALL NOT be +cleared. +``` +``` +For each credential type cleared, a LockUser­ +Change event with the corresponding Lock­ +DataType SHALL be generated. This event +SHALL have DataIndex set to 0xFFFE. +``` +For each credential cleared whose user doesn’t have another valid credential, the corresponding +user record SHALL be reset back to default values and its UserStatus value SHALL be set to Avail­ +able and UserType value SHALL be set to UnrestrictedUser and all schedules SHALL be cleared. In +this case a LockUserChange event SHALL be generated for the user being cleared. + +Return status SHALL be one of the following values: + +``` +Name Summary +SUCCESS Clearing the requested credential was success­ +ful. +FAILURE Some unexpected internal error occurred clear­ +ing the requested credential. +INVALID_COMMAND One or more fields violate constraints or are +invalid. +``` +**5.2.10.40.1. Credential Field** + +This field SHALL contain a credential structure that contains the CredentialTypeEnum and the cre­ +dential index (0xFFFE for all credentials or 0 if not applicable) to clear. This SHALL be null if clear­ +ing all credential types otherwise it SHALL NOT be null. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 441 +``` + +**5.2.10.41. UnboltDoor Command** + +This command causes the lock device to unlock the door without pulling the latch. This command +includes an optional code for the lock. The door lock MAY require a code depending on the value of +the RequirePINForRemoteOperation attribute. + +### NOTE + +``` +If the attribute AutoRelockTime is supported, the lock will transition to the locked +state when the auto relock time has expired. +``` +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PINCode octstr [COTA & PIN] +``` +**5.2.10.41.1. PINCode Field** + +See PINCode field. + +**5.2.10.42. SetAliroReaderConfig Command** + +This command allows communicating an Aliro Reader configuration, as defined in [Aliro], to the +lock. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SigningKey octstr 32 M +1 Verification­ +Key +``` +``` +octstr 65 M +``` +``` +2 GroupIden­ +tifier +``` +``` +octstr 16 M +``` +``` +3 GroupRe­ +solvingKey +``` +``` +octstr 16 ALBU +``` +**5.2.10.42.1. SigningKey Field** + +This field SHALL indicate the signing key component of the Reader’s key pair. + +**5.2.10.42.2. VerificationKey Field** + +This field SHALL indicate the verification key component of the Reader’s key pair. This SHALL be +an uncompressed elliptic curve public key as defined in section 2.3.3 of SEC 1. + +**5.2.10.42.3. GroupIdentifier Field** + +This field SHALL indicate the reader group identifier for the lock. + +**5.2.10.42.4. GroupResolvingKey Field** + +This field SHALL indicate the group resolving key for the lock. + +``` +Page 442 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.10.42.5. Effect on Receipt** + +1. If the lock already has an Aliro Reader configuration defined, (i.e. the AliroReaderVerification­ + Key attribute is not null), the response SHALL be INVALID_IN_STATE. + +### NOTE + +``` +This avoids accidentally overwriting values that were just set by a different +administrator. If overwriting those is desired, they should be explicitly cleared +with the ClearAliroReaderConfig command. +``` +2. Otherwise: + a. The door lock server SHALL save the SigningKey internally. + b. The AliroReaderVerificationKey attribute SHALL be set to the value of VerificationKey. + c. The AliroReaderGroupIdentifier attribute SHALL be set to the value of GroupIdentifier. + d. If the AliroBLEUWB feature is supported, the AliroGroupResolvingKey attribute SHALL be + set to the value of GroupResolvingKey. + e. The response SHALL be SUCCESS. + +**5.2.10.43. ClearAliroReaderConfig Command** + +This command allows clearing an existing Aliro Reader configuration for the lock. + +Administrators SHALL NOT clear an Aliro Reader configuration without explicit user permission. + +### NOTE + +``` +Using this command will revoke the ability of all existing Aliro user devices that +have the old verification key to interact with the lock. This effect is not restricted to +a single fabric or otherwise scoped in any way. +``` +**5.2.10.43.1. Effect on Receipt** + +On receipt of this command: + +1. The door lock server SHALL clear out the stored SigningKey. +2. The AliroReaderVerificationKey and AliroReaderGroupIdentifier attributes SHALL be set to + null. +3. If the AliroBLEUWB feature is supported, the AliroGroupResolvingKey attribute SHALL be set to + null. + +**5.2.11. Events** + +This cluster SHALL support these events: + +``` +ID Name Priority Quality Access Conformance +0x00 DoorLock­ +Alarm +``` +### CRITICAL V M + +``` +0x01 DoorState­ +Change +``` +``` +desc V DPS +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 443 +``` + +``` +ID Name Priority Quality Access Conformance +0x02 LockOperation desc V M +0x03 LockOpera­ +tionError +``` +``` +desc V M +``` +``` +0x04 LockUser­ +Change +``` +### INFO V USR + +The Events specified in this cluster are not intended to define the user experience. The events are +only intended to define the metadata format used to notify any nodes that have subscribed for +updates. + +If the DoorState reported in the DoorStateChange event is not DoorClosed then the priority SHALL +be CRITICAL; otherwise it MAY be INFO. + +If the LockOperationType reported in the LockOperation event is Unlock or ForcedUserEvent then +the priority SHALL be CRITICAL; otherwise it MAY be INFO. + +If the OperationError reported in the LockOperationError event is DisabledUserDenied or the Lock­ +OperationType is Lock the priority SHALL be CRITICAL; otherwise it MAY be INFO. + +**5.2.11.1. DoorLockAlarm Event** + +The door lock server provides several alarms which can be sent when there is a critical state on the +door lock. The alarms available for the door lock server are listed in AlarmCodeEnum. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 AlarmCode Alarm­ +CodeEnum +``` +``` +all M +``` +**5.2.11.1.1. AlarmCode Field** + +This field SHALL indicate the alarm code of the event that has happened. + +**5.2.11.2. DoorStateChange Event** + +The door lock server sends out a DoorStateChange event when the door lock door state changes. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 DoorState DoorSta­ +teEnum +``` +``` +all M +``` +``` +Page 444 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.11.2.1. DoorState Field** + +This field SHALL indicate the new door state for this door event. + +**5.2.11.3. LockOperation Event** + +The door lock server sends out a LockOperation event when the event is triggered by the various +lock operation sources. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 LockOpera­ +tionType +``` +``` +LockOpera­ +tionType­ +Enum +``` +``` +all M +``` +``` +1 Opera­ +tionSource +``` +``` +Opera­ +tionSourceE +num +``` +``` +all M +``` +``` +2 UserIndex uint16 all X M +3 FabricIndex fabric-idx all X M +4 SourceNode node-id all X M +5 Credentials list[Creden­ +tialStruct] +``` +``` +1 to Num­ +berOfCre­ +dentialsSup­ +portedPe­ +rUser +``` +### X [USR] + +- If the door lock server supports the Unbolt Door command, it SHALL generate a LockOperation + event with LockOperationType set to Unlock after an Unbolt Door command succeeds. +- If the door lock server supports the Unbolting feature and an Unlock Door command is per­ + formed, it SHALL generate a LockOperation event with LockOperationType set to Unlatch when + the unlatched state is reached and a LockOperation event with LockOperationType set to + Unlock when the lock successfully completes the unlock → hold latch → release latch and + return to unlock state operation. +- If the command fails during holding or releasing the latch but after passing the unlocked state, + the door lock server SHALL generate a LockOperationError event with LockOperationType set + to Unlatch and a LockOperation event with LockOperationType set to Unlock. + ◦ If it fails before reaching the unlocked state, the door lock server SHALL generate only a + LockOperationError event with LockOperationType set to Unlock. +- Upon manual actuation, a door lock server that supports the Unbolting feature: + ◦ SHALL generate a LockOperation event of LockOperationType Unlatch when it is actuated + from the outside. + ◦ MAY generate a LockOperation event of LockOperationType Unlatch when it is actuated + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 445 +``` + +``` +from the inside. +``` +**5.2.11.3.1. LockOperationType Field** + +This field SHALL indicate the type of the lock operation that was performed. + +**5.2.11.3.2. OperationSource Field** + +This field SHALL indicate the source of the lock operation that was performed. + +**5.2.11.3.3. UserIndex Field** + +This field SHALL indicate the UserIndex who performed the lock operation. This SHALL be null if +there is no user index that can be determined for the given operation source. This SHALL NOT be +null if a user index can be determined. In particular, this SHALL NOT be null if the operation was +associated with a valid credential. + +**5.2.11.3.4. FabricIndex Field** + +This field SHALL indicate the fabric index of the fabric that performed the lock operation. This +SHALL be null if there is no fabric that can be determined for the given operation source. This +SHALL NOT be null if the operation source is "Remote". + +**5.2.11.3.5. SourceNode Field** + +This field SHALL indicate the Node ID of the node that performed the lock operation. This SHALL be +null if there is no Node associated with the given operation source. This SHALL NOT be null if the +operation source is "Remote". + +**5.2.11.3.6. Credentials Field** + +This field SHALL indicate the list of credentials used in performing the lock operation. This SHALL +be null if no credentials were involved. + +**5.2.11.4. LockOperationError Event** + +The door lock server sends out a LockOperationError event when a lock operation fails for various +reasons. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 LockOpera­ +tionType +``` +``` +LockOpera­ +tionType­ +Enum +``` +``` +all M +``` +``` +1 Opera­ +tionSource +``` +``` +Opera­ +tionSourceE +num +``` +``` +all M +``` +``` +Page 446 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +2 Opera­ +tionError +``` +``` +Opera­ +tionErrorEn +um +``` +``` +all M +``` +``` +3 UserIndex uint16 all X M +4 FabricIndex fabric-idx all X M +5 SourceNode node-id all X M +6 Credentials list[Creden­ +tialStruct] +``` +``` +1 to Num­ +berOfCre­ +dentialsSup­ +portedPe­ +rUser +``` +### X [USR] + +**5.2.11.4.1. LockOperationType Field** + +This field SHALL indicate the type of the lock operation that was performed. + +**5.2.11.4.2. OperationSource Field** + +This field SHALL indicate the source of the lock operation that was performed. + +**5.2.11.4.3. OperationError Field** + +This field SHALL indicate the lock operation error triggered when the operation was performed. + +**5.2.11.4.4. UserIndex Field** + +This field SHALL indicate the lock UserIndex who performed the lock operation. This SHALL be null +if there is no user id that can be determined for the given operation source. + +**5.2.11.4.5. FabricIndex Field** + +This field SHALL indicate the fabric index of the fabric that performed the lock operation. This +SHALL be null if there is no fabric that can be determined for the given operation source. This +SHALL NOT be null if the operation source is "Remote". + +**5.2.11.4.6. SourceNode Field** + +This field SHALL indicate the Node ID of the node that performed the lock operation. This SHALL be +null if there is no Node associated with the given operation source. This SHALL NOT be null if the +operation source is "Remote". + +**5.2.11.4.7. Credentials Field** + +This field SHALL indicate the list of credentials used in performing the lock operation. This SHALL +be null if no credentials were involved. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 447 +``` + +**5.2.11.5. LockUserChange Event** + +The door lock server sends out a LockUserChange event when a lock user, schedule, or credential +change has occurred. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Lock­ +DataType +``` +``` +Lock­ +DataType­ +Enum +``` +``` +all M +``` +``` +1 DataOpera­ +tionType +``` +``` +DataOpera­ +tionType­ +Enum +``` +``` +all M +``` +``` +2 Opera­ +tionSource +``` +``` +Opera­ +tionSourceE +num +``` +``` +Aliro, +Unspecified, +Keypad, +Remote +``` +### M + +``` +3 UserIndex uint16 all X M +4 FabricIndex fabric-idx all X M +5 SourceNode node-id all X M +6 DataIndex uint16 all X M +``` +**5.2.11.5.1. LockDataType Field** + +This field SHALL indicate the lock data type that was changed. + +**5.2.11.5.2. DataOperationType Field** + +This field SHALL indicate the data operation performed on the lock data type changed. + +**5.2.11.5.3. OperationSource Field** + +This field SHALL indicate the source of the user data change. + +**5.2.11.5.4. UserIndex Field** + +This field SHALL indicate the lock UserIndex associated with the change (if any). This SHALL be +null if there is no specific user associated with the data operation. This SHALL be 0xFFFE if all users +are affected (e.g. Clear Users). + +**5.2.11.5.5. FabricIndex Field** + +This field SHALL indicate the fabric index of the fabric that performed the change (if any). This +SHALL be null if there is no fabric that can be determined to have caused the change. This SHALL +NOT be null if the operation source is "Remote". + +``` +Page 448 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.11.5.6. SourceNode Field** + +This field SHALL indicate the Node ID that performed the change (if any). The Node ID of the node +that performed the change. This SHALL be null if there was no Node involved in the change. This +SHALL NOT be null if the operation source is "Remote". + +**5.2.11.5.7. DataIndex Field** + +This field SHALL indicate the index of the specific item that was changed (e.g. schedule, PIN, RFID, +etc.) in the list of items identified by LockDataType. This SHALL be null if the LockDataType does +not correspond to a list that can be indexed into (e.g. ProgrammingUser). This SHALL be 0xFFFE if +all indices are affected (e.g. ClearPINCode, ClearRFIDCode, ClearWeekDaySchedule, ClearYear­ +DaySchedule, etc.). + +**5.3. Window Covering Cluster** + +The window covering cluster provides an interface for controlling and adjusting automatic window +coverings such as drapery motors, automatic shades, curtains and blinds. + +**5.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Mandatory global ClusterRevision attribute +added; CCB 1994 1995 1996 1997 2086 2094 2095 +2096 2097 +2 CCB 2328 +3 CCB 2477 2555 2845 3028 +4 All Hubs changes with FeatureMap & Opera­ +tionalStatus attribute +5 New data model format and notation. Created +plus clarified PositionAware and AbsolutePosi­ +tion features. General cleanup of functionality. +``` +**5.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint WNCV +``` +**5.3.3. Cluster ID** + +``` +ID Name +0x0102 Window Covering +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 449 +``` + +**5.3.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 LF Lift O.a+ Lift control and +behavior for lift­ +ing/sliding win­ +dow coverings +1 TL Tilt O.a+ Tilt control and +behavior for tilt­ +ing window cover­ +ings +2 PA_LF PositionAwareLift [LF] Position aware lift +control is sup­ +ported. +3 ABS AbsolutePosition O Absolute position­ +ing is supported. +4 PA_TL PositionAwareTilt [TL] Position aware tilt +control is sup­ +ported. +``` +Due to backward compatibility reasons this feature map SHALL match the advertised Type +Attribute Supported Features. + +**5.3.4.1. Lift Feature** + +The Lift feature applies to window coverings that lift up and down (e.g. for a roller shade, Up and +Down is lift Open and Close) or slide left to right (e.g. for a sliding curtain, Left and Right is lift Open +and Close). + +**5.3.4.2. Tilt Feature** + +The Tilt feature applies to window coverings with vertical or horizontal strips. + +**5.3.4.3. PositionAware Features** + +Relative positioning with _percent100ths_ (min step 0.01%) attribute is mandatory, e.g. Max 10000 +equals 100.00% and relative positioning with _percent_ (min step 1%) attribute is for backward com­ +patibility. + +The _CurrentPosition_ attributes SHALL always reflects the physical position of an actuator and the +_TargetPosition_ attribute SHALL reflect the requested position of an actuator once a positioning +command is received. + +**5.3.4.3.1. PositionAwareLift Feature** + +Relative positioning for lift attributes and commands. + +``` +Page 450 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.3.4.3.2. PositionAwareTilt Feature** + +Relative positioning for tilt attributes and commands. + +**5.3.4.4. AbsolutePosition Feature** + +The percentage attributes SHALL indicate the position as a percentage between the InstalledOpen­ +Limits and InstalledClosedLimits attributes of the window covering starting at the open (0.00%). + +As a general rule, absolute positioning (in centimeters or tenth of a degrees) SHOULD NOT be sup­ +ported for new implementations. + +**5.3.5. Data Types** + +**5.3.5.1. ConfigStatusBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 Operational Device is operational. M +1 OnlineReserved D +2 LiftMovementRe­ +versed +``` +``` +The lift movement is +reversed. +``` +### LF + +``` +3 LiftPositionAware Supports the Position­ +AwareLift feature +(PA_LF). +``` +### PA_LF + +``` +4 TiltPositionAware Supports the Position­ +AwareTilt feature +(PA_TL). +``` +### PA_TL + +``` +5 LiftEncoderCon­ +trolled +``` +``` +Uses an encoder for lift. PA_LF +``` +``` +6 TiltEncoderControlled Uses an encoder for tilt. PA_TL +``` +**5.3.5.1.1. Operational Bit** + +This bit SHALL indicate whether the window covering is operational for regular use: + +- 0 = Not Operational +- 1 = Operational + +**5.3.5.1.2. LiftMovementReversed Bit** + +This bit SHALL indicate whether the lift movement is reversed: + +- 0 = Lift movement is normal +- 1 = Lift movement is reversed + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 451 +``` + +**5.3.5.1.3. LiftPositionAware Bit** + +This bit SHALL indicate whether the window covering supports the PositionAwareLift feature: + +- 0 = Lift control is not position aware +- 1 = Lift control is position aware (PA_LF) + +**5.3.5.1.4. TiltPositionAware Bit** + +This bit SHALL indicate whether the window covering supports the PositionAwareTilt feature: + +- 0 = Tilt control is not position aware +- 1 = Tilt control is position aware (PA_TL) + +**5.3.5.1.5. LiftEncoderControlled Bit** + +This bit SHALL indicate whether a position aware controlled window covering is employing an +encoder for positioning the height of the window covering: + +- 0 = Timer Controlled +- 1 = Encoder Controlled + +**5.3.5.1.6. TiltEncoderControlled Bit** + +This bit SHALL indicate whether a position aware controlled window covering is employing an +encoder for tilting the window covering: + +- 0 = Timer Controlled +- 1 = Encoder Controlled + +**5.3.5.2. ModeBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 MotorDirectionRe­ +versed +``` +``` +Reverse the lift direc­ +tion. +``` +### M + +``` +1 CalibrationMode Perform a calibration. M +2 MaintenanceMode Freeze all motions for +maintenance. +``` +### M + +``` +3 LedFeedback Control the LEDs feed­ +back. +``` +### M + +**5.3.5.2.1. MotorDirectionReversed Bit** + +This bit SHALL control the motor direction: + +- 0 = Lift movement is normal + +``` +Page 452 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- 1 = Lift movement is reversed + +**5.3.5.2.2. CalibrationMode Bit** + +This bit SHALL set the window covering into calibration mode: + +- 0 = Normal mode +- 1 = Calibration mode + +**5.3.5.2.3. MaintenanceMode Bit** + +This bit SHALL set the window covering into maintenance mode: + +- 0 = Normal mode +- 1 = Maintenance mode + +**5.3.5.2.4. LedFeedback Bit** + +This bit SHALL control feedback LEDs: + +- 0 = LEDs are off +- 1 = LEDs will display feedback + +**5.3.5.3. OperationalStatusBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +1..0 Global Global operational +state. +``` +### M + +``` +3..2 Lift Lift operational state. LF +5..4 Tilt Tilt operational state. TL +``` +The OperationalStatusBitmap is using several internal operational state fields (composed of 2 bits) +following this definition: + +- 00b = Currently not moving +- 01b = Currently opening (e.g. moving from closed to open). +- 10b = Currently closing (e.g. moving from open to closed). +- 11b = Reserved + +**5.3.5.3.1. Global Bits** + +These bits SHALL indicate in which direction the covering is currently moving or if it has stopped. +Global operational state SHALL always reflect the overall motion of the device. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 453 +``` + +**5.3.5.3.2. Lift Bits** + +These bits SHALL indicate in which direction the covering’s lift is currently moving or if it has +stopped. + +**5.3.5.3.3. Tilt Bits** + +These bits SHALL indicate in which direction the covering’s tilt is currently moving or if it has +stopped. + +**5.3.5.4. SafetyStatusBitmap Type** + +This data type is derived from map16. + +``` +Bit Name Summary Conformance +0 RemoteLockout Movement commands +are ignored (locked +out). e.g. not granted +authorization, outside +some time/date range. +``` +### M + +``` +1 TamperDetection Tampering detected on +sensors or any other +safety equipment. Ex: a +device has been +forcedly moved with­ +out its actuator(s). +``` +### M + +``` +2 FailedCommunication Communication failure +to sensors or other +safety equipment. +``` +### M + +``` +3 PositionFailure Device has failed to +reach the desired posi­ +tion. e.g. with position +aware device, time +expired before Target­ +Position is reached. +``` +### M + +``` +4 ThermalProtection Motor(s) and/or electric +circuit thermal protec­ +tion activated. +``` +### M + +``` +5 ObstacleDetected An obstacle is prevent­ +ing actuator movement. +``` +### M + +``` +Page 454 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary Conformance +6 Power Device has power +related issue or limita­ +tion e.g. device is run­ +ning w/ the help of a +backup battery or +power might not be +fully available at the +moment. +``` +### M + +``` +7 StopInput Local safety sensor (not +a direct obstacle) is pre­ +venting movements +(e.g. Safety EU Standard +EN60335). +``` +### M + +``` +8 MotorJammed Mechanical problem +related to the motor(s) +detected. +``` +### M + +``` +9 HardwareFailure PCB, fuse and other +electrics problems. +``` +### M + +``` +10 ManualOperation Actuator is manually +operated and is pre­ +venting actuator move­ +ment (e.g. actuator is +disengaged/decoupled). +``` +### M + +``` +11 Protection Protection is activated. M +``` +**5.3.5.5. TypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 RollerShade RollerShade LF +1 RollerShade2Motor RollerShade - 2 Motor LF +2 RollerShadeExterior RollerShade - Exterior LF +3 RollerShadeExterior2­ +Motor +``` +``` +RollerShade - Exterior - +2 Motor +``` +### LF + +``` +4 Drapery Drapery (curtain) LF +5 Awning Awning LF +6 Shutter Shutter LF | TL +7 TiltBlindTiltOnly Tilt Blind - Tilt Only TL +8 TiltBlindLiftAndTilt Tilt Blind - Lift & Tilt LF & TL +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 455 +``` + +``` +Value Name Summary Conformance +9 ProjectorScreen Projector Screen LF +255 Unknown Unknown O +``` +**5.3.5.6. EndProductTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 RollerShade Simple Roller Shade LF +1 RomanShade Roman Shade LF +2 BalloonShade Balloon Shade LF +3 WovenWood Woven Wood LF +4 PleatedShade Pleated Shade LF +5 CellularShade Cellular Shade LF +6 LayeredShade Layered Shade LF +7 LayeredShade2D Layered Shade 2D LF +8 SheerShade Sheer Shade LF & TL +9 TiltOnlyInteriorBlind Tilt Only Interior Blind TL +10 InteriorBlind Interior Blind LF & TL +11 VerticalBlindStripCur­ +tain +``` +``` +Vertical Blind, Strip +Curtain +``` +### LF & TL + +``` +12 InteriorVenetianBlind Interior Venetian Blind LF & TL +13 ExteriorVenetian­ +Blind +``` +``` +Exterior Venetian Blind LF & TL +``` +``` +14 LateralLeftCurtain Lateral Left Curtain LF +15 LateralRightCurtain Lateral Right Curtain LF +16 CentralCurtain Central Curtain LF +17 RollerShutter Roller Shutter LF +18 ExteriorVerti­ +calScreen +``` +``` +Exterior Vertical Screen LF +``` +``` +19 AwningTerracePatio Awning Terrace (Patio) LF +20 AwningVerticalScreen Awning Vertical Screen LF +21 TiltOnlyPergola Tilt Only Pergola LF | TL +22 SwingingShutter Swinging Shutter LF | TL +23 SlidingShutter Sliding Shutter LF | TL +255 Unknown Unknown O +``` +``` +Page 456 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.3.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Type TypeEnum desc F 0 R V M +0x0001 Physical­ +Clos­ +edLim­ +itLift +``` +``` +uint16 all F 0 R V [LF & +PA_LF & +ABS] +``` +``` +0x0002 Physical­ +Clos­ +edLimit­ +Tilt +``` +``` +uint16 all F 0 R V [TL & +PA_TL & +ABS] +``` +``` +0x0003 Current­ +Position­ +Lift^1 +``` +``` +uint16 Installe­ +dOpenLim­ +itLift to +Installed­ +ClosedLim­ +itLift +``` +``` +X N null R V [LF & +PA_LF & +ABS] +``` +``` +0x0004 Current­ +Position­ +Tilt^1 +``` +``` +uint16 Installe­ +dOpen­ +LimitTilt to +Installed­ +Clos­ +edLimitTilt +``` +``` +X N null R V [TL & +PA_TL & +ABS] +``` +``` +0x0005 NumberO­ +fActua­ +tionsLift +``` +``` +uint16 all N 0 R V [LF] +``` +``` +0x0006 NumberO­ +fActua­ +tionsTilt +``` +``` +uint16 all N 0 R V [TL] +``` +``` +0x0007 ConfigSta­ +tus +``` +``` +ConfigSta­ +tusBitmap +``` +``` +desc N desc R V M +``` +``` +0x0008 Current­ +Position­ +LiftPer­ +centage^1 +``` +``` +percent X N P null R V [LF & +PA_LF] +``` +``` +0x0009 Current­ +Position­ +TiltPer­ +centage^1 +``` +``` +percent all X N P null R V [TL & +PA_TL] +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 457 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x000A Opera­ +tionalSta­ +tus +``` +``` +Opera­ +tionalSta­ +tusBitmap +``` +``` +0b00xx +xxxx +``` +### P 0 R V M + +``` +0x000B TargetPo­ +sitionLift­ +Per­ +cent100ths 2 +``` +``` +per­ +cent100ths +``` +``` +X P null R V LF & PA_LF +``` +``` +0x000C TargetPo­ +sitionTilt­ +Per­ +cent100ths 2 +``` +``` +per­ +cent100ths +``` +``` +X P null R V TL & PA_TL +``` +``` +0x000D EndPro­ +ductType +``` +``` +EndPro­ +ductType­ +Enum +``` +``` +desc F 0 R V M +``` +``` +0x000E Current­ +Position­ +LiftPer­ +cent100ths 1 +``` +``` +per­ +cent100ths +``` +``` +max 10000 X N P null R V LF & PA_LF +``` +``` +0x000F Current­ +Position­ +TiltPer­ +cent100ths 1 +``` +``` +per­ +cent100ths +``` +``` +max 10000 X N P null R V TL & PA_TL +``` +``` +0x0010 Installe­ +dOpen­ +LimitLift +``` +``` +uint16 max 65534 N 0 R V LF & PA_LF +& ABS +``` +``` +0x0011 Installed­ +Clos­ +edLim­ +itLift +``` +``` +uint16 max 65534 N 65534 R V LF & PA_LF +& ABS +``` +``` +0x0012 Installe­ +dOpen­ +LimitTilt +``` +``` +uint16 max 65534 N 0 R V TL & PA_TL +& ABS +``` +``` +0x0013 Installed­ +Clos­ +edLimit­ +Tilt +``` +``` +uint16 max 65534 N 65534 R V TL & PA_TL +& ABS +``` +``` +0x0014 Veloc­ +ityLift +``` +### D + +Page 458 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0015 Accelera­ +tionTimeL +ift +``` +### D + +``` +0x0016 Decelera­ +tionTimeL +ift +``` +### D + +``` +0x0017 Mode ModeB­ +itmap. +``` +``` +0b0000 +xxxx +``` +### N 0 RW VM M + +``` +0x0018 Intermedi­ +ateSet­ +pointsLift +``` +### D + +``` +0x0019 Intermedi­ +ateSet­ +pointsTilt +``` +### D + +``` +0x001A SafetySta­ +tus +``` +``` +SafetySta­ +tusBitmap +``` +``` +desc P 0 R V O +``` +### NOTE + +``` +Nullable positions +1 - The null value indicates that the current position is unknown, e.g. calibration is +needed. +``` +``` +2 - The null value indicates that the value is unavailable, e.g. no target position has +been set. +``` +**5.3.6.1. Type Attribute** + +This attribute SHALL identify the type of window covering. + +**5.3.6.2. PhysicalClosedLimitLift Attribute** + +This attribute SHALL indicate the maximum possible encoder position possible (Unit _cm_ , centime­ +ters) to position the height of the window covering lift. + +**5.3.6.3. PhysicalClosedLimitTilt Attribute** + +This attribute SHALL indicate the maximum possible encoder position possible (Unit _0.1°_ , tenths of +a degree) to position the angle of the window covering tilt. + +**5.3.6.4. CurrentPositionLift Attribute** + +This attribute SHALL indicate the actual lift position (Unit _cm_ , centimeters) of the window covering +from the fully-open position. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 459 +``` + +**5.3.6.5. CurrentPositionTilt Attribute** + +This attribute SHALL indicate the actual tilt position (Unit _0.1°_ , tenths of a degree) of the window +covering from the fully-open position. + +**5.3.6.6. NumberOfActuationsLift Attribute** + +This attribute SHALL indicate the total number of lift/slide actuations applied to the window cover­ +ing since the device was installed. + +**5.3.6.7. NumberOfActuationsTilt Attribute** + +This attribute SHALL indicate the total number of tilt actuations applied to the window covering +since the device was installed. + +**5.3.6.8. ConfigStatus Attribute** + +This attribute specifies the configuration and status information of the window covering. + +To change settings, devices SHALL write to the Mode attribute. The behavior causing the setting or +clearing of each bit is vendor specific. + +**5.3.6.8.1. Operational Bit** + +The SafetyStatus & Mode attributes might affect this bit state. + +**5.3.6.8.2. LiftMovementReversed Bit** + +This bit identifies if the directions of the lift/slide movements have been reversed in order for com­ +mands (e.g: Open, Close, GoTos) to match the physical installation conditions + +This bit can be adjusted by setting the MotorDirectionReversed bit in the Mode attribute. + +**5.3.6.8.3. LiftEncoderControlled Bit** + +This bit is ignored if the device does not support the PositionAwareLift feature (PA_LF). + +**5.3.6.8.4. TiltEncoderControlled Bit** + +This bit is ignored if the device does not support the PositionAwareTilt feature (PA_TL). + +**5.3.6.9. CurrentPositionLiftPercent100ths Attribute** + +This attribute SHALL indicate the actual position as a percentage with a minimal step of 0.01%. E.g +Max 10000 equals 100.00%. + +**5.3.6.10. CurrentPositionTiltPercent100ths Attribute** + +This attribute SHALL indicate the actual position as a percentage with a minimal step of 0.01%. E.g +Max 10000 equals 100.00%. + +``` +Page 460 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.3.6.11. CurrentPositionLiftPercentage Attribute** + +This attribute SHALL indicate the actual position as a percentage from 0% to 100% with 1% default +step. This attribute is equal to CurrentPositionLiftPercent100ths attribute divided by 100. + +**5.3.6.12. CurrentPositionTiltPercentage Attribute** + +This attribute SHALL indicate the actual position as a percentage from 0% to 100% with 1% default +step. This attribute is equal to CurrentPositionTiltPercent100ths attribute divided by 100. + +**5.3.6.13. TargetPositionLiftPercent100ths Attribute** + +This attribute SHALL indicate the position where the window covering lift will go or is moving to as +a percentage (Unit _0.01%_ ). + +**5.3.6.14. TargetPositionTiltPercent100ths Attribute** + +This attribute SHALL indicate the position where the window covering tilt will go or is moving to as +a percentage (Unit _0.01%_ ). + +**5.3.6.15. OperationalStatus Attribute** + +This attribute SHALL indicate the currently ongoing operations and applies to all type of devices. + +**5.3.6.16. EndProductType Attribute** + +This attribute SHOULD provide more detail about the product type than can be determined from +the main category indicated by the Type attribute. + +The table below helps to match the EndProductType attribute with the Type attribute. + +``` +Value Name Indoor Outdoor Indicative +Dimension +``` +``` +Recommended +Type Attribute +0 RollerShade I 1D RollerShade +1 RomanShade I 1D RollerShade +2 BalloonShade I 1D RollerShade +3 WovenWood I 1D RollerShade +4 PleatedShade I 1D RollerShade +5 CellularShade I 1D RollerShade +6 LayeredShade I 1D RollerShade +7 LayeredShade2D I 2D RollerShade2Mo­ +tor +8 SheerShade I 2D TiltBlindLif­ +tAndTilt +9 TiltOnlyInterior­ +Blind +``` +``` +I 1D TiltBlindTiltOnly +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 461 +``` + +``` +Value Name Indoor Outdoor Indicative +Dimension +``` +``` +Recommended +Type Attribute +10 InteriorBlind I 2D TiltBlindLif­ +tAndTilt +11 VerticalBlind­ +StripCurtain +``` +``` +I 2D TiltBlindLif­ +tAndTilt +12 InteriorVenetian­ +Blind +``` +``` +I 2D TiltBlindLif­ +tAndTilt +13 ExteriorVene­ +tianBlind +``` +``` +O 2D TiltBlindLif­ +tAndTilt +14 LateralLeftCur­ +tain +``` +``` +I 1D Drapery +``` +``` +15 LateralRightCur­ +tain +``` +``` +I 1D Drapery +``` +``` +16 CentralCurtain I 1D Drapery +17 RollerShutter O 1D RollerShadeExte­ +rior +18 ExteriorVerti­ +calScreen +``` +``` +O 1D RollerShadeExte­ +rior +19 AwningTerra­ +cePatio +``` +``` +O 1D Awning +``` +``` +20 AwningVerti­ +calScreen +``` +``` +O 1D Awning +``` +``` +21 TiltOnlyPergola O 1D Shutter +22 SwingingShutter O 1D Shutter +23 SlidingShutter O 1D Shutter +255 Unknown Unknown +``` +**5.3.6.17. InstalledOpenLimitLift Attribute** + +This attribute SHALL indicate the open limit for lifting the window covering whether position (in +centimeters) is encoded or timed. + +**5.3.6.18. InstalledClosedLimitLift Attribute** + +This attribute SHALL indicate the closed limit for lifting the window covering whether position (in +centimeters) is encoded or timed. + +**5.3.6.19. InstalledOpenLimitTilt Attribute** + +This attribute SHALL indicate the open limit for tilting the window covering whether position (in +tenth of a degree) is encoded or timed. + +``` +Page 462 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.3.6.20. InstalledClosedLimitTilt Attribute** + +This attribute SHALL indicate the closed limit for tilting the window covering whether position (in +tenth of a degree) is encoded or timed. + +**5.3.6.21. Mode Attribute** + +The Mode attribute allows configuration of the window covering, such as: reversing the motor +direction, placing the window covering into calibration mode, placing the motor into maintenance +mode, disabling the network, and disabling status LEDs. + +In the case a device does not support or implement a specific mode, e.g. the device has a specific +installation method and reversal is not relevant or the device does not include a maintenance +mode, any write interaction to the Mode attribute, with an unsupported mode bit or any out of +bounds bits set, must be ignored and a response containing the status of CONSTRAINT_ERROR will +be returned. + +**5.3.6.21.1. MotorDirectionReversed Bit** + +This bit SHALL control the LiftMovementReversed bit in the ConfigStatus attribute. + +**5.3.6.21.2. CalibrationMode Bit** + +If in calibration mode, all commands (e.g: UpOrOpen, DownOrClose, GoTos) that can result in move­ +ment, could be accepted and result in a self-calibration being initiated before the command is exe­ +cuted. + +In case the window covering does not have the ability or is not able to perform a self-calibration, +the command SHOULD be ignored and a FAILURE status SHOULD be returned. + +In a write interaction, setting this bit to 0, while the device is in calibration mode, is not allowed +and SHALL generate a FAILURE error status. In order to leave calibration mode, the device must +perform its calibration routine, either as a self-calibration or assisted by external tool(s), depending +on the device/manufacturer implementation. + +A manufacturer might choose to set the Operational bit of the ConfigStatus attribute to its not oper­ +ational value, if applicable during calibration mode. + +**5.3.6.21.3. MaintenanceMode Bit** + +While in maintenance mode, all commands (e.g: UpOrOpen, DownOrClose, GoTos) or local inputs +that can result in movement, must be ignored and respond with a BUSY status. Additionally, the +Operational bit of the ConfigStatus attribute should be set to its not operational value. + +**5.3.6.22. SafetyStatus Attribute** + +The SafetyStatus attribute reflects the state of the safety sensors and the common issues preventing +movements. By default for nominal operation all flags are cleared (0). A device might support none, +one or several bit flags from this attribute (all optional). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 463 +``` + +**5.3.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 UpOrOpen client ⇒ server Y O M +0x01 DownOrClose client ⇒ server Y O M +0x02 StopMotion client ⇒ server Y O M +0x04 GoToLiftValue client ⇒ server Y O [LF & ABS] +0x05 GoToLiftPer­ +centage +``` +``` +client ⇒ server Y O (LF & PA_LF), +[LF] +0x07 GoToTiltValue client ⇒ server Y O [TL & ABS] +0x08 GoToTiltPer­ +centage +``` +``` +client ⇒ server Y O (TL & PA_TL), +[TL] +``` +**5.3.7.1. UpOrOpen Command** + +Upon receipt of this command, the window covering will adjust its position so the physical lift/slide +and tilt is at the maximum open/up position. This will happen as fast as possible. The server attrib­ +utes SHALL be updated as follows: + +if the PositionAware feature is supported: + +- TargetPositionLiftPercent100ths attribute SHALL be set to 0.00%. +- TargetPositionTiltPercent100ths attribute SHALL be set to 0.00%. + +The server positioning attributes will follow the movements, once the movement has successfully +finished, the server attributes SHALL be updated as follows: + +if the PositionAware feature is supported: + +- CurrentPositionLiftPercent100ths attribute SHALL be 0.00%. +- CurrentPositionLiftPercentage attribute SHALL be 0%. +- CurrentPositionTiltPercent100ths attribute SHALL be 0.00%. +- CurrentPositionTiltPercentage attribute SHALL be 0%. + +if the AbsolutePosition feature is supported: + +- CurrentPositionLift attribute SHALL be equal to the InstalledOpenLimitLift attribute. +- CurrentPositionTilt attribute SHALL be equal to the InstalledOpenLimitTilt attribute. + +**5.3.7.2. DownOrClose Command** + +Upon receipt of this command, the window covering will adjust its position so the physical lift/slide +and tilt is at the maximum closed/down position. This will happen as fast as possible. The server +attributes supported SHALL be updated as follows: + +``` +Page 464 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +if the PositionAware feature is supported: + +- TargetPositionLiftPercent100ths attribute SHALL be set to 100.00%. +- TargetPositionTiltPercent100ths attribute SHALL be set to 100.00%. + +The server positioning attributes will follow the movements, once the movement has successfully +finished, the server attributes SHALL be updated as follows: + +if the PositionAware feature is supported: + +- CurrentPositionLiftPercent100ths attribute SHALL be 100.00%. +- CurrentPositionLiftPercentage attribute SHALL be 100%. +- CurrentPositionTiltPercent100ths attribute SHALL be 100.00%. +- CurrentPositionTiltPercentage attribute SHALL be 100%. + +if the AbsolutePosition feature is supported: + +- CurrentPositionLift attribute SHALL be equal to the InstalledClosedLimitLift attribute. +- CurrentPositionTilt attribute SHALL be equal to the InstalledClosedLimitTilt attribute. + +**5.3.7.3. StopMotion Command** + +Upon receipt of this command, the window covering will stop any adjusting to the physical tilt and +lift/slide that is currently occurring. The server attributes supported SHALL be updated as follows: + +- TargetPositionLiftPercent100ths attribute will be set to CurrentPositionLiftPercent100ths + attribute value. +- TargetPositionTiltPercent100ths attribute will be set to CurrentPositionTiltPercent100ths + attribute value. + +**5.3.7.4. GoToLiftValue Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 LiftValue uint16 desc M +``` +**5.3.7.4.1. LiftValue Field** + +This field SHALL specify the requested physical lift/slide position in unit cm (centimeters). + +**5.3.7.4.2. Effect on Receipt** + +Upon receipt of this command, the window covering will adjust the lift position to the value speci­ +fied in the LiftValue field, as long as that value is not larger thanInstalledOpenLimitLift attribute +and not smaller than InstalledClosedLimitLift attribute. The TargetPositionLiftPercent100ths +attribute SHALL update its value accordingly. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 465 +``` + +If the value is out of bounds a response containing the status of CONSTRAINT_ERROR will be +returned. + +**5.3.7.5. GoToLiftPercentage Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 LiftPer­ +cent100thsV +alue +``` +``` +per­ +cent100ths +``` +``` +desc M +``` +Upon receipt of this command, the server will adjust the window covering to the lift/slide percent­ +age specified in the payload of this command. + +If the command includes LiftPercent100thsValue, then TargetPositionLiftPercent100ths attribute +SHALL be set to LiftPercent100thsValue. Otherwise the TargetPositionLiftPercent100ths attribute +SHALL be set to LiftPercentageValue * 100. + +If a client includes LiftPercent100thsValue in the command, the LiftPercentageValue SHALL be set +to LiftPercent100thsValue / 100, so a legacy server which only supports LiftPercentageValue (not +LiftPercent100thsValue) has a value to set the target position. + +If the server does not support the PositionAware feature, then a zero percentage SHALL be treated +as a UpOrOpen command and a non-zero percentage SHALL be treated as an DownOrClose com­ +mand. If the device is only a tilt control device, then the command SHOULD be ignored and a +UNSUPPORTED_COMMAND status SHOULD be returned. + +**5.3.7.6. GoToTiltValue Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TiltValue uint16 desc M +``` +**5.3.7.6.1. TiltValue Field** + +This field SHALL specify the requested physical tilt position in unit _0.1°_ (tenth of a degrees). + +**5.3.7.6.2. Effect on Receipt** + +Upon receipt of this command, the window covering will adjust the tilt position to the value speci­ +fied in the TiltValue field, as long as that value is not larger than InstalledOpenLimitTilt attribute +and not smaller than InstalledClosedLimitTilt attribute. The TargetPositionTiltPercent100ths +attribute SHALL update its value accordingly. + +If the tilt value is out of bounds a response containing the status of CONSTRAINT_ERROR will be + +``` +Page 466 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +returned. + +**5.3.7.7. GoToTiltPercentage Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TiltPer­ +cent100thsV +alue +``` +``` +per­ +cent100ths +``` +``` +desc M +``` +Upon receipt of this command, the server will adjust the window covering to the tilt percentage +specified in the payload of this command. + +If the command includes TiltPercent100thsValue, then TargetPositionTiltPercent100ths attribute +SHALL be set to TiltPercent100thsValue. Otherwise the TargetPositionTiltPercent100ths attribute +SHALL be set to TiltPercentageValue * 100. + +If a client includes TiltPercent100thsValue in the command, the TiltPercentageValue SHALL be set +to TiltPercent100thsValue / 100, so a legacy server which only supports TiltPercentageValue (not +TiltPercent100thsValue) has a value to set the target position. + +If the server does not support the PositionAware feature, then a zero percentage SHALL be treated +as a UpOrOpen command and a non-zero percentage SHALL be treated as an DownOrClose com­ +mand. If the device is only a tilt control device, then the command SHOULD be ignored and a +UNSUPPORTED_COMMAND status SHOULD be returned. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 467 +``` + +Page 468 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 6. Media** + +The Cluster Library is made of individual chapters such as this one. See Document Control in the +Cluster Library for a list of all chapters and documents. References between chapters are made +using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. References +to external documents are contained in Chapter 1 and are made using [ _Rn_ ] notation. + +**6.1. General Description** + +**6.1.1. Introduction** + +The clusters specified in this document are for use typically in applications involving media (e.g., +Video Players, Content Apps, Speakers), but MAY be used in any application domain. + +**6.1.2. Cluster List** + +This section lists the media specific clusters as specified in this chapter. + +_Table 11. Overview of the Media Clusters_ + +``` +Cluster ID Cluster Name Description +0x050E Account Login This cluster provides an inter­ +face for facilitating user +account login on an application +or a node. +0x050D Application Basic Provides information about a +Content App running on a Video +Player device which is repre­ +sented as an endpoint. +0x050C Application Launcher This cluster provides an inter­ +face for launching content on a +Video Player device. +0x050B Audio Output This cluster provides an inter­ +face for controlling the Output +on a Video Player device. +0x0504 Channel This cluster provides an inter­ +face for controlling the current +Channel on an endpoint. +0x0510 Content App Observer This cluster provides an inter­ +face for sending targeted mes­ +sages from a Content App to a +Client of that Content App. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 469 +``` + +``` +Cluster ID Cluster Name Description +0x050A Content Launcher This cluster provides an inter­ +face for launching content on a +Video Player device or a Con­ +tent App. +0x0509 Keypad Input This cluster provides an inter­ +face for controlling a Video +Player or a Content App using +action commands such as UP, +DOWN, and SELECT. +0x0507 Media Input This cluster provides an inter­ +face for controlling the Input +Selector on a Video Player +device. +0x0506 Media Playback This cluster provides an inter­ +face for controlling Media Play­ +back (PLAY, PAUSE, etc) on a +Video Player device. +0x0505 Target Navigator This cluster provides an inter­ +face for UX navigation within a +set of targets on a Video Player +device or Content App endpoint. +0x050F Content Control This cluster provides an inter­ +face for controlling Content +controls such as turning on/off +Content Control feature on a +Video Player device. +``` +_Example Usage of the Media Clusters_ + +``` +Page 470 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.2. Account Login Cluster** + +This cluster provides commands that facilitate user account login on a Content App or a node. For +example, a Content App running on a Video Player device, which is represented as an endpoint (see +Device Type Library document), can use this cluster to help make the user account on the Content +App match the user account on the Client. + +Often a fabric administrator will facilitate commissioning of a Client (such as a Casting Video +Client), and invoke commands on the AccountLogin cluster on the Content App associated with that +client. Specifically: + +1. GetSetupPIN in order to attempt to obtain the Passcode for commissioning. +2. Login in order to let the Content App know that commissioning has completed. The Content App + can use information provided in this command in order to determine the user account associ­ + ated with the client, and potentially assume that user account. +3. Logout in order to let the Content App know that client access has been removed, and poten­ + tially clear the current user account. + +The cluster server for this cluster may be supported on each endpoint that represents a Content +App on a Video Player device. + +See Device Type Library document for details of how a Content App, represented as an endpoint on + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 471 +``` + +the Video Player device, may implement the cluster server for this cluster to simplify account login +for its users. + +**6.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Add support for 8 character PIN code, Add Node +to Login, Logout commands. Add LoggedOut +event. +``` +**6.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint ALOGIN +``` +**6.2.3. Cluster ID** + +``` +ID Name +0x050E Account Login +``` +**6.2.4. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 GetSetupPIN client ⇒ server GetSetupPIN­ +Response +``` +### A F T M + +``` +0x01 GetSetupPIN­ +Response +``` +``` +client ⇐ server N F M +``` +``` +0x02 Login client ⇒ server Y A F T M +0x03 Logout client ⇒ server Y O F T M +``` +**6.2.4.1. GetSetupPIN Command** + +The purpose of this command is to determine if the active user account of the given Content App +matches the active user account of a given Commissionee, and when it does, return a Setup PIN +code which can be used for password-authenticated session establishment (PASE) with the Commis­ +sionee. + +For example, a Video Player with a Content App Platform may invoke this command on one of its +Content App endpoints to facilitate commissioning of a Phone App made by the same vendor as the +Content App. If the accounts match, then the Content App may return a setup code that can be used + +``` +Page 472 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +by the Video Player to commission the Phone App without requiring the user to physically input a +setup code. + +The account match is determined by the Content App using a method which is outside the scope of +this specification and will typically involve a central service which is in communication with both +the Content App and the Commissionee. The GetSetupPIN command is needed in order to provide +the Commissioner/Admin with a Setup PIN when this Commissioner/Admin is operated by a differ­ +ent vendor from the Content App. + +This method is used to facilitate Setup PIN exchange (for PASE) between Commissioner and Com­ +missionee when the same user account is active on both nodes. With this method, the Content App +satisfies proof of possession related to commissioning by requiring the same user account to be +active on both Commissionee and Content App, while the Commissioner/Admin ensures user con­ +sent by prompting the user prior to invocation of the command. + +Upon receipt of this command, the Content App checks if the account associated with the Tempo­ +rary Account Identifier sent by the client is the same account that is active on itself. If the accounts +are the same, then the Content App returns the GetSetupPIN Response which includes a Setup PIN +that may be used for PASE with the Commissionee. + +The Temporary Account Identifier for a Commissionee may be populated with the Rotating ID field +of the client’s commissionable node advertisement (see Rotating Device Identifier section in [Mat­ +terCore]) encoded as an octet string where the octets of the Rotating Device Identifier are encoded +as 2-character sequences by representing each octet’s value as a 2-digit hexadecimal number, using +uppercase letters. + +The Setup PIN is a character string so that it can accommodate different future formats, including +alpha-numeric encodings. For a Commissionee it SHALL be populated with the Manual Pairing +Code (see Manual Pairing Code section in [MatterCore]) encoded as a string (11 characters) or the +Passcode portion of the Manual Pairing Code (when less than 11 characters). + +The server SHALL implement rate limiting to prevent brute force attacks. No more than 10 unique +requests in a 10 minute period SHALL be allowed; a command response status of FAILURE should +sent for additional commands received within the 10 minute period. Because access to this com­ +mand is limited to nodes with Admin-level access, and the user is prompted for consent prior to +Commissioning, there are in place multiple obstacles to successfully mounting a brute force attack. +A Content App that supports this command SHALL ensure that the Temporary Account Identifier +used by its clients is not valid for more than 10 minutes. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TempAc­ +countIdenti­ +fier +``` +``` +string 16 to 100 M +``` +**6.2.4.1.1. TempAccountIdentifier Field** + +This field SHALL specify the client’s Temporary Account Identifier. The length of this field SHALL +be at least 16 characters to protect the account holder against password guessing attacks. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 473 +``` + +**6.2.4.2. GetSetupPINResponse Command** + +This message is sent in response to the GetSetupPIN command, and contains the Setup PIN code, or +null when the account identified in the request does not match the active account of the running +Content App. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SetupPIN string desc M +``` +**6.2.4.2.1. SetupPIN Field** + +This field SHALL provide the setup PIN code as a text string at least 8 characters in length or empty +string to indicate that the accounts do not match. + +### NOTE + +``` +Newer cluster clients should be aware that AccountLogin cluster version 1 specified +an 11 digit minimum length. +``` +**6.2.4.3. Login Command** + +The purpose of this command is to allow the Content App to assume the user account of a given +Commissionee by leveraging the Setup PIN code input by the user during the commissioning +process. + +For example, a Video Player with a Content App Platform may invoke this command on one of its +Content App endpoints after the commissioning has completed of a Phone App made by the same +vendor as the Content App. The Content App may determine whether the Temporary Account Iden­ +tifier maps to an account with a corresponding Setup PIN and, if so, it may automatically login to +the account for the corresponding user. The end result is that a user performs commissioning of a +Phone App to a Video Player by inputting the Setup PIN for the Phone App into the Video Player UX. +Once commissioning has completed, the Video Player invokes this command to allow the corre­ +sponding Content App to assume the same user account as the Phone App. + +The verification of Setup PIN for the given Temporary Account Identifier is determined by the Con­ +tent App using a method which is outside the scope of this specification and will typically involve a +central service which is in communication with both the Content App and the Commissionee. +Implementations of such a service should impose aggressive time outs for any mapping of Tempo­ +rary Account Identifier to Setup PIN in order to prevent accidental login due to delayed invocation. + +Upon receipt, the Content App checks if the account associated with the client’s Temp Account Iden­ +tifier has a current active Setup PIN with the given value. If the Setup PIN is valid for the user +account associated with the Temp Account Identifier, then the Content App MAY make that user +account active. + +The Temporary Account Identifier for a Commissionee may be populated with the Rotating ID field +of the client’s commissionable node advertisement encoded as an octet string where the octets of +the Rotating Device Identifier are encoded as 2-character sequences by representing each octet’s +value as a 2-digit hexadecimal number, using uppercase letters. + +``` +Page 474 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The Setup PIN for a Commissionee may be populated with the Manual Pairing Code encoded as a +string of decimal numbers (11 characters) or the Passcode portion of the Manual Pairing Code +encoded as a string of decimal numbers (8 characters). + +The server SHALL implement rate limiting to prevent brute force attacks. No more than 10 unique +requests in a 10 minute period SHALL be allowed; a command response status of FAILURE should +sent for additional commands received within the 10 minute period. Because access to this com­ +mand is limited to nodes with Admin-level access, and the user is involved when obtaining the +SetupPIN, there are in place multiple obstacles to successfully mounting a brute force attack. A Con­ +tent App that supports this command SHALL ensure that the Temporary Account Identifier used by +its clients is not valid for more than 10 minutes. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TempAc­ +countIdenti­ +fier +``` +``` +string 16 to 100 M +``` +``` +1 SetupPIN string min 8 M +2 Node node-id O +``` +**6.2.4.3.1. TempAccountIdentifier Field** + +This field SHALL specify the client’s temporary account identifier. + +**6.2.4.3.2. SetupPIN Field** + +This field SHALL provide the setup PIN code as a text string at least 8 characters in length. + +``` +NOTE Newer cluster clients should be aware that AccountLogin cluster version 1 specified +an 11 digit minimum length. +``` +**6.2.4.3.3. Node Field** + +This optional field SHALL provide the Node ID of the Client. This field can be used by the Content +App to keep track of Nodes which currently have access to it. + +**6.2.4.4. Logout Command** + +The purpose of this command is to instruct the Content App to clear the current user account. This +command SHOULD be used by clients of a Content App to indicate the end of a user session. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Node node-id O +``` +**6.2.4.4.1. Node Field** + +This optional field SHALL provide the Node ID of the Client. This field can be used by the Content + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 475 +``` + +App to keep track of Nodes which currently have access to it. + +**6.2.5. Events** + +``` +ID Name Priority Access Conformance +0 LoggedOut CRITICAL A S O +``` +**6.2.5.1. LoggedOut Event** + +This event can be used by the Content App to indicate that the current user has logged out. In +response to this event, the Fabric Admin SHALL remove access to this Content App by the specified +Node. If no Node is provided, then the Fabric Admin SHALL remove access to all non-Admin Nodes. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Node node-id all O +``` +**6.2.5.1.1. Node** + +This field SHALL provide the Node ID corresponding to the user account that has logged out, if that +Node ID is available. If it is NOT available, this field SHALL NOT be present in the event. + +**6.3. Application Basic Cluster** + +This cluster provides information about a Content App running on a Video Player device which is +represented as an endpoint (see Device Type Library document). + +The cluster server for this cluster should be supported on each endpoint that represents a Content +App on a Video Player device. This cluster provides identification information about the Content +App such as vendor and product. + +**6.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**6.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint APBSC +``` +``` +Page 476 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.3.3. Cluster ID** + +``` +ID Name +0x050D Application Basic +``` +**6.3.4. Data Types** + +**6.3.4.1. ApplicationStatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Stopped Application is not run­ +ning. +``` +### M + +``` +1 ActiveVisibleFocus Application is running, +is visible to the user, +and is the active target +for input. +``` +### M + +``` +2 ActiveHidden Application is running +but not visible to the +user. +``` +### M + +``` +3 ActiveVisibleNotFocus Application is running +and visible, but is not +the active target for +input. +``` +### M + +**6.3.4.2. ApplicationStruct Type** + +This indicates a global identifier for an Application given a catalog. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Cata­ +logVen­ +dorID +``` +``` +uint16 all M +``` +``` +1 Applica­ +tionID +``` +``` +string all M +``` +**6.3.4.2.1. CatalogVendorID Field** + +This field SHALL indicate the Connectivity Standards Alliance issued vendor ID for the catalog. The +DIAL registry SHALL use value 0x0000. + +It is assumed that Content App Platform providers (see Video Player Architecture section in [Matter­ +DevLib]) will have their own catalog vendor ID (set to their own Vendor ID) and will assign an +ApplicationID to each Content App. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 477 +``` + +**6.3.4.2.2. ApplicationID Field** + +This field SHALL indicate the application identifier, expressed as a string, such as "123456-5433", +"PruneVideo" or "Company X". This field SHALL be unique within a catalog. + +For the DIAL registry catalog, this value SHALL be the DIAL prefix. + +**6.3.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Vendor­ +Name +``` +``` +string max 32 F empty R V O +``` +``` +0x0001 VendorID vendor-id all F R V O +0x0002 Applica­ +tionName +``` +``` +string desc F R V M +``` +``` +0x0003 ProductID uint16 all F R V O +0x0004 Applica­ +tion +``` +``` +Applica­ +tionStruct +``` +``` +desc F R V M +``` +``` +0x0005 Status Applica­ +tionSta­ +tusEnum +``` +``` +desc MS R V M +``` +``` +0x0006 Applica­ +tionVer­ +sion +``` +``` +string max 32 F R V M +``` +``` +0x0007 Allowed­ +Ven­ +dorList +``` +``` +list[ven­ +dor-id] +``` +### F R A M + +**6.3.5.1. VendorName Attribute** + +This attribute SHALL specify a human readable (displayable) name of the vendor for the Content +App. + +**6.3.5.2. VendorID Attribute** + +This attribute, if present, SHALL specify the Connectivity Standards Alliance assigned Vendor ID for +the Content App. + +**6.3.5.3. ApplicationName Attribute** + +This attribute SHALL specify a human readable (displayable) name of the Content App assigned by +the vendor. For example, "NPR On Demand". The maximum length of the ApplicationName +attribute is 256 bytes of UTF-8 characters. + +``` +Page 478 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.3.5.4. ProductID Attribute** + +This attribute, if present, SHALL specify a numeric ID assigned by the vendor to identify a specific +Content App made by them. If the Content App is certified by the Connectivity Standards Alliance, +then this would be the Product ID as specified by the vendor for the certification. + +**6.3.5.5. Application Attribute** + +This attribute SHALL specify a Content App which consists of an Application ID using a specified +catalog. + +**6.3.5.6. Status Attribute** + +This attribute SHALL specify the current running status of the application. + +**6.3.5.7. ApplicationVersion Attribute** + +This attribute SHALL specify a human readable (displayable) version of the Content App assigned +by the vendor. The maximum length of the ApplicationVersion attribute is 32 bytes of UTF-8 charac­ +ters. + +**6.3.5.8. AllowedVendorList Attribute** + +This attribute is a list of vendor IDs. Each entry is a vendor-id. + +**6.4. Application Launcher Cluster** + +This cluster provides an interface for launching applications on a Video Player device such as a TV. + +This cluster is supported on endpoints that can launch Applications, such as a Casting Video Player +device with a Content App Platform. It supports identifying an Application by global identifier from +a given catalog, and launching it. It also supports tracking the currently in-focus Application. + +Depending on the support for the Application Platform feature, the cluster can either support +launching the application corresponding to the endpoint on which the cluster is supported (AP fea­ +ture not supported) or it can support launching any application (AP feature supported). + +**6.4.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Addition of new states to StatusEnum +``` +**6.4.2. Classification** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 479 +``` + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint APPLAUNCHER +``` +**6.4.3. Cluster ID** + +``` +ID Name +0x050C Application Launcher +``` +**6.4.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 AP ApplicationPlatform Support for attributes +and commands +required for endpoint +to support launching +any application within +the supported applica­ +tion catalogs +``` +**6.4.5. Data Types** + +**6.4.5.1. StatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Success Command succeeded M +1 AppNotAvailable Requested app is not +available +``` +### M + +``` +2 SystemBusy Video platform unable +to honor command +``` +### M + +``` +3 PendingUserApproval User approval for app +download is pending +``` +### M + +``` +4 Downloading Downloading the +requested app +``` +### M + +``` +5 Installing Installing the requested +app +``` +### M + +**6.4.5.2. ApplicationStruct Type** + +This indicates a global identifier for an Application given a catalog. + +``` +Page 480 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Cata­ +logVen­ +dorID +``` +``` +uint16 all M +``` +``` +1 Applica­ +tionID +``` +``` +string all M +``` +**6.4.5.2.1. CatalogVendorID Field** + +This field SHALL indicate the CSA-issued vendor ID for the catalog. The DIAL registry SHALL use +value 0x0000. + +Content App Platform providers will have their own catalog vendor ID (set to their own Vendor ID) +and will assign an ApplicationID to each Content App. + +**6.4.5.2.2. ApplicationID Field** + +This field SHALL indicate the application identifier, expressed as a string, such as "PruneVideo" or +"Company X". This field SHALL be unique within a catalog. + +For the DIAL registry catalog, this value SHALL be the DIAL prefix (see [DIAL Registry]). + +**6.4.5.3. ApplicationEPStruct Type** + +This specifies an app along with its corresponding endpoint. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Applica­ +tion +``` +``` +Applica­ +tionStruct +``` +``` +all M +``` +``` +1 Endpoint endpoint- +no +``` +``` +all MS O +``` +**6.4.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Cata­ +logList +``` +``` +list[uint16] N R V AP +``` +``` +0x0001 Cur­ +rentApp +``` +``` +Applica­ +tionEP­ +Struct +``` +``` +desc X null R V O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 481 +``` + +**6.4.6.1. CatalogList Attribute** + +This attribute SHALL specify the list of supported application catalogs, where each entry in the list +is the CSA-issued vendor ID for the catalog. The DIAL registry (see [DIAL Registry]) SHALL use value +0x0000. + +It is expected that Content App Platform providers will have their own catalog vendor ID (set to +their own Vendor ID) and will assign an ApplicationID to each Content App. + +**6.4.6.2. CurrentApp Attribute** + +This attribute SHALL specify the current in-focus application, identified using an Application ID, +catalog vendor ID and the corresponding endpoint number when the application is represented by +a Content App endpoint. A null SHALL be used to indicate there is no current in-focus application. + +**6.4.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 LaunchApp client ⇒ server LauncherRe­ +sponse +``` +### O M + +``` +0x01 StopApp client ⇒ server LauncherRe­ +sponse +``` +### O M + +``` +0x02 HideApp client ⇒ server LauncherRe­ +sponse +``` +### O M + +``` +0x03 LauncherRe­ +sponse +``` +``` +client ⇐ server N M +``` +**6.4.7.1. LaunchApp Command** + +Upon receipt of this command, the server SHALL launch the application with optional data. The +application SHALL be either + +- the specified application, if the Application Platform feature is supported; +- otherwise the application corresponding to the endpoint. + +The endpoint SHALL launch and bring to foreground the requisite application if the application is +not already launched and in foreground. The Status attribute SHALL be updated to ActiveVisibleFo­ +cus on the Application Basic cluster of the Endpoint corresponding to the launched application. The +Status attribute SHALL be updated on any other application whose Status MAY have changed as a +result of this command. The CurrentApp attribute, if supported, SHALL be updated to reflect the +new application in the foreground. + +This command returns a Launcher Response. + +``` +Page 482 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Application Application­ +Struct +``` +``` +desc AP +``` +``` +1 Data octstr MS O +``` +**6.4.7.1.1. Application Field** + +This field SHALL specify the Application to launch. + +**6.4.7.1.2. Data Field** + +This field SHALL specify optional app-specific data to be sent to the app. + +### NOTE + +``` +This format and meaning of this value is proprietary and outside the specification. +It provides a transition path for device makers that use other protocols (like DIAL) +which allow for proprietary data. Apps that are not yet Matter aware can be +launched via Matter, while retaining the existing ability to launch with proprietary +data. +``` +**6.4.7.2. StopApp Command** + +Upon receipt of this command, the server SHALL stop the application if it is running. The applica­ +tion SHALL be either + +- the specified application, if the Application Platform feature is supported; +- otherwise the application corresponding to the endpoint. + +The Status attribute SHALL be updated to Stopped on the Application Basic cluster of the Endpoint +corresponding to the stopped application. The Status attribute SHALL be updated on any other +application whose Status MAY have changed as a result of this command. + +This command returns a Launcher Response. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Application Application­ +Struct +``` +``` +desc MS AP +``` +**6.4.7.2.1. Application Field** + +This field SHALL specify the Application to stop. + +**6.4.7.3. HideApp Command** + +Upon receipt of this command, the server SHALL hide the application. The application SHALL be +either + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 483 +``` + +- the specified application, if the Application Platform feature is supported; +- otherwise the application corresponding to the endpoint. + +The endpoint MAY decide to stop the application based on manufacturer specific behavior or +resource constraints if any. The Status attribute SHALL be updated to ActiveHidden or Stopped, +depending on the action taken, on the Application Basic cluster of the Endpoint corresponding to +the application on which the action was taken. The Status attribute SHALL be updated on any other +application whose Status MAY have changed as a result of this command. + +This command returns a Launcher Response. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Application Application­ +Struct +``` +``` +desc MS AP +``` +**6.4.7.3.1. Application Field** + +This field SHALL specify the Application to hide. + +**6.4.7.4. LauncherResponse Command** + +This command SHALL be generated in response to LaunchApp/StopApp/HideApp commands. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status StatusEnum all M +1 Data octstr MS O +``` +**6.4.7.4.1. Status Field** + +This field SHALL indicate the status of the command which resulted in this response. + +**6.4.7.4.2. Data Field** + +This field SHALL specify Optional app-specific data. + +**6.5. Audio Output Cluster** + +This cluster provides an interface for controlling the Output on a Video Player device such as a TV. + +This cluster would be supported on a device with audio outputs like a Video Player device (Smart +TV, TV Setup Top Box, Smart Speaker, etc). + +This cluster provides the list of available outputs and provides commands for selecting and renam­ +ing them. + +The cluster server for Audio Output is implemented by a device that has configurable audio output. + +``` +Page 484 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.5.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**6.5.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint AUDIOOUTPUT +``` +**6.5.3. Cluster ID** + +``` +ID Name +0x050B Audio Output +``` +**6.5.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 NU NameUpdates Supports updates to +output names +``` +**6.5.5. Data Types** + +**6.5.5.1. OutputTypeEnum Type** + +This data type is derived from enum8. + +The type of output, expressed as an enum, with the following values: + +``` +Value Name Summary Conformance +0 HDMI HDMI M +1 BT M +2 Optical M +3 Headphone M +4 Internal M +5 Other M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 485 +``` + +**6.5.5.2. OutputInfoStruct Type** + +This contains information about an output. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Index uint8 all M +1 OutputType OutputType­ +Enum +``` +``` +desc M +``` +``` +2 Name string all M +``` +**6.5.5.2.1. Index Field** + +This field SHALL indicate the unique index into the list of outputs. + +**6.5.5.2.2. OutputType Field** + +This field SHALL indicate the type of output. + +**6.5.5.2.3. Name Field** + +The device defined and user editable output name, such as “Soundbar”, “Speakers”. This field may +be blank, but SHOULD be provided when known. + +**6.5.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Output­ +List +``` +``` +list[Out­ +putInfoS­ +truct] +``` +### R V M + +``` +0x0001 Cur­ +rentOut­ +put +``` +``` +uint8 all R V M +``` +**6.5.6.1. OutputList Attribute** + +This attribute provides the list of outputs supported by the device. + +**6.5.6.2. CurrentOutput Attribute** + +This attribute contains the value of the index field of the currently selected OutputInfoStruct. + +**6.5.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 SelectOutput client ⇒ server Y O M +``` +``` +Page 486 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Direction Response Access Conformance +0x01 RenameOut­ +put +``` +``` +client ⇒ server Y M NU +``` +**6.5.7.1. SelectOutput Command** + +Upon receipt, this SHALL change the output on the device to the output at a specific index in the +Output List. + +Note that when the current output is set to an output of type HDMI, adjustments to volume via a +Speaker endpoint on the same node MAY cause HDMI volume up/down commands to be sent to the +given HDMI output. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Index uint8 all M +``` +**6.5.7.1.1. Index Field** + +This SHALL indicate the index field of the OutputInfoStruct from the OutputList attribute in which +to change to. + +**6.5.7.2. RenameOutput Command** + +Upon receipt, this SHALL rename the output at a specific index in the Output List. + +Updates to the output name SHALL appear in the device’s settings menus. Name updates MAY auto­ +matically be sent to the actual device to which the output connects. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Index uint8 all M +1 Name string all M +``` +**6.6. Channel Cluster** + +This cluster provides an interface for controlling the current Channel on a device or endpoint. + +This cluster server would be supported on Video Player devices or endpoints that allow Channel +control such as a Content App. This cluster provides a list of available channels and provides com­ +mands for absolute and relative channel changes. Some of these commands and/or their responses +MAY be large (see Large Message Quality under Data Model section in [MatterCore]), but they do +not have the Large quality indicator (L) because they can also be transferred over MRP (see Mes­ +sage Reliability Protocol in [MatterCore]) in pages that fit within the MRP MTU limit. However, an +implementation MAY leverage a transport like TCP that allows large payloads, if available, to mini­ +mize the number of messages required to transfer the corresponding payload. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 487 +``` + +The cluster server for Channel is implemented by an endpoint that controls the current Channel. + +**6.6.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Add EG and RP features, Identifier and Type to +Channel Info for Over-the-Top (OTT) channel +support. +``` +**6.6.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint CHANNEL +``` +**6.6.3. Cluster ID** + +``` +ID Name +0x0504 Channel +``` +**6.6.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 CL ChannelList Provides list of avail­ +able channels. +1 LI LineupInfo Provides lineup info, +which is a reference to +an external source of +lineup information. +2 EG ElectronicGuide Provides electronic pro­ +gram guide informa­ +tion. +3 RP RecordProgram Provides ability to +record program. +``` +**6.6.5. Data Types** + +``` +Page 488 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.6.5.1. RecordingFlagBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 Scheduled The program is sched­ +uled for recording. +``` +### M + +``` +1 RecordSeries The program series is +scheduled for record­ +ing. +``` +### M + +``` +2 Recorded The program is +recorded and available +to be played. +``` +### M + +**6.6.5.2. LineupInfoTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 MSO Multi System Operator M +``` +**6.6.5.3. StatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Success Command succeeded M +1 MultipleMatches More than one equal +match for the Chan­ +nelInfoStruct passed in. +``` +### M + +``` +2 NoMatches No matches for the +ChannelInfoStruct +passed in. +``` +### M + +**6.6.5.4. ChannelTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Satellite The channel is sourced +from a satellite +provider. +``` +### M + +``` +1 Cable The channel is sourced +from a cable provider. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 489 +``` + +``` +Value Name Summary Conformance +2 Terrestrial The channel is sourced +from a terrestrial +provider. +``` +### M + +``` +3 OTT The channel is sourced +from an OTT provider. +``` +### M + +**6.6.5.5. ChannelInfoStruct Type** + +This indicates a channel in a channel lineup. + +While the major and minor numbers in the ChannelInfoStruct support use of ATSC channel format, +a lineup MAY use other formats which can map into these numeric values. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Major­ +Number +``` +``` +uint16 all M +``` +``` +1 Minor­ +Number +``` +``` +uint16 all M +``` +``` +2 Name string empty O +3 CallSign string empty O +4 Affiliate­ +CallSign +``` +``` +string empty O +``` +``` +5 Identifier string empty O +6 Type Channel­ +TypeEnum +``` +``` +empty O +``` +**6.6.5.5.1. MajorNumber Field** + +This field SHALL indicate the channel major number value (for example, using ATSC format). When +the channel number is expressed as a string, such as "13.1" or "256", the major number would be 13 +or 256, respectively. This field is required but SHALL be set to 0 for channels such as over-the-top +channels that are not represented by a major or minor number. + +**6.6.5.5.2. MinorNumber Field** + +This field SHALL indicate the channel minor number value (for example, using ATSC format). When +the channel number is expressed as a string, such as "13.1" or "256", the minor number would be 1 +or 0, respectively. This field is required but SHALL be set to 0 for channels such as over-the-top +channels that are not represented by a major or minor number. + +**6.6.5.5.3. Name Field** + +This field SHALL indicate the marketing name for the channel, such as “The CW" or "Comedy Cen­ +tral". This field is optional, but SHOULD be provided when known. + +``` +Page 490 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.6.5.5.4. CallSign Field** + +This field SHALL indicate the call sign of the channel, such as "PBS". This field is optional, but +SHOULD be provided when known. + +**6.6.5.5.5. AffiliateCallSign Field** + +This field SHALL indicate the local affiliate call sign, such as "KCTS". This field is optional, but +SHOULD be provided when known. + +**6.6.5.5.6. Identifier Field** + +This SHALL indicate the unique identifier for a specific channel. This field is optional, but SHOULD +be provided when MajorNumber and MinorNumber are not available. + +**6.6.5.5.7. Type Field** + +This SHALL indicate the type or grouping of a specific channel. This field is optional, but SHOULD +be provided when known. + +**6.6.5.6. LineupInfoStruct Type** + +The Lineup Info allows references to external lineup sources like Gracenote. The combination of +OperatorName, LineupName, and PostalCode MUST uniquely identify a lineup. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Operator­ +Name +``` +``` +string M +``` +``` +1 Lineup­ +Name +``` +``` +string empty O +``` +``` +2 PostalCode string empty O +3 LineupIn­ +foType +``` +``` +LineupIn­ +foType­ +Enum +``` +``` +desc M +``` +**6.6.5.6.1. OperatorName Field** + +This field SHALL indicate the name of the operator, for example “Comcast”. + +**6.6.5.6.2. LineupName Field** + +This field SHALL indicate the name of the provider lineup, for example "Comcast King County". This +field is optional, but SHOULD be provided when known. + +**6.6.5.6.3. PostalCode Field** + +This field SHALL indicate the postal code (zip code) for the location of the device, such as "98052". +This field is optional, but SHOULD be provided when known. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 491 +``` + +**6.6.5.6.4. LineupInfoType Field** + +This field SHALL indicate the type of lineup. This field is optional, but SHOULD be provided when +known. + +**6.6.5.7. ProgramStruct Type** + +This indicates a program within an electronic program guide (EPG). + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Identifier string max 255 M +1 Channel ChannelIn­ +foStruct +``` +### M + +``` +2 StartTime epoch-s M +3 EndTime epoch-s M +4 Title string max 255 M +5 Subtitle string max 255 empty O +6 Descrip­ +tion +``` +``` +string max 8192 empty O +``` +``` +7 AudioLan­ +guages +``` +``` +list[string] max 10 +[max 50] +``` +``` +empty O +``` +``` +8 Ratings list[string] max 255 empty O +9 Thumb­ +nailUrl +``` +``` +string max 8192 empty O +``` +``` +10 PosterAr­ +tUrl +``` +``` +string max 8192 empty O +``` +``` +11 DvbiUrl string max 8192 empty O +12 Release­ +Date +``` +``` +string max 30 empty O +``` +``` +13 Parental­ +Guidance­ +Text +``` +``` +string max 255 empty O +``` +``` +14 Record­ +ingFlag +``` +``` +Record­ +ingFlag­ +Bitmap +``` +### RP + +``` +15 SeriesInfo SeriesIn­ +foStruct +``` +``` +X null O +``` +``` +16 Catego­ +ryList +``` +``` +list[Pro­ +gramCate­ +goryStruct] +``` +``` +max 255 empty O +``` +``` +Page 492 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +17 CastList list[Pro­ +gramCast­ +Struct] +``` +``` +max 255 empty O +``` +``` +18 Exter­ +nalIDList +``` +``` +list[Addi­ +tionalIn­ +foStruct] +``` +``` +max 255 empty O +``` +**6.6.5.7.1. Identifier Field** + +This field SHALL indicate a unique identifier for a program within an electronic program guide list. +The identifier SHALL be unique across multiple channels. + +**6.6.5.7.2. Channel Field** + +This field SHALL indicate the channel associated to the program. + +**6.6.5.7.3. StartTime Field** + +This field SHALL indicate an epoch time in seconds indicating the start time of a program, as a UTC +time. This field can represent a past or future value. + +**6.6.5.7.4. EndTime Field** + +This field SHALL indicate an epoch time in seconds indicating the end time of a program, as a UTC +time. This field can represent a past or future value but SHALL be greater than the StartTime. + +**6.6.5.7.5. Title Field** + +This field SHALL indicate the title or name for the specific program. For example, “MCIS: Los Ange­ +les”. + +**6.6.5.7.6. Subtitle Field** + +This field SHALL indicate the subtitle for the specific program. For example, “Maybe Today" which +is an episode name for “MCIS: Los Angeles”. This field is optional but SHALL be provided if applica­ +ble and known. + +**6.6.5.7.7. Description Field** + +This field SHALL indicate the brief description for the specific program. For example, a description +of an episode. This field is optional but SHALL be provided if known. + +**6.6.5.7.8. AudioLanguages Field** + +This field SHALL indicate the audio language for the specific program. The value is a string contain­ +ing one of the standard Tags for Identifying Languages RFC 5646. This field is optional but SHALL +be provided if known. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 493 +``` + +**6.6.5.7.9. Ratings Field** + +This field SHALL be used for indicating the level of parental guidance recommended for of a partic­ +ular program. This can be any rating system used in the country or region where the program is +broadcast. For example, in the United States “TV-PG” may contain material that parents can find not +suitable for younger children but can be accepted in general for older children. This field is +optional but SHALL be provided if known. + +**6.6.5.7.10. ThumbnailUrl Field** + +This field SHALL represent a URL of a thumbnail that clients can use to render an image for the +program. The syntax of this field SHALL follow the syntax as specified in RFC 1738 and SHALL use +the https scheme. + +**6.6.5.7.11. PosterArtUrl Field** + +This field SHALL represent a URL of a poster that clients can use to render an image for the pro­ +gram on the detail view. The syntax of this field SHALL follow the syntax as specified in RFC 1738 +and SHALL use the https scheme. + +**6.6.5.7.12. DvbiUrl Field** + +This field SHALL represent the DVB-I URL associated to the program. The syntax of this field SHALL +follow the syntax as specified in RFC 1738 and SHALL use the https scheme. + +**6.6.5.7.13. ReleaseDate Field** + +This field SHALL be a string, in ISO 8601 format, representing the date on which the program was +released. This field is optional but when provided, the year SHALL be provided as part of the string. + +**6.6.5.7.14. ParentalGuidanceText Field** + +This field SHALL represent a string providing additional information on the parental guidance. This +field is optional. + +**6.6.5.7.15. RecordingFlag Field** + +This field SHALL represent the recording status of the program. This field is required if the Record­ +Program feature is set. + +**6.6.5.7.16. SeriesInfo Field** + +This field SHALL represent the information of a series such as season and episode number. This +field is optional but SHOULD be provided if the program represents a series and this information is +available. + +**6.6.5.7.17. CategoryList Field** + +This field SHALL represent the category of a particular program. This field is optional but SHALL be +provided if known. + +``` +Page 494 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.6.5.7.18. CastList Field** + +This field SHALL represent a list of the cast or the crew on the program. A single cast member may +have more than one role. This field is optional but SHALL be provided if known. + +**6.6.5.7.19. ExternalIDList Field** + +This field SHALL indicate the list of additional external content identifiers. + +**6.6.5.8. ProgramCategoryStruct Type** + +This object defines the category associated to a program. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Category string max 256 M +1 SubCate­ +gory +``` +``` +string max 256 empty O +``` +**6.6.5.8.1. Category Field** + +This field SHALL represent the category or genre of the program. Ex. News. + +**6.6.5.8.2. SubCategory Field** + +This field SHALL represent the sub-category or sub-genre of the program. Ex. Local. + +**6.6.5.9. SeriesInfoStruct Type** + +This object provides the episode information related to a program. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Season string max 256 M +1 Episode string max 256 M +``` +**6.6.5.9.1. Season Field** + +This field SHALL represent the season of the series associated to the program. + +**6.6.5.9.2. Episode Field** + +This field SHALL represent the episode of the program. + +**6.6.5.10. ProgramCastStruct Type** + +This object provides the cast information related to a program. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 495 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Name string max 256 M +1 Role string max 256 M +``` +**6.6.5.10.1. Name Field** + +This field SHALL represent the name of the cast member. + +**6.6.5.10.2. Role Field** + +This field SHALL represent the role of the cast member. Ex. Actor, Director. + +**6.6.5.11. PageTokenStruct Type** + +This object defines the pagination structure. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Limit uint16 all 0 O +1 After string max 8192 empty O +2 Before string max 8192 empty O +``` +**6.6.5.11.1. Limit Field** + +This field SHALL indicate the maximum number of entries that should be retrieved from the pro­ +gram guide in a single response. It allows clients to specify the size of the paginated result set based +on their needs. + +**6.6.5.11.2. After Field** + +This field SHALL indicate the cursor that pinpoints the start of the upcoming data page. In a Cursor- +based pagination system, the field acts as a reference point, ensuring the set of results corresponds +directly to the data following the specified cursor. In a Offset-based pagination system, the field, +along with limit, indicate the offset from which entries in the program guide will be retrieved. + +**6.6.5.11.3. Before Field** + +This field SHALL indicate the cursor that pinpoints the end of the upcoming data page. In a Cursor- +based pagination system, the field acts as a reference point, ensuring the set of results corresponds +directly to the data preceding the specified cursor. In a Offset-based pagination system, the field, +along with limit, indicate the offset from which entries in the program guide will be retrieved. + +**6.6.5.12. ChannelPagingStruct Type** + +This object defines the paging structure that includes the previous and next pagination tokens. + +``` +Page 496 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Previous­ +Token +``` +``` +PageToken­ +Struct +``` +``` +X null O +``` +``` +1 NextTo­ +ken +``` +``` +PageToken­ +Struct +``` +``` +X null O +``` +**6.6.5.12.1. PreviousToken Field** + +This field SHALL indicate the token to retrieve the preceding page. Absence of this field denotes the +response as the initial page. + +**6.6.5.12.2. NextToken Field** + +This field SHALL indicate the token to retrieve the next page. Absence of this field denotes the +response as the last page. + +**6.6.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Channel­ +List +``` +``` +list[Chan­ +nelInfoS­ +truct] +``` +``` +empty R V CL +``` +``` +0x0001 Lineup LineupIn­ +foStruct +``` +``` +desc X null R V LI +``` +``` +0x0002 Cur­ +rentChan­ +nel +``` +``` +ChannelIn­ +foStruct +``` +``` +desc X null R V O +``` +**6.6.6.1. ChannelList Attribute** + +This attribute SHALL provide the list of supported channels. + +**6.6.6.2. Lineup Attribute** + +This attribute SHALL identify the channel lineup using external data sources. + +**6.6.6.3. CurrentChannel Attribute** + +This attribute SHALL contain the current channel. When supported but a channel is not currently +tuned to (if a content application is in foreground), the value of the field SHALL be null. + +**6.6.7. Commands** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 497 +``` + +``` +ID Name Direction Response Access Quality Confor­ +mance +0x00 ChangeCha +nnel +``` +``` +client ⇒ +server +``` +``` +ChangeChan­ +nelResponse +``` +### O CL | LI + +``` +0x01 ChangeCha +nnelRe­ +sponse +``` +``` +client ⇐ +server +``` +### N CL | LI + +``` +0x02 ChangeCha +nnelByNum­ +ber +``` +``` +client ⇒ +server +``` +### Y O M + +``` +0x03 SkipChan­ +nel +``` +``` +client ⇒ +server +``` +### Y O M + +``` +0x04 GetPro­ +gramGuide +``` +``` +client ⇒ +server +``` +``` +Pro­ +gramGuideR +esponse +``` +### O EG + +``` +0x05 Pro­ +gramGuide +Response +``` +``` +client ⇐ +server +``` +### N EG + +``` +0x06 RecordPro­ +gram +``` +``` +client ⇒ +server +``` +### Y O RP & EG + +``` +0x07 Cancel­ +RecordPro­ +gram +``` +``` +client ⇒ +server +``` +### Y O RP & EG + +**6.6.7.1. ChangeChannel Command** + +Change the channel to the channel case-insensitive exact matching the value passed as an argu­ +ment. + +The match priority order SHALL be: Identifier, AffiliateCallSign, CallSign, Name, Number. In the +match string, the Channel number should be presented in the "Major.Minor" format, such as "13.1". + +Upon receipt, this SHALL generate a ChangeChannelResponse command. + +Upon success, the CurrentChannel attribute, if supported, SHALL be updated to reflect the change. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Match string M +``` +**6.6.7.1.1. Match Field** + +This field SHALL contain a user-input string to match in order to identify the target channel. + +``` +Page 498 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.6.7.2. ChangeChannelResponse Command** + +This command SHALL be generated in response to a ChangeChannel command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status StatusEnum desc M +1 Data string any O +``` +**6.6.7.2.1. Status Field** + +This field SHALL indicate the status of the command which resulted in this response. + +**6.6.7.2.2. Data Field** + +This field SHALL indicate Optional app-specific data. + +**6.6.7.3. ChangeChannelByNumber Command** + +Change the channel to the channel with the given Number in the _ChannelList_ attribute. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 MajorNum­ +ber +``` +``` +uint16 all M +``` +``` +1 MinorNum­ +ber +``` +``` +uint16 all M +``` +**6.6.7.3.1. MajorNumber Field** + +This field SHALL indicate the channel major number value (ATSC format) to which the channel +should change. + +**6.6.7.3.2. MinorNumber Field** + +This field SHALL indicate the channel minor number value (ATSC format) to which the channel +should change. + +**6.6.7.4. SkipChannel Command** + +This command provides channel up and channel down functionality, but allows channel index +jumps of size _Count_. + +When the value of the increase or decrease is larger than the number of channels remaining in the +given direction, then the behavior SHALL be to return to the beginning (or end) of the channel list +and continue. For example, if the current channel is at index 0 and count value of -1 is given, then +the current channel should change to the last channel. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 499 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Count int16 all M +``` +**6.6.7.4.1. Count Field** + +This field SHALL indicate the number of steps to increase (Count is positive) or decrease (Count is +negative) the current channel. + +**6.6.7.5. GetProgramGuide Command** + +This command retrieves the program guide. It accepts several filter parameters to return specific +schedule and program information from a content app. The command shall receive in response a +ProgramGuideResponse. Standard error codes SHALL be used when arguments provided are not +valid. For example, if StartTime is greater than EndTime, the status code INVALID_ACTION SHALL +be returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StartTime epoch-s M +1 EndTime epoch-s M +2 ChannelList list[Chan­ +nelInfoS­ +truct] +``` +``` +max 255 empty O +``` +``` +3 PageToken PageToken­ +Struct +``` +``` +X null O +``` +``` +5 Record­ +ingFlag +``` +``` +Record­ +ingFlag­ +Bitmap +``` +``` +X null O +``` +``` +6 Exter­ +nalIDList +``` +``` +list[Addition­ +alInfoStruct] +``` +``` +max 255 empty O +``` +``` +7 Data octstr max 8092 MS O +``` +**6.6.7.5.1. StartTime Field** + +This field SHALL indicate the beginning of the time window for which program guide entries are to +be retrieved, as a UTC time. Entries with a start time on or after this value will be included in the +results. + +**6.6.7.5.2. EndTime Field** + +This field SHALL indicate the end of the time window for which program guide entries are to be +retrieved, as a UTC time. Entries with an end time on or before this value will be included in the +results. This field can represent a past or future value but SHALL be greater than the StartTime. + +``` +Page 500 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.6.7.5.3. ChannelList Field** + +This field SHALL indicate the set of channels for which program guide entries should be fetched. By +providing a list of channels in this field, the response will only include entries corresponding to the +specified channels. + +**6.6.7.5.4. PageToken Field** + +This field SHALL indicate the pagination token used for managing pagination progression. + +**6.6.7.5.5. RecordingFlag Field** + +This field SHALL indicate the flags of the programs for which entries should be fetched. + +**6.6.7.5.6. ExternalIDList Field** + +This field SHALL indicate the list of additional external content identifiers. + +**6.6.7.5.7. Data Field** + +This field SHALL indicate Optional app-specific data. + +**6.6.7.6. ProgramGuideResponse Command** + +This command is a response to the GetProgramGuide command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Paging ChannelPag­ +ingStruct +``` +### M + +``` +1 Program­ +List +``` +``` +list[Program­ +Struct] +``` +``` +empty M +``` +**6.6.7.6.1. Paging Field** + +This field SHALL indicate the necessary pagination attributes that define information for both the +succeeding and preceding data pages. + +**6.6.7.6.2. ProgramList Field** + +This field SHALL indicate the list of programs. + +**6.6.7.7. RecordProgram Command** + +Record a specific program or series when it goes live. This functionality enables DVR recording fea­ +tures. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 501 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ProgramI­ +dentifier +``` +``` +string max 255 M +``` +``` +1 Shoul­ +dRecord­ +Series +``` +``` +bool M +``` +``` +2 Exter­ +nalIDList +``` +``` +list[Addition­ +alInfoStruct] +``` +``` +max 255 empty O +``` +``` +3 Data octstr max 8092 MS O +``` +**6.6.7.7.1. ProgramIdentifier Field** + +This field SHALL indicate the program identifier for the program that should be recorded. This +value is provided by the identifier field in ProgramStruct. + +**6.6.7.7.2. ShouldRecordSeries Field** + +This field SHALL indicate whether the whole series associated to the program should be recorded. +For example, invoking record program on an episode with that flag set to true, the target should +schedule record the whole series. + +**6.6.7.7.3. ExternalIDList Field** + +This field, if present, SHALL indicate the list of additional external content identifiers. + +**6.6.7.7.4. Data Field** + +This field, if present, SHALL indicate app-specific data. + +**6.6.7.8. CancelRecordProgram Command** + +Cancel recording for a specific program or series. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ProgramI­ +dentifier +``` +``` +string max 255 M +``` +``` +1 Shoul­ +dRecord­ +Series +``` +``` +bool M +``` +``` +2 Exter­ +nalIDList +``` +``` +list[Addition­ +alInfoStruct] +``` +``` +max 255 empty O +``` +``` +3 Data octstr max 8092 MS O +``` +``` +Page 502 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.6.7.8.1. ProgramIdentifier Field** + +This field SHALL indicate the program identifier for the program that should be cancelled from +recording. This value is provided by the identifier field in ProgramStruct. + +**6.6.7.8.2. ShouldRecordSeries Field** + +This field SHALL indicate whether the whole series associated to the program should be cancelled +from recording. For example, invoking record program on an episode with that flag set to true, the +target should schedule record the whole series. + +**6.6.7.8.3. ExternalIDList Field** + +This field, if present, SHALL indicate the list of additional external content identifiers. + +**6.6.7.8.4. Data Field** + +This field, if present, SHALL indicate app-specific data. + +**6.7. Content Launcher Cluster** + +This cluster provides an interface for launching content on a Video Player device such as a Stream­ +ing Media Player, Smart TV or Smart Screen. + +This cluster would be supported on a Video Player device or devices that can playback content, +such as a Streaming Media Player, Smart TV or Smart Screen. This cluster supports playing back +content referenced by URL. It supports finding content by type and global identifier, and either +playing the content or displaying the search results. + +The cluster server for Content Launcher is implemented by an endpoint that can launch content, +such as a Video Player, or an endpoint representing a Content App on such a device. + +When this cluster is implemented for an Content App Endpoint (Endpoint with type “Content App” +and having an Application Basic cluster), the Video Player device SHALL launch the application +when a client invokes the LaunchContent or LaunchURL commands. + +**6.7.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Add Seasons, Episode, Any and CurrentContext +to search, Added Text/Audio tracks support with +PlaybackPreferences field +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 503 +``` + +**6.7.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint CONTENTLAUNCHER +``` +**6.7.3. Cluster ID** + +``` +ID Name +0x050A Content Launcher +``` +**6.7.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 CS ContentSearch Device supports con­ +tent search (non-app +specific) +1 UP URLPlayback Device supports basic +URL-based file play­ +back +2 AS AdvancedSeek Enables clients to +implement more +advanced media seek­ +ing behavior in their +user interface, such as +for example a "seek +bar". +3 TT TextTracks Device or app supports +Text Tracks. +4 AT AudioTracks Device or app supports +Audio Tracks. +``` +**6.7.5. Data Types** + +**6.7.5.1. SupportedProtocolsBitmap Type** + +This data type is derived from map32. + +``` +Bit Name Summary +0 DASH Device supports Dynamic Adap­ +tive Streaming over HTTP +(DASH) +``` +``` +Page 504 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary +1 HLS Device supports HTTP Live +Streaming (HLS) +``` +**6.7.5.2. StatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Success Command succeeded M +1 URLNotAvailable Requested URL could +not be reached by +device. +``` +### M + +``` +2 AuthFailed Requested URL +returned 401 error +code. +``` +### M + +``` +3 TextTrackNotAvail­ +able +``` +``` +Requested Text Track +(in PlaybackPrefer­ +ences) not available +``` +### TT + +``` +4 AudioTrackNotAvail­ +able +``` +``` +Requested Audio Track +(in PlaybackPrefer­ +ences) not available +``` +### AT + +**6.7.5.3. ParameterEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Actor Actor represents an +actor credited in video +media content; for +example, “Gaby Hoff­ +man” +``` +### M + +``` +1 Channel Channel represents the +identifying data for a +television channel; for +example, "PBS" +``` +### M + +``` +2 Character A character repre­ +sented in video media +content; for example, +“Snow White” +``` +### M + +``` +3 Director A director of the video +media content; for +example, “Spike Lee” +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 505 +``` + +``` +Value Name Summary Conformance +4 Event An event is a reference +to a type of event; +examples would +include sports, music, +or other types of +events. For example, +searching for "Football +games" would search +for a 'game' event +entity and a 'football' +sport entity. +``` +### M + +``` +5 Franchise A franchise is a video +entity which can repre­ +sent a number of video +entities, like movies or +TV shows. For example, +take the fictional fran­ +chise "Intergalactic +Wars" which repre­ +sents a collection of +movie trilogies, as well +as animated and live +action TV shows. This +entity type was intro­ +duced to account for +requests by customers +such as "Find Inter­ +galactic Wars movies", +which would search for +all 'Intergalactic Wars' +programs of the MOVIE +MediaType, rather than +attempting to match to +a single title. +``` +### M + +``` +6 Genre Genre represents the +genre of video media +content such as action, +drama or comedy. +``` +### M + +``` +7 League League represents the +categorical information +for a sporting league; +for example, "NCAA" +``` +### M + +Page 506 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Value Name Summary Conformance** + +8 **Popularity** Popularity indicates +whether the user asks +for popular content. + +### M + +9 **Provider** The provider (MSP) the +user wants this media +to be played on; for +example, "Netflix". + +### M + +10 **Sport** Sport represents the +categorical information +of a sport; for example, +football + +### M + +11 **SportsTeam** SportsTeam represents +the categorical infor­ +mation of a profes­ +sional sports team; for +example, "University of +Washington Huskies" + +### M + +12 **Type** The type of content +requested. Supported +types are "Movie", +"MovieSeries", +"TVSeries", "TVSeason", +"TVEpisode", "Trailer", +"SportsEvent", +"LiveEvent", and +"Video" + +### M + +13 **Video** Video represents the +identifying data for a +specific piece of video +content; for example, +"Manchester by the +Sea". + +### M + +14 **Season** Season represents the +specific season number +within a TV series. + +### O + +15 **Episode** Episode represents a +specific episode num­ +ber within a Season in +a TV series. + +### O + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 507 +``` + +``` +Value Name Summary Conformance +16 Any Represents a search +text input across many +parameter types or +even outside of the +defined param types. +``` +### O + +**6.7.5.4. MetricTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Pixels Dimensions defined in +a number of Pixels +``` +### M + +``` +1 Percentage Dimensions defined as +a percentage +``` +### M + +**6.7.5.4.1. Pixels Value** + +This value is used for dimensions defined in a number of Pixels. + +**6.7.5.4.2. Percentage Value** + +This value is for dimensions defined as a percentage of the overall display dimensions. For exam­ +ple, if using a Percentage Metric type for a Width measurement of 50.0, against a display width of +1920 pixels, then the resulting value used would be 960 pixels (50.0% of 1920) for that dimension. +Whenever a measurement uses this Metric type, the resulting values SHALL be rounded ("floored") +towards 0 if the measurement requires an integer final value. + +**6.7.5.5. AdditionalInfoStruct Type** + +This object defines additional name=value pairs that can be used for identifying content. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Name string max 256 M +1 Value string max 8192 M +``` +**6.7.5.5.1. Name Field** + +This field SHALL indicate the name of external id, ex. "musicbrainz". + +**6.7.5.5.2. Value Field** + +This field SHALL indicate the value for external id, ex. "ST0000000666661". + +``` +Page 508 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.7.5.6. ParameterStruct Type** + +This object defines inputs to a search for content for display or playback. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Type Parame­ +terEnum +``` +``` +all M +``` +``` +1 Value string max 1024 M +2 Exter­ +nalIDList +``` +``` +list[Addi­ +tionalIn­ +foStruct] +``` +``` +all empty O +``` +**6.7.5.6.1. Type Field** + +This field SHALL indicate the entity type. + +**6.7.5.6.2. Value Field** + +This field SHALL indicate the entity value, which is a search string, ex. “Manchester by the Sea”. + +**6.7.5.6.3. ExternalIDList Field** + +This field SHALL indicate the list of additional external content identifiers. + +**6.7.5.7. ContentSearchStruct Type** + +This object defines inputs to a search for content for display or playback. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Parame­ +terList +``` +``` +list[Para­ +meter­ +Struct] +``` +``` +all 0 M +``` +**6.7.5.7.1. ParameterList Field** + +This field SHALL indicate the list of parameters comprising the search. If multiple parameters are +provided, the search parameters SHALL be joined with 'AND' logic. e.g. action movies with Tom +Cruise will be represented as [{Actor: 'Tom Cruise'}, {Type: 'Movie'}, {Genre: 'Action'}] + +**6.7.5.8. DimensionStruct Type** + +This object defines dimension which can be used for defining Size of background images. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Width double MS M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 509 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +1 Height double MS M +2 Metric Metric­ +TypeEnum +``` +### M + +**6.7.5.8.1. Width Field** + +This field SHALL indicate the width using the metric defined in Metric + +**6.7.5.8.2. Height Field** + +This field SHALL indicate the height using the metric defined in Metric + +**6.7.5.8.3. Metric Field** + +This field SHALL indicate metric used for defining Height/Width. + +**6.7.5.9. StyleInformationStruct Type** + +This object defines style information which can be used by content providers to change the Media +Player’s style related properties. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ImageURL string max 8192 MS O +1 Color string 7,9 MS O +2 Size Dimen­ +sionStruct +``` +### MS O + +**6.7.5.9.1. ImageURL Field** + +This field SHALL indicate the URL of image used for Styling different Video Player sections like +Logo, Watermark etc. The syntax of this field SHALL follow the syntax as specified in RFC 1738 and +SHALL use the https scheme. + +**6.7.5.9.2. Color Field** + +This field SHALL indicate the color, in RGB or RGBA, used for styling different Video Player sections +like Logo, Watermark, etc. The value SHALL conform to the 6-digit or 8-digit format defined for CSS +sRGB hexadecimal color notation [https://www.w3.org/TR/css-color-4/#hex-notation]. Examples: + +- #76DE19 for R=0x76, G=0xDE, B=0x19, A absent +- #76DE1980 for R=0x76, G=0xDE, B=0x19, A=0x80 + +**6.7.5.9.3. Size Field** + +This field SHALL indicate the size of the image used for Styling different Video Player sections like + +``` +Page 510 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Logo, Watermark etc. + +**6.7.5.10. BrandingInformationStruct Type** + +This object defines Branding Information which can be provided by the client in order to customize +the skin of the Video Player during playback. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Provider­ +Name +``` +``` +string max 256 M +``` +``` +1 Background StyleInfor­ +mationStruct +``` +### MS O + +``` +2 Logo StyleInfor­ +mationStruct +``` +### MS O + +``` +3 ProgressBar StyleInfor­ +mationStruct +``` +### MS O + +``` +4 Splash StyleInfor­ +mationStruct +``` +### MS O + +``` +5 WaterMark StyleInfor­ +mationStruct +``` +### MS O + +**6.7.5.10.1. ProviderName Field** + +This field SHALL indicate name of the provider for the given content. + +**6.7.5.10.2. Background Field** + +This field SHALL indicate background of the Video Player while content launch request is being +processed by it. This background information MAY also be used by the Video Player when it is in +idle state. + +**6.7.5.10.3. Logo Field** + +This field SHALL indicate the logo shown when the Video Player is launching. This is also used +when the Video Player is in the idle state and Splash field is not available. + +**6.7.5.10.4. ProgressBar Field** + +This field SHALL indicate the style of progress bar for media playback. + +**6.7.5.10.5. Splash Field** + +This field SHALL indicate the screen shown when the Video Player is in an idle state. If this prop­ +erty is not populated, the Video Player SHALL default to logo or the provider name. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 511 +``` + +**6.7.5.10.6. Watermark Field** + +This field SHALL indicate watermark shown when the media is playing. + +**6.7.5.11. PlaybackPreferencesStruct Type** + +PlaybackPreferencesStruct defines the preferences sent by the client to the receiver in the Content­ +Launcher LaunchURL or LaunchContent commands. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PlaybackPo­ +sition +``` +``` +uint64 X AS +``` +``` +1 TextTrack TrackPrefer­ +enceStruct +``` +### X TT + +``` +2 Audio­ +Tracks +``` +``` +list[Track­ +PreferenceS­ +truct] +``` +### X AT + +**6.7.5.11.1. PlaybackPosition Field** + +This field SHALL indicate the preferred position (in milliseconds) in the media to launch playback +from. In case the position falls in the middle of a frame, the server SHALL set the position to the +beginning of that frame and set the SampledPosition attribute on the MediaPlayback cluster accord­ +ingly. A value of null SHALL indicate that playback position is not applicable for the current state of +the media playback. (For example : Live media with no known duration and where seek is not sup­ +ported). + +**6.7.5.11.2. TextTrack Field** + +This field SHALL indicate the user’s preferred Text Track. A value of null SHALL indicate that the +user did not specify a preferred Text Track on the client. In such a case, the decision to display and +select a Text Track is up to the server. + +**6.7.5.11.3. AudioTracks Field** + +This field SHALL indicate the list of the user’s preferred Audio Tracks. If the list contains multiple +values, each AudioTrack must also specify a unique audioOutputIndex to play the track on. A value +of null SHALL indicate that the user did not specify a preferred Audio Track on the client. In such a +case, the decision to play and select an Audio Track is up to the server. + +**6.7.5.12. TrackPreferenceStruct Type** + +This structure defines Text/Audio Track preferences. + +``` +Page 512 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Language­ +Code +``` +``` +string max 32 M +``` +``` +1 Characteris­ +tics +``` +``` +list[Charac­ +teristi­ +cEnum] +``` +``` +X null O +``` +``` +2 AudioOut­ +putIndex +``` +``` +uint8 X AT +``` +**6.7.5.12.1. LanguageCode Field** + +This field SHALL contain one of the standard Tags for Identifying Languages RFC 5646, which iden­ +tifies the primary language used in the Track. + +**6.7.5.12.2. Characteristics Field** + +This field SHALL contain a list of enumerated CharacteristicEnum values that indicate a purpose, +trait or feature associated with the Track. A value of null SHALL indicate that there are no Charac­ +teristics corresponding to the Track. + +**6.7.5.12.3. AudioOutputIndex Field** + +This field if present SHALL indicate the index of the OutputInfoStruct from the OutputList attribute +(from the AudioOutput cluster) and indicates which audio output the Audio Track should be played +on. + +This field SHALL NOT be present if the track is not an audio track. + +If the track is an audio track, this field MUST be present. A value of null SHALL indicate that the +server can choose the audio output(s) to play the Audio Track on. + +**6.7.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Accept­ +Header +``` +``` +list[string] max +100[max +1024] +``` +``` +N empty R V UP +``` +``` +0x0001 Support­ +edStream­ +ingProto­ +cols +``` +``` +Supported­ +Protocols­ +Bitmap +``` +### N 0 R V UP + +**6.7.6.1. AcceptHeader Attribute** + +This attribute SHALL provide a list of content types supported by the Video Player or Content App + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 513 +``` + +in the form of entries in the HTTP "Accept" request header. + +**6.7.6.2. SupportedStreamingProtocols Attribute** + +This attribute SHALL provide information about supported streaming protocols. + +**6.7.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 LaunchCon­ +tent +``` +``` +client ⇒ server LauncherRe­ +sponse +``` +### O CS + +``` +0x01 LaunchURL client ⇒ server LauncherRe­ +sponse +``` +### O UP + +``` +0x02 LauncherRe­ +sponse +``` +``` +client ⇐ server N CS | UP +``` +**6.7.7.1. LaunchContent Command** + +Upon receipt, this SHALL launch the specified content with optional search criteria. + +This command returns a Launch Response. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Search Con­ +tentSearch­ +Struct +``` +``` +desc M +``` +``` +1 AutoPlay bool desc M +2 Data string MS O +3 Playback­ +Preferences +``` +``` +Playback­ +Prefer­ +encesStruct +``` +``` +all MS O +``` +``` +4 UseCurrent­ +Context +``` +``` +bool desc TRUE O +``` +**6.7.7.1.1. Search Field** + +This field SHALL indicate the content to launch. + +**6.7.7.1.2. AutoPlay Field** + +This field SHALL indicate whether to automatically start playing content, where: + +- TRUE means best match should start playing automatically. +- FALSE means matches should be displayed on screen for user selection. + +``` +Page 514 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.7.7.1.3. Data Field** + +This field, if present, SHALL indicate app-specific data. + +**6.7.7.1.4. PlaybackPreferences Field** + +This field, if present, SHALL indicate the user’s preferred Text/AudioTracks and playbackPosition +for the media, sent from the client to the server. If the server does not find an available track for +the title being played exactly matching a Track requested here, in the list of available tracks, it may +default to picking another track that closely matches the requested track. Alternately, it may go with +user preferences set on the server side (it will use this option if these PlaybackPreferences are not +specified). In the case of text tracks, that may mean that the subtitle text is not displayed at all. In +the cases where the preferred Text/AudioTracks are not available, the server SHALL return the +TextTrackNotAvailable and/or AudioTrackNotAvailable Status(es) in the LauncherResponse. + +**6.7.7.1.5. UseCurrentContext Field** + +This field, if present, SHALL indicate whether to consider the context of current ongoing activity on +the receiver to fulfill the request. For example if the request only includes data in ContentSearch +that specifies an Episode number, and UseCurrentContent is set to TRUE, if there is a TV series on +going, the request refers to the specific episode of the ongoing season of the TV series. TRUE means +current activity context MAY be considered FALSE means current activity context SHALL NOT be +considered + +**6.7.7.2. LaunchURL Command** + +Upon receipt, this SHALL launch content from the specified URL. + +The content types supported include those identified in the AcceptHeader and SupportedStreaming­ +Protocols attributes. + +A check SHALL be made to ensure the URL is secure (uses HTTPS). + +When playing a video stream in response to this command, an indication (ex. visual) of the identity +of the origin node of the video stream SHALL be provided. This could be in the form of a friendly +name label which uniquely identifies the node to the user. This friendly name label is typically +assigned by the Matter Admin (ex. TV) at the time of commissioning and, when it’s a device, is often +editable by the user. It might be a combination of a company name and friendly name, for example, +”Acme” or “Acme Streaming Service on Alice’s Phone”. + +This command returns a Launch Response. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ContentURL string any M +1 Dis­ +playString +``` +``` +string any MS O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 515 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +2 BrandingIn­ +formation +``` +``` +BrandingIn­ +formation­ +Struct +``` +``` +any MS O +``` +``` +3 Playback­ +Preferences +``` +``` +Playback­ +Prefer­ +encesStruct +``` +``` +any MS O +``` +**6.7.7.2.1. ContentURL Field** + +This field SHALL indicate the URL of content to launch. The syntax of this field SHALL follow the +syntax as specified in RFC 1738 and SHALL use the https scheme. + +**6.7.7.2.2. DisplayString Field** + +This field, if present, SHALL provide a string that MAY be used to describe the content being +accessed at the given URL. + +**6.7.7.2.3. BrandingInformation Field** + +This field, if present, SHALL indicate the branding information that MAY be displayed when playing +back the given content. + +**6.7.7.2.4. PlaybackPreferences Field** + +This field, if present, SHALL indicate the user’s preferred Text/AudioTracks and playbackPosition +for the media, sent from the client to the server. If the server does not find an available track for +the title being played exactly matching a Track requested here, in the list of available tracks, it may +default to picking another track that closely matches the requested track. Alternately, it may go with +user preferences set on the server side (it will use this option if these PlaybackPreferences are not +specified). In the case of text tracks, that may mean that the subtitle text is not displayed at all. In +the cases where the preferred Text/AudioTracks are not available, the server SHALL return the +TextTrackNotAvailable and/or AudioTrackNotAvailable Status(es) in the LauncherResponse. + +**6.7.7.3. LauncherResponse Command** + +This command SHALL be generated in response to LaunchContent and LaunchURL commands. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status StatusEnum all M +1 Data string MS O +``` +**6.7.7.3.1. Status Field** + +This field SHALL indicate the status of the command which resulted in this response. + +``` +Page 516 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.7.7.3.2. Data Field** + +This field SHALL indicate Optional app-specific data. + +**6.8. Keypad Input Cluster** + +This cluster provides an interface for key code based input and control on a device like a Video +Player or an endpoint like a Content App. This may include text or action commands such as UP, +DOWN, and SELECT. + +This cluster would be supported on Video Player devices as well as devices that support remote +control input from a keypad or remote. This cluster provides the list of supported keypad inputs +and provides a command for sending them. + +The cluster server for Keypad Input is implemented by a device that can receive keypad input, such +as a Video Player, or an endpoint that can receive keypad input, such as a Content App. + +The key codes used are those defined in the HDMI CEC specification (see HDMI). + +Devices MAY understand a subset of these key codes. Feature flags are used to indicate a specific +subset that is supported. Device MAY support additional codes beyond what is indicated in feature +flags. + +**6.8.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**6.8.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint KEYPADINPUT +``` +**6.8.3. Cluster ID** + +``` +ID Name +0x0509 Keypad Input +``` +**6.8.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 517 +``` + +``` +Bit Code Feature Summary +0 NV NavigationKeyCodes Supports UP, DOWN, +LEFT, RIGHT, SELECT, +BACK, EXIT, MENU +1 LK LocationKeys Supports CEC keys 0x0A +(Settings) and 0x09 +(Home) +2 NK NumberKeys Supports numeric input +0..9 +``` +**6.8.5. Data Types** + +**6.8.5.1. StatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Success Succeeded M +1 UnsupportedKey Key code is not sup­ +ported. +``` +### M + +``` +2 InvalidKeyInCur­ +rentState +``` +``` +Requested key code is +invalid in the context of +the responder’s current +state. +``` +### M + +**6.8.5.2. CecKeyCodeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Conformance +0x00 Select M +0x01 Up M +0x02 Down M +0x03 Left M +0x04 Right M +0x05 RightUp M +0x06 RightDown M +0x07 LeftUp M +0x08 LeftDown M +0x09 RootMenu M +0x0A SetupMenu M +``` +``` +Page 518 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Value Name Conformance** + +0x0B **ContentsMenu** M + +0x0C **FavoriteMenu** M + +0x0D **Exit** M + +0x10 **MediaTopMenu** M + +0x11 **MediaContextSensitiveMenu** M + +0x1D **NumberEntryMode** M + +0x1E **Number11** M + +0x1F **Number12** M + +0x20 **Number0OrNumber10** M + +0x21 **Numbers1** M + +0x22 **Numbers2** M + +0x23 **Numbers3** M + +0x24 **Numbers4** M + +0x25 **Numbers5** M + +0x26 **Numbers6** M + +0x27 **Numbers7** M + +0x28 **Numbers8** M + +0x29 **Numbers9** M + +0x2A **Dot** M + +0x2B **Enter** M + +0x2C **Clear** M + +0x2F **NextFavorite** M + +0x30 **ChannelUp** M + +0x31 **ChannelDown** M + +0x32 **PreviousChannel** M + +0x33 **SoundSelect** M + +0x34 **InputSelect** M + +0x35 **DisplayInformation** M + +0x36 **Help** M + +0x37 **PageUp** M + +0x38 **PageDown** M + +0x40 **Power** M + +0x41 **VolumeUp** M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 519 +``` + +``` +Value Name Conformance +0x42 VolumeDown M +0x43 Mute M +0x44 Play M +0x45 Stop M +0x46 Pause M +0x47 Record M +0x48 Rewind M +0x49 FastForward M +0x4A Eject M +0x4B Forward M +0x4C Backward M +0x4D StopRecord M +0x4E PauseRecord M +0x4F Reserved M +0x50 Angle M +0x51 SubPicture M +0x52 VideoOnDemand M +0x53 ElectronicProgramGuide M +0x54 TimerProgramming M +0x55 InitialConfiguration M +0x56 SelectBroadcastType M +0x57 SelectSoundPresentation M +0x60 PlayFunction M +0x61 PausePlayFunction M +0x62 RecordFunction M +0x63 PauseRecordFunction M +0x64 StopFunction M +0x65 MuteFunction M +0x66 RestoreVolumeFunction M +0x67 TuneFunction M +0x68 SelectMediaFunction M +0x69 SelectAvInputFunction M +0x6A SelectAudioInputFunction M +``` +Page 520 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +Value Name Conformance +0x6B PowerToggleFunction M +0x6C PowerOffFunction M +0x6D PowerOnFunction M +0x71 F1Blue M +0x72 F2Red M +0x73 F3Green M +0x74 F4Yellow M +0x75 F5 M +0x76 Data M +``` +**6.8.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 SendKey client ⇒ server SendKeyRe­ +sponse +``` +### O M + +``` +0x01 SendKeyRe­ +sponse +``` +``` +client ⇐ server N M +``` +**6.8.6.1. SendKey Command** + +Upon receipt, this SHALL process a keycode as input to the media endpoint. + +If a device has multiple media endpoints implementing this cluster, such as a casting video player +endpoint with one or more content app endpoints, then only the endpoint receiving the command +SHALL process the keycode as input. In other words, a specific content app endpoint SHALL NOT +process a keycode received by a different content app endpoint. + +If a second SendKey request with the same KeyCode value is received within 200 ms, then the end­ +point will consider the first key press to be a press and hold. When such a repeat KeyCode value is +not received within 200 ms, then the endpoint will consider the last key press to be a release. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 KeyCode CecKey­ +CodeEnum +``` +``` +all M +``` +**6.8.6.1.1. KeyCode Field** + +This field SHALL indicate the key code to process. + +**6.8.6.2. SendKeyResponse Command** + +This command SHALL be generated in response to a SendKey command. The data for this com­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 521 +``` + +mand SHALL be as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status StatusEnum all M +``` +**6.8.6.2.1. Status Field** + +This field SHALL indicate the status of the request. + +**6.9. Media Input Cluster** + +This cluster provides an interface for controlling the Input Selector on a media device such as a +Video Player. + +This cluster would be implemented on TV and other media streaming devices, as well as devices +that provide input to or output from such devices. + +This cluster provides the list of available inputs and provides commands for selecting and renam­ +ing them. + +The cluster server for Media Input is implemented by a device that has selectable input, such as a +Video Player device. + +**6.9.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**6.9.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint MEDIAINPUT +``` +**6.9.3. Cluster ID** + +``` +ID Name +0x0507 Media Input +``` +**6.9.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Page 522 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Summary +0 NU NameUpdates Supports updates to the +input names +``` +**6.9.5. Data Types** + +**6.9.5.1. InputTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Internal Indicates content not +coming from a physical +input. +``` +### M + +``` +1 Aux M +2 Coax M +3 Composite M +4 HDMI M +5 Input M +6 Line M +7 Optical M +8 Video M +9 SCART M +10 USB M +11 Other M +``` +**6.9.5.2. InputInfoStruct Type** + +This contains information about an input. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Index uint8 all M +1 InputType InputType­ +Enum +``` +``` +desc M +``` +``` +2 Name string M +3 Descrip­ +tion +``` +``` +string M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 523 +``` + +**6.9.5.2.1. Index Field** + +This field SHALL indicate the unique index into the list of Inputs. + +**6.9.5.2.2. InputType Field** + +This field SHALL indicate the type of input + +**6.9.5.2.3. Name Field** + +This field SHALL indicate the input name, such as “HDMI 1”. This field may be blank, but SHOULD +be provided when known. + +**6.9.5.2.4. Description Field** + +This field SHALL indicate the user editable input description, such as “Living room Playstation”. +This field may be blank, but SHOULD be provided when known. + +**6.9.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 InputList list[InputIn +foStruct] +``` +### R V M + +``` +0x0001 CurrentIn­ +put +``` +``` +uint8 all R V M +``` +**6.9.6.1. InputList Attribute** + +This attribute SHALL provide a list of the media inputs supported by the device. + +**6.9.6.2. CurrentInput Attribute** + +This attribute SHALL contain the value of the index field of the currently selected InputInfoStruct. + +**6.9.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 SelectInput client ⇒ server Y O M +0x01 ShowInputSta­ +tus +``` +``` +client ⇒ server Y O M +``` +``` +0x02 HideInputSta­ +tus +``` +``` +client ⇒ server Y O M +``` +``` +0x03 RenameInput client ⇒ server Y M NU +``` +**6.9.7.1. SelectInput Command** + +Upon receipt, this command SHALL change the media input on the device to the input at a specific + +``` +Page 524 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +index in the Input List. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Index uint8 all M +``` +**6.9.7.1.1. Index Field** + +This field SHALL indicate the index field of the InputInfoStruct from the InputList attribute in +which to change to. + +**6.9.7.2. ShowInputStatus Command** + +Upon receipt, this command SHALL display the active status of the input list on screen. + +**6.9.7.3. HideInputStatus Command** + +Upon receipt, this command SHALL hide the input list from the screen. + +**6.9.7.4. RenameInput Command** + +Upon receipt, this command SHALL rename the input at a specific index in the Input List. + +Updates to the input name SHALL appear in the device’s settings menus. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Index uint8 all M +1 Name string all M +``` +**6.10. Media Playback Cluster** + +This cluster provides an interface for controlling Media Playback (PLAY, PAUSE, etc) on a media +device such as a TV, Set-top Box, or Smart Speaker. + +This cluster server would be supported on Video Player devices or endpoints that provide media +playback, such as a Content App. This cluster provides an interface for controlling Media Playback. + +**6.10.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Added Text/Audio tracks support, Audio-while- +advancing (AA) feature, StateChanged event +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 525 +``` + +**6.10.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint MEDIAPLAYBACK +``` +**6.10.3. Cluster ID** + +``` +ID Name +0x0506 Media Playback +``` +**6.10.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 AS AdvancedSeek Advanced media seek­ +ing +1 VS VariableSpeed Variable speed play­ +back +2 TT TextTracks Text Tracks +3 AT AudioTracks Audio Tracks +4 AA AudioAdvance Can play audio during +fast and slow playback +speeds +``` +**6.10.4.1. AdvancedSeek Feature** + +This feature provides access to the time offset location within current playback media and allows +for jumping to a specific location using time offsets. This enables clients to implement more +advanced media seeking behavior in their user interface, for instance a "seek bar". + +**6.10.4.2. VariableSpeed Feature** + +This feature is for a device which supports variable speed playback on media that supports it. + +**6.10.4.3. TextTracks Feature** + +This feature is for a device or app that supports Text Tracks. + +**6.10.4.4. AudioTracks Feature** + +This feature is for a device or app that supports Audio Tracks. + +**6.10.4.5. AudioAdvance Feature** + +This feature is for a device or app that supports playing audio during fast and slow advance and + +``` +Page 526 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +rewind (e.g., while playback speed is not 1). A device that supports this feature MAY only support +playing audio during certain speeds. + +A cluster implementing AA SHALL implement AS. + +**6.10.5. Data Types** + +**6.10.5.1. PlaybackStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Playing Media is currently play­ +ing (includes FF and +REW) +``` +### M + +``` +1 Paused Media is currently +paused +``` +### M + +``` +2 NotPlaying Media is not currently +playing +``` +### M + +``` +3 Buffering Media is not currently +buffering and playback +will start when buffer +has been filled +``` +### M + +**6.10.5.2. StatusEnum Type** + +Status Data Type is derived from enum8. + +``` +Value Name Summary Conformance +0 Success Succeeded M +1 InvalidStateForCom­ +mand +``` +``` +Requested playback +command is invalid in +the current playback +state. +``` +### M + +``` +2 NotAllowed Requested playback +command is not +allowed in the current +playback state. For +example, attempting to +fast-forward during a +commercial might +return NotAllowed. +``` +### M + +``` +3 NotActive This endpoint is not +active for playback. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 527 +``` + +``` +Value Name Summary Conformance +4 SpeedOutOfRange The FastForward or +Rewind Command was +issued but the media is +already playing back at +the fastest speed sup­ +ported by the server in +the respective direc­ +tion. +``` +### VS + +``` +5 SeekOutOfRange The Seek Command +was issued with a value +of position outside of +the allowed seek range +of the media. +``` +### AS + +**6.10.5.3. CharacteristicEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 ForcedSubtitles Textual information +meant for display when +no other text represen­ +tation is selected. It is +used to clarify dialogue, +alternate languages, +texted graphics or loca­ +tion/person IDs that are +not otherwise covered +in the dubbed/localized +audio. +``` +### M + +``` +1 DescribesVideo Textual or audio media +component containing +a textual description +(intended for audio +synthesis) or an audio +description describing +a visual component +``` +### M + +``` +2 EasyToRead Simplified or reduced +captions as specified in +[United States Code +Title 47 CFR +79.103(c)(9)]. +``` +### M + +``` +Page 528 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Value Name Summary Conformance** + +3 **FrameBased** A media characteristic +that indicates that a +track selection option +includes frame-based +content. + +### M + +4 **MainProgram** Main media compo­ +nent(s) which is/are +intended for presenta­ +tion if no other infor­ +mation is provided + +### M + +5 **OriginalContent** A media characteristic +that indicates that a +track or media selec­ +tion option contains +original content. + +### M + +6 **VoiceOverTranslation** A media characteristic +that indicates that a +track or media selec­ +tion option contains a +language translation +and verbal interpreta­ +tion of spoken dialog. + +### M + +7 **Caption** Textual media compo­ +nent containing tran­ +scriptions of spoken +dialog and auditory +cues such as sound +effects and music for +the hearing impaired. + +### M + +8 **Subtitle** Textual transcriptions +of spoken dialog. + +### M + +9 **Alternate** Textual media compo­ +nent containing tran­ +scriptions of spoken +dialog and auditory +cues such as sound +effects and music for +the hearing impaired. + +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 529 +``` + +``` +Value Name Summary Conformance +10 Supplementary Media content compo­ +nent that is supplemen­ +tary to a media content +component of a differ­ +ent media component +type. +``` +### M + +``` +11 Commentary Experience that con­ +tains a commentary +(e.g. director’s com­ +mentary) (typically +audio) +``` +### M + +``` +12 DubbedTranslation Experience that con­ +tains an element that is +presented in a different +language from the orig­ +inal (e.g. dubbed audio, +translated captions) +``` +### M + +``` +13 Description Textual or audio media +component containing +a textual description +(intended for audio +synthesis) or an audio +description describing +a visual component +``` +### M + +``` +14 Metadata Media component con­ +taining information +intended to be +processed by applica­ +tion specific elements. +``` +### M + +``` +15 EnhancedAudioIntel­ +ligibility +``` +``` +Experience containing +an element for +improved intelligibility +of the dialogue. +``` +### M + +Page 530 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +Value Name Summary Conformance +16 Emergency Experience that pro­ +vides information, +about a current emer­ +gency, that is intended +to enable the protection +of life, health, safety, +and property, and may +also include critical +details regarding the +emergency and how to +respond to the emer­ +gency. +``` +### M + +``` +17 Karaoke Textual representation +of a songs’ lyrics, usu­ +ally in the same lan­ +guage as the associated +song as specified in +[SMPTE ST 2067-2]. +``` +### M + +**6.10.5.4. PlaybackPositionStruct Type** + +This structure defines a playback position within a media stream being played. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 UpdatedAt epoch-us all M +1 Position uint64 all X M +``` +**6.10.5.4.1. UpdatedAt Field** + +This field SHALL indicate the time when the position was last updated. + +**6.10.5.4.2. Position Field** + +This field SHALL indicate the associated discrete position within the media stream, in milliseconds +from the beginning of the stream, being associated with the time indicated by the UpdatedAt field. +The Position SHALL NOT be greater than the duration of the media if duration is specified. The Posi­ +tion SHALL NOT be greater than the time difference between current time and start time of the +media when start time is specified. + +A value of null SHALL indicate that playback position is not applicable for the current state of the +media playback (For example : Live media with no known duration and where seek is not sup­ +ported). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 531 +``` + +**6.10.5.5. TrackStruct Type** + +This structure defines a uniquely identifiable Text Track or Audio Track. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ID string max 32 M +1 TrackAt­ +tributes +``` +``` +TrackAt­ +trib­ +utesStruct +``` +``` +all M +``` +**6.10.5.5.1. ID Field** + +This field SHALL indicate the Identifier for the Track which is unique within the Track catalog. The +Track catalog contains all the Text/Audio tracks corresponding to the main media content. + +**6.10.5.5.2. TrackAttributes Field** + +This field SHALL indicate the Attributes associated to the Track, like languageCode. + +**6.10.5.6. TrackAttributesStruct Type** + +This structure includes the attributes associated with a Text/Audio Track + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Language­ +Code +``` +``` +string max 32 M +``` +``` +1 Character­ +istics +``` +``` +list[Charac­ +teristi­ +cEnum] +``` +``` +all X null O +``` +``` +2 Display­ +Name +``` +``` +string max 256 X null O +``` +**6.10.5.6.1. LanguageCode Field** + +The value is a String containing one of the standard Tags for Identifying Languages RFC 5646, +which identifies the primary language used in the Track. + +**6.10.5.6.2. Characteristics Field** + +This is a list of enumerated CharacteristicEnum values that indicate a purpose, trait or feature asso­ +ciated with the Track. A value of null SHALL indicate that there are no Characteristics correspond­ +ing to the Track. + +**6.10.5.6.3. DisplayName Field** + +The value is a String containing a user displayable name for the Track. A value of null SHALL indi­ +cate that there is no DisplayName corresponding to the Track. + +``` +Page 532 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.10.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Cur­ +rentState +``` +``` +Playback­ +StateEnum +``` +``` +desc R V M +``` +``` +0x0001 StartTime epoch-us desc X null R V AS +0x0002 Duration uint64 desc X null R V AS +0x0003 Sampled­ +Position +``` +``` +Playback­ +Position­ +Struct +``` +``` +desc X null R V AS +``` +``` +0x0004 Playback­ +Speed +``` +``` +single desc 0 R V AS +``` +``` +0x0005 SeekRang +eEnd +``` +``` +uint64 desc X null R V AS +``` +``` +0x0006 SeekRang +eStart +``` +``` +uint64 desc X null R V AS +``` +``` +0x0007 ActiveAu­ +dioTrack +``` +``` +Track­ +Struct +``` +``` +desc X null R V AT +``` +``` +0x0008 Avail­ +ableAu­ +dioTracks +``` +``` +list[Track­ +Struct] +``` +``` +desc X null R V AT +``` +``` +0x0009 ActiveTex +tTrack +``` +``` +Track­ +Struct +``` +``` +desc X null R V TT +``` +``` +0x000A Available­ +Text­ +Tracks +``` +``` +list[Track­ +Struct] +``` +``` +desc X null R V TT +``` +**6.10.6.1. CurrentState Attribute** + +This attribute SHALL indicate the current playback state of media. + +During fast-forward, rewind, and other seek operations; this attribute SHALL be set to PLAYING. + +**6.10.6.2. StartTime Attribute** + +This attribute SHALL indicate the start time of the media, in case the media has a fixed start time +(for example, live stream or television broadcast), or null when start time does not apply to the cur­ +rent media (for example, video-on-demand). This time is a UTC time. The client needs to handle con­ +version to local time, as required, taking in account time zone and possible local DST offset. + +**6.10.6.3. Duration Attribute** + +This attribute SHALL indicate the duration, in milliseconds, of the current media being played back + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 533 +``` + +or null when duration is not applicable (for example, in live streaming content with no known +duration). This attribute SHALL never be 0. + +**6.10.6.4. SampledPosition Attribute** + +This attribute SHALL indicate the position of playback (Position field) at the time (UpdateAt field) +specified in the attribute. The client MAY use the SampledPosition attribute to compute the current +position within the media stream based on the PlaybackSpeed, PlaybackPositionStruct.UpdatedAt +and PlaybackPositionStruct.Position fields. To enable this, the SampledPosition attribute SHALL be +updated whenever a change in either the playback speed or the playback position is triggered out­ +side the normal playback of the media. The events which MAY cause this to happen include: + +- Starting or resumption of playback +- Seeking +- Skipping forward or backward +- Fast-forwarding or rewinding +- Updating of playback speed as a result of explicit request, or as a result of buffering events + +**6.10.6.5. PlaybackSpeed Attribute** + +This attribute SHALL indicate the speed at which the current media is being played. The new Play­ +backSpeed SHALL be reflected in this attribute whenever any of the following occurs: + +- Starting of playback +- Resuming of playback +- Fast-forwarding +- Rewinding + +The PlaybackSpeed SHALL reflect the ratio of time elapsed in the media to the actual time taken for +the playback assuming no changes to media playback (for example buffering events or requests to +pause/rewind/forward). + +- A value for PlaybackSpeed of 1 SHALL indicate normal playback where, for example, playback + for 1 second causes the media to advance by 1 second within the duration of the media. +- A value for PlaybackSpeed which is greater than 0 SHALL indicate that as playback is happen­ + ing the media is currently advancing in time within the duration of the media. +- A value for PlaybackSpeed which is less than 0 SHALL indicate that as playback is happening + the media is currently going back in time within the duration of the media. +- A value for PlaybackSpeed of 0 SHALL indicate that the media is currently not playing back. + When the CurrentState attribute has the value of PAUSED, NOT_PLAYING or BUFFERING, the + PlaybackSpeed SHALL be set to 0 to reflect that the media is not playing. + +Following examples illustrate the PlaybackSpeed attribute values in various conditions. + +``` +Page 534 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Seconds of Media +Played +``` +``` +Actual Time Taken in +Seconds +``` +``` +Direction of playback PlaybackSpeed +``` +``` +2 2 Forward 1.0 +2 1 Forward 2.0 +1 2 Forward 0.5 +2 2 Reverse -1.0 +2 1 Reverse -2.0 +1 2 Reverse -0.5 +``` +**6.10.6.6. SeekRangeStart Attribute** + +This attribute SHALL indicate the earliest valid position to which a client MAY seek back, in mil­ +liseconds from start of the media. A value of Nas SHALL indicate that seeking backwards is not +allowed. + +**6.10.6.7. SeekRangeEnd Attribute** + +This attribute SHALL indicate the furthest forward valid position to which a client MAY seek for­ +ward, in milliseconds from the start of the media. When the media has an associated StartTime, a +value of null SHALL indicate that a seek forward is valid only until the current time within the +media, using a position computed from the difference between the current time offset and Start­ +Time, in milliseconds from start of the media, truncating fractional milliseconds towards 0. A value +of Nas when StartTime is not specified SHALL indicate that seeking forward is not allowed. + +**6.10.6.8. ActiveAudioTrack Attribute** + +ActiveTrack refers to the Audio track currently set and being used for the streaming media. A value +of null SHALL indicate that no Audio Track corresponding to the current media is currently being +played. + +**6.10.6.9. AvailableAudioTracks Attribute** + +AvailableAudioTracks refers to the list of Audio tracks available for the current title being played. A +value of null SHALL indicate that no Audio Tracks corresponding to the current media are selec­ +table by the client. + +**6.10.6.10. ActiveTextTrack Attribute** + +ActiveTrack refers to the Text track currently set and being used for the streaming media. This can +be nil. A value of null SHALL indicate that no Text Track corresponding to the current media is cur­ +rently being displayed. + +**6.10.6.11. AvailableTextTracks Attribute** + +AvailableTextTracks refers to the list of Text tracks available for the current title being played. This +can be an empty list. A value of null SHALL indicate that no Text Tracks corresponding to the cur­ +rent media are selectable by the client. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 535 +``` + +**6.10.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Play client ⇒ server PlaybackRe­ +sponse +``` +### O M + +``` +0x01 Pause client ⇒ server PlaybackRe­ +sponse +``` +### O M + +``` +0x02 Stop client ⇒ server PlaybackRe­ +sponse +``` +### O M + +``` +0x03 StartOver client ⇒ server PlaybackRe­ +sponse +``` +### O O + +``` +0x04 Previous client ⇒ server PlaybackRe­ +sponse +``` +### O O + +``` +0x05 Next client ⇒ server PlaybackRe­ +sponse +``` +### O O + +``` +0x06 Rewind client ⇒ server PlaybackRe­ +sponse +``` +### O VS + +``` +0x07 FastForward client ⇒ server PlaybackRe­ +sponse +``` +### O VS + +``` +0x08 SkipForward client ⇒ server PlaybackRe­ +sponse +``` +### O O + +``` +0x09 SkipBackward client ⇒ server PlaybackRe­ +sponse +``` +### O O + +``` +0x0A PlaybackRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x0B Seek client ⇒ server PlaybackRe­ +sponse +``` +### O AS + +``` +0x0C ActivateAu­ +dioTrack +``` +``` +client ⇒ server Y O AT +``` +``` +0x0D ActivateText­ +Track +``` +``` +client ⇒ server Y O TT +``` +``` +0x0E Deactivate­ +TextTrack +``` +``` +client ⇒ server Y O TT +``` +**6.10.7.1. Play Command** + +Upon receipt, this SHALL play media. If content is currently in a FastForward or Rewind state. Play +SHALL return media to normal playback speed. + +**6.10.7.2. Pause Command** + +Upon receipt, this SHALL pause playback of the media. + +``` +Page 536 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.10.7.3. Stop Command** + +Upon receipt, this SHALL stop playback of the media. User-visible outcome is context-specific. This +MAY navigate the user back to the location from where the media was originally launched. + +**6.10.7.4. StartOver Command** + +Upon receipt, this SHALL Start Over with the current media playback item. + +**6.10.7.5. Previous Command** + +Upon receipt, this SHALL cause the handler to be invoked for "Previous". User experience is con­ +text-specific. This will often Go back to the previous media playback item. + +**6.10.7.6. Next Command** + +Upon receipt, this SHALL cause the handler to be invoked for "Next". User experience is context- +specific. This will often Go forward to the next media playback item. + +**6.10.7.7. Rewind Command** + +Upon receipt, this SHALL start playback of the media backward in case the media is currently play­ +ing in the forward direction or is not playing. If the playback is already happening in the back­ +wards direction receipt of this command SHALL increase the speed of the media playback back­ +wards. + +Different "rewind" speeds MAY be reflected on the media playback device based upon the number +of sequential calls to this function and the capability of the device. This is to avoid needing to define +every speed (multiple fast, slow motion, etc). If the PlaybackSpeed attribute is supported it SHALL +be updated to reflect the new speed of playback. If the playback speed cannot be changed for the +media being played(for example, in live streaming content not supporting seek), the status of +NOT_ALLOWED SHALL be returned. If the playback speed has reached the maximum supported +speed for media playing backwards, the status of SPEED_OUT_OF_RANGE SHALL be returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 AudioAd­ +vanceUn­ +muted +``` +``` +bool all false AA +``` +**6.10.7.7.1. AudioAdvanceUnmuted Field** + +This field SHALL indicate whether audio should be unmuted by the player during rewind. + +A value of true does not guarantee that audio can be heard by the user since the speaker may be +muted, turned down to a low level and/or unplugged. + +**6.10.7.8. FastForward Command** + +Upon receipt, this SHALL start playback of the media in the forward direction in case the media is + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 537 +``` + +currently playing in the backward direction or is not playing. If the playback is already happening +in the forward direction receipt of this command SHALL increase the speed of the media playback. + +Different "fast-forward" speeds MAY be reflected on the media playback device based upon the +number of sequential calls to this function and the capability of the device. This is to avoid needing +to define every speed (multiple fast, slow motion, etc). If the PlaybackSpeed attribute is supported it +SHALL be updated to reflect the new speed of playback. If the playback speed cannot be changed +for the media being played(for example, in live streaming content not supporting seek), the status +of NOT_ALLOWED SHALL be returned. If the playback speed has reached the maximum supported +speed for media playing forward, the status of SPEED_OUT_OF_RANGE SHALL be returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 AudioAd­ +vanceUn­ +muted +``` +``` +bool all false AA +``` +**6.10.7.8.1. AudioAdvanceUnmuted Field** + +This field SHALL indicate whether audio should be unmuted by the player during fast forward. + +A value of true does not guarantee that audio can be heard by the user since the speaker may be +muted, turned down to a low level and/or unplugged. + +**6.10.7.9. SkipForward Command** + +Upon receipt, this SHALL Skip forward in the media by the given number of milliseconds, using the +data as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 DeltaPosi­ +tionMillisec­ +onds +``` +``` +uint64 all M +``` +**6.10.7.9.1. DeltaPositionMilliseconds Field** + +This field SHALL indicate the duration of the time span to skip forward in the media, in millisec­ +onds. In case the resulting position falls in the middle of a frame, the server SHALL set the position +to the beginning of that frame and set the SampledPosition attribute on the cluster accordingly. If +the resultant position falls beyond the furthest valid position in the media the client MAY seek for­ +ward to, the position should be set to that furthest valid position. If the SampledPosition attribute is +supported it SHALL be updated on the cluster accordingly. + +**6.10.7.10. SkipBackward Command** + +Upon receipt, this SHALL Skip backward in the media by the given number of milliseconds, using +the data as follows: + +``` +Page 538 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 DeltaPosi­ +tionMillisec­ +onds +``` +``` +uint64 all M +``` +**6.10.7.10.1. DeltaPositionMilliseconds Field** + +This field SHALL indicate the duration of the time span to skip backward in the media, in millisec­ +onds. In case the resulting position falls in the middle of a frame, the server SHALL set the position +to the beginning of that frame and set the SampledPosition attribute on the cluster accordingly. If +the resultant position falls before the earliest valid position to which a client MAY seek back to, the +position should be set to that earliest valid position. If the SampledPosition attribute is supported it +SHALL be updated on the cluster accordingly. + +**6.10.7.11. Seek Command** + +Upon receipt, this SHALL change the playback position in the media to the given position using data +as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Position uint64 all M +``` +**6.10.7.11.1. Position Field** + +This field SHALL indicate the position (in milliseconds) in the media to seek to. In case the position +falls in the middle of a frame, the server SHALL set the position to the beginning of that frame and +set the SampledPosition attribute on the cluster accordingly. If the position falls before the earliest +valid position or beyond the furthest valid position to which a client MAY seek back or forward to +respectively, the status of SEEK_OUT_OF_RANGE SHALL be returned and no change SHALL be made +to the position of the playback. + +**6.10.7.12. PlaybackResponse Command** + +This command SHALL be generated in response to various Playback Commands. The data for this +command SHALL be as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status StatusEnum desc M +1 Data string any O +``` +**6.10.7.12.1. Status Field** + +This field SHALL indicate the status of the command which resulted in this response. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 539 +``` + +**6.10.7.12.2. Data Field** + +This field SHALL indicate Optional app-specific data. + +**6.10.7.13. ActivateAudioTrack Command** + +Upon receipt, the server SHALL set the active Audio Track to the one identified by the TrackID in +the Track catalog for the streaming media. If the TrackID does not exist in the Track catalog, OR +does not correspond to the streaming media OR no media is being streamed at the time of receipt of +this command, the server will return an error status of INVALID_ARGUMENT. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TrackID string max 32 M +1 AudioOut­ +putIndex +``` +``` +uint8 all X AT +``` +**6.10.7.13.1. TrackID Field** + +This field SHALL indicate the Audio Track to activate. + +**6.10.7.13.2. AudioOutputIndex Field** + +This value is the index field of the OutputInfoStruct from the OutputList attribute (from the +AudioOutput cluster) and indicates which audio output the Audio Track should be played on. This +field is absent for Text Tracks and only present for Audio Tracks. A value of null SHALL indicate +that the server can choose the audio output(s) to play the Audio Track on. + +**6.10.7.14. ActivateTextTrack Command** + +Upon receipt, the server SHALL set the active Text Track to the one identified by the TrackID in the +Track catalog for the streaming media. If the TrackID does not exist in the Track catalog, OR does +not correspond to the streaming media OR no media is being streamed at the time of receipt of this +command, the server SHALL return an error status of INVALID_ARGUMENT. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TrackID string max 32 M +``` +**6.10.7.14.1. TrackID Field** + +This field SHALL indicate the Text Track to activate. + +**6.10.7.15. DeactivateTextTrack Command** + +If a Text Track is active (i.e. being displayed), upon receipt of this command, the server SHALL stop +displaying it. + +``` +Page 540 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.10.8. Events** + +``` +ID Name Priority Access Conformance +0x00 StateChanged INFO V O +``` +**6.10.8.1. StateChanged Event** + +If supported, this event SHALL be generated when there is a change in any of the supported attrib­ +utes of the Media Playback cluster. This event SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0x0000 Cur­ +rentState +``` +``` +PlaybackSta­ +teEnum +``` +``` +desc M +``` +``` +0x0001 StartTime epoch-us desc AS +0x0002 Duration uint64 desc AS +0x0003 SampledPo­ +sition +``` +``` +PlaybackPo­ +sitionStruct +``` +``` +desc AS +``` +``` +0x0004 Playback­ +Speed +``` +``` +single desc AS +``` +``` +0x0005 SeekRangeE +nd +``` +``` +uint64 desc AS +``` +``` +0x0006 SeekRangeS +tart +``` +``` +uint64 desc AS +``` +``` +0x0007 Data octstr max 900 O +0x0008 AudioAd­ +vanceUn­ +muted +``` +``` +bool desc false AA +``` +**6.10.8.1.1. CurrentState Field** + +This field SHALL indicate the updated playback state as defined by the CurrentState attribute, and +has the same constraint as that attribute. + +**6.10.8.1.2. StartTime Field** + +This field SHALL indicate the updated start time as defined by the StartTime attribute, and has the +same constraint as that attribute. + +**6.10.8.1.3. Duration Field** + +This field SHALL indicate the updated duration as defined by the Duration attribute, and has the +same constraint as that attribute. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 541 +``` + +**6.10.8.1.4. SampledPosition Field** + +This field SHALL indicate the updated position of playback as defined by the SampledPosition +attribute, and has the same constraint as that attribute. + +**6.10.8.1.5. PlaybackSpeed Field** + +This field SHALL indicate the updated speed at which the current media is being played as defined +by the PlaybackSpeed attribute, and has the same constraint as that attribute. + +**6.10.8.1.6. SeekRangeStart Field** + +This field SHALL indicate the updated start of the seek range start as defined by the SeekRangeStart +attribute, and has the same constraint as that attribute. + +**6.10.8.1.7. SeekRangeEnd Field** + +This field SHALL indicate the updated start of the seek range end as defined by the SeekRangeEnd +attribute, and has the same constraint as that attribute. + +**6.10.8.1.8. Data Field** + +This field SHALL indicate Optional app-specific data. + +**6.10.8.1.9. AudioAdvanceUnmuted Field** + +This field SHALL indicate whether audio is unmuted by the player due to a FF or REW command. +This field is only meaningful when the PlaybackSpeed is present and not equal to 0 (paused) or 1 +(normal playback). Typically the value will be false (muted), however, some players will play audio +during certain fast forward and rewind speeds, and in these cases, the value will be true (not +muted). + +A value of true does not guarantee that audio can be heard by the user since the speaker may be +muted, turned down to a low level and/or unplugged. + +**6.11. Target Navigator Cluster** + +This cluster provides an interface for UX navigation within a set of targets on a device or endpoint. + +This cluster would be supported on Video Player devices or devices with navigable user interfaces. +This cluster would also be supported on endpoints with navigable user interfaces such as a Content +App. It supports listing a set of navigation targets, tracking and changing the current target. + +The cluster server for Target Navigator is implemented by endpoints on a device that support UX +navigation. + +When this cluster is implemented for a Content App endpoint, the Video Player device containing +the endpoint SHALL launch the Content App when a client invokes the NavigateTarget command. + +``` +Page 542 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.11.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Add TargetUpdated event +``` +**6.11.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint TGTNAV +``` +**6.11.3. Cluster ID** + +``` +ID Name +0x0505 Target Navigator +``` +**6.11.4. Data Types** + +**6.11.4.1. StatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Success Command succeeded M +1 TargetNotFound Requested target was +not found in the Tar­ +getList +``` +### M + +``` +2 NotAllowed Target request is not +allowed in current +state. +``` +### M + +**6.11.4.2. TargetInfoStruct Type** + +This indicates an object describing the navigable target. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Identifier uint8 max 254 M +1 Name string M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 543 +``` + +**6.11.4.2.1. Identifier Field** + +This field SHALL contain an unique id within the TargetList. + +**6.11.4.2.2. Name Field** + +This field SHALL contain a name string for the TargetInfoStruct. + +**6.11.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 TargetList list[Target­ +InfoStruct] +``` +### R V M + +``` +0x0001 Current­ +Target +``` +``` +uint8 desc 0xFF R V O +``` +**6.11.5.1. TargetList Attribute** + +This attribute SHALL represent a list of targets that can be navigated to within the experience pre­ +sented to the user by the Endpoint (Video Player or Content App). The list SHALL NOT contain any +entries with the same Identifier in the TargetInfoStruct object. + +**6.11.5.2. CurrentTarget Attribute** + +This attribute SHALL represent the Identifier for the target which is currently in foreground on the +corresponding Endpoint (Video Player or Content App), or 0xFF to indicate that no target is in the +foreground. + +When not 0xFF, the CurrentTarget SHALL be an Identifier value contained within one of the Target­ +InfoStruct objects in the TargetList attribute. + +**6.11.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 NavigateTar­ +get +``` +``` +client ⇒ server NavigateTarge­ +tResponse +``` +### O M + +``` +0x01 NavigateTar­ +getResponse +``` +``` +client ⇐ server N M +``` +**6.11.6.1. NavigateTarget Command** + +Upon receipt, this SHALL navigation the UX to the target identified. + +``` +ID Field Type Constraint Quality Default Confor­ +mance +0 Target uint8 all M +``` +``` +Page 544 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Field Type Constraint Quality Default Confor­ +mance +1 Data string MS O +``` +**6.11.6.1.1. Target Field** + +This field SHALL indicate the Identifier for the target for UX navigation. The Target SHALL be an +Identifier value contained within one of the TargetInfoStruct objects in the TargetList attribute. + +**6.11.6.1.2. Data Field** + +This field SHALL indicate Optional app-specific data. + +**6.11.6.2. NavigateTargetResponse Command** + +This command SHALL be generated in response to NavigateTarget command. + +``` +ID Field Type Constraint Quality Default Confor­ +mance +0 Status StatusEnum all M +1 Data string any MS O +``` +**6.11.6.2.1. Status Field** + +This field SHALL indicate the of the command. + +**6.11.6.2.2. Data Field** + +This field SHALL indicate Optional app-specific data. + +**6.11.7. Events** + +``` +ID Name Priority Access Conformance +0x00 TargetUpdated INFO V O +``` +**6.11.7.1. TargetUpdated Event** + +This event SHALL be generated when there is a change in either the active target or the list of avail­ +able targets or both. This event SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TargetList list[Target­ +InfoStruct] +``` +### O + +``` +1 CurrentTar­ +get +``` +``` +uint8 desc 0xFF O +``` +``` +2 Data octstr max 900 O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 545 +``` + +**6.11.7.2. TargetList Field** + +This field SHALL indicate the updated target list as defined by the TargetList attribute if there is a +change in the list of targets. Otherwise this field can be omitted from the event. + +**6.11.7.3. CurrentTarget Field** + +This field SHALL indicate the updated target that is in foreground as defined by the CurrentTarget +attribute if supported (see CurrentTarget attribute for constraints). + +**6.11.7.4. Data Field** + +This field SHALL indicate Optional app-specific data. + +**6.12. Content App Observer Cluster** + +This cluster provides an interface for sending targeted commands to an Observer of a Content App +on a Video Player device such as a Streaming Media Player, Smart TV or Smart Screen. + +The cluster server for Content App Observer is implemented by an endpoint that communicates +with a Content App, such as a Casting Video Client. + +The cluster client for Content App Observer is implemented by a Content App endpoint. + +A Content App is informed of the NodeId of an Observer when a binding is set on the Content App. +For a Content App Platform, the binding is set by the platform when a CastingVideoClient is granted +access to the Content App, and the CastingVideoClient supports the Content App Observer cluster. +The Content App can then send the ContentAppMessage to the Observer (server cluster), and the +Observer responds with a ContentAppMessageResponse. + +The Data and EncodingHint fields of the ContentAppMessage and ContentAppMessageResponse +contain content app-specific values, the format and interpretation of which is defined by the Con­ +tent App vendor, analogous to the custom message features offered by other popular casting proto­ +cols. Standardized cluster and commands are used here rather than manufacturer-specific cluster +and commands because of the role that the Content App Platform plays in creating the ACLs and +Bindings on both sides of the communication between the Content App Observer endpoint and the +Content App endpoint. + +By using standard cluster and commands: + +1. The Content App Platform is able to easily determine that a binding is needed on the Content + App endpoint because it can recognize the Content App Observer cluster implemented by a + client node. +2. The Content App Platform is able to easily identify commands that are allowed to be sent by the + Content App to a client node because those commands use the Content App Observer cluster. +3. The Content App is able to easily determine that a node supports the Content App Observer clus­ + ter because it has received a binding which specifies the Content App Observer cluster. +4. The Casting Video Client is able to support a single cluster for receiving commands from any + Content App and does not need to explicitly list every Content App it understands. + +``` +Page 546 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +A Content App Observer SHOULD ignore the Data and EncodingHint field values in commands from +a Content App it does not recognize. A Content App SHOULD ignore the Data field values in +responses when the EncodingHint value is blank or not recognized. + +**6.12.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**6.12.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint APPOBSERVER +``` +**6.12.3. Cluster ID** + +``` +ID Name +0x0510 Content App Observer +``` +**6.12.4. Data Types** + +**6.12.4.1. StatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Success Command succeeded M +1 UnexpectedData Data field in command +was not understood by +the Observer +``` +### M + +**6.12.5. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Con­ +tentAppMes­ +sage +``` +``` +client ⇒ server Con­ +tentAppMes­ +sageResponse +``` +### O M + +``` +0x01 Con­ +tentAppMes­ +sageResponse +``` +``` +client ⇐ server N M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 547 +``` + +**6.12.5.1. ContentAppMessage Command** + +Upon receipt, the data field MAY be parsed and interpreted. Message encoding is specific to the Con­ +tent App. A Content App MAY when possible read attributes from the Basic Information Cluster on +the Observer and use this to determine the Message encoding. + +This command returns a ContentAppMessage Response. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Data string max 500 M +1 EncodingH­ +int +``` +``` +string max 100 O +``` +**6.12.5.1.1. Data Field** + +This field SHALL indicate content app-specific data. + +**6.12.5.1.2. EncodingHint Field** + +This optional field SHALL indicate a content app-specific hint to the encoding of the data. + +**6.12.5.2. ContentAppMessageResponse Command** + +This command SHALL be generated in response to ContentAppMessage command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status StatusEnum all M +1 Data string max 500 O +2 EncodingH­ +int +``` +``` +string max 100 O +``` +**6.12.5.2.1. Status Field** + +This field SHALL indicate the status of the command which resulted in this response. + +**6.12.5.2.2. Data Field** + +This optional field SHALL indicate content app-specific data. + +**6.12.5.2.3. EncodingHint Field** + +This optional field SHALL indicate a content app-specific hint to the encoding of the data. + +**6.13. Content Control Cluster** + +This cluster is used for managing the content control (including "parental control") settings on a + +``` +Page 548 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +media device such as a TV, or Set-top Box. + +This cluster allows to configure content control settings by clients with the Management privilege. +It is responsibility of the end product to enforce appropriate right access (for example, to prevent a +child from disabling this feature). + +``` +NOTE Support for Content Control cluster is provisional. +``` +**6.13.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**6.13.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint CONCON +``` +**6.13.3. Cluster ID** + +``` +ID Name Conformance +0x050F Content Control P +``` +**6.13.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 ST ScreenTime Supports managing +screen time limits. +1 PM PINManagement Supports managing a +PIN code which is used +for restricting access to +configuration of this +feature. +2 BU BlockUnrated Supports managing +content controls for +unrated content. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 549 +``` + +``` +Bit Code Feature Summary +3 OCR OnDemandContentRat­ +ing +``` +``` +Supports managing +content controls based +upon rating threshold +for on demand content. +4 SCR ScheduledContentRat­ +ing +``` +``` +Supports managing +content controls based +upon rating threshold +for scheduled content. +5 BC BlockChannels Supports managing a +set of channels that are +prohibited. +6 BA BlockApplications Supports managing a +set of applications that +are prohibited. +7 BTW BlockContentTimeWin­ +dow +``` +``` +Supports managing +content controls based +upon setting time win­ +dow in which all con­ +tents and applications +SHALL be blocked. +``` +**6.13.5. Data Types** + +**6.13.5.1. DayOfWeekBitmap type** + +This data type is derived from map8. + +``` +Bit Name Summary +0 Sunday Sunday +1 Monday Monday +2 Tuesday Tuesday +3 Wednesday Wednesday +4 Thursday Thursday +5 Friday Friday +6 Saturday Saturday +``` +**6.13.5.2. RatingNameStruct Type** + +``` +Page 550 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Rating­ +Name +``` +``` +string max 8 M +``` +``` +1 Rating­ +NameDesc +``` +``` +string max 64 O +``` +**6.13.5.2.1. RatingName Field** + +This field SHALL indicate the name of the rating level of the applied rating system. The applied rat­ +ing system is dependent upon the region or country where the Node has been provisioned, and may +vary from one country to another. + +**6.13.5.2.2. RatingNameDesc Field** + +This field SHALL specify a human readable (displayable) description for RatingName. + +**6.13.5.3. BlockChannelStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 BlockChan +nelIndex +``` +``` +uint16 all X M +``` +``` +1 Major­ +Number +``` +``` +uint16 all M +``` +``` +2 Minor­ +Number +``` +``` +uint16 all M +``` +``` +3 Identifier string all O +``` +**6.13.5.3.1. BlockChannelIndex Field** + +This field SHALL indicate a unique index value for a blocked channel. This value may be used to +indicate one selected channel which will be removed from BlockChannelList attribute. + +**6.13.5.3.2. MajorNumber Field** + +This field SHALL indicate the channel major number value (for example, using ATSC format). When +the channel number is expressed as a string, such as "13.1" or "256", the major number would be 13 +or 256, respectively. This field is required but SHALL be set to 0 for channels such as over-the-top +channels that are not represented by a major or minor number. + +**6.13.5.3.3. MinorNumber Field** + +This field SHALL indicate the channel minor number value (for example, using ATSC format). When +the channel number is expressed as a string, such as "13.1" or "256", the minor number would be 1 +or 0, respectively. This field is required but SHALL be set to 0 for channels such as over-the-top +channels that are not represented by a major or minor number. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 551 +``` + +**6.13.5.3.4. Identifier** + +This field SHALL indicate the unique identifier for a specific channel. This field is optional, but +SHOULD be provided when MajorNumber and MinorNumber are not available. + +**6.13.5.4. AppInfoStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Cata­ +logVen­ +dorID +``` +``` +uint16 all M +``` +``` +1 Applica­ +tionID +``` +``` +string all M +``` +**6.13.5.4.1. CatalogVendorID Field** + +This field SHALL indicate the CSA-issued vendor ID for the catalog. The DIAL registry SHALL use +value 0x0000. + +Content App Platform providers will have their own catalog vendor ID (set to their own Vendor ID) +and will assign an ApplicationID to each Content App. + +**6.13.5.4.2. ApplicationID field** + +This field SHALL indicate the application identifier, expressed as a string, such as "PruneVideo" or +"Company X". This field SHALL be unique within a catalog. + +**6.13.5.5. TimeWindowStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 TimeWin­ +dowIndex +``` +``` +uint16 all X M +``` +``` +1 Day­ +OfWeek +``` +``` +Day­ +OfWeek­ +Bitmap +``` +``` +desc M +``` +``` +2 TimePe­ +riod +``` +``` +list[TimePe +riodStruct] +``` +``` +desc M +``` +**6.13.5.5.1. TimeWindowIndex Field** + +This field SHALL indicate a unique index of a specific time window. This value may be used to indi­ +cate a selected time window which will be removed from the BlockContentTimeWindow attribute. + +**6.13.5.5.2. DayOfWeek Field** + +This field SHALL indicate a day of week. + +``` +Page 552 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.13.5.5.3. TimePeriod Field** + +This field SHALL indicate one or more discrete time periods. + +**6.13.5.6. TimePeriodStruct type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 StartHour uint8 0 to 23 M +1 Start­ +Minute +``` +``` +uint8 0 to 59 M +``` +``` +2 EndHour uint8 0 to 23 M +3 End­ +Minute +``` +``` +uint8 0 to 59 M +``` +**6.13.5.6.1. StartHour Field** + +This field SHALL indicate the starting hour. + +**6.13.5.6.2. StartMinute Field** + +This field SHALL indicate the starting minute. + +**6.13.5.6.3. EndHour Field** + +This field SHALL indicate the ending hour. EndHour SHALL be equal to or greater than StartHour + +**6.13.5.6.4. EndMinute Field** + +This field SHALL indicate the ending minute. If EndHour is equal to StartHour then EndMinute +SHALL be greater than StartMinute. If the EndHour is equal to 23 and the EndMinute is equal to 59, +all contents SHALL be blocked until 23:59:59. + +**6.13.6. Status Codes** + +**6.13.6.1. StatusCodeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary +0x02 InvalidPINCode Provided PIN Code does not +match the current PIN code. +0x03 InvalidRating Provided Rating is out of scope +of the corresponding Rating list. +0x04 InvalidChannel Provided Channel(s) is invalid. +0x05 ChannelAlreadyExist Provided Channel(s) already +exists. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 553 +``` + +``` +Value Name Summary +0x06 ChannelNotExist Provided Channel(s) doesn’t +exist in BlockChannelList +attribute. +0x07 UnidentifiableApplication Provided Application(s) is not +identified. +0x08 ApplicationAlreadyExist Provided Application(s) already +exists. +0x09 ApplicationNotExist Provided Application(s) doesn’t +exist in BlockApplicationList +attribute. +0x0A TimeWindowAlreadyExist Provided time Window already +exists in BlockContentTimeWin­ +dow attribute. +0x0B TimeWindowNotExist Provided time window doesn’t +exist in BlockContentTimeWin­ +dow attribute. +``` +**6.13.7. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Enabled bool all R V M +0x0001 OnDeman­ +dRatings +``` +``` +list[Rating­ +NameStruc +t] +``` +``` +all R V OCR +``` +``` +0x0002 OnDeman­ +dRat­ +ingThresh­ +old +``` +``` +string max 8 R V OCR +``` +``` +0x0003 Sched­ +uledCon­ +tentRat­ +ings +``` +``` +list[Rating­ +NameStruc +t] +``` +``` +all R V SCR +``` +``` +0x0004 Sched­ +uledCon­ +tentRat­ +ingThresh­ +old +``` +``` +string max 8 R V SCR +``` +``` +0x0005 ScreenDai +lyTime +``` +``` +elapsed-s max 86400 R V ST +``` +``` +Page 554 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0006 Remain­ +ingScreen­ +Time +``` +``` +elapsed-s max 86400 R V ST +``` +``` +0x0007 BlockUn­ +rated +``` +``` +bool all R V BU +``` +``` +0x0008 BlockChan +nelList +``` +``` +list[BlockC +hannel­ +Struct] +``` +``` +all R V BC +``` +``` +0x0009 BlockAp­ +plication­ +List +``` +``` +list[AppIn­ +foStruct] +``` +``` +all R V BA +``` +``` +0x000A BlockCon­ +tent­ +TimeWin­ +dow +``` +``` +list[TimeW +indow­ +Struct] +``` +``` +max 7 R V BTW +``` +**6.13.7.1. Enabled Attribute** + +This attribute SHALL indicate whether the Content Control feature implemented on a media device +is turned off (FALSE) or turned on (TRUE). + +**6.13.7.2. OnDemandRatings Attribute** + +This attribute SHALL provide the collection of ratings that are currently valid for this media device. +The items should honor the metadata of the on-demand content (e.g. Movie) rating system for one +country or region where the media device has been provisioned. For example, for the MPAA sys­ +tem, RatingName may be one value out of "G", "PG", "PG-13", "R", "NC-17". + +The media device SHALL have a way to determine which rating system applies for the on-demand +content and then populate this attribute. For example, it can do it through examining the Location +attribute in the Basic Information cluster, and then determining which rating system applies. + +The ratings in this collection SHALL be in order from a rating for the youngest viewers to the one +for the oldest viewers. Each rating in the list SHALL be unique. + +**6.13.7.3. OnDemandRatingThreshold Attribute** + +This attribute SHALL indicate a threshold rating as a content filter which is compared with the rat­ +ing for on-demand content. For example, if the on-demand content rating is greater than or equal to +OnDemandRatingThreshold, for a rating system that is ordered from lower viewer age to higher +viewer age, then on-demand content is not appropriate for the User and the Node SHALL prevent +the playback of content. + +This attribute SHALL be set to one of the values present in the OnDemandRatings attribute. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 555 +``` + +When this attribute changes, the device SHOULD make the user aware of any limits of this feature. +For example, if the feature does not control content within apps, then the device should make this +clear to the user when the attribute changes. + +**6.13.7.4. ScheduledContentRatings Attribute** + +This attribute SHALL indicate a collection of ratings which ScheduledContentRatingThreshold can +be set to. The items should honor metadata of the scheduled content rating system for the country +or region where the media device has been provisioned. + +The media device SHALL have a way to determine which scheduled content rating system applies +and then populate this attribute. For example, this can be done by examining the Location attribute +in Basic Information cluster, and then determining which rating system applies. + +The ratings in this collection SHALL be in order from a rating for the youngest viewers to the one +for the oldest viewers. Each rating in the list SHALL be unique. + +**6.13.7.5. ScheduledContentRatingThreshold Attribute** + +This attribute SHALL indicate a threshold rating as a content filter which is used to compare with +the rating for scheduled content. For example, if the scheduled content rating is greater than or +equal to ScheduledContentRatingThreshold for a rating system that is ordered from lower viewer +age to higher viewer age, then the scheduled content is not appropriate for the User and SHALL be +blocked. + +This attribute SHALL be set to one of the values present in the ScheduledContentRatings attribute. + +When this attribute changes, the device SHOULD make the user aware of any limits of this feature. +For example, if the feature does not control content within apps, then the device should make this +clear to the user when the attribute changes. + +**6.13.7.6. ScreenDailyTime Attribute** + +This attribute SHALL indicate the amount of time (in seconds) which the User is allowed to spend +watching TV within one day when the Content Control feature is activated. + +**6.13.7.7. RemainingScreenTime Attribute** + +This attribute SHALL indicate the remaining screen time (in seconds) which the User is allowed to +spend watching TV for the current day when the Content Control feature is activated. When this +value equals 0, the media device SHALL terminate the playback of content. + +This attribute SHALL be updated when the AddBonusTime command is received and processed suc­ +cessfully (with the correct PIN). + +**6.13.7.8. BlockUnrated Attribute** + +This attribute SHALL indicate whether the playback of unrated content is allowed when the Con­ +tent Control feature is activated. If this attribute equals FALSE, then playback of unrated content +SHALL be permitted. Otherwise, the media device SHALL prevent the playback of unrated content. + +``` +Page 556 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +When this attribute changes, the device SHOULD make the user aware of any limits of this feature. +For example, if the feature does not control content within apps, then the device should make this +clear to the user when the attribute changes. + +**6.13.7.9. BlockChannelList Attribute** + +This attribute SHALL indicate a set of channels that SHALL be blocked when the Content Control +feature is activated. + +**6.13.7.10. BlockApplicationList Attribute** + +This attribute SHALL indicate a set of applications that SHALL be blocked when the Content Control +feature is activated. + +**6.13.7.11. BlockContentTimeWindow Attribute** + +This attribute SHALL indicate a set of periods during which the playback of content on media +device SHALL be blocked when the Content Control feature is activated. The media device SHALL +reject any request to play content during one period of this attribute. If it is entering any one period +of this attribute, the media device SHALL block content which is playing and generate an event +EnteringBlockContentTimeWindow. There SHALL NOT be multiple entries in this attribute list for +the same day of week. + +**6.13.8. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 UpdatePIN client ⇒ server Y M T PM +0x01 ResetPIN client ⇒ server ResetPINRe­ +sponse +``` +### A T PM + +``` +0x02 ResetPINRe­ +sponse +``` +``` +client ⇐ server N PM +``` +``` +0x03 Enable client ⇒ server Y M T M +0x04 Disable client ⇒ server Y M T M +0x05 AddBonus­ +Time +``` +``` +client ⇒ server Y O ST +``` +``` +0x06 SetScreenDai­ +lyTime +``` +``` +client ⇒ server Y M ST +``` +``` +0x07 BlockUnrated­ +Content +``` +``` +client ⇒ server Y M BU +``` +``` +0x08 UnblockUnrat­ +edContent +``` +``` +client ⇒ server Y M BU +``` +``` +0x09 SetOnDeman­ +dRatingTh­ +reshold +``` +``` +client ⇒ server Y M OCR +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 557 +``` + +``` +ID Name Direction Response Access Conformance +0x0A SetScheduled­ +ContentRat­ +ingThreshold +``` +``` +client ⇒ server Y M SCR +``` +``` +0x0B AddBlockCha +nnels +``` +``` +client ⇒ server Y M BC +``` +``` +0x0C Remove­ +BlockChan­ +nels +``` +``` +client ⇒ server Y M BC +``` +``` +0x0D AddBlockAp­ +plications +``` +``` +client ⇒ server Y M BA +``` +``` +0x0E RemoveBlock­ +Applications +``` +``` +client ⇒ server Y M BA +``` +``` +0x0F SetBlockCon­ +tentTimeWin­ +dow +``` +``` +client ⇒ server Y M BTW +``` +``` +0x10 RemoveBlock­ +Content­ +TimeWindow +``` +``` +client ⇒ server Y M BTW +``` +**6.13.8.1. UpdatePIN Command** + +The purpose of this command is to update the PIN used for protecting configuration of the content +control settings. Upon success, the old PIN SHALL no longer work. + +The PIN is used to ensure that only the Node (or User) with the PIN code can make changes to the +Content Control settings, for example, turn off Content Controls or modify the ScreenDailyTime. The +PIN is composed of a numeric string of up to 6 human readable characters (displayable). + +Upon receipt of this command, the media device SHALL check if the OldPIN field of this command +is the same as the current PIN. If the PINs are the same, then the PIN code SHALL be set to NewPIN. +Otherwise a response with InvalidPINCode error status SHALL be returned. + +The media device MAY provide a default PIN to the User via an out of band mechanism. For security +reasons, it is recommended that a client encourage the user to update the PIN from its default value +when performing configuration of the Content Control settings exposed by this cluster. The Reset­ +PIN command can also be used to obtain the default PIN. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 OldPIN string max 6 M +1 NewPIN string max 6 M +``` +``` +Page 558 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.13.8.1.1. OldPIN Field** + +This field SHALL specify the original PIN. Once the UpdatePIN command is performed successfully, +it SHALL be invalid. + +**6.13.8.1.2. NewPIN Field** + +This field SHALL indicate a new PIN for the Content Control feature. + +**6.13.8.2. ResetPIN Command** + +The purpose of this command is to reset the PIN. + +If this command is executed successfully, a ResetPINResponse command with a new PIN SHALL be +returned. + +**6.13.8.3. ResetPINResponse Command** + +This command SHALL be generated in response to a ResetPIN command. The data for this com­ +mand SHALL be as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PINCode string max 6 M +``` +**6.13.8.3.1. PINCode Field** + +This field SHALL indicate a new PIN of the Content Control feature. + +**6.13.8.4. Enable Command** + +The purpose of this command is to turn on the Content Control feature on a media device. + +Upon receipt of the Enable command, the media device SHALL set the Enabled attribute to TRUE. + +**6.13.8.5. Disable Command** + +The purpose of this command is to turn off the Content Control feature on a media device. + +On receipt of the Disable command, the media device SHALL set the Enabled attribute to FALSE. + +**6.13.8.6. AddBonusTime Command** + +The purpose of this command is to add the extra screen time for the user. + +If a client with Operate privilege invokes this command, the media device SHALL check whether +the PINCode passed in the command matches the current PINCode value. If these match, then the +RemainingScreenTime attribute SHALL be increased by the specified BonusTime value. + +If the PINs do not match, then a response with InvalidPINCode error status SHALL be returned, and +no changes SHALL be made to RemainingScreenTime. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 559 +``` + +If a client with Manage privilege or greater invokes this command, the media device SHALL ignore +the PINCode field and directly increase the RemainingScreenTime attribute by the specified Bonus­ +Time value. + +A server that does not support the PM feature SHALL respond with InvalidPINCode to clients that +only have Operate privilege unless: + +- It has been provided with the PIN value to expect via an out of band mechanism, and +- The client has provided a PINCode that matches the expected PIN value. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PINCode string max 6 O +1 BonusTime elapsed-s desc 300s M +``` +**6.13.8.6.1. PINCode Field** + +This field SHALL indicate the PIN. + +This field SHALL be optional for clients with Manage or greater privilege but SHALL be mandatory +for clients with Operate privilege. The PIN provided in this field SHALL be used to guarantee that a +client with Operate permission is allowed to invoke this command only if the PIN passed in this +command is equal to the current PIN value. + +**6.13.8.6.2. BonusTime Field** + +This field SHALL indicate the amount of extra time (in seconds) to increase RemainingScreenTime. +This field SHALL NOT exceed the remaining time of this day. + +**6.13.8.7. SetScreenDailyTime Command** + +The purpose of this command is to set the ScreenDailyTime attribute. + +Upon receipt of the SetScreenDailyTime command, the media device SHALL set the ScreenDaily­ +Time attribute to the ScreenTime value. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ScreenTime elapsed-s max 86400 M +``` +**6.13.8.7.1. ScreenTime Field** + +This field SHALL indicate the time (in seconds) which the User is allowed to spend watching TV on +this media device within one day. + +**6.13.8.8. BlockUnratedContent Command** + +The purpose of this command is to specify whether programs with no Content rating must be +blocked by this media device. + +``` +Page 560 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Upon receipt of the BlockUnratedContent command, the media device SHALL set the BlockUnrated +attribute to TRUE. + +**6.13.8.9. UnblockUnratedContent Command** + +The purpose of this command is to specify whether programs with no Content rating must be +blocked by this media device. + +Upon receipt of the UnblockUnratedContent command, the media device SHALL set the BlockUn­ +rated attribute to FALSE. + +**6.13.8.10. SetOnDemandRatingThreshold Command** + +The purpose of this command is to set the OnDemandRatingThreshold attribute. + +Upon receipt of the SetOnDemandRatingThreshold command, the media device SHALL check if the +Rating field is one of values present in the OnDemandRatings attribute. If not, then a response with +InvalidRating error status SHALL be returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Rating string max 8 M +``` +**6.13.8.10.1. Rating** + +This field indicates a threshold rating for filtering on-demand content. This field SHALL be set to +one of the values present in the OnDemandRatings attribute + +**6.13.8.11. SetScheduledContentRatingThreshold Command** + +The purpose of this command is to set ScheduledContentRatingThreshold attribute. + +Upon receipt of the SetScheduledContentRatingThreshold command, the media device SHALL +check if the Rating field is one of values present in the ScheduledContentRatings attribute. If not, +then a response with InvalidRating error status SHALL be returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Rating string max 8 M +``` +**6.13.8.11.1. Rating** + +This field indicates a threshold rating for filtering scheduled content. This field SHALL be set to one +of the values present in the ScheduledContentRatings attribute. + +**6.13.8.12. AddBlockChannels command** + +The purpose of this command is to set BlockChannelList attribute. + +Upon receipt of the AddBlockChannels command, the media device SHALL check if the channels + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 561 +``` + +passed in this command are valid. If the channel is invalid, then a response with InvalidChannel +error Status SHALL be returned. + +If there is at least one channel in Channels field which is not in the BlockChannelList attribute, the +media device SHALL process the request by adding these new channels into the BlockChannelList +attribute and return a successful Status Response. During this process, the media device SHALL +assign one unique index to BlockChannelIndex field for every channel passed in this command. + +If all channels in Channel field already exist in the BlockChannelList attribute, then a response with +ChannelAlreadyExist error Status SHALL be returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Channels list[BlockCha +nnelStruct] +``` +``` +all M +``` +**6.13.8.12.1. Channels Field** + +This field indicates a set of channels that SHALL be blocked when the Content Control feature is +activated. This field SHALL be set to values present in ChannelList attribute in the Channel cluster. +The BlockChannelIndex field passed in this command SHALL be NULL. + +**6.13.8.13. RemoveBlockChannels command** + +The purpose of this command is to remove channels from the BlockChannelList attribute. + +Upon receipt of the RemoveBlockChannels command, the media device SHALL check if the chan­ +nels indicated by ChannelIndexes passed in this command are present in BlockChannelList +attribute. If one or more channels indicated by ChannelIndexes passed in this command field are +not present in the BlockChannelList attribute, then a response with ChannelNotExist error Status +SHALL be returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ChannelIn­ +dexes +``` +``` +list[uint16] all M +``` +**6.13.8.13.1. ChannelIndexes Field** + +This field SHALL specify a set of indexes indicating Which channels SHALL be removed from the +BlockChannelList attribute. + +**6.13.8.14. AddBlockApplications Command** + +The purpose of this command is to set applications to the BlockApplicationList attribute. + +Upon receipt of the AddBlockApplications command, the media device SHALL check if the Applica­ +tions passed in this command are installed. If there is an application in Applications field which is +not identified by media device, then a response with UnidentifiableApplication error Status MAY be + +``` +Page 562 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +returned. + +If there is one or more applications which are not present in BlockApplicationList attribute, the +media device SHALL process the request by adding the new application to the BlockApplicationList +attribute and return a successful Status Response. + +If all applications in Applications field are already present in BlockApplicationList attribute, then a +response with ApplicationAlreadyExist error Status SHALL be returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Applica­ +tions +``` +``` +list[AppIn­ +foStruct] +``` +``` +all M +``` +**6.13.8.14.1. Applications Field** + +This field indicates a set of applications that SHALL be blocked when the Content Control feature is +activated. + +**6.13.8.15. RemoveBlockApplications Command** + +The purpose of this command is to remove applications from the BlockApplicationList attribute. + +Upon receipt of the RemoveBlockApplications command, the media device SHALL check if the +applications passed in this command present in the BlockApplicationList attribute. If one or more +applications in Applications field which are not present in the BlockApplicationList attribute, then a +response with ApplicationNotExist error Status SHALL be returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Applica­ +tions +``` +``` +list[AppIn­ +foStruct] +``` +``` +all M +``` +**6.13.8.15.1. Applications Field** + +This field indicates a set of applications which SHALL be removed from BlockApplicationList +attribute. + +**6.13.8.16. SetBlockContentTimeWindow Command** + +The purpose of this command is to set the BlockContentTimeWindow attribute. + +Upon receipt of the SetBlockContentTimeWindow command, the media device SHALL check if the +TimeWindowIndex field passed in this command is NULL. If the TimeWindowIndex field is NULL, +the media device SHALL check if there is an entry in the BlockContentTimeWindow attribute which +matches with the TimePeriod and DayOfWeek fields passed in this command. * If Yes, then a +response with TimeWindowAlreadyExist error status SHALL be returned. * If No, then the media +device SHALL assign one unique index for this time window and add it into the BlockContent­ +TimeWindow list attribute. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 563 +``` + +If the TimeWindowIndex field is not NULL and presents in the BlockContentTimeWindow attribute, +the media device SHALL replace the original time window with the new time window passed in this +command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TimeWin­ +dow +``` +``` +TimeWin­ +dowStruct +``` +### M + +**6.13.8.16.1. TimeWindow Field** + +This field SHALL indicate a time window requested to set to the BlockContentTimeWindow +attribute. + +**6.13.8.17. RemoveBlockContentTimeWindow Command** + +The purpose of this command is to remove the selected time windows from the BlockContent­ +TimeWindow attribute. + +Upon receipt of the RemoveBlockContentTimeWindow command, the media device SHALL check if +the time window index passed in this command presents in the BlockContentTimeWindow +attribute. + +If one or more time window indexes passed in this command are not present in BlockContent­ +TimeWindow attribute, then a response with TimeWindowNotExist error status SHALL be +returned. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TimeWin­ +dowIndexes +``` +``` +list[uint16] M +``` +**6.13.8.17.1. TimeWindowIndexes Field** + +This field SHALL specify a set of time window indexes indicating which time windows will be +removed from the BlockContentTimeWindow attribute. + +**6.13.9. Events** + +``` +ID Name Priority Access Conformance +0x00 Remain­ +ingScreenTime­ +Expired +``` +### INFO V ST + +``` +0x01 EnteringBlock­ +ContentTimeWin­ +dow +``` +### INFO V BTW + +``` +Page 564 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.13.9.1. RemainingScreenTimeExpired Event** + +This event SHALL be generated when the RemainingScreenTime equals 0. + +**6.13.9.2. EnteringBlockContentTimeWindow Event** + +This event SHALL be generated when entering a period of blocked content as configured in the +BlockContentTimeWindow attribute. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 565 +``` + +Page 566 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 7. Robots** + +The Cluster Library is made of individual chapters such as this one. See Document Control in the +Cluster Library for a list of all chapters and documents. References between chapters are made +using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. + +**7.1. General Description** + +**7.1.1. Introduction** + +The clusters specified in this section define the operation of robotic devices, such as Robotic Vac­ +uum Cleaners (RVCs). + +**7.1.2. Cluster List** + +This section lists the RVC specific clusters as specified in this chapter. + +_Table 12. Overview of the RVC Clusters_ + +``` +Cluster ID Cluster Name Description +0x0054 RVC Run Mode Commands and attributes for +controlling the running mode of +an RVC device. +0x0055 RVC Clean Mode Commands and attributes for +controlling the cleaning mode +of an RVC device. +0x0061 RVC Operational State Commands and attributes for +monitoring and controlling the +operational state of an RVC +device. +``` +**7.2. RVC Run Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for the running modes of robotic vacuum cleaner devices. + +**7.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 567 +``` + +``` +Revision Description +2 Add constraint about switching from non-Idle to +non-Idle modes. ChangeToModeResponse com­ +mand: StatusText must be provided for Invalid­ +InMode status. Deprecate the OnMode attribute +and the related feature map bit. Add the Map­ +ping mode tag. +3 Remove constraint on changing cleaning modes +while the RVC Run Mode cluster is in a non-Idle +mode. Continue to allow InvalidInMode +response for devices that do not support such +mode changes. +``` +**7.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint RVCRUNM +``` +**7.2.3. Cluster ID** + +``` +ID Name +0x0054 RVC Run Mode +``` +**7.2.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**7.2.4.1. DirectModeChange Feature** + +This feature indicates whether the cluster implementation supports changing the run modes while +the RVC Run Mode cluster’s CurrentMode attribute is set to a mode without the Idle mode tag. If the +implementation does not support such a change, the ChangeToModeResponse command SHALL +have the StatusCode field set to the InvalidInMode value. + +**7.2.5. Data Types** + +**7.2.5.1. ModeOptionStruct Type** + +The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOption­ +Struct type. A blank field indicates no change. + +``` +Page 568 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label M +1 Mode M +2 ModeTags 1 to 8 M +``` +**7.2.6. Attributes** + +The table below lists the changes relative to the Mode Base cluster for the attributes. A blank field +indicates no change. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +0x0001 Current­ +Mode +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +**7.2.6.1. SupportedModes Attribute** + +At least one entry in the SupportedModes attribute SHALL include the Idle mode tag in the Mode­ +Tags field. + +At least one entry in the SupportedModes attribute (different from the one above) SHALL include +the Cleaning mode tag in the ModeTags field. + +The Mapping, Cleaning, and Idle mode tags are mutually exclusive and SHALL NOT be used +together in a mode’s ModeTags. + +**7.2.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**7.2.7.1. ChangeToModeResponse Command Namespace Definitions** + +The following table defines the derived cluster specific StatusCode values. + +``` +Status Code Value Name +0x41 Stuck +0x42 DustBinMissing +0x43 DustBinFull +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 569 +``` + +``` +Status Code Value Name +0x44 WaterTankEmpty +0x45 WaterTankMissing +0x46 WaterTankLidOpen +0x47 MopCleaningPadMissing +0x48 BatteryLow +``` +**7.2.7.2. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +0x4000 Idle +0x4001 Cleaning +0x4002 Mapping +``` +**7.2.7.2.1. Idle Tag** + +The device is not performing any of the main operations of the other modes. However, auxiliary +actions, such as seeking the charger or charging, may occur. + +For example, the device has completed cleaning, successfully or not, on its own or due to a com­ +mand, or has not been asked to clean after a restart. + +**7.2.7.2.2. Cleaning Tag** + +The device was asked to clean so it may be actively running, or paused due to an error, due to a +pause command, or for recharging etc. If currently paused and the device can resume it will con­ +tinue to clean. + +``` +Page 570 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.2.7.2.3. Mapping Tag** + +The device was asked to create a map of the space it is located in, so it may be actively running, or +paused due to an error, due to a pause command, or for recharging etc. If currently paused and the +device can resume, it will continue to map. + +### NOTE + +``` +this mode is intended to be used so the current space can be mapped by the device +if the robot has not previously done that, or if the layout has substantially changed, +for an optimal subsequent cleaning experience. +``` +**7.2.8. Mode Use** + +- Clients SHALL start a cleaning cycle by switching from a mode with the Idle mode tag to a mode + with the Cleaning mode tag. +- Clients SHALL stop a cleaning cycle by switching from a mode with the Cleaning mode tag to a + mode with the Idle mode tag. +- Clients SHALL start a mapping cycle by switching from a mode with the Idle mode tag to a mode + with the Mapping mode tag. +- Clients SHALL stop a mapping cycle by switching from a mode with the Mapping mode tag to a + mode with the Idle mode tag. + +The RVC Run Mode cluster’s SupportedModes attribute MAY include multiple modes with the Clean­ +ing mode tag, and/or modes with the Mapping mode tag. + +**7.3. RVC Clean Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for the cleaning type of robotic vacuum cleaner devices. + +**7.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Add constraint about changing cleaning modes +while the RVC Run Mode cluster is in a non-Idle +mode. ChangeToModeResponse command: Sta­ +tusText must be provided for InvalidInMode sta­ +tus. Deprecate the OnMode attribute and the +related feature map bit. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 571 +``` + +``` +Revision Description +3 Remove constraint on changing cleaning modes +while the RVC Run Mode cluster is in a non-Idle +mode. Continue to allow InvalidInMode +response for devices that do not support such +mode changes. +``` +**7.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint RVCCLEANM +``` +**7.3.3. Cluster ID** + +``` +ID Name +0x0055 RVC Clean Mode +``` +**7.3.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**7.3.5. Data Types** + +**7.3.5.1. ModeOptionStruct Type** + +The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOption­ +Struct type. A blank field indicates no change. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label M +1 Mode M +2 ModeTags 1 to 8 M +``` +**7.3.6. Attributes** + +The table below lists the changes relative to the Mode Base cluster for the attributes. A blank field +indicates no change. + +``` +Page 572 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +0x0001 Current­ +Mode +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +**7.3.6.1. SupportedModes Attribute** + +At least one entry in the SupportedModes attribute SHALL include the Vacuum and/or the Mop +mode tag in the ModeTags field list. + +**7.3.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**7.3.7.1. ChangeToModeResponse Command Namespace Definitions** + +The following table defines the derived cluster specific StatusCode values. + +``` +Status Code Value Name +0x40 CleaningInProgress +``` +**7.3.7.2. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +0x4000 DeepClean +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 573 +``` + +``` +Mode Tag Value Name +0x4001 Vacuum +0x4002 Mop +``` +**7.3.7.2.1. Deep Clean Tag** + +While in this mode, the device is optimizing for improved cleaning. + +**7.3.7.2.2. Vacuum Tag** + +The device’s vacuuming feature is enabled in this mode. + +**7.3.7.2.3. Mop Tag** + +The device’s mopping feature is enabled in this mode. + +**7.3.8. Mode Examples** + +A few examples of modes and their mode tags are provided below. + +For the "Turbo, Vacuum Only" mode, tags: 0x4000 (Deep Clean), 0x4001 (Vacuum). + +For the "Mop Only" mode, tags: 0x4002 (Mop), 0x0003 (Low Noise). + +For the "Rapid Vacuum and Mop" mode, tags: 0x0001 (Quick), 0x4001 (Vacuum), 0x4002 (Mop). + +Note that the "Low Noise" and "Quick" mode tags are defined in the generic Mode Base cluster spec­ +ification. + +**7.4. RVC Operational State Cluster** + +This cluster is derived from the Operational State cluster and provides an interface for monitoring +the operational state of a robotic vacuum cleaner. + +**7.4.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 The Pause and Resume commands are usable in +all compatible states. Deprecate the Start and +Stop commands. Add the GoHome command. +``` +**7.4.2. Classification** + +``` +Page 574 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Hierarchy Role Scope PICS Code +Operational State Application Endpoint RVCOPSTATE +``` +**7.4.3. Cluster ID** + +``` +ID Name +0x0061 RVC Operational State +``` +**7.4.4. Data Types** + +**7.4.4.1. OperationalStateEnum Type** + +This data type is derived from enum8. + +The values defined herein are applicable to this derived cluster of Operational State only and are +additional to the set of values defined in Operational State itself. + +``` +Value Name Summary Conformance +0x00 Stopped The device is stopped M +0x01 Running The device is operating M +0x02 Paused The device is paused +during an operation +``` +### M + +``` +0x03 Error The device is in an +error state +``` +### M + +``` +0x40 SeekingCharger The device is en route +to the charging dock +``` +### M + +``` +0x41 Charging The device is charging M +0x42 Docked The device is on the +dock, not charging +``` +### M + +RVC Pause Compatibility defines the compatibility of the states this cluster defines with the Pause +command. + +_Table 13. RVC Pause Compatibility_ + +``` +State Value State Name Pause-Compatible Notes +0x40 SeekingCharger Y +0x41 Charging N +0x42 Docked N +``` +RVC Resume Compatibility defines the compatibility of the states this cluster defines with the +Resume command. + +_Table 14. RVC Resume Compatibility_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 575 +``` + +``` +State Value State Name Resume-Compatible Notes +0x40 SeekingCharger N +0x41 Charging Y +0x42 Docked Y +``` +While in the Charging or Docked states, the device SHALL NOT attempt to resume unless it transi­ +tioned to those states while operating and can resume, such as, for example, if it is recharging while +in a cleaning cycle. Else, if the operational state is Charging or Docked but there’s no operation to +resume or the operation can’t be resumed, the device SHALL respond with an OperationalComman­ +dResponse command with an ErrorStateID of CommandInvalidInState but take no further action. + +**7.4.4.2. ErrorStateEnum Type** + +This data type is derived from enum8. + +The values defined herein are applicable to this derived cluster of Operational State only and are +additional to the set of values defined in Operational State itself. + +``` +Value Name Summary Conformance +0x00 NoError The device is not in an +error state +``` +### M + +``` +0x01 UnableToStartOrRe­ +sume +``` +``` +The device is unable to +start or resume opera­ +tion +``` +### M + +``` +0x02 UnableToCompleteOp­ +eration +``` +``` +The device was unable +to complete the current +operation +``` +### M + +``` +0x03 CommandInvalidIn­ +State +``` +``` +The device cannot +process the command +in its current state +``` +### M + +``` +0x40 FailedToFindCharg­ +ingDock +``` +``` +The device has failed to +find or reach the charg­ +ing dock +``` +### M + +``` +0x41 Stuck The device is stuck and +requires manual inter­ +vention +``` +### M + +``` +0x42 DustBinMissing The device has detected +that its dust bin is miss­ +ing +``` +### M + +``` +0x43 DustBinFull The device has detected +that its dust bin is full +``` +### M + +``` +Page 576 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0x44 WaterTankEmpty The device has detected +that its water tank is +empty +``` +### M + +``` +0x45 WaterTankMissing The device has detected +that its water tank is +missing +``` +### M + +``` +0x46 WaterTankLidOpen The device has detected +that its water tank lid is +open +``` +### M + +``` +0x47 MopCleaningPadMiss­ +ing +``` +``` +The device has detected +that its cleaning pad is +missing +``` +### M + +**7.4.5. Commands** + +The table below lists the changes relative to the Operational State cluster for the commands. A +blank field indicates no change. + +``` +ID Name Direction Response Access Conformance +0x00 Pause +0x01 Stop X +0x02 Start X +0x03 Resume +0x04 Operational­ +Comman­ +dResponse +0x80 GoHome client ⇒ server Operational­ +Comman­ +dResponse +``` +### O O + +**7.4.5.1. GoHome Command** + +On receipt of this command, the device SHALL start seeking the charging dock, if possible in the +current state of the device. + +If this command is received when already in the SeekingCharger state the device SHALL respond +with an OperationalCommandResponse command with an ErrorStateID of NoError but the com­ +mand SHALL have no other effect. + +A device that receives this command in any state which does not allow seeking the charger, such as +Charging or Docked, SHALL respond with an OperationalCommandResponse command with an +ErrorStateID of CommandInvalidInState and SHALL have no other effect. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 577 +``` + +Otherwise, on success: + +- The OperationalState attribute SHALL be set to SeekingCharger. +- The device SHALL respond with an OperationalCommandResponse command with an + ErrorStateID of NoError. + +``` +Page 578 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 8. Home Appliances** + +The Cluster Library is made of individual chapters such as this one. See Document Control in the +Cluster Library for a list of all chapters and documents. References between chapters are made +using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. + +**8.1. General Description** + +**8.1.1. Introduction** + +The clusters specified in this section are typically used in control of home appliances, such as laun­ +dry washers, refrigerators etc. + +**8.1.2. Cluster List** + +This section lists the home appliance specific clusters as specified in this chapter. + +_Table 15. Overview of the Home Appliance Clusters_ + +``` +Cluster ID Cluster Name Description +Common Clusters +0x0056 Temperature Control Commands and attributes for +control of a temperature set +point +Dishwasher Clusters +0x0059 Dishwasher Mode Commands and attributes for +controlling a dishwasher +0x005D Dishwasher Alarm Alarm definitions for Dish­ +washer devices +Laundry Clusters (General) +0x0051 Laundry Washer Mode Commands and attributes for +controlling a laundry washer or +dryer +Laundry Dryer Clusters +0x004A Laundry Dryer Controls Commands and attributes for +the control of options on a +device that does laundry drying +Laundry Washer Clusters +0x0053 Laundry Washer Controls Commands and attributes for +the control of options on a +device that does laundry wash­ +ing +Microwave Oven Clusters +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 579 +``` + +``` +Cluster ID Cluster Name Description +0x005E Microwave Oven Mode Modes associated with a +Microwave Oven +0x005F Microwave Oven Control Commands and attributes for +controlling a Microwave Oven +Oven Clusters +0x0048 Oven Operational State Operational states and phases +associated with an Oven +0x0049 Oven Mode Modes associated with an Oven +Refrigerator Clusters +0x0052 Refrigerator And Temperature +Controlled Cabinet Mode +``` +``` +Commands and attributes for +controlling a refrigerator or a +temperature controlled cabinet +0x0057 Refrigerator Alarm Alarm definitions for Refrigera­ +tor devices +``` +**8.2. Temperature Control Cluster** + +This cluster provides an interface to the setpoint temperature on devices such as washers, refriger­ +ators, and water heaters. The setpoint temperature is the temperature to which a device using this +cluster would attempt to control to. This cluster does not provide access to the actual or physical +temperature associated with any device using this cluster. Access to the physical temperature asso­ +ciated with a device using this cluster would be provided by other clusters as part of that devices +device type definition. + +The values and constraints of the attributes communicated to clients SHOULD match the controls +on any physical interface on a device implementing this server. For example, the value of the Step +attribute SHOULD match the incremental value by which the temperature setpoint can be changed +on the physical device. + +**8.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**8.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint TCTL +``` +``` +Page 580 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.2.3. Cluster ID** + +``` +ID Name +0x0056 Temperature Control +``` +**8.2.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 TN TemperatureNum­ +ber +``` +``` +O.a Use actual temper­ +ature numbers +1 TL TemperatureLevel O.a Use temperature +levels +2 STEP TemperatureStep [TN] Use step control +with temperature +numbers +``` +**8.2.4.1. TemperatureNumber Feature** + +For devices that use an actual temperature value for the temperature setpoint, such as some water +heaters, the feature TN SHALL be used. Note that this cluster provides and supports temperatures +in degrees Celsius via the temperature data type. + +**8.2.4.2. TemperatureLevel Feature** + +For devices that use vendor-specific temperature levels for the temperature setpoint, such as some +washers, the feature TL SHALL be used. + +**8.2.4.3. TemperatureStep Feature** + +For devices that support discrete temperature setpoints that are larger than the temperature reso­ +lution imposed via the temperature data type, the Step feature MAY be used. + +**8.2.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Tempera­ +tureSet­ +point +``` +``` +tempera­ +ture +``` +``` +MinTem­ +perature to +MaxTem­ +perature +``` +### R V TN + +``` +0x0001 MinTem­ +perature +``` +``` +tempera­ +ture +``` +``` +max (Max­ +Tempera­ +ture - 1)* +``` +### F R V TN + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 581 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0002 MaxTem­ +perature +``` +``` +tempera­ +ture +``` +``` +desc F R V TN +``` +``` +0x0003 Step tempera­ +ture +``` +``` +max (Max­ +Tempera­ +ture - +MinTem­ +perature) +``` +### F R V STEP + +``` +0x0004 Select­ +edTemper­ +a­ +tureLevel +``` +``` +uint8 max 31 R V TL +``` +``` +0x0005 Support­ +edTemper­ +a­ +tureLevels +``` +``` +list[string] max +32[max 16] +``` +### R V TL + +``` +NOTE * See temperature data type, in the data model, for encoding units. +``` +**8.2.5.1. TemperatureSetpoint Attribute** + +This attribute SHALL represent the desired Temperature Setpoint on the device. + +**8.2.5.2. MinTemperature Attribute** + +This attribute SHALL represent the minimum temperature to which the TemperatureSetpoint +attribute MAY be set. + +**8.2.5.3. MaxTemperature Attribute** + +This attribute SHALL represent the maximum temperature to which the TemperatureSetpoint +attribute MAY be set. + +If the Step attribute is supported, this attribute SHALL be such that MaxTemperature = MinTemper­ +ature + Step * n, where n is an integer and n > 0. If the Step attribute is not supported, this attribute +SHALL be such that MaxTemperature > MinTemperature. + +**8.2.5.4. Step Attribute** + +This attribute SHALL represent the discrete value by which the TemperatureSetpoint attribute can +be changed via the SetTemperature command. + +``` +For example, if the value of MinTemperature is 25.00C (2500) and the Step value is 0.50C (50), +valid values of the TargetTemperature field of the SetTemperature command would be 25.50C +(2550), 26.00C (2600), 26.50C (2650), etc. +``` +``` +Page 582 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.2.5.5. SelectedTemperatureLevel Attribute** + +This attribute SHALL represent the currently selected temperature level setting of the server. This +attribute SHALL be the positional index of the list item in the SupportedTemperatureLevels list that +represents the currently selected temperature level setting of the server. + +**8.2.5.6. SupportedTemperatureLevels Attribute** + +This attribute SHALL represent the list of supported temperature level settings that may be selected +via the TargetTemperatureLevel field in the SetTemperature command. Each string is readable text +that describes each temperature level setting in a way that can be easily understood by humans. +For example, a washing machine can have temperature levels like "Cold", "Warm", and "Hot". Each +string is specified by the manufacturer. + +Each item in this list SHALL represent a unique temperature level. Each entry in this list SHALL +have a unique value. The entries in this list SHALL appear in order of increasing temperature level +with list item 0 being the setting with the lowest temperature level. + +**8.2.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 SetTempera­ +ture +``` +``` +client ⇒ server Y O M +``` +**8.2.6.1. SetTemperature Command** + +The SetTemperature command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TargetTem­ +perature +``` +``` +temperature desc TN +``` +``` +1 TargetTem­ +pera­ +tureLevel +``` +``` +uint8 desc TL +``` +**8.2.6.1.1. TargetTemperature Field** + +This field SHALL specify the desired temperature setpoint that the server is to be set to. + +The TargetTemperature SHALL be from MinTemperature to MaxTemperature inclusive. If the Step +attribute is supported, TargetTemperature SHALL be such that (TargetTemperature - MinTempera­ +ture) % Step == 0. + +**8.2.6.1.2. TargetTemperatureLevel Field** + +This field SHALL specify the index of the list item in the SupportedTemperatureLevels list that rep­ +resents the desired temperature level setting of the server. The value of this field SHALL be +between 0 and the length of the SupportedTemperatureLevels list -1. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 583 +``` + +**8.2.6.1.3. Effect on Receipt** + +If the TargetTemperature or TargetTemperatureLevel fields of the command meet all constraints +but the server is unable to execute the command at the time the command is received by the server +(e.g. due to the design of a device it cannot accept a change in its temperature setting after it has +begun operation), then the server SHALL respond with a status code of INVALID_IN_STATE, and dis­ +card the command. + +If the TN feature is supported, on receipt of this command, + +- If the value of the TargetTemperature field meets all constraints, the server SHALL set the Tem­ + peratureSetpoint attribute to the value of the TargetTemperature field and the response SHALL + have a status code of SUCCESS. +- Otherwise (e.g. if the value of the TargetTemperature field falls outside of the constraints of the + TemperatureSetpoint attribute or if the Step attribute is supported in the server and the value + of the TargetTemperature field is such that (TargetTemperature - MinTemperature) % Step != 0), + the status of the response SHALL be CONSTRAINT_ERROR and the value of the TemperatureSet­ + point attribute SHALL remain unchanged. + +If the TL feature is supported, on receipt of this command, + +- If value of the TargetTemperatureLevel field meets all constraints, the server SHALL set its + SelectedTemperatureLevel attribute to the value of TargetTemperatureLevel field and respond + with status SUCCESS. +- Otherwise (e.g. if the value of the TargetTemperatureLevel field is out of bounds of the Support­ + edTemperatureLevels list), the status of the response SHALL be CONSTRAINT_ERROR, and the + value of SelectedTemperatureLevel SHALL remain unchanged. + +**8.3. Dishwasher Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for dishwasher devices. + +**8.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 ChangeToModeResponse command: StatusText +must be provided for InvalidInMode status +3 Set OnOff feature as disallowed (previously a +Device Type override), Set StartUpMode and +OnMode as disallowed (previously provisional) +``` +``` +Page 584 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint DISHM +``` +**8.3.3. Cluster ID** + +``` +ID Name +0x0059 Dishwasher Mode +``` +**8.3.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**8.3.5. Data Types** + +**8.3.5.1. ModeOptionStruct Type** + +The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOption­ +Struct type. A blank field indicates no change. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label M +1 Mode M +2 ModeTags 1 to 8 M +``` +**8.3.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +``` +### M + +``` +0x0001 Current­ +Mode +``` +### M + +``` +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 585 +``` + +**8.3.6.1. SupportedModes Attribute** + +At least one entry in the SupportedModes attribute SHALL include the Normal mode tag in the Mod­ +eTags field list. + +**8.3.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**8.3.7.1. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +0x4000 Normal +0x4001 Heavy +0x4002 Light +``` +**8.3.7.1.1. Normal Tag** + +The normal regime of operation. + +**8.3.7.1.2. Heavy Tag** + +Mode optimized for washing heavily-soiled dishes. + +**8.3.7.1.3. Light Tag** + +Mode optimized for light washing. + +**8.4. Dishwasher Alarm Cluster** + +This cluster is a derived cluster of the Alarm Base cluster and provides the alarm definition related +to dishwasher devices. + +``` +Page 586 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.4.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**8.4.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Alarm Base Application Endpoint DISHALM +``` +**8.4.3. Cluster ID** + +``` +ID Name +0x005D Dishwasher Alarm +``` +**8.4.4. Data Types** + +**8.4.4.1. AlarmBitmap Type** + +This data type is derived from map32. + +``` +Bit Name Summary Conformance +0 InflowError Water inflow is abnor­ +mal +``` +``` +P, O.a+ +``` +``` +1 DrainError Water draining is +abnormal +``` +``` +P, O.a+ +``` +``` +2 DoorError Door or door lock is +abnormal +``` +``` +O.a+ +``` +``` +3 TempTooLow Unable to reach normal +temperature +``` +``` +P, O.a+ +``` +``` +4 TempTooHigh Temperature is too +high +``` +``` +P, O.a+ +``` +``` +5 WaterLevelError Water level is abnor­ +mal +``` +``` +P, O.a+ +``` +**8.5. Laundry Washer Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for laundry washer as well as laundry dryer devices. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 587 +``` + +**8.5.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 ChangeToModeResponse command: StatusText +must be provided for InvalidInMode status +3 Set OnOff feature, StartUpMode, and OnMode as +disallowed (previously a Device Type override) +``` +**8.5.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint LWM +``` +**8.5.3. Cluster ID** + +``` +ID Name +0x0051 Laundry Washer Mode +``` +**8.5.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**8.5.5. Data Types** + +**8.5.5.1. ModeOptionStruct Type** + +The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOption­ +Struct type. A blank field indicates no change. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label M +1 Mode M +2 ModeTags 1 to 8 M +``` +``` +Page 588 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.5.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +``` +### M + +``` +0x0001 Current­ +Mode +``` +### M + +``` +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +**8.5.6.1. SupportedModes Attribute** + +At least one entry in the SupportedModes attribute SHALL include the Normal mode tag in the Mod­ +eTags field list. + +**8.5.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**8.5.7.1. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +0x4000 Normal +0x4001 Delicate +0x4002 Heavy +0x4003 Whites +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 589 +``` + +**8.5.7.1.1. Normal Tag** + +The normal regime of operation. + +**8.5.7.1.2. Delicate Tag** + +Mode optimized for washing delicate garments. + +**8.5.7.1.3. Heavy Tag** + +Mode optimized for heavy washing. + +**8.5.7.1.4. Whites Tag** + +Mode optimized for stain removal on white fabrics. + +**8.5.8. Mode Examples** + +A few examples of Laundry modes and their mode tags are provided below. + +- For the "Heavy Wash, Whites" mode, tags: 0x4002 (Heavy), 0x4003 (Whites). +- For the "Fast" mode, tags: 0x0001 (Quick), 0x4000 (Normal). + +**8.6. Laundry Washer Controls Cluster** + +This cluster provides a way to access options associated with the operation of a laundry washer +device type. + +**8.6.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Updated Feature Map Conformance +``` +**8.6.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint WASHERCTRL +``` +**8.6.3. Cluster ID** + +``` +ID Name +0x0053 Laundry Washer Controls +``` +``` +Page 590 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.6.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 SPIN Spin O.a+ Multiple spin +speeds supported +1 RINSE Rinse O.a+ Multiple rinse +cycles supported +``` +**8.6.4.1. Spin Feature** + +This feature indicates multiple spin speeds are supported in at least one supported mode. Note that +some modes may not support multiple spin speeds even if this feature is supported. + +**8.6.4.2. Rinse Feature** + +This feature indicates multiple rinse cycles are supported in at least one supported mode. Note that +some modes may not support selection of the number of rinse cycles even if this feature is sup­ +ported. + +**8.6.5. Data Types** + +**8.6.5.1. NumberOfRinsesEnum Type** + +This data type is derived from enum8. + +The NumberOfRinsesEnum provides a representation of the number of rinses that will be per­ +formed for a selected mode. NumberOfRinsesEnum is derived from enum8. It is up to the device +manufacturer to determine the mapping between the enum values and the corresponding numbers +of rinses. + +``` +Value Name Summary Conformance +0 None This laundry washer +mode does not perform +rinse cycles +``` +### RINSE + +``` +1 Normal This laundry washer +mode performs normal +rinse cycles determined +by the manufacturer +``` +### RINSE + +``` +2 Extra This laundry washer +mode performs an +extra rinse cycle +``` +### RINSE + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 591 +``` + +``` +Value Name Summary Conformance +3 Max This laundry washer +mode performs the +maximum number of +rinse cycles determined +by the manufacturer +``` +### RINSE + +**8.6.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Spin­ +Speeds +``` +``` +list[string] max +16[max 64] +``` +### R V SPIN + +``` +0x0001 Spin­ +SpeedCur­ +rent +``` +``` +uint8 max 15 X desc RW VO SPIN +``` +``` +0x0002 Num­ +berOfRins +es +``` +``` +Num­ +berOfRins­ +esEnum +``` +``` +desc 1 RW VO RINSE +``` +``` +0x0003 Support­ +edRinses +``` +``` +list[Num­ +berOfRins­ +esEnum] +``` +``` +max 4 R V RINSE +``` +**8.6.6.1. SpinSpeeds Attribute** + +This attribute SHALL indicate the list of spin speeds available to the appliance in the currently +selected mode. The spin speed values are determined by the manufacturer. At least one spin speed +value SHALL be provided in the SpinSpeeds list. The list of spin speeds MAY change depending on +the currently selected Laundry Washer mode. For example, Quick mode might have a completely +different list of SpinSpeeds than Delicates mode. + +**8.6.6.2. SpinSpeedCurrent Attribute** + +This attribute SHALL indicate the currently selected spin speed. It is the index into the SpinSpeeds +list of the selected spin speed, as such, this attribute can be an integer between 0 and the number of +entries in SpinSpeeds - 1. If a value is received that is outside of the defined constraints, a CON­ +STRAINT_ERROR SHALL be sent as the response. If a value is attempted to be written that doesn’t +match a valid index (e.g. an index of 5 when the list has 4 values), a CONSTRAINT_ERROR SHALL be +sent as the response. If null is written to this attribute, there will be no spin speed for the selected +cycle. If the value is null, there will be no spin speed on the current mode. + +**8.6.6.3. NumberOfRinses Attribute** + +This attribute SHALL indicate how many times a rinse cycle SHALL be performed on a device for +the current mode of operation. A value of None SHALL indicate that no rinse cycle will be per­ +formed. This value may be set by the client to adjust the number of rinses that are performed for + +``` +Page 592 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +the current mode of operation. If the device is not in a compatible state to accept the provided +value, an INVALID_IN_STATE error SHALL be sent as the response. + +**8.6.6.4. SupportedRinses Attribute** + +This attribute SHALL indicate the amount of rinses allowed for a specific mode. Each entry SHALL +indicate a NumberOfRinsesEnum value that is possible in the selected mode on the device. The +value of this attribute MAY change at runtime based on the currently selected mode. Each entry +SHALL be distinct. + +**8.7. Refrigerator And Temperature Controlled Cabinet** + +**Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for refrigerator and temperature controlled cabinet devices. + +**8.7.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 ChangeToModeResponse command: StatusText +must be provided for InvalidInMode status +3 Set OnOff feature, StartUpMode, and OnMode as +disallowed (previously a Device Type override) +``` +**8.7.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint TCCM +``` +**8.7.3. Cluster ID** + +``` +ID Name +0x0052 Refrigerator And Temperature Controlled Cabi­ +net Mode +``` +**8.7.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 593 +``` + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**8.7.5. Data Types** + +**8.7.5.1. ModeOptionStruct Type** + +The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOption­ +Struct type. A blank field indicates no change. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label M +1 Mode M +2 ModeTags 1 to 8 M +``` +**8.7.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +``` +### M + +``` +0x0001 Current­ +Mode +``` +### M + +``` +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +**8.7.6.1. SupportedModes Attribute** + +At least one entry in the SupportedModes attribute SHALL include the Auto mode tag in the Mode­ +Tags field list. + +**8.7.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**8.7.7.1. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +``` +``` +Page 594 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Mode Tag Value Name +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +0x4000 RapidCool +0x4001 RapidFreeze +``` +**8.7.7.1.1. RapidCool Tag** + +This mode reduces the temperature rapidly, typically above freezing grade. + +**8.7.7.1.2. RapidFreeze Tag** + +This mode reduces the temperature rapidly, below freezing grade. + +**8.7.8. Mode Examples** + +A few examples of Refrigerator and Temperature Controlled Cabinet modes and their mode tags +are provided below. + +- For the "Normal" mode, tags: 0x0000 (Auto) +- For the "Energy Save" mode, tags: 0x0004 (LowEnergy) +- For the "Rapid Cool" mode, tags: 0x4000 (RapidCool) + +**8.8. Refrigerator Alarm Cluster** + +This cluster is a derived cluster of Alarm Base cluster and provides the alarm definition related to +refrigerator and temperature controlled cabinet devices. + +**8.8.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 595 +``` + +**8.8.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Alarm Base Application Endpoint REFALM +``` +**8.8.3. Cluster ID** + +``` +ID Name +0x0057 Refrigerator Alarm +``` +**8.8.4. Features** + +``` +Bit Code Feature Conformance Summary +0 RESET Reset X Supports the abil­ +ity to reset alarms +``` +**8.8.5. Data Types** + +**8.8.5.1. AlarmBitmap Type** + +This data type is derived from map32. + +``` +Bit Name Summary Conformance +0 DoorOpen The cabinet’s door has +been open for a vendor +defined amount of +time. +``` +### M + +**8.8.6. Attributes** + +**8.8.6.1. Mask Attribute** + +If the generation of the alarm has not been suppressed at the device itself, then this attribute +SHALL have these fixed values. + +``` +Bit Name Value +0 DoorOpen 1 +``` +This alarm SHALL be cleared only when the door is closed (manual action). + +If the generation of the alarm is suppressed at the device itself, then bit 0 SHALL have a value of 0. +It SHALL be re-set to 1 if the alarm is re-enabled at the device itself. + +**8.8.7. Commands** + +``` +Page 596 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Direction Response Access Conformance +0x01 ModifyEn­ +abledAlarms +``` +### X + +**8.9. Laundry Dryer Controls Cluster** + +This cluster provides a way to access options associated with the operation of a laundry dryer +device type. + +**8.9.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**8.9.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint DRYERCTRL +``` +**8.9.3. Cluster ID** + +``` +ID Name +0x004A Laundry Dryer Controls +``` +**8.9.4. Data Types** + +**8.9.4.1. DrynessLevelEnum Type** + +This data type is derived from enum8. + +This enum provides a representation of the level of dryness that will be used while drying in a +selected mode. + +It is up to the device manufacturer to determine the mapping between the enum values and the +corresponding temperature level. + +``` +Value Name Summary Conformance +0 Low Provides a low dryness +level for the selected +mode +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 597 +``` + +``` +Value Name Summary Conformance +1 Normal Provides the normal +level of dryness for the +selected mode +``` +### M + +``` +2 Extra Provides an extra dry­ +ness level for the +selected mode +``` +### M + +``` +3 Max Provides the max dry­ +ness level for the +selected mode +``` +### M + +**8.9.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edDry­ +nessLevels +``` +``` +list[Dry­ +nessLeve­ +lEnum] +``` +``` +1 to 4 R V M +``` +``` +0x0001 SelectedDr +ynessLevel +``` +``` +Dry­ +nessLeve­ +lEnum +``` +``` +desc X desc RW VO M +``` +**8.9.5.1. SupportedDrynessLevels Attribute** + +This attribute SHALL indicate the list of supported dryness levels available to the appliance in the +currently selected mode. The dryness level values are determined by the manufacturer. At least one +dryness level value SHALL be provided in the SupportedDrynessLevels list. The list of dryness lev­ +els MAY change depending on the currently-selected Laundry Dryer mode. + +**8.9.5.2. SelectedDrynessLevel Attribute** + +This attribute SHALL indicate the currently-selected dryness level and it SHALL be the index into +the SupportedDrynessLevels list of the selected dryness level. + +If an attempt is made to write this attribute with a value other than null or a value contained in +SupportedDrynessLevels, a CONSTRAINT_ERROR response SHALL be sent as the response. If an +attempt is made to write this attribute while the device is not in a state that supports modifying the +dryness level, an INVALID_IN_STATE error SHALL be sent as the response. A value of null SHALL +indicate that there will be no dryness level setting for the current mode. + +**8.10. Oven Cavity Operational State Cluster** + +This cluster is derived from the Operational State cluster and provides an interface for monitoring +the operational state of an oven. + +``` +Page 598 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.10.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Set Pause and Resume commands as disallowed +(previously a Device Type override) +``` +**8.10.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Operational State Application Endpoint OVENOPSTATE +``` +**8.10.3. Cluster ID** + +``` +ID Name +0x0048 Oven Cavity Operational State +``` +**8.10.4. Attributes** + +**8.10.4.1. PhaseList Attribute** + +As defined in the base cluster, this attribute indicates a list of names of different phases that the +device can go through for the selected function or mode. + +For this derived cluster, only these pre-defined strings may be used in the PhaseList attribute: + +"pre-heating", "pre-heated", and "cooling down". + +Other values SHALL NOT be used. + +As defined in the base cluster, a null value indicates that the device does not present phases during +its operation. When this attribute’s value is null, the CurrentPhase attribute SHALL also be set to +null. + +**8.10.5. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Pause X +0x01 Stop +0x02 Start +0x03 Resume X +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 599 +``` + +``` +ID Name Direction Response Access Conformance +0x04 Operational­ +Comman­ +dResponse +``` +**8.11. Oven Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for oven devices. + +**8.11.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Set OnOff feature, StartUpMode, and OnMode as +disallowed (previously a Device Type override) +``` +**8.11.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint OTCCM +``` +**8.11.3. Cluster ID** + +``` +ID Name +0x0049 Oven Mode +``` +**8.11.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**8.11.5. Data Types** + +**8.11.5.1. ModeOptionStruct Type** + +The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOption­ +Struct type. A blank field indicates no change. + +``` +Page 600 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label M +1 Mode M +2 ModeTags 1 to 8 M +``` +**8.11.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +0x0001 Current­ +Mode +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +**8.11.6.1. SupportedModes Attribute** + +At least one entry in the SupportedModes attribute SHALL include the Bake mode tag in the Mode­ +Tags field list. + +**8.11.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**8.11.7.1. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 601 +``` + +``` +Mode Tag Value Name +0x0009 Day +0x4000 Bake +0x4001 Convection +0x4002 Grill +0x4003 Roast +0x4004 Clean +0x4005 Convection Bake +0x4006 Convection Roast +0x4007 Warming +0x4008 Proofing +0x4009 Steam +``` +**8.11.7.1.1. Bake Tag** + +This mode sets the device into baking mode for baking food items. + +**8.11.7.1.2. Convection Tag** + +This mode sets the device into convection mode which creates an airflow within the device during +the cooking duration. + +**8.11.7.1.3. Grill Tag** + +This mode sets the device into grill mode for grilling food items. This is the same as Broil for many +regions. + +**8.11.7.1.4. Roast Tag** + +This mode sets the device into roast mode for roasting food items. + +**8.11.7.1.5. Clean Tag** + +This mode sets the device into cleaning mode to clean the internal components of the appliance. + +**8.11.7.1.6. Convection Bake Tag** + +This mode sets the device into convection bake mode which creates an airflow within the device +during the baking duration. + +**8.11.7.1.7. Convection Roast Tag** + +This mode sets the device into convection roast mode which creates an airflow within the device +during the roasting duration. + +``` +Page 602 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.11.7.1.8. Warming Tag** + +This mode sets the device into a warming mode which begins warming the cavity. + +**8.11.7.1.9. Proofing Tag** + +This mode sets the device into proofing mode which creates an environment ready for proofing. + +**8.11.8. Mode Examples** + +A few examples of Oven modes and their mode tags are provided below. + +- For the "Convection" mode, tags: 0x4001 (Convection) +- For the "Bake" mode, tags: 0x4000 (Bake) +- For the "Bake and Warm" mode, tags: 0x4000 (Bake), 0x4007 (Warming) +- For the "Convection Cook and Clean" mode, tags: 0x4001 (Convection), 0x4004 (Clean) + +**8.12. Microwave Oven Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for microwave oven devices. + +**8.12.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Set OnOff feature as disallowed +``` +**8.12.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint MWOM +``` +**8.12.3. Cluster ID** + +``` +ID Name +0x005E Microwave Oven Mode +``` +**8.12.4. Features** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 603 +``` + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**8.12.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +0x0001 Current­ +Mode +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +**8.12.5.1. SupportedModes Attribute** + +Exactly one entry in the SupportedModes attribute SHALL include the Normal mode tag in the Mod­ +eTags field. + +The Normal and Defrost mode tags are mutually exclusive and SHALL NOT both be used together in +a mode’s ModeTags. + +**8.12.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 ChangeTo­ +Mode +``` +### X + +``` +0x01 ChangeTo­ +ModeRe­ +sponse +``` +### X + +**8.12.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**8.12.7.1. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +``` +``` +Page 604 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Mode Tag Value Name +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +0x4000 Normal +0x4001 Defrost +``` +**8.12.7.1.1. Normal tag** + +This is the normal mode of operation for general cooking of food. + +**8.12.7.1.2. Defrost tag** + +This is a mode optimized for defrosting food. + +**8.13. Microwave Oven Control Cluster** + +This cluster defines the requirements for the Microwave Oven Control cluster. + +This cluster has dependencies with the Operational State and Microwave Oven Mode clusters. The +Operational State cluster and the Microwave Oven Mode clusters, or derivatives of those clusters +SHALL appear on the same endpoint as this cluster. + +**8.13.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**8.13.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint MWOCTRL +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 605 +``` + +**8.13.3. Cluster ID** + +``` +ID Name +0x005F Microwave Oven Control +``` +**8.13.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 PWRNUM PowerAsNumber O.a Power is specified +as a unitless num­ +ber or a percent­ +age +1 WATTS PowerInWatts P, O.a Power is specified +in Watts +2 PWRLMTS PowerNumber­ +Limits +``` +``` +[PWRNUM] Supports the limit +attributes used +with the PWRNUM +feature +``` +**8.13.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 CookTime elapsed-s 1 to Max­ +CookTime +``` +### 30 R V M + +``` +0x0001 MaxCook­ +Time +``` +``` +elapsed-s 1 to 86400 F MS R V M +``` +``` +0x0002 PowerSet­ +ting +``` +``` +uint8 desc desc R V PWRNUM +``` +``` +0x0003 MinPower uint8 1 to 99 F 10 R V PWRLMTS +0x0004 MaxPower uint8 (MinPower ++ 1) to 100 +``` +### F 100 R V PWRLMTS + +``` +0x0005 PowerStep uint8 desc F 10 R V PWRLMTS +0x0006 Support­ +edWatts +``` +``` +list[uint16] 1 to 10 F MS R V P, WATTS +``` +``` +0x0007 Selected­ +WattIndex +``` +``` +uint8 desc MS R V P, WATTS +``` +``` +0x0008 WattRat­ +ing +``` +``` +uint16 all F MS R V O +``` +``` +Page 606 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.13.5.1. CookTime Attribute** + +This attribute SHALL indicate the total cook time associated with the operation of the device. + +This attribute SHALL remain unchanged during the operation of the oven unless the value is +changed via a command or out-of-band action. + +**8.13.5.2. MaxCookTime Attribute** + +This attribute SHALL indicate the maximum value to which the CookTime attribute can be set. + +**8.13.5.3. PowerSetting Attribute** + +This attribute SHALL indicate the power level associated with the operation of the device. + +If the MinPower, MaxPower, and PowerStep attributes are not supported: + +- The minimum value of this attribute SHALL be 10, +- The maximum value of this attribute SHALL be 100, +- The value SHALL be in even multiples of 10, +- The default value SHALL be 100. + +If the MinPower, MaxPower, and PowerStep attributes are supported: + +- The value of this attribute SHALL be between MinPower and MaxPower inclusive. +- The value of this attribute SHALL be such that (PowerSetting - MinPower) % PowerStep == 0 + +**8.13.5.4. MinPower Attribute** + +This attribute SHALL indicate the minimum value to which the PowerSetting attribute that can be +set on the server. + +**8.13.5.5. MaxPower Attribute** + +This attribute SHALL indicate the maximum value to which the PowerSetting attribute that can be +set on the server. + +**8.13.5.6. PowerStep Attribute** + +This attribute SHALL indicate the increment of power that can be set on the server. + +The value of this attribute SHALL be between 1 and MaxPower inclusive. + +The value of this attribute SHALL be such that (MaxPower - MinPower) % PowerStep == 0 + +For example, if MinPower is 1, MaxPower is 10, and PowerSetting can be set to any integer between +MinPower and MaxPower, PowerStep would be set to 1. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 607 +``` + +**8.13.5.7. SupportedWatts Attribute** + +This attribute SHALL indicate the list of power levels (in W) supported by the server. + +**8.13.5.8. SelectedWattIndex Attribute** + +This attribute SHALL indicate the index into the list of SupportedWatts of the currently selected +power setting. + +The index SHALL be a valid index into the SupportedWatts list. + +**8.13.5.9. WattRating Attribute** + +This attribute SHALL indicate the rating, in Watts, of the microwave power of the oven. + +Supporting this attribute can assist clients in suggesting cooking settings for various foods and bev­ +erages. + +**8.13.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 SetCookingPa­ +rameters +``` +``` +client ⇒ server Y O M +``` +``` +0x01 AddMoreTime client ⇒ server Y O O +``` +**8.13.6.1. Command Responses Impacted By the Operational State Cluster** + +When the Operational State cluster or a cluster derived from it is included on the same endpoint as +this cluster, the server MAY respond to commands defined in this cluster with an INVALID_IN_S­ +TATE response if the server is unable to accept those command due to restrictions imposed by the +current operational state of the device or other factors. + +**8.13.6.2. SetCookingParameters Command** + +This command is used to set the cooking parameters associated with the operation of the device. +This command supports the following fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 CookMode uint8 desc desc O.b+ +1 CookTime elapsed-s 1 to Max­ +CookTime +``` +``` +30 O.b+ +``` +``` +2 PowerSet­ +ting +``` +``` +uint8 MinPower to +MaxPower +``` +``` +MaxPower [PWR­ +NUM].b+ +3 WattSet­ +tingIndex +``` +``` +uint8 desc MS [WATTS].b+ +``` +``` +Page 608 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +4 StartAfter­ +Setting +``` +``` +bool all false O +``` +**8.13.6.2.1. CookMode Field** + +This field SHALL indicate the value to which the CurrentMode attribute of the Microwave Oven +Mode cluster should be set. The value of this field SHALL be one from the list of SupportedModes +from the Microwave Oven Mode cluster. + +If this field is missing, the CurrentMode attribute SHALL be set to a mode having the Normal mode +tag. + +**8.13.6.2.2. CookTime Field** + +This field SHALL indicate the CookTime associated with the operation of the device. The value of +this field SHALL be subject to the constraints of the CookTime attribute of this cluster. + +If this field is missing, the CookTime attribute SHALL be set to 30 seconds by the server. + +**8.13.6.2.3. PowerSetting Field** + +This field SHALL indicate the PowerSetting associated with the operation of the device. The value of +this field SHALL be subject to the constraints of the PowerSetting attribute of this cluster. If the +PowerSetting field does not conform to the constraints of the PowerSetting attribute, the server +SHALL return a CONSTRAINT_ERROR status. + +If this field is missing, the PowerSetting attribute SHALL be set to 100 if MaxPower is not supported +by the server, otherwise it SHALL be set to MaxPower if the MaxPower attribute is supported by the +server. + +**8.13.6.2.4. WattSettingIndex Field** + +This field SHALL indicate the value to which the SelectedWattIndex attribute is set. If the value of +this field is greater than or equal to the length of the SupportedWatts attribute list, the server +SHALL return a CONSTRAINT_ERROR status and the value of the SelectedWattIndex attribute +SHALL be unchanged. + +If this field is missing, the SelectedWattIndex attribute SHALL be set by the server to the index asso­ +ciated with the highest Watt setting for the selected CookMode. + +**8.13.6.2.5. StartAfterSetting Field** + +This field SHALL indicate whether or not oven operation SHALL be started when the command is +received. + +**8.13.6.2.6. Effect on Receipt** + +If this command is received while the operational state of the server cannot support the command +in that state, the server SHALL respond with an INVALID_IN_STATE response and the attributes and + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 609 +``` + +state SHALL remain unchanged. See Operational State Cluster for details on the operational states. + +If this command is received and any fields sent with the command do not meet the constraints of +any of the associated attributes (i.e. bearing the same name as the field or as described in the field +description), the server SHALL respond with a response of CONSTRAINT_ERROR and the attributes +and state SHALL remain unchanged. + +If the StartAfterSetting field is present in the command but the Start command of the Operational +State cluster or one of its derivatives on the same endpoint as this cluster is not supported, the +server SHALL respond with a response of INVALID_COMMAND and the attributes and state SHALL +remain unchanged. + +Otherwise: + +- The attributes associated with any included fields SHALL be set to the values of those fields. +- The attributes associated with any missing fields SHALL be set to the values as specified in + descriptions of the missing fields. +- If the StartAfterSetting field is included: + ◦ If the value of StartAfterSetting is TRUE, oven operation SHALL start. + ◦ If the value of StartAfterSetting is FALSE, oven operation SHALL NOT start. + +**8.13.6.3. AddMoreTime Command** + +This command is used to add more time to the CookTime attribute of the server. + +This command supports these fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TimeToAdd elapsed-s 1 to Max­ +CookTime +``` +### M + +**8.13.6.3.1. TimeToAdd Field** + +This field SHALL indicate the number of seconds to be added to the CookTime attribute. + +**8.13.6.3.2. Effect on Receipt** + +Upon receipt of this command, if the sum of the value of the TimeToAdd field and the current value +of the CookTime attribute is greater than the MaxCookTime attribute, the server SHALL respond +with a response of CONSTRAINT_ERROR and the command SHALL be ignored. + +If this command is received while the operational state of the server cannot support the command +in that state, the server SHALL respond with an INVALID_IN_STATE response. See Operational State +Cluster for details on the operational states. + +Otherwise, the server SHALL add the value of the TimeToAdd field to the value of the CookTime +attribute of this cluster and the server SHALL add the value of the TimeToAdd field to the value of + +``` +Page 610 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +the CountdownTime attribute of the Operational State cluster if that cluster or a derivative is on the +same endpoint as this cluster. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 611 +``` + +Page 612 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 9. Energy Management** + +The Cluster Library is made of individual chapters such as this one. See Document Control in the +Cluster Library for a list of all chapters and documents. References between chapters are made +using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. + +**9.1. General Description** + +**9.1.1. Introduction** + +The clusters specified in this chapter are for use typically in Energy Management applications with +associated security controls at the application layer. These clusters may be used in any application +domain. + +**9.1.2. Cluster List** + +This section lists the Energy Management specific clusters as specified in this chapter. + +_Table 16. Overview of the Energy Management Clusters_ + +``` +Cluster ID Cluster Name Description +0x009F Device Energy Management +Mode +``` +``` +Commands and attributes for +setting the mode of devices with +energy management capability +0x0098 Device Energy Management Generic cluster for enabling +power adjustment, sharing +power forecasts and modifying +power forecasts for devices +0x0099 Energy EVSE Commands and attributes for +controlling an EVSE +0x009D Energy EVSE Mode Commands and attributes for +setting the mode of an EVSE +0x0094 Water Heater Management Commands and attributes for +controlling a Water Heater +0x009E Water Heater Mode Commands and attributes for +setting the mode of a Water +Heater +0x009B Energy Preference Attributes and commands for +expressing user preferences +around energy consumption +``` +**9.2. Device Energy Management Cluster** + +This cluster allows a client to manage the power draw of a device. An example of such a client could + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 613 +``` + +be an Energy Management System (EMS) which controls an Energy Smart Appliance (ESA). + +In most deployments the EMS will be the client, and the ESA will host the Device Energy Manage­ +ment Cluster server. + +_Figure 17. Example of the how an EMS is a client of multiple ESAs Device Energy Management clusters._ + +This cluster is intended to be generic in nature and could apply to any electrical load or generator +(e.g. a Battery Electric Storage System - BESS, solar PV inverter, EVSE, HVAC, heat pump, hot water +heater, white goods appliances etc). + +It consists of the following areas which SHALL be supported by all devices implementing this clus­ +ter: + +- Description of ESA and its capabilities & power limits (sometimes referred to as a nameplate) +- Current state of operation (including user opt-out, safety limitations / alarms) + +There are some optional capabilities that some ESAs may be able to offer: + +- Ability to control the load or generation +- Forecast data, including when it can be flexible (i.e. modify the power or time period) +- The ability to have their power profile adjusted by an EMS, and to provide an updated Forecast + back to the EMS. + +This allows the EMS to manage multiple home loads and where ESAs can be flexible, continuously +optimizing the home energy to minimize cost, reduce CO2 impact, maximize self-consumption of +solar PV and provide Demand Side Response (DSR) Grid services. + +It is likely that the ESA may also use the Pricing Cluster to obtain incentive signals such as 'grid car­ +bon intensity', 'time of use' or 'type of use' tariffs to schedule its operation to run at the cheapest +and greenest times. + +``` +Page 614 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 18. Example of the how an HVAC may use multiple clusters_ + +### NOTE + +``` +Grid Services are market dependent and will use other protocols ([OpenADR] / +[IEEE2030.5]) to communicate grid events to the EMS. These are outside the scope of +Matter. +``` +### NOTE + +``` +Different markets may follow different approaches, but the UK [PAS1878] and +[EUCodeOfConduct] give examples of how ESAs may be mandated to support these +features in the future. +``` +**9.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Updates after 0.7 Ballot review +3 Updates to match cluster spec updates +4 Updates to feature conformance. Corrected Fore­ +castID type +``` +**9.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint DEM +``` +**9.2.3. Cluster ID** + +``` +ID Name +0x0098 Device Energy Management +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 615 +``` + +**9.2.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 PA PowerAdjustment O Allows an EMS to +make a temporary +power adjustment +(within the limits +offered by the +ESA). +1 PFR PowerForecastRe­ +porting +``` +``` +[!PA].a,(STA|PAU| +FA|CON),O +``` +``` +Allows an ESA to +advertise its +indicative future +power consump­ +tion vs time. +2 SFR StateForecastRe­ +porting +``` +``` +[!PA].a Allows an ESA to +advertise its +indicative future +state vs time. +3 STA StartTimeAdjust­ +ment +``` +``` +O Allows an EMS to +delay an ESA’s +planned opera­ +tion. +4 PAU Pausable O Allows an EMS to +pause an ESA’s +planned opera­ +tion. +5 FA ForecastAdjust­ +ment +``` +``` +O Allows an EMS to +adjust an ESA’s +planned opera­ +tion. +6 CON Constraint­ +BasedAdjustment +``` +``` +O Allows an EMS to +request con­ +straints to an ESA’s +planned opera­ +tion. +``` +The conformance rules specified above can be described as: + +- At least one of the features SHALL be supported. +- At most one of the 'SFR' and 'PFR' features SHALL be supported. +- If one or more of the 'STA', 'PAU', 'FA', or 'CON' features are supported, then either the 'PFR' or + the 'SFR' feature SHALL also be supported. + +``` +Page 616 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- If PA is supported, SFR SHALL NOT be supported + +**9.2.4.1. PowerAdjustment Feature** + +For Energy Smart Appliances (ESA) the definition of being 'smart' mandates that they can report +their current power adjustment capability and have an EMS request a temporary adjustment. This +may typically be to curtail power requirements during peak periods, but can also be used to turn on +an ESA if there is excess renewable or local generation (Solar PV). + +For example, a home may have solar PV which often produces more power than the home requires, +resulting in the excess power flowing into the grid. This excess power naturally fluctuates when +clouds pass overhead and other loads in the home are switched on and off. + +**EVSE Example:** An EMS may therefore be able to turn on the EVSE (if the vehicle is plugged in) and +can start charging the vehicle, and periodically modify the charging power depending on PV gener­ +ation and other home loads, so as to minimize import and export to the grid. An EMS may also use +this feature to control the discharging (and re-charging) of the vehicle if the EVSE and vehicle sup­ +port the V2X feature of the EVSE cluster of the associated EVSE device. + +**9.2.4.2. PowerForecastReporting Feature** + +For Energy Smart Appliances (ESA) the definition of being 'smart' implies that they can report their +indicative forecast power demands or generation, to a greater or lesser extent. For some ESAs this +is highly predictable (in terms of both power and time), in other appliances this is more challenging +and only a basic level of forecast is possible. + +Forecasts are defined from a current time, using a slot format, where the slot is akin to a relatively +constant operating mode. + +**Washing machine example:** a washing machine may have stages of a washing cycle: heating, tum­ +bling, rinse and spin stages. At each stage, the approximate minimum and maximum power con­ +sumption may be known, as well as the duration of that stage. + +In some circumstances the ESA may allow the stage to be delayed or paused (subject to safety and +manufacturer’s discretion and user preferences). + +Typically, appliances with a heating element cannot have their power consumption adjusted and +can only be paused or delayed. + +Some ESAs may not be flexible other than a delayed cycle start (for example, once the washing +cycle has been started then they run continuously until the cycle completes). + +Appliances that only support the PowerForecastReporting and not any of the adjustment features +may indicate that they are not flexible in the forecast slot format. + +The PowerForecastReporting and the adjustment features aim to align to the [SAREF4ENER] ontol­ +ogy. + +**Inverter driven ESAs:** some inverter driven ESAs can consume or generate a variable amount of +power. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 617 +``` + +For example, a single phase EVSE can be adjusted in the range of 6-32Amps in 0.6 Amp steps in EU +or on a hardwired 120V supply in the range of 6-15 Amps in US. + +For example, a home battery may be adjusted to charge or discharge in steps of 1W. + +For example, a heat pump may be able to modulate its compressor inverter between 20-100% of its +rated power. + +The ESA indicates its power adjustment range and its nominal power consumption as part of its +Forecast. + +**9.2.4.3. StateForecastReporting Feature** + +Some ESAs do not know their actual power consumption, but do know the state of operation. Like +the PowerForecastingReporting feature, this uses the same slot structure mechanism to indicate a +change in state vs time. + +An external observing EMS may have access to real-time meter readings, and could learn the typi­ +cal power consumption based on the advertised internal state of the ESA. + +To enable this capability, the ESA SHALL report its internal operational state using an manufacturer +specific value. + +Once the EMS has built a model of the state vs observed power consumption, it may request a fore­ +cast adjustment for particular times of the day, encouraging the ESA to use power at alternative +times. + +**9.2.4.4. StartTimeAdjustment Feature** + +ESAs which support the Start Time Adjustment feature, allow an EMS to recommend a change to +the start time of the energy transfer that the ESA has previously suggested it would use. + +**Washing machine example:** A Washing Machine may have been set to start a wash cycle at 9pm +when the variable tariff normally reduces. + +However, the EMS is aware that a grid event has occurred, making it cheaper to run the cycle at a +later time, but the washing machine is not aware of this. + +The EMS first requests the Forecast data from each of its registered ESAs. It determines that the +washing machine has a power profile suggesting it will start the wash cycle at 9pm, but the EMS +now knows that the grid event means it will be cheaper to delay the start until 11pm. + +The EMS can then optimize the cost by asking the washing machine to delay starting the wash cycle +until 11pm. + +It does this by sending a StartTimeAdjustRequest to the washing machine to request delaying the +start of the washing cycle. + +**9.2.4.5. Pausable Feature** + +ESAs which support the Pausable feature, allow an EMS to recommend a pause in the middle of a + +``` +Page 618 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +forecast power profile that the ESA is currently using. + +**Washing machine example:** A Washing Machine is in operation, and starting its water heating +step. + +However, the EMS becomes aware from the smart meter that the total home load on the grid is +close to exceeding its allowed total grid load. + +The EMS first requests the Forecast data from each of its registered ESAs. It determines that the +washing machine has a power profile suggesting its current step in the wash cycle is using power to +heat the water, but that this step can be paused. + +The EMS can then reduce the grid load by asking the washing machine to pause the wash cycle for +a short duration. + +It does this by sending a PauseRequest to the washing machine to request pausing the current step +of the forecast power usage for a period to allow other home loads to finish before resuming the +washing cycle. + +**9.2.4.6. ForecastAdjustment Feature** + +ESAs which support the Forecast adjustment feature, allow an EMS to recommend a change to the +start, duration and/or power level limits of the steps of the power profile that the ESA has previ­ +ously suggested it would use. + +**Heat pump and Solar PV example:** A heat pump may have the ability to heat hot water as well as +heating the home. The heat pump scheduling system may have determined that the home will be +unoccupied during the day, or that the indoor temperature is above the set-point and so it knows +that it will not need to heat the home. + +However, the hot water tank is likely to need to be reheated before the homeowner comes home in +the evening. The heat pump is not aware that the property also has a solar PV inverter which is also +an ESA that is communicating with the EMS. + +The EMS first requests the Forecast data from each of its registered ESAs. It determines that the +heat pump has a power profile suggesting it needs to heat hot water around 6pm. The solar PV +inverter has forecast that it will generate 3.6kW of power during the middle of the day and into the +afternoon before the sun goes down. + +The EMS can then optimize the home considering other non-ESA loads and can ask the heat pump +to heat the hot water around 3pm when it has forecast that excess solar power will be available. + +It does this by sending a ModifyForecastRequest to the heat pump and asks the heat pump to expect +to run at a lower power consumption (within the solar excess power) which requires the heat +pump to run for a longer duration to achieve its required energy demand. + +**9.2.4.7. ConstraintBasedAdjustment Feature** + +ESAs which support the Constraint-Based Adjustment feature allow an EMS to inform the ESA of +periods during which power usage should be modified (for example when the EMS has been made +aware that the grid supplier has requested reduced energy usage due to overall peak grid demand) + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 619 +``` + +and may cause the ESA to modify the intended power profile has previously suggested it would use. + +**EVSE example:** An EVSE scheduling system may have determined that the vehicle would be +charged starting at a moderate rate at 1am, so that it has enough charge by the time it is needed +later that morning. + +However, the DSR service provider has informed the EMS that due to high forecast winds it is now +forecast that there will be very cheap energy available from wind generation between 2am and +3am. + +The EMS first requests the Forecast data from each of its registered ESAs. It determines that the +EVSE has a power profile suggesting it plans to start charging the vehicle at 1am. + +The EMS can then try to reduce the cost of charging the EV by informing the EVSE of the desire to +increase the charging between scheduled times. + +It does this by sending a RequestConstraintBasedForecast to the EVSE and asks it to run at a higher +NominalPower consumption during the constraint period, which may require it to decrease its +charge rate outside the constraint period to achieve its required energy demand. + +**9.2.5. Dependencies** + +This cluster does not report electrical power and electrical energy. Devices that use this cluster +SHALL also support the Electrical Power Measurement and optionally support the Electrical Energy +Measurement cluster to allow an energy management system to perform its role. See Device Type +library for device specific details. + +**9.2.6. Definitions** + +**9.2.6.1. Power** + +Power is defined in the main specification (see Data Model) in units of milliwatts. It is a signed +value, where positive values indicate the direction of power flow into the node. A negative value +indicates that the device is supplying power, and thus reducing the overall load of the premises on +the grid supply. + +``` +Page 620 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 19. Power flows into devices_ + +**Solar PV inverter example:** A solar PV inverter is normally connected to the premises' wiring, so +its generation power will be indicated as a negative integer, since power is flowing out of the node +towards the mains connection. Note that at night (when there is no solar production) the PV +inverter will consume some standby power, and this will result in a small positive power reading. + +**Grid Power:** Power from the grid is measured by a utility meter which is imported into the node, so +positive power values indicate that power is flowing into the premises. Negative values indicate +power is flowing back towards the grid. + +**EVSE example:** An EVSE provides power to the EV (when charging) so a positive value indicates +that the power is flowing into the EVSE from the mains supply when the EV is charging, and is act­ +ing as a load on the grid supply, and negative value indicates that the EV is discharging. + +**BESS example:** A battery storage inverter normally provides power to loads when discharging, so +negative power indicates discharging (power is flowing back to the mains supply) therefore reduc­ +ing the load on the grid, and positive power indicates power flowing from the mains to the battery +during charging (adding load to the grid). + +**Washing Machine example:** A washing machine only consumes power (i.e. is a load), so it will +always have a positive power value. + +**9.2.6.2. Energy** + +Energy is defined in the main specification (see Data Model). This is defined in units of mWh (milli­ +watt-hours). It is signed value, where positive values indicate the direction of current flow towards +a load. + +**9.2.7. Data Types** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 621 +``` + +**9.2.7.1. CostTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Financial Financial cost M +1 GHGEmissions Grid CO2e grams cost M +2 Comfort Consumer comfort +impact cost +``` +### M + +``` +3 Temperature Temperature impact +cost +``` +### M + +**9.2.7.1.1. Financial Value** + +This value SHALL indicate that the cost is related to the financial cost to provide the energy. + +**9.2.7.1.2. GHGEmissions Value** + +This value SHALL indicate that the cost is related to greenhouse gas emissions (in grams of CO2e). + +**9.2.7.1.3. Comfort Value** + +This value SHALL indicate that the cost is related to some abstract sense of comfort expressed by +the consumer; a higher value indicates more discomfort. For example, a consumer may be more +comfortable knowing that their EV is charged earlier in the day in case there is a sudden need to +depart and drive to the hospital. Or the consumer may feel inconvenienced by the fact that they +need to wait for the washing machine to finish its load so that they can use it again. + +**9.2.7.1.4. Temperature Value** + +This value SHALL indicate that the cost is related to the temperature of the home or water being at +its setpoint. Some consumers may be more sensitive to being too hot or too cold. + +This is expressed in degrees Celsius. + +**9.2.7.2. ESATypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 EVSE EV Supply Equipment O +1 SpaceHeating Space heating appli­ +ance +``` +### O + +``` +2 WaterHeating Water heating appli­ +ance +``` +### O + +``` +3 SpaceCooling Space cooling appliance O +``` +``` +Page 622 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +4 SpaceHeatingCooling Space heating and cool­ +ing appliance +``` +### O + +``` +5 BatteryStorage Battery Electric Storage +System +``` +### O + +``` +6 SolarPV Solar PV inverter O +7 FridgeFreezer Fridge / Freezer O +8 WashingMachine Washing Machine O +9 Dishwasher Dishwasher O +10 Cooking Cooking appliance O +11 HomeWaterPump Home water pump (e.g. +drinking well) +``` +### O + +``` +12 IrrigationWaterPump Irrigation water pump O +13 PoolPump Pool pump O +255 Other Other appliance type O +``` +**9.2.7.3. ESAStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Offline The ESA is not available +to the EMS (e.g. start- +up, maintenance mode) +``` +### M + +``` +1 Online The ESA is working +normally and can be +controlled by the EMS +``` +### M + +``` +2 Fault The ESA has developed +a fault and cannot pro­ +vide service +``` +### M + +``` +3 PowerAdjustActive The ESA is in the mid­ +dle of a power adjust­ +ment event +``` +### PA + +``` +4 Paused The ESA is currently +paused by a client +using the PauseRequest +command +``` +### PAU + +**9.2.7.4. OptOutStateEnum Type** + +This data type is derived from enum8. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 623 +``` + +``` +Value Name Summary Conformance +0 NoOptOut The user has not opted +out of either local or +grid optimizations +``` +### M + +``` +1 LocalOptOut The user has opted out +of local EMS optimiza­ +tions only +``` +### M + +``` +2 GridOptOut The user has opted out +of grid EMS optimiza­ +tions only +``` +### M + +``` +3 OptOut The user has opted out +of all external opti­ +mizations +``` +### M + +**9.2.7.5. CauseEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 NormalCompletion The ESA completed the +power adjustment as +requested +``` +### M + +``` +1 Offline The ESA was set to +offline +``` +### M + +``` +2 Fault The ESA has developed +a fault could not com­ +plete the adjustment +``` +### M + +``` +3 UserOptOut The user has disabled +the ESA’s flexibility +capability +``` +### M + +``` +4 Cancelled The adjustment was +cancelled by a client +``` +### M + +**9.2.7.6. AdjustmentCauseEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 LocalOptimization The adjustment is to +optimize the local +energy usage +``` +### M + +``` +Page 624 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +1 GridOptimization The adjustment is to +optimize the grid +energy usage +``` +### M + +**9.2.7.7. ForecastUpdateReasonEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 InternalOptimization The update was due to +internal ESA device +optimization +``` +### M + +``` +1 LocalOptimization The update was due to +local EMS optimization +``` +### M + +``` +2 GridOptimization The update was due to +grid optimization +``` +### M + +**9.2.7.8. PowerAdjustReasonEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 NoAdjustment There is no Power +Adjustment active +``` +### M + +``` +1 LocalOptimizationAd­ +justment +``` +``` +There is PowerAdjust­ +ment active due to local +EMS optimization +``` +### M + +``` +2 GridOptimizationAd­ +justment +``` +``` +There is PowerAdjust­ +ment active due to local +EMS optimization +``` +### M + +**9.2.7.9. CostStruct Type** + +This indicates a generic mechanism for expressing cost to run an appliance, in terms of financial, +GHG emissions, comfort value etc. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 CostType CostType­ +Enum +``` +``` +all 0 M +``` +``` +1 Value int32 all 0 M +2 Decimal­ +Points +``` +``` +uint8 all 0 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 625 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +3 Currency uint16 max 999 0 O +``` +**9.2.7.9.1. CostType Field** + +This field SHALL indicate the type of cost being represented (see CostTypeEnum). + +**9.2.7.9.2. Value Field** + +This field SHALL indicate the value of the cost. This may be negative (indicating that it is not a cost, +but a free benefit). + +For example, if the Value was -302 and DecimalPoints was 2, then this would represent a benefit of +3.02. + +**9.2.7.9.3. DecimalPoints Field** + +This field SHALL indicate the number of digits to the right of the decimal point in the Value field. +For example, if the Value was 102 and DecimalPoints was 2, then this would represent a cost of 1.02. + +**9.2.7.9.4. Currency Field** + +Indicates the currency for the value in the Value field. The value of the currency field SHALL match +the values defined by [ISO 4217]. + +This is an optional field. It SHALL be included if CostType is Financial. + +**9.2.7.10. PowerAdjustStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 MinPower power-mW all 0 M +1 MaxPower power-mW min Min­ +Power +``` +### 0 M + +``` +2 MinDura­ +tion +``` +``` +elapsed-s all 0 M +``` +``` +3 MaxDura­ +tion +``` +``` +elapsed-s min Min­ +Duration +``` +### M + +**9.2.7.10.1. MinPower Field** + +This field SHALL indicate the minimum power that the ESA can have its power adjusted to. + +Note that this is a signed value. Negative values indicate power flows out of the node (e.g. discharg­ +ing a battery). + +``` +Page 626 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.2.7.10.2. MaxPower Field** + +This field SHALL indicate the maximum power that the ESA can have its power adjusted to. + +Note that this is a signed value. Negative values indicate power flows out of the node (e.g. discharg­ +ing a battery). + +For example, if the charging current of an EVSE can be adjusted within the range of 6A to 32A on a +230V supply, then the power adjustment range is between 1380W and 7360W. Here the MinPower +would be 1380W, and MaxPower would be 7360W. + +For example, if a battery storage inverter can discharge between 0 to 3000W towards a load, then +power is flowing out of the node and is therefore negative. Its MinPower would be -3000W and its +MaxPower would be 0W. + +In another example, if a battery storage inverter can charge its internal battery, between 0W and +2000W. Here power is flowing into the node when charging. As such the MinPower becomes 0W +and MaxPower becomes 2000W. + +**9.2.7.10.3. MinDuration field** + +This field SHALL indicate the minimum duration, in seconds, that a controller may invoke an ESA +power adjustment. Manufacturers may use this to as an anti-cycling capability to avoid controllers +from rapidly making power adjustments. + +**9.2.7.10.4. MaxDuration field** + +This field SHALL indicate the maximum duration, in seconds, that a controller may invoke an ESA +power adjustment. Manufacturers may use this to protect the user experience, to avoid over heat­ +ing of the ESA, ensuring that there is sufficient headroom to use or store energy in the ESA or for +any other reason. + +**9.2.7.11. PowerAdjustCapabilityStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 PowerAd­ +justCapa­ +bility +``` +``` +list[Power­ +Adjust­ +Struct] +``` +``` +max 8 X null M +``` +``` +1 Cause PowerAd­ +justReaso­ +nEnum +``` +``` +all 0 M +``` +**9.2.7.12. PowerAdjustCapability** + +This field SHALL indicate how the ESA can be adjusted at the current time. + +For example, a battery storage inverter may need to regulate its internal temperature, or the charg­ +ing rate of the battery may be limited due to cold temperatures, or a change in the state of charge of +the battery may mean that the maximum charging or discharging rate is limited. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 627 +``` + +An empty list SHALL indicate that no power adjustment is currently possible. + +Multiple entries in the list allow indicating that permutations of scenarios may be possible. + +For example, a 10kWh battery could be at 80% state of charge. If charging at 2kW, then it would be +full in 1 hour. However, it could be discharged at 2kW for 4 hours. + +In this example the list of PowerAdjustStructs allows multiple scenarios to be offered as follows: + +``` +Entry [0] - Charging option: +MinPower 0 Watts +MaxPower 2000 Watts +MinDuration 60 seconds +MaxDuration 3600 seconds (1 hour) +Entry [1] - Discharging option: +MinPower -2000 Watts +MaxPower 0 Watts +MinDuration 60 seconds +MaxDuration 14400 seconds (4 hours) +``` +**9.2.7.12.1. Cause field** + +This field SHALL indicate the cause of the currently active power adjustment. + +**9.2.7.13. ForecastStruct Type** + +This indicates a list of 'slots' describing the overall timing of the ESA’s planned energy and power +use, with different power and energy demands per slot. For example, slots might be used to +describe the distinct stages of a washing machine cycle. + +Where an ESA does not know the actual power and energy use of the system, it may support the SFR +feature and instead report its internal state. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Fore­ +castID +``` +``` +uint32 all 0 M +``` +``` +1 ActiveSlot­ +Number +``` +``` +uint16 all X 0 M +``` +``` +2 StartTime epoch-s all M +3 EndTime epoch-s all M +4 Earliest­ +StartTime +``` +``` +epoch-s all X STA +``` +``` +Page 628 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +5 LatestEnd­ +Time +``` +``` +epoch-s all STA +``` +``` +6 IsPausable bool all M +7 Slots list[Slot­ +Struct] +``` +``` +max 10 M +``` +``` +8 Forecas­ +tUp­ +dateRea­ +son +``` +``` +Forecas­ +tUp­ +dateReaso­ +nEnum +``` +``` +all M +``` +**9.2.7.13.1. ForecastID Field** + +This field SHALL indicate the sequence number for the current forecast. If the ESA updates a fore­ +cast, it shall monotonically increase this value. + +The ESA does not need to persist this value across reboots, since the EMS SHOULD be able to detect +that any previous subscriptions are lost if a device reboots. The loss of a subscription and subse­ +quent re-subscription allows the EMS to learn about any new forecasts. + +The value of ForecastID is allowed to wrap. + +**9.2.7.13.2. ActiveSlotNumber Field** + +This field SHALL indicate which element of the Slots list is currently active in the Forecast +sequence. A null value indicates that the sequence has not yet started. + +**9.2.7.13.3. StartTime Field** + +This field SHALL indicate the planned start time, in UTC, for the entire Forecast. + +**9.2.7.13.4. EndTime Field** + +This field SHALL indicate the planned end time, in UTC, for the entire Forecast. + +**9.2.7.13.5. EarliestStartTime Field** + +This field SHALL indicate the earliest start time, in UTC, that the entire Forecast can be shifted to. + +A null value indicates that it can be started immediately. + +**9.2.7.13.6. LatestEndTime Field** + +This field SHALL indicate the latest end time, in UTC, for the entire Forecast. + +e.g. for an EVSE charging session, this may indicate the departure time for the vehicle, by which +time the charging session must end. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 629 +``` + +**9.2.7.13.7. IsPausable Field** + +This field SHALL indicate that some part of the Forecast can be paused. It aims to allow a client to +read this flag and if it is false, then none of the slots contain SlotIsPausable set to true. This can save +a client from having to check each slot in the list. + +**9.2.7.13.8. Slots Field** + +This field SHALL contain a list of SlotStructs. + +It SHALL contain at least 1 entry, and a maximum of 10. + +**9.2.7.13.9. ForecastUpdateReason Field** + +This field SHALL contain the reason the current Forecast was generated. + +**9.2.7.14. SlotStruct Type** + +This indicates a specific stage of an ESA’s operation. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 MinDura­ +tion +``` +``` +elapsed-s all M +``` +``` +1 MaxDura­ +tion +``` +``` +elapsed-s all M +``` +``` +2 Default­ +Duration +``` +``` +elapsed-s all M +``` +``` +3 Elapsed­ +SlotTime +``` +``` +elapsed-s all M +``` +``` +4 Remain­ +ingSlot­ +Time +``` +``` +elapsed-s all M +``` +``` +5 Slo­ +tIsPaus­ +able +``` +``` +bool all PAU +``` +``` +6 MinPause­ +Duration +``` +``` +elapsed-s all PAU +``` +``` +7 Max­ +PauseDu­ +ration +``` +``` +elapsed-s all PAU +``` +``` +8 Manufac­ +turerE­ +SAState +``` +``` +uint16 all SFR +``` +``` +9 Nomi­ +nalPower +``` +``` +power-mW all PFR +``` +``` +Page 630 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +10 MinPower power-mW all PFR +11 MaxPower power-mW all PFR +12 Nomi­ +nalEnergy +``` +``` +energy- +mWh +``` +``` +all PFR +``` +``` +13 Costs list[Cost­ +Struct] +``` +``` +max 5 O +``` +``` +14 MinPow­ +erAdjust­ +ment +``` +``` +power-mW all FA & PFR +``` +``` +15 MaxPow­ +erAdjust­ +ment +``` +``` +power-mW all FA & PFR +``` +``` +16 MinDura­ +tionAd­ +justment +``` +``` +elapsed-s all FA +``` +``` +17 MaxDura­ +tionAd­ +justment +``` +``` +elapsed-s all FA +``` +**9.2.7.14.1. MinDuration Field** + +This field SHALL indicate the minimum time (in seconds) that the appliance expects to be in this +slot for. + +**9.2.7.14.2. MaxDuration Field** + +This field SHALL indicate the maximum time (in seconds) that the appliance expects to be in this +slot for. + +**9.2.7.14.3. DefaultDuration Field** + +This field SHALL indicate the expected time (in seconds) that the appliance expects to be in this slot +for. + +**9.2.7.14.4. ElapsedSlotTime Field** + +This field SHALL indicate the time (in seconds) that has already elapsed whilst in this slot. If the slot +has not yet been started, then it SHALL be 0. Once the slot has been completed, then this reflects +how much time was spent in this slot. + +When subscribed to, a change in this field value SHALL NOT cause the Forecast attribute to be +updated since this value may change every 1 second. + +When the Forecast attribute is read, then this value SHALL be the most recent value. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 631 +``` + +**9.2.7.14.5. RemainingSlotTime Field** + +This field SHALL indicate the time (in seconds) that is estimated to be remaining. + +Note that it may not align to the DefaultDuration - ElapsedSlotTime since an appliance may have +revised its planned operation based on conditions. + +When subscribed to, a change in this field value SHALL NOT cause the Forecast attribute to be +updated, since this value may change every 1 second. + +Note that if the ESA is currently paused, then this value SHALL NOT change. + +When the Forecast attribute is read, then this value SHALL be the most recent value. + +**9.2.7.14.6. SlotIsPausable Field** + +This field SHALL indicate whether this slot can be paused. + +**9.2.7.14.7. MinPauseDuration Field** + +This field SHALL indicate the shortest period that the slot can be paused for. This can be set to avoid +controllers trying to pause ESAs for short periods and then resuming operation in a cyclic fashion +which may damage or cause excess energy to be consumed with restarting of an operation. + +**9.2.7.14.8. MaxPauseDuration Field** + +This field SHALL indicate the longest period that the slot can be paused for. + +**9.2.7.14.9. ManufacturerESAState Field** + +This field SHALL indicate a manufacturer defined value indicating the state of the ESA. + +This may be used by an observing EMS which also has access to the metering data to ascertain the +typical power drawn when the ESA is in a manufacturer defined state. + +Some appliances, such as smart thermostats, may not know how much power is being drawn by the +HVAC system, but do know what they have asked the HVAC system to do. + +Manufacturers can use this value to indicate a variety of states in an unspecified way. For example, +they may choose to use values between 0-100 as a percentage of compressor modulation, or could +use these values as Enum states meaning heating with fan, heating without fan etc. + +``` +NOTE An ESA SHALL always use the same value to represent the same operating state. +``` +By providing this information a smart EMS may be able to learn the observed power draw when +the ESA is put into a specific state. It can potentially then use the ManufacturerESAState field in the +Forecast attribute along with observed power drawn to predict the power draw from the appliance +and potentially ask it to modify its timing via one of the adjustment request commands, or adjust +other ESAs power to compensate. + +``` +Page 632 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.2.7.14.10. NominalPower Field** + +This field SHALL indicate the expected power that the appliance will use during this slot. It may be +considered the average value over the slot, and some variation from this would be expected (for +example, as it is ramping up). + +**9.2.7.14.11. MinPower Field** + +This field SHALL indicate the lowest power that the appliance expects to use during this slot. (e.g. +during a ramp up it may be 0W). + +Some appliances (e.g. battery inverters which can charge and discharge) may have a negative +power. + +**9.2.7.14.12. MaxPower Field** + +This field SHALL indicate the maximum power that the appliance expects to use during this slot. +(e.g. during a ramp up it may be 0W). This field ignores the effects of short-lived inrush currents. + +Some appliances (e.g. battery inverters which can charge and discharge) may have a negative +power. + +**9.2.7.14.13. NominalEnergy Field** + +This field SHALL indicate the expected energy that the appliance expects to use or produce during +this slot. + +Some appliances (e.g. battery inverters which can charge and discharge) may have a negative +energy. + +**9.2.7.14.14. Costs Field** + +This field SHALL indicate the current estimated cost for operating. + +For example, if the device has access to an Energy pricing server it may be able to use the tariff to +estimate the cost of energy for this slot in the power forecast. + +When an Energy Management System requests a change in the schedule, then the device MAY sug­ +gest a change in the cost as a result of shifting its energy. This can allow a demand side response +service to be informed of the relative cost to use energy at a different time. + +The Costs field is a list of CostStruct structures which allows multiple CostTypeEnum and Values to +be shared by the energy appliance. These could be based on GHG emissions, comfort value for the +consumer etc. + +For example, comfort could be expressed in abstract units or in currency. A water heater that is +heated earlier in the day is likely to lose some of its heat before it is needed, which could require a +top-up heating event to occur later in the day (which may incur additional cost). + +If the ESA cannot calculate its cost for any reason (such as losing its connection to a Price server) it +may omit this field. This is treated as extra meta data that an EMS may use to optimize a system. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 633 +``` + +**9.2.7.14.15. MinPowerAdjustment Field** + +This field SHALL indicate the minimum power that the appliance can be requested to use. + +For example, some EVSEs cannot be switched on to charge below 6A which may equate to ~1.3kW +in EU markets. If the slot indicates a NominalPower of 0W (indicating it is expecting to be off ), this +allows an ESA to indicate it could be switched on to charge, but this would be the minimum power +limit it can be set to. + +**9.2.7.14.16. MaxPowerAdjustment Field** + +This field SHALL indicate the maximum power that the appliance can be requested to use. + +For example, an EVSE may be limited by its electrical supply to 32A which would be ~7.6kW in EU +markets. If the slot indicates a NominalPower of 0W (indicating it is expecting to be off ), this allows +an ESA to indicate it could be switched on to charge, but this would be the maximum power limit it +can be set to. + +**9.2.7.14.17. MinDurationAdjustment Field** + +This field SHALL indicate the minimum time, in seconds, that the slot can be requested to short­ +ened to. + +For example, if the slot indicates a NominalPower of 0W (indicating it is expecting to be off ), this +would allow an ESA to specify the minimum time it could be switched on for. This is to help protect +the appliance from being damaged by short cycling times. + +For example, a heat pump compressor may have a minimum cycle time of order a few minutes. + +**9.2.7.14.18. MaxDurationAdjustment Field** + +This field SHALL indicate the maximum time, in seconds, that the slot can be requested to extended +to. + +For example, if the slot indicates a NominalPower of 0W (indicating it is expecting to be off ), this +allows an ESA to specify the maximum time it could be switched on for. This may allow a battery or +water heater to indicate the maximum duration that it can charge for before becoming full. In the +case of a battery inverter which can be discharged, it may equally indicate the maximum time the +battery could be discharged for (at the MaxPowerAdjustment power level). + +**9.2.7.15. SlotAdjustmentStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 SlotIndex uint8 desc M +1 Nomi­ +nalPower +``` +``` +power-mW desc PFR +``` +``` +2 Duration elapsed-s desc M +``` +``` +Page 634 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.2.7.15.1. SlotIndex Field** + +This field SHALL indicate the index into the Slots list within the Forecast that is to be modified. It +SHALL be less than the actual length of the Slots list (implicitly it must be in the range 0 to 9 based +on the maximum length of the Slots list constraint). + +**9.2.7.15.2. NominalPower Field** + +This field SHALL indicate the new requested power that the ESA SHALL operate at. It MUST be +between the AbsMinPower and AbsMaxPower attributes as advertised by the ESA if it supports PFR. + +This is a signed value and can be used to indicate charging or discharging. + +If the ESA does NOT support PFR this value SHALL be ignored by the ESA. + +**9.2.7.15.3. Duration Field** + +This field SHALL indicate the new requested duration, in seconds, that the ESA SHALL extend or +shorten the slot duration to. It MUST be between the MinDurationAdjustment and MaxDurationAd­ +justment for the slot as advertised by the ESA. + +**9.2.7.16. ConstraintsStruct Type** + +The ConstraintsStruct allows a client to inform an ESA about a constraint period (such as a grid +event, or perhaps excess solar PV). The format allows the client to suggest that the ESA can either +turn up its energy consumption, or turn down its energy consumption during this period. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 StartTime epoch-s desc M +1 Duration elapsed-s max 86400 M +2 Nomi­ +nalPower +``` +``` +power-mW desc PFR +``` +``` +3 Maxi­ +mumEn­ +ergy +``` +``` +energy- +mWh +``` +``` +all PFR +``` +``` +4 LoadCon­ +trol +``` +``` +int8 all SFR +``` +**9.2.7.16.1. StartTime Field** + +This field SHALL indicate the start time of the constraint period that the client wishes the ESA to +compute a new Forecast. + +This value is in UTC and MUST be in the future. + +**9.2.7.16.2. Duration Field** + +This field SHALL indicate the duration of the constraint in seconds. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 635 +``` + +**9.2.7.16.3. NominalPower Field** + +This field SHALL indicate the nominal power that client wishes the ESA to operate at during the +constrained period. It MUST be between the AbsMinPower and AbsMaxPower attributes as adver­ +tised by the ESA if it supports PFR. + +This is a signed value and can be used to indicate charging or discharging. + +**9.2.7.16.4. MaximumEnergy Field** + +This field SHALL indicate the maximum energy that can be transferred to or from the ESA during +the constraint period. + +This is a signed value and can be used to indicate charging or discharging. + +**9.2.7.16.5. LoadControl Field** + +This field SHALL indicate the turn up or turn down nature that the grid wants as the outcome by +the ESA during the constraint period. + +This is expressed as a signed value between -100 to +100. A value of 0 would indicate no bias to +using more or less energy. A negative value indicates a request to use less energy. A positive value +indicates a request to use more energy. + +Note that the mapping between values and operation is manufacturer specific. + +**9.2.8. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 ESAType ESAType­ +Enum +``` +``` +all F Other R V M +``` +``` +0x0001 ESACan­ +Generate +``` +``` +bool all F false R V M +``` +``` +0x0002 ESAState ESASta­ +teEnum +``` +``` +desc 0 R V M +``` +``` +0x0003 AbsMin­ +Power +``` +``` +power-mW all 0 R V M +``` +``` +0x0004 AbsMax­ +Power +``` +``` +power-mW min +AbsMin­ +Power +``` +### 0 R V M + +``` +0x0005 PowerAd­ +justment­ +Capability +``` +``` +PowerAd­ +justCapa­ +bilityStruct +``` +``` +all X Q null R V PA +``` +``` +0x0006 Forecast Forecast­ +Struct +``` +``` +all X Q null R V PFR | SFR +``` +``` +Page 636 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0007 OptOut­ +State +``` +``` +OptOutSta­ +teEnum +``` +``` +desc 0 R V PA | STA | +PAU | FA | +CON +``` +**9.2.8.1. ESAType Attribute** + +This attribute SHALL indicate the type of ESA. + +This attribute enables an EMS to understand some of the basic properties about how the energy +may be consumed, generated, and stored by the ESA. + +For example, the heat energy converted by a heat pump will naturally be lost through the building +to the outdoor environment relatively quickly, compared to storing heat in a well-insulated hot +water tank. Similarly, battery storage and EVs can store electrical energy for much longer dura­ +tions. + +This attribute can also help the EMS display information to a user and to make basic assumptions +about typical best use of energy. For example, an EVSE may not always have an EV plugged in, so +knowing the type of ESA that is being controlled can allow advanced energy management strate­ +gies. + +**9.2.8.2. ESACanGenerate Attribute** + +This attribute SHALL indicate whether the ESA is classed as a generator or load. This allows an EMS +to understand whether the power values reported by the ESA need to have their sign inverted +when dealing with forecasts and adjustments. + +For example, a solar PV inverter (being a generator) may produce negative values to indicate gener­ +ation (since power is flowing out of the node into the home), however a display showing the power +to the consumers may need to present a positive solar production value to the consumer. + +For example, a home battery storage system (BESS) which needs to charge the battery and then dis­ +charge to the home loads, would be classed as a generator. These types of devices SHALL have this +field set to true. When generating its forecast or advertising its PowerAdjustmentCapability, the +power values shall be negative to indicate discharging to the loads in the home, and positive to indi­ +cate when it is charging its battery. + +``` +GRID meter = Σ LoadPowers + Σ GeneratorPowers +``` +Example: + +``` +Home has the following loads: +Water Heater: 3000W +TV: 200W +FridgeFreezer: 200W +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 637 +``` + +``` +Total: 3400W +``` +``` +Home has the following generators (ESACanGenerate = true) +Solar: -2500W +BESS: -900W +Total: -3400W +``` +``` +GRID Meter: +Σ Loads: 3400W +Σ Generators: -3400W +Total: 0W +``` +**9.2.8.3. ESAState Attribute** + +This attribute SHALL indicate the current state of the ESA. + +If the ESA is in the Offline or Fault state it cannot be controlled by an EMS, and may not be able to +report its Forecast information. An EMS may subscribe to the ESAState to get notified about changes +in operational state. + +The ESA may have a local user interface to allow a service technician to put the ESA into Offline +mode, for example to avoid the EMS accidentally starting or stopping the appliance when it is being +serviced or tested. + +**9.2.8.4. AbsMinPower Attribute** + +This attribute SHALL indicate the minimum electrical power that the ESA can consume when +switched on. This does not include when in power save or standby modes. + +### NOTE + +``` +For Generator ESAs that can discharge an internal battery (such as a battery storage +inverter) to loads in the home, the AbsMinPower will be a negative number repre­ +senting the maximum power that the ESA can discharge its internal battery. +``` +**9.2.8.5. AbsMaxPower Attribute** + +This attribute SHALL indicate the maximum electrical power that the ESA can consume when +switched on. + +Note that for Generator ESAs that can charge a battery by importing power into the node (such as a +battery storage inverter), the AbsMaxPower will be a positive number representing the maximum +power at which the ESA can charge its internal battery. + +For example, a battery storage inverter that can charge its battery at a maximum power of 2000W +and can discharge the battery at a maximum power of 3000W, would have a AbsMinPower: -3000, +AbsMaxPower: 2000W. + +``` +Page 638 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.2.8.6. PowerAdjustmentCapability Attribute** + +This attribute SHALL indicate how the ESA can be adjusted at the current time, and the state of any +active adjustment. + +A null value indicates that no power adjustment is currently possible, and nor is any adjustment +currently active. + +This attribute SHOULD be updated periodically by ESAs to reflect any changes in internal state, for +example temperature or stored energy, which would affect the power or duration limits. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once every 10 seconds on changes, or +- When it changes from null to any other value and vice versa. + +**9.2.8.7. Forecast Attribute** + +This attribute allows an ESA to share its intended forecast with a client (such as an Energy Manage­ +ment System). + +A null value indicates that there is no forecast currently available (for example, a program has not +yet been selected by the user). + +A server MAY reset this value attribute to null on a reboot, and it does not need to persist any previ­ +ous forecasts. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once every 10 seconds on changes, or +- When it changes from null to any other value and vice versa, or +- As a result of a command which causes the forecast to be updated, or +- As a result of a change in the opt-out status which in turn may cause the ESA to recalculate its + forecast. + +**9.2.8.8. OptOutState Attribute** + +This attribute SHALL indicate the current Opt-Out state of the ESA. The ESA may have a local user +interface to allow the user to control this OptOutState. An EMS may subscribe to the OptOutState to +get notified about changes in operational state. + +If the ESA is in the LocalOptOut or OptOut states, so it cannot be controlled by an EMS for local opti­ +mization reasons, it SHALL reject any commands which have the AdjustmentCauseEnum value +LocalOptimization. If the ESA is in the GridOptOut or OptOut states, so it cannot be controlled by an +EMS for grid optimization reasons, it SHALL reject any commands which have the Adjustment­ +CauseEnum value GridOptimization. + +If the user changes the Opt-Out state of the ESA which is currently operating with a Forecast that is +due to a previous StartTimeAdjustRequest, ModifyForecastRequest or RequestConstraintBasedFore­ +cast command that would now not be permitted due to the new Opt-out state (i.e. the Forecast + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 639 +``` + +attribute ForecastUpdateReason field currently contains a reason which is now opted out), the ESA +SHALL behave as if it had received a CancelRequest command. + +If the user changes the Opt-Out state of the ESA which currently has the ESAStateEnum with value +Paused due to a previous PauseRequest command that would now not be permitted due to the new +Opt-out state, and the ESA supports the PFR or SFR features (i.e. the Forecast attribute ForecastUp­ +dateReason field currently contains a reason which is now opted out), the ESA SHALL behave as if it +had received a ResumeRequest command. + +If the user changes the Opt-Out state of the ESA which currently has the ESAStateEnum with value +PowerAdjustActive due to a previous PowerAdjustRequest command that would now not be permit­ +ted due to the new Opt-out state (i.e. the Forecast attribute ForecastUpdateReason field currently +contains a reason which is now opted out), the ESA SHALL behave as if it had received a Can­ +celPowerAdjustRequest command. + +If the ESA is in the LocalOptOut, GridOptOut, or NoOptOut states, the device is still permitted to +optimize its own energy usage, for example, using tariff information it may obtain. + +**9.2.9. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 PowerAdjus­ +tRequest +``` +``` +client ⇒ server Y O PA +``` +``` +0x01 CancelPower­ +AdjustRequest +``` +``` +client ⇒ server Y O PA +``` +``` +0x02 StartTimeAd­ +justRequest +``` +``` +client ⇒ server Y O STA +``` +``` +0x03 PauseRequest client ⇒ server Y O PAU +0x04 ResumeReque +st +``` +``` +client ⇒ server Y O PAU +``` +``` +0x05 ModifyFore­ +castRequest +``` +``` +client ⇒ server Y O FA +``` +``` +0x06 RequestCon­ +straintBased­ +Forecast +``` +``` +client ⇒ server Y O CON +``` +``` +0x07 CancelRequest client ⇒ server Y O STA | FA | CON +``` +**9.2.9.1. PowerAdjustRequest Command** + +Allows a client to request an adjustment in the power consumption of an ESA for a specified dura­ +tion. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Power power-mW desc M +``` +``` +Page 640 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 Duration elapsed-s desc M +2 Cause Adjustment­ +CauseEnum +``` +``` +desc M +``` +**9.2.9.1.1. Power Field** + +This field SHALL indicate the power that the ESA SHALL use during the adjustment period. + +This value SHALL be between the MinPower and MaxPower fields of the PowerAdjustStruct in the +PowerAdjustmentCapability attribute. + +**9.2.9.1.2. Duration Field** + +This field SHALL indicate the duration that the ESA SHALL maintain the requested power for. + +This value SHALL be between the MinDuration and MaxDuration fields of the PowerAdjustStruct in +the PowerAdjustmentCapability attribute. + +**9.2.9.1.3. Cause Field** + +This field SHALL indicate the cause of the request from the EMS. + +**9.2.9.1.4. Effect on receipt** + +On receipt of this command, the ESA SHALL validate that the Power and Duration specified in the +command are within the limits of its current operation and advertised PowerAdjustmentCapability +attribute, the OptOutState permits the specified AdjustmentCauseEnum (see OptOutState for +details), and the ESAState is Online. + +If the PowerAdjustRequest command is accepted, then the ESA SHALL change its ESAState to Pow­ +erAdjustActive, and the PowerAdjustmentCapability attribute SHALL be updated to set the Cause +value from the Cause field of this command. + +The command status returned SHALL be SUCCESS if the adjustment is accepted; otherwise the com­ +mand SHALL be rejected with CONSTRAINT_ERROR if the Power, Duration, or Cause values are not +permitted as above, or with FAILURE otherwise. + +**Start of adjustment** + +The ESA SHALL generate a PowerAdjustStart Event when it begins to adjust its power. + +The ESA then begins to adjust its power consumption or generation to the power level commanded +in the Power field. + +**End of adjustment (normal completion)** + +After the elapsed duration, the ESA SHALL revert to normal (or idle) power levels. + +The ESA SHALL also generate a PowerAdjustEnd Event with a cause code to indicate a 'Normal + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 641 +``` + +completion', the ESAState SHALL be restored to Online, and the PowerAdjustmentCapability +attribute SHALL be updated to set the Cause value to 'NoAdjustment'. + +**Failure or Opt-out during adjustment** + +If during the power adjustment session a failure or other condition occurs (such as the user decid­ +ing to opt-out by updating the OptOutState) then the ESA SHALL generate a PowerAdjustEnd Event +to indicate the end of the session, with the appropriate cause code. + +The ESAState SHALL be updated to reflect the new state, and the PowerAdjustmentCapability +attribute SHALL be updated to set the Cause value to 'NoAdjustment'. + +**Receiving a new PowerAdjustRequest command when adjustment is on-going** + +If an existing power adjustment is already happening, and a new PowerAdjustRequest command is +received, then if the ESA allows it, the ESA SHALL return SUCCESS, and the PowerAdjustmentCapa­ +bility attribute SHALL be updated to set the Cause value from the Cause field of the new command. +If the ESA does not permit this new PowerAdjustmentRequest command to interrupt the adjust­ +ment that is in progress, it SHALL return BUSY. + +Note that if the new command is accepted, then the ESA SHALL NOT generate a new PowerAdjus­ +tEnd Event until the new duration has elapsed. This is to avoid generating too many events in cases +where a device is routinely commanded with overlapping power adjustments. + +For example, a battery inverter ESA may be sent a new request every 5 seconds to adjust its dis­ +charge power based on real-time meter readings. Each command may have a 60 second duration, +but this command is superseded after 5 seconds by a new request. + +After the client has sent its last command and after this command duration expires then the last +active power adjustment has been completed. This final command causes the PowerAdjustEnd +Event to be generated when the ESAState is restored to Online, and the PowerAdjustmentCapability +attribute SHALL be updated to set the Cause value to 'NoAdjustment'. + +**9.2.9.2. CancelPowerAdjustRequest Command** + +Allows a client to cancel an ongoing PowerAdjustmentRequest operation. + +**9.2.9.2.1. Effect on receipt** + +On receipt of this command, the ESA SHALL end the active power adjustment session and return to +normal (or idle) power levels. + +If the ESAState is not PowerAdjustActive, then the command SHALL be rejected with INVALID_IN_S­ +TATE. + +If the command is accepted, the ESA SHALL generate an PowerAdjustEnd Event and the ESAState +SHALL be restored to Online, the PowerAdjustmentCapability attribute SHALL be updated to set the +Cause value to 'NoAdjustment', and the command status returned SHALL be SUCCESS. + +``` +Page 642 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.2.9.3. StartTimeAdjustRequest Command** + +Allows a client to adjust the start time of a Forecast sequence that has not yet started operation (i.e. +where the current Forecast StartTime is in the future). + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Requested­ +StartTime +``` +``` +epoch-s desc M +``` +``` +1 Cause Adjustment­ +CauseEnum +``` +``` +all M +``` +**9.2.9.3.1. RequestedStartTime Field** + +This field SHALL indicate the requested start time, in UTC, that the client would like the appliance +to shift its Forecast to. This value MUST be in the future. + +A client can estimate the entire Forecast sequence duration by computing the EndTime - StartTime +fields from the Forecast attribute, and therefore avoid scheduling the start time too late. + +This value SHALL be after the EarliestStartTime in the Forecast attribute. The new EndTime, that +can be computed from the RequestedStartTime and the Forecast sequence duration, SHALL be +before the LatestEndTime. + +**9.2.9.3.2. Cause Field** + +This field SHALL indicate the cause of the request from the EMS. + +**9.2.9.3.3. Effect on receipt** + +On receipt of this command, if the ESA supports STA, and the OptOutState permits the specified +AdjustmentCauseEnum (see OptOutState for details), and the RequestedStartTime adjustment +would be within constraints described in RequestedStartTime then ESA SHALL accept the request +to modify the Start Time. + +If the RequestedStartTime value resulted in a time shift which is outside the time constraints of Ear­ +liestStartTime and LatestEndTime, or the Cause is not permitted, then the command SHALL be +rejected with CONSTRAINT_ERROR; in other failure scenarios the command SHALL be rejected with +FAILURE. + +The command status returned SHALL be SUCCESS if the StartTime in the Forecast is updated. The +ESA SHALL update its Forecast attribute using the new RequestedStartTime including a new Fore­ +castID, StartTime, EndTime, and ForecastUpdateReason. + +**9.2.9.4. PauseRequest Command** + +Allows a client to temporarily pause an operation and reduce the ESAs energy demand. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 643 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Duration elapsed-s desc M +1 Cause Adjustment­ +CauseEnum +``` +``` +all M +``` +**9.2.9.4.1. Duration Field** + +This field SHALL indicate the duration that the ESA SHALL be paused for. This value SHALL be +between the MinPauseDuration and MaxPauseDuration indicated in the ActiveSlotNumber index in +the Slots list in the Forecast. + +**9.2.9.4.2. Cause Field** + +This field SHALL indicate the cause of the request from the EMS. + +**9.2.9.4.3. Effect on receipt** + +On receipt of this command, if the ESA supports PAU and the SlotIsPausable field is true in the +ActiveSlotNumber index in the Slots list, the OptOutState permits the specified Adjustment­ +CauseEnum (see OptOutState for details), and the OptOutState is Online or PowerAdjustActive, the +ESA SHALL allow its current operation to be Paused. If the Cause is not permitted, then the com­ +mand SHALL be rejected with CONSTRAINT_ERROR. + +If the ESA SlotIsPausable field is false for the ActiveSlotNumber, then the command SHALL be +rejected with FAILURE. + +The ESA SHALL validate that the Duration field is within the range of MinPauseDuration and Max­ +PauseDuration. If it is outside of this range then the command SHALL be rejected with CONSTRAIN­ +T_ERROR. + +The command status returned SHALL be SUCCESS if the ESA is paused. + +Once the command has been accepted, the ESA SHALL also generate a Paused Event and the ESAS­ +tate SHALL be set to Paused. + +The ESA SHALL update its update its Forecast to account for the pause, including updating the Fore­ +castUpdateReason from the Cause field. + +**Pause timer start** The ESA SHALL start a Pause timer based on the value of the Duration field. + +**Paused State** Whilst in the Paused state, the ESA SHALL NOT consume or produce significant +power (other than required to keep its basic control system operational). + +**Pause timer expiry** When the Pause timer expires the ESA SHALL automatically resume operation. +When it does this, then it SHALL also generate a Resumed Event and the ESAState SHALL be +updated accordingly to reflect its current state (for example, it may still have PowerAdjustActive +now it has resumed from the Pause). The ESA SHALL update its Forecast including setting Forecas­ +tUpdateReason to InternalOptimization to account for the resumption after the pause. + +``` +Page 644 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Receiving a further pause request command whilst paused** If a further Pause Request is +received in the same forecast slot whilst already in the paused state, the ESA SHALL again validate +that the Duration value is within the range of the (possibly revised) MinPauseDuration and Max­ +PauseDuration. If it is outside of this range then the command SHALL be rejected with CONSTRAIN­ +T_ERROR. + +If the command is accepted the pause timer SHALL be extended by the new Duration. + +**ResumeRequest** A client MAY send a ResumeRequest command, before the Pause timer has +expired, to request the ESA to return to its normal operating state. See ResumeRequest for details. + +**Failure or Opt-out during PauseRequest** A consumer MAY decide to opt-out of the remotely com­ +manded PauseRequest by updating the OptOutState, and the ESA SHALL also change the ESAState +to the new state. + +If the ESA develops a fault whilst Paused, the ESAState SHALL be set to Fault. + +On change of ESAState (from Paused to another state), the ESA SHALL generate a Resumed Event. + +**9.2.9.5. ResumeRequest Command** + +Allows a client to cancel the PauseRequest command and enable earlier resumption of operation. + +**9.2.9.5.1. Effect on receipt** + +On receipt of this command, if the ESA supports PAU and it is currently Paused, the ESA MAY decide +not to resume immediately if the MinPauseDuration has not yet elapsed. This behavior is manufac­ +turer specific. + +If accepted, the ESA SHALL resume its operation. The ESA SHALL also generate a Resumed Event +and the ESAState SHALL be updated accordingly to reflect its current state. + +The command status returned SHALL be SUCCESS if the operation is resumed, or the command +SHALL be rejected with the response INVALID_IN_STATE if the ESA is not currently Paused, other­ +wise the command SHALL be rejected with FAILURE. + +The ESA SHALL update its Forecast including setting ForecastUpdateReason to InternalOptimization +to account for the resumption after the pause. + +**9.2.9.6. ModifyForecastRequest Command** + +Allows a client to modify a Forecast within the limits allowed by the ESA. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ForecastID uint32 all M +1 SlotAdjust­ +ments +``` +``` +list[SlotAd­ +just­ +mentStruct] +``` +``` +max 10 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 645 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +2 Cause Adjustment­ +CauseEnum +``` +``` +all M +``` +**9.2.9.6.1. ForecastID Field** + +This field SHALL indicate the ForecastID that is to be modified. + +**9.2.9.6.2. SlotAdjustments Field** + +This field SHALL contain a list of SlotAdjustment parameters that should be modified in the corre­ +sponding Forecast with matching ForecastID. + +**9.2.9.6.3. Cause Field** + +This field SHALL indicate the cause of the request from the EMS. + +**9.2.9.6.4. Effect on receipt** + +On receipt of this command, if the ESA supports FA, and the OptOutState permits the specified +AdjustmentCauseEnum (see OptOutState for details), it SHALL attempt to adjust its forecast. + +The client may be an energy management system which has retrieved the forecasts from multiple +ESA and then performed some optimization (for example, taking advantage of local solar PV gener­ +ation). + +The ESA SHALL inspect the requested forecast and ensure that it does not exceed the limits set in +each of its slots. The ESA manufacturer may also reject the request if it could cause the user’s pref­ +erences to be breached (for example, if it may cause the home to be too hot or too cold, or a battery +to be insufficiently charged). + +Note that the client may make an adjustment when the ESA’s program has already been started. In +this case the ActiveSlotNumber may have moved through the Forecast sequence. Any attempts to +modify slots which have already been run SHALL result in the entire command being rejected. + +The command allows a single modification to a particular slot, or to multiple slots in a single com­ +mand by sending a list of modifications. + +If the ESA accepts the requested Forecast then it SHALL update its Forecast attribute (incrementing +its ForecastID, and updating its ForecastUpdateReason from the Cause value) and run the revised +Forecast as its new intended operation. + +Note that an ESA may adapt its Forecast based on a slot modification. For example, if an ESA was +switched on earlier in the day to take account of available solar PV, then it may not need to use +energy later in the day. It may add or remove slots as it chooses. This may result in several itera­ +tions for the Energy Management System to reprocess updated forecasts until it has stabilized on an +agreed set of changes. + +If for any reason the ESA cannot accept the entire requested forecast adjustments then it SHALL + +``` +Page 646 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +reject the entire command. + +If the Cause is not permitted, or the requested forecast exceeds any of the limits in the respective +slots, then the command SHALL be rejected with CONSTRAINT_ERROR, otherwise if the ForecastID +is valid, and the entire list of SlotAdjustmentStruct are accepted, the command status returned +SHALL be SUCCESS, otherwise the command SHALL be rejected with FAILURE. + +**9.2.9.7. RequestConstraintBasedForecast Command** + +Allows a client to ask the ESA to recompute its Forecast based on power and time constraints. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Constraints list[Con­ +straintsStruc +t] +``` +``` +max 10 M +``` +``` +1 Cause Adjustment­ +CauseEnum +``` +``` +all M +``` +**9.2.9.7.1. Constraints Field** + +This field SHALL indicate the series of turn up or turn down power requests that the ESA is being +asked to constrain its operation within. These requests SHALL be in the future, SHALL be in +chronological order, starting with the earliest start time, and SHALL NOT overlap in time. + +For example, a grid event which requires devices to reduce power (turn down) between 4pm and +6pm and due to excess power on the grid overnight, may request ESAs to increase their power +demand (turn up) between midnight and 6am. + +If this ESA supports PFR this would have 2 entries in the list as follows: + +``` +Entry [0] - Turn Down +StartTime2023-10-23T16:00:00 +Duration 7200 (2 hours) +NominalPower 20 W +MaximumEnergy 40 Wh +``` +``` +Entry [1] - Turn Up +StartTime2023-10-24T00:00:00 +Duration21,600 (6 hours) +NominalPower 7000 W +MaximumEnergy 42000 Wh +``` +If this ESA supports SFR where it does not know the actual power, but has an understanding of the +functions that use more energy, it could be requested to use more or less energy using the LoadCon­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 647 +``` + +trol field as follows: + +``` +Entry [0] - Turn Down +StartTime2023-10-23T16:00:00 +Duration 7200 (2 hours) +LoadControl-100 (Use less power) +``` +``` +Entry [1] - Turn Up +StartTime2023-10-24T00:00:00 +Duration21,600 (6 hours) +LoadControl+100 (Use more power) +``` +**9.2.9.7.2. Cause Field** + +This field SHALL indicate the cause of the request from the EMS. + +**9.2.9.7.3. Effect on receipt** + +On receipt of this command, if the ESA supports CON, and the OptOutState permits the specified +AdjustmentCauseEnum (see OptOutState for details), it may be requested to generate a new forecast +by a client. + +For example the client may be an energy management system which has determined that the peak +load on the home should be reduced (for example a grid event) or that there is more local genera­ +tion available and the solar export power needs to be consumed. + +The EMS may not be best placed to make the forecast adjustment because the ESA knows more +about its internal operation and system efficiencies. + +For example the total energy used when charging a battery faster may result in increased heat +losses in the inverter, so the total energy required to charge a battery with 10kWh of stored energy +may vary based on charging power. + +The ESA SHALL inspect the constraints field to ensure that the constraints defined for that field and +its elements are met. The ESA manufacturer may also reject the request if it could cause the user’s +preferences to be breached (e.g. may cause the home to be too hot or too cold, or a battery to be +insufficiently charged). + +If the ESA can meet the requested power limits, it SHALL regenerate a new Power Forecast with a +new ForecastID and ForecastUpdateReason from the Cause value. + +If an appliance has already begun running a program (and agreed to modify its schedule), it may +continue to run the same program and meet the same user settings (e.g. ECO mode), but may take +more or less time to complete the cycle. The new reported Forecast will start from the current time, +i.e. the slots that have already been completed SHALL NOT be included in the new forecast. + +The command status returned SHALL be SUCCESS, otherwise if the Cause is not permitted, or the +constraints field value does not meet the defined constraints, the command SHALL be rejected with + +``` +Page 648 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +CONSTRAINT_ERROR, otherwise the command SHALL be rejected with FAILURE. + +**9.2.9.8. CancelRequest Command** + +Allows a client to request cancellation of a previous adjustment request in a StartTimeAdjustRe­ +quest, ModifyForecastRequest or RequestConstraintBasedForecast command. + +**9.2.9.8.1. Effect on receipt** + +On receipt of this command, the ESA SHALL attempt to cancel the effects of any previous adjust­ +ment request commands, and re-evaluate its forecast for intended operation ignoring those previ­ +ous requests. + +If the ESA ForecastUpdateReason was already Internal Optimization, then the command SHALL be +rejected with INVALID_IN_STATE. + +If the command is accepted, the ESA SHALL update its ESAState if required, and the command sta­ +tus returned SHALL be SUCCESS. The ESA SHALL update its Forecast attribute to match its new +intended operation, and update the ForecastUpdateReason to Internal Optimization. + +**9.2.10. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 PowerAdjust­ +Start +``` +### INFO V PA + +``` +0x01 PowerAdjus­ +tEnd +``` +### INFO V PA + +``` +0x02 Paused INFO V PAU +0x03 Resumed INFO V PAU +``` +**9.2.10.1. PowerAdjustStart Event** + +This event SHALL be generated when the Power Adjustment session is started. + +**9.2.10.2. PowerAdjustEnd Event** + +This event SHALL be generated when the Power Adjustment session ends. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Cause CauseEnum all NormalCom­ +pletion +``` +### M + +``` +1 Duration elapsed-s all M +2 EnergyUse energy-mWh all M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 649 +``` + +**9.2.10.2.1. Cause Field** + +This field SHALL indicate the reason why the power adjustment session ended. + +**9.2.10.2.2. Duration Field** + +This field SHALL indicate the number of seconds that the power adjustment session lasted before +ending. + +**9.2.10.2.3. EnergyUse Field** + +This field SHALL indicate the approximate energy used by the ESA during the session. + +For example, if the ESA was on and was adjusted to be switched off, then this SHALL be 0 mWh. If +this was a battery inverter that was requested to discharge it would have a negative EnergyUse +value. If this was a normal load that was turned on, then it will have positive value. + +**9.2.10.3. Paused Event** + +This event SHALL be generated when the ESA enters the Paused state. + +There is no data for this event. + +**9.2.10.4. Resumed Event** + +This event SHALL be generated when the ESA leaves the Paused state and resumes operation. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Cause CauseEnum all NormalCom­ +pletion +``` +### M + +**9.2.10.4.1. Cause Field** + +This field SHALL indicate the reason why the pause ended. + +**9.3. Energy EVSE Cluster** + +Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or +Plug-In Hybrid Electric Vehicle. This cluster provides an interface to the functionality of Electric +Vehicle Supply Equipment (EVSE) management. + +Devices targeted by this cluster include Electric Vehicle Supply Equipment (EVSE). The cluster +generically assumes a signaling protocol (J1772 in NA and IEC61851 in Europe and Asia) between +the EVSE and Electric Vehicle (EV) that utilizes a pilot signal to manage the states of the charging +process. [SAE J2847/3_202311] version and IEC61841 define Pilot signal as a modulated DC voltage +on a single wire. + +Power Line Communication (PLC) is supported by some EVSEs (e.g. for support of ISO 15118 in +Europe and SAE J2931/4 in NA) and may enable features such as Vehicle to Grid (V2G) or Vehicle to + +``` +Page 650 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Home (V2H) that allows for bi-directional charging/discharging of electric vehicles. + +More modern EVSE devices may optionally support ISO 15118-20 in Europe and SAE J2836/3 for NA +to support bi-directional charging (Vehicle to Grid - V2G) and Plug and Charge capabilities. + +This cluster definition assumes AC charging only. DC charging options may be added in future revi­ +sions of this cluster. + +This cluster supports a safety mechanism that may lockout remote operation until the initial latch­ +ing conditions have been met. Some of the fault conditions defined in SAE J1772, such as Ground- +Fault Circuit Interrupter (GFCI) or Charging Circuit Interrupting Device (CCID), may require clear­ +ing by an operator by, for example, pressing a button on the equipment or breaker panel. + +This EVSE cluster is written around support of a single EVSE. Having multiple EVSEs at home or a +business is managed by backend system and outside scope of this cluster. + +Note that in many deployments the EVSE may be outside the home and may suffer from intermit­ +tent network connections (e.g. a weak WiFi signal). It also allows for a charging profile to be pre- +configured, in case there is a temporary communications loss during a charging session. + +**9.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Updates after 0.7 Ballot review +3 Added Q quality for SessionDuration, SessionEn­ +ergyCharged and SessionEnergyDischarged. +Updates to V2X and associated areas. Make PREF +mandatory. +``` +**9.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint EEVSE +``` +**9.3.3. Cluster ID** + +``` +ID Name +0x0099 Energy EVSE +``` +**9.3.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 651 +``` + +``` +Bit Code Feature Conformance Summary +0 PREF ChargingPrefer­ +ences +``` +``` +M EVSE supports +storing user charg­ +ing preferences +1 SOC SoCReporting P,O EVSE supports +reporting of vehi­ +cle State of Charge +(SoC) +2 PNC PlugAndCharge P,O EVSE supports PLC +to support Plug +and Charge +3 RFID RFID O EVSE is fitted with +an RFID reader +4 V2X V2X P,O EVSE supports bi- +directional charg­ +ing / discharging +``` +**9.3.4.1. ChargingPreferences Feature** + +Since some EVSEs cannot obtain the SoC from the vehicle, some EV charging solutions allow the +consumer to specify a daily charging target (for adding energy to the EV’s battery). This feature +allows the consumer to specify how many miles or km of additional range they need for their typi­ +cal daily commute. This range requirement can be converted into a daily energy demand with a tar­ +get charging completion time. + +The EVSE itself can use this information (or may allow a controller such as an EMS) to compute an +optimized charging schedule. + +An EVSE device which includes a Device Energy Management device with the Device Energy Man­ +agement cluster PFR (Power Forecast Reporting) feature can use the charging preferences informa­ +tion to produce its power forecast. + +EVSE devices that support the Device Energy Management cluster’s FA feature can have their charg­ +ing profiles set by a controller device such as an EMS. For example, if the EVSE advertises a simple +power forecast which allows the EMS to adjust over a wide range of power and time durations, +then the EVSE may allow the EMS to propose a revised optimized forecast (which is the charging +profile). For example, a solar PV ESA may also share its Forecast, so enabling an EMS to adjust the +EVSE forecast to the best time to charge so that any excess solar generation is used to charge the EV. + +See the Device Energy Management Cluster for more details. + +**9.3.4.2. SoCReporting Feature** + +Vehicles and EVSEs which support ISO 15118 may allow the vehicle to report its battery size and +state of charge. If the EVSE supports PLC it may have a vehicle connected which optionally supports +reporting of its battery size and current State of Charge (SoC). + +``` +Page 652 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +If the EVSE supports reporting of State of Charge this feature will only work if a compatible EV is +connected. + +Note some EVSEs may use other undefined mechanisms to obtain vehicle State of Charge outside +the scope of this cluster. + +**9.3.4.3. PlugAndCharge Feature** + +If the EVSE supports PLC, it may be able to support the Plug and Charge feature. e.g. this may allow +the vehicle ID to be obtained which may allow an energy management system to track energy usage +per vehicle (e.g. to give the owner an indicative cost of charging, or for work place charging). + +If the EVSE supports the Plug and Charge feature, it will only work if a compatible EV is connected. + +**9.3.4.4. RFID Feature** + +If the EVSE is fitted with an RFID reader, it may be possible to obtain the User or Vehicle ID from an +RFID card. This may be used to record a charging session against a specific charging account, and +may optionally be used to authorize a charging session. + +An RFID event can be generated when a user taps an RFID card onto the RFID reader. The event +must be subscribed to by the EVSE Management cluster client. This client may use this to enable the +EV to charge or discharge. The lookup and authorization of RIFD UID is outside the scope of this +cluster. + +**9.3.4.5. V2X Feature** + +If the EVSE can support bi-directional charging, it may be possible to request that the vehicle can +discharge to the home or grid. + +The charging and discharging may be controlled by a home Energy Management System (EMS) +using the Device Energy Management cluster of the associated Device Energy Management device. +For example, an EMS may use the PA (Power Adjustment) feature to continually adjust the +charge/discharge current to/from the EV so as to minimise the energy flow from/to the grid as the +demand in the home and the solar supply to the home both fluctuate. + +**9.3.5. Dependencies** + +The server side of this cluster SHALL depend on setting time from another device or using a real- +time clock. + +This can either use a built-in real-time clock or non Matter time source, or can be derived using the +Time Synchronization cluster. + +**9.3.5.1. Diagnostic Event logs** + +``` +It is quite common that users may experience issues charging their vehicle, which, without +logs to understand what happened, makes it very difficult to resolve the root cause. +``` +``` +Matter supports events (see Matter specification section 7.14) which includes a buffered log of +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 653 +``` + +``` +previous events including a Timestamp (see Matter specification 7.14.2.2). +``` +``` +This Timestamp can be the System Time (since boot) or Epoch Time. It is recommended to use +Epoch time (which can be set using the Time Synchronization cluster), which would allow +remote support operatives to retrieve the event logs and analyze them against a user +reported actual time. +``` +**9.3.6. Definitions** + +**EVSE Session -** An EVSE session starts when an EV is plugged in. It ends when it is unplugged. + +**9.3.7. Data Types** + +**9.3.7.1. TargetDayOfWeekBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 Sunday Sunday M +1 Monday Monday M +2 Tuesday Tuesday M +3 Wednesday Wednesday M +4 Thursday Thursday M +5 Friday Friday M +6 Saturday Saturday M +``` +**9.3.7.2. StateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 NotPluggedIn The EV is not plugged +in. +``` +### M + +``` +1 PluggedInNoDemand The EV is plugged in, +but not demanding cur­ +rent. +``` +### M + +``` +2 PluggedInDemand The EV is plugged in +and is demanding cur­ +rent, but EVSE is not +allowing current to +flow. +``` +### M + +``` +Page 654 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +3 PluggedInCharging The EV is plugged in, +charging is in progress, +and current is flowing +``` +### M + +``` +4 PluggedInDischarging The EV is plugged in, +discharging is in +progress, and current is +flowing +``` +### V2X + +``` +5 SessionEnding The EVSE is transition­ +ing from any plugged- +in state to NotPluggedIn +``` +### M + +``` +6 Fault There is a fault (see +FaultState attribute) +``` +### M + +**9.3.7.3. SupplyStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Disabled The EV is not currently +allowed to charge or +discharge +``` +### M + +``` +1 ChargingEnabled The EV is currently +allowed to charge +``` +### M + +``` +2 DischargingEnabled The EV is currently +allowed to discharge +``` +### [V2X] + +``` +3 DisabledError The EV is not currently +allowed to charge or +discharge due to an +error. The error must +be cleared before oper­ +ation can continue. +``` +### M + +``` +4 DisabledDiagnostics The EV is not currently +allowed to charge or +discharge due to self- +diagnostics mode. +``` +### M + +``` +5 Enabled The EV is currently +allowed to charge and +discharge +``` +### [V2X] + +**9.3.7.4. FaultStateEnum Type** + +This data type is derived from enum8. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 655 +``` + +``` +Value Name Summary Conformance +0 NoError The EVSE is not in an +error state. +``` +### M + +``` +1 MeterFailure The EVSE is unable to +obtain electrical mea­ +surements. +``` +### M + +``` +2 OverVoltage The EVSE input voltage +level is too high. +``` +### M + +``` +3 UnderVoltage The EVSE input voltage +level is too low. +``` +### M + +``` +4 OverCurrent The EVSE detected +charging current +higher than allowed by +charger. +``` +### M + +``` +5 ContactWetFailure The EVSE detected volt­ +age on charging pins +when the contactor is +open. +``` +### M + +``` +6 ContactDryFailure The EVSE detected +absence of voltage after +enabling contactor. +``` +### M + +``` +7 GroundFault The EVSE has an unbal­ +anced current supply. +``` +### M + +``` +8 PowerLoss The EVSE has detected +a loss in power. +``` +### M + +``` +9 PowerQuality The EVSE has detected +another power quality +issue (e.g. phase imbal­ +ance). +``` +### M + +``` +10 PilotShortCircuit The EVSE pilot signal +amplitude short cir­ +cuited to ground. +``` +### M + +``` +11 EmergencyStop The emergency stop +button was pressed. +``` +### M + +``` +12 EVDisconnected The EVSE detected that +the cable has been dis­ +connected. +``` +### M + +``` +13 WrongPowerSupply The EVSE could not +determine proper +power supply level. +``` +### M + +Page 656 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +Value Name Summary Conformance +14 LiveNeutralSwap The EVSE detected Live +and Neutral are +swapped. +``` +### M + +``` +15 OverTemperature The EVSE internal tem­ +perature is too high. +``` +### M + +``` +255 Other Any other reason. M +``` +**9.3.7.5. EnergyTransferStoppedReasonEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 EVStopped The EV decided to stop M +1 EVSEStopped The EVSE decided to +stop +``` +### M + +``` +2 Other An other unknown rea­ +son +``` +### M + +**9.3.7.6. ChargingTargetStruct Type** + +This represents a single user specified charging target for an EV. + +An EVSE or EMS system optimizer may use this information to take the Time of Use Tariff, grid car­ +bon intensity, local generation (solar PV) into account to provide the cheapest and cleanest energy +to the EV. + +The optimization strategy is not defined here, however in simple terms, the AddedEnergy require­ +ment can be fulfilled by knowing the charging Power (W) and the time needed to charge. + +``` +To compute the Charging Time: Required Energy (Wh) = Power (W) x ChargingTime (s) / 3600 +``` +``` +Therefore: ChargingTime (s) = (3600 x RequiredEnergy (wH)) / Power (W) +``` +``` +To compute the charging time: Charging StartTime = TargetTimeMinutesPastMidnight - +ChargingTime +``` +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Target­ +TimeMinu +tesPast­ +Midnight +``` +``` +uint16 max 1439 0 M +``` +``` +1 TargetSoC percent 0 SOC, O.a+ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 657 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +2 AddedEn­ +ergy +``` +``` +energy- +mWh +``` +``` +min 0 0 [SOC], O.a+ +``` +**9.3.7.6.1. TargetTimeMinutesPastMidnight Field** + +This field SHALL indicate the desired charging completion time of the associated day. The time will +be represented by a 16 bits unsigned integer to designate the minutes since midnight. For example, +6am will be represented by 360 minutes since midnight and 11:30pm will be represented by 1410 +minutes since midnight. + +This field is based on local wall clock time. In case of Daylight Savings Time transition which may +result in an extra hour or one hour less in the day, the charging algorithm should take into account +the shift appropriately. + +Note that if the TargetTimeMinutesPastMidnight values are too close together (e.g. 2 per day) these +may overlap. The EVSE may have to coalesce the charging targets into a single target. e.g. if the 1st +charging target cannot be met in the time available, the EVSE may be forced to begin working +towards the 2nd charging target and immediately continue until both targets have been satisfied +(or the vehicle becomes full). + +The EVSE itself cannot predict the behavior of the vehicle (i.e. if it cannot obtain the SoC from the +vehicle), so should attempt to perform a sensible operation based on these targets. It is recom­ +mended that the charging schedule is pessimistic (i.e. starts earlier) since the vehicle may charge +more slowly than the electrical supply may provide power (especially if it is cold). + +If the user configures large charging targets (e.g. high values of AddedEnergy or SoC) then it is +expected that the EVSE may need to begin charging immediately, and may not be able to guarantee +that the vehicle will be able to reach the target. + +**9.3.7.6.2. TargetSoC Field** + +This field represents the target SoC that the vehicle should be charged to before the Target­ +TimeMinutesPastMidnight. + +If the EVSE supports the SOC feature and can obtain the SoC of the vehicle: + +- the TargetSoC field SHALL take precedence over the AddedEnergy field. +- the EVSE SHOULD charge to the TargetSoC and then stop the charging automatically when it + reaches that point. +- if the TargetSoC value is set to 100% then the EVSE SHOULD continue to charge the vehicle until + the vehicle decides to stop charging. + +If the EVSE does not support the SOC feature or cannot obtain the SoC of the vehicle: + +- the AddedEnergy field SHALL take precedence over the TargetSoC field, and if the EVSE does + not support the SOC feature then the TargetSoC field may only take the values null or 100%. +- if the AddedEnergy field has not been provided, the EVSE SHOULD assume the vehicle is empty + +``` +Page 658 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +and charge until the vehicle stops demanding a charge. +``` +**9.3.7.6.3. AddedEnergy Field** + +This field represents the amount of energy that the user would like to have added to the vehicle +before the TargetTimeMinutesPastMidnight. + +This represents a positive value in mWh that SHOULD be added during the session (i.e. if the vehi­ +cle charging is stopped and started several times, this equates to the total energy since the vehicle +has been plugged in). + +The maximum value (500kWh) is much larger than most EV batteries on the market today. If the +client tries to set this value too high then the EVSE will need to start charging immediately and con­ +tinue charging until the vehicle stops demanding charge (i.e. it is full). Therefore the maximum +value should be set based on typical battery size of the vehicles on the market (e.g. 70000Wh), how­ +ever this is up to the client to carefully choose a value. + +### NOTE + +``` +If the EVSE can obtain the Battery Capacity of the vehicle, it SHOULD NOT limit this +AddedEnergy value to the Battery Capacity of the vehicle, since the EV may also +require energy for heating and cooling of the battery during charging, or for heat­ +ing or cooling the cabin. +``` +**9.3.7.7. ChargingTargetScheduleStruct Type** + +This represents a set of user specified charging targets for an EV for a set of specified days. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Day­ +OfWeek­ +ForSe­ +quence +``` +``` +TargetDay­ +OfWeek­ +Bitmap +``` +``` +all M +``` +``` +1 Charging­ +Targets +``` +``` +list[Charg­ +ingTarget­ +Struct] +``` +``` +max 10 M +``` +**9.3.7.8. DayOfWeekForSequence Field** + +This field SHALL indicate the days of the week that the charging targets SHOULD be associated to. +This field is a bitmap and therefore the associated targets could be applied to multiple days. + +**9.3.7.9. ChargingTargets Field** + +This field SHALL indicate a list of up to 10 charging targets for each of the associated days of the +week. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 659 +``` + +**9.3.8. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 State StateEnum all X R V M +0x0001 Sup­ +plyState +``` +``` +SupplySta­ +teEnum +``` +``` +all R V M +``` +``` +0x0002 FaultState FaultSta­ +teEnum +``` +``` +all R V M +``` +``` +0x0003 Chargin­ +gEnable­ +dUntil +``` +``` +epoch-s all X N 0 R V M +``` +``` +0x0004 Dis­ +chargin­ +gEnable­ +dUntil +``` +``` +epoch-s all X N 0 R V V2X +``` +``` +0x0005 CircuitCa­ +pacity +``` +``` +amperage- +mA +``` +``` +min 0 N 0 R V M +``` +``` +0x0006 Minimum­ +Charge­ +Current +``` +``` +amperage- +mA +``` +``` +min 0 N 6000 R V M +``` +``` +0x0007 Maxi­ +mum­ +Charge­ +Current +``` +``` +amperage- +mA +``` +``` +min 0 N 0 R V M +``` +``` +0x0008 Maxi­ +mumDis­ +charge­ +Current +``` +``` +amperage- +mA +``` +``` +min 0 N 0 R V V2X +``` +``` +0x0009 UserMaxi­ +mum­ +Charge­ +Current +``` +``` +amperage- +mA +``` +``` +desc N 0 RW VM O +``` +``` +0x000A Random­ +izationDe­ +layWin­ +dow +``` +``` +elapsed-s max 86400 N 600 RW VM O +``` +``` +0x0023 NextCharg +eStart­ +Time +``` +``` +epoch-s all X null R V PREF +``` +``` +Page 660 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0024 NextChar­ +geTarget­ +Time +``` +``` +epoch-s all X null R V PREF +``` +``` +0x0025 NextCharg +­ +eRequired +Energy +``` +``` +energy- +mWh +``` +``` +min 0 X null R V PREF +``` +``` +0x0026 NextChar­ +geTarget­ +SoC +``` +``` +percent X null R V PREF +``` +``` +0x0027 Approxi­ +mateEVEf­ +ficiency +``` +``` +uint16 desc X N null RW VM [PREF] +``` +``` +0x0030 State­ +OfCharge +``` +``` +percent X null R V SOC +``` +``` +0x0031 BatteryCa­ +pacity +``` +``` +energy- +mWh +``` +``` +min 0 X null R V SOC +``` +``` +0x0032 VehicleID string max 32 X null R V PNC +0x0040 SessionID uint32 all X N null R V M +0x0041 Session­ +Duration +``` +``` +elapsed-s all X N Q null R V M +``` +``` +0x0042 SessionEn­ +ergy­ +Charged +``` +``` +energy- +mWh +``` +``` +min 0 X N Q null R V M +``` +``` +0x0043 SessionEn­ +ergyDis­ +charged +``` +``` +energy- +mWh +``` +``` +min 0 X N Q null R V V2X +``` +**9.3.8.1. State Attribute** + +This attribute SHALL indicate the current status of the EVSE. This higher-level status is partly +derived from the signaling protocol as communicated between the EVSE and the vehicle through +the pilot signal. + +The State attribute SHALL change when the EVSE detects change of condition of the EV (plugged in +or unplugged, whether the vehicle is asking for demand or not, and if it is charging or discharging). + +### NOTE + +``` +SessionEnding is not really a state but a transition. However, the transition period +may take a few seconds and is useful for some clean up purposes. +``` +The Fault state is used to indicate that the FaultState attribute is not NoError. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 661 +``` + +A null value SHALL indicate that the state cannot be determined. + +**9.3.8.2. SupplyState Attribute** + +This attribute SHALL indicate whether the EV is currently allowed to charge from or discharge to +the EVSE. + +**9.3.8.3. FaultState Attribute** + +This attribute SHALL indicate the type of fault detected by the EVSE (internally or as detected in the +pilot signal). + +When the SupplyState attribute is DisabledError, the FaultState attribute will be one of the values +listed in FaultStateEnum, except NoError. For all values of SupplyState other than DisabledError, +the FaultState attribute SHALL be NoError. + +**9.3.8.4. ChargingEnabledUntil Attribute** + +This attribute SHALL indicate the time, in UTC, that the EVSE will automatically stop current flow to +the EV. + +A null value indicates the EVSE is always enabled for charging. + +A value in the past or 0x0 indicates that EVSE charging SHALL be disabled. The attribute is only set +via the payload of the EnableCharging command. + +This attribute SHALL be persisted, for example a temporary power failure should not stop the vehi­ +cle from being charged. + +**9.3.8.5. DischargingEnabledUntil Attribute** + +This attribute SHALL indicate the time, in UTC, that the EVSE will automatically stop current flow +from the EV. + +A null value indicates the EVSE is always enabled for discharging. + +A value in the past or 0x0 indicates that EVSE discharging SHALL be disabled. The attribute is only +set via the payload of the EnableDischarging command. + +This attribute SHALL be persisted, for example a temporary power failure should not stop the vehi­ +cle from being discharged. + +**9.3.8.6. CircuitCapacity Attribute** + +This attribute SHALL indicate the capacity that the circuit that the EVSE is connected to can pro­ +vide. It is intended to allow implementation of a self-managed network of EVSEs. It is assumed that +the device will allow the setting of such values by an installer. + +**9.3.8.7. MinimumChargeCurrent Attribute** + +This attribute SHALL indicate the minimum current that can be delivered by the EVSE to the EV. + +``` +Page 662 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The attribute can be set using the EnableCharging command. + +**9.3.8.8. MaximumChargeCurrent Attribute** + +This attribute SHALL indicate the maximum current that can be delivered by the EVSE to the EV. + +This SHALL represent the actual maximum current offered to the EV at any time. Note that the EV +can draw less current than this value. For example, the EV may be limiting its power draw based on +the operating conditions of the battery, such as temperature and state of charge. + +The attribute can be initially set using the EnableCharging command or by adjusting the UserMaxi­ +mumChargeCurrent attribute. + +``` +This attribute value SHALL be the minimum of: +``` +- CircuitCapacity - Electrician’s installation setting +- CableAssemblyCurrentLimit (detected by the EVSE when the cable is plugged in) +- MaximumChargeCurrent field in the EnableCharging command +- UserMaximumChargeCurrent attribute + +**9.3.8.9. MaximumDischargeCurrent Attribute** + +This attribute SHALL indicate the maximum current that can be received by the EVSE from the EV. + +This attribute can be set using the EnableDischarging command. + +``` +This attribute value SHALL be the minimum of: +``` +- CircuitCapacity - Electrician’s installation setting +- CableAssemblyCurrentLimit (detected by the EVSE when the cable is plugged in) +- MaximumDischargeCurrent field in the EnableDischarging command + +**9.3.8.10. UserMaximumChargeCurrent Attribute** + +This attribute SHALL indicate a maximum current that can set by the consumer (e.g. via an app) as +a preference to further reduce the charging rate. This may be desirable if the home owner has a +solar PV or battery storage system which may only be able to deliver a limited amount of power. +The consumer can manually control how much they allow the EV to take. + +This attribute value SHALL be limited by the EVSE to be in the range of: + +``` +MinimumChargeCurrent <= UserMaximumChargeCurrent <= MaximumChargeCurrent +``` +where MinimumChargeCurrent and MaximumChargeCurrent are the values received in the +EnableCharging command. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 663 +``` + +Its default value SHOULD be initialized to the same as the CircuitCapacity attribute. This value +SHALL be persisted across reboots to ensure it does not cause charging issues during temporary +power failures. + +**9.3.8.11. RandomizationDelayWindow Attribute** + +This attribute SHALL indicate the size of a random window over which the EVSE will randomize +the start of a charging session. This value is in seconds. + +This is a feature that is mandated in some markets (such as UK) where the EVSE should by default +randomize its start time within the randomization window. By default in the UK this should be +600s. + +For example, if the RandomizationDelayWindow is 600s (i.e. 10 minutes) and if there was a cheap +rate energy starting at 00:30, then the EVSE must compute a random delay between 0-599s and add +this to its initial planned start time. + +**9.3.8.12. NextChargeStartTime Attribute** + +This attribute SHALL indicate the time, in UTC, when the EVSE plans to start the next scheduled +charge based on the charging preferences. + +A null value indicates that there is no scheduled charging (for example, the EVSE Mode is set to use +Manual mode tag), or that the vehicle is not plugged in with the SupplyState indicating that charg­ +ing is enabled. + +**9.3.8.13. NextChargeTargetTime Attribute** + +This attribute SHALL indicate the time, in UTC, when the EVSE SHOULD complete the next sched­ +uled charge based on the charging preferences. + +A null value indicates that there is no scheduled charging (for example, the EVSE Mode is set to use +Manual mode tag), or that the vehicle is not plugged in with the SupplyState indicating that charg­ +ing is enabled. + +**9.3.8.14. NextChargeRequiredEnergy Attribute** + +This attribute SHALL indicate the amount of energy that the EVSE is going to attempt to add to the +vehicle in the next charging target. + +A null value indicates that there is no scheduled charging (for example, the EVSE Mode is set to use +Manual mode tag), or that the vehicle is not plugged in with the SupplyState indicating that charg­ +ing is enabled, or that the next ChargingTargetStruct is using the TargetSoC value to charge the +vehicle. + +**9.3.8.15. NextChargeTargetSoC Attribute** + +This attribute SHALL indicate the target SoC the EVSE is going to attempt to reach when the vehicle +is next charged. + +A null value indicates that there is no scheduled charging (for example, the EVSE Mode is set to use + +``` +Page 664 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Manual mode tag), or that the vehicle is not plugged in with the SupplyState indicating that charg­ +ing is enabled, or that the next ChargingTargetStruct is using the AddedEnergy value to charge the +vehicle. + +If the SOC feature is not supported, only the values null and 100% are supported. + +**9.3.8.16. ApproximateEVEfficiency Attribute** + +This attribute SHALL indicate the vehicle efficiency rating for a connected vehicle. + +This can be used to help indicate to the user _approximately_ how many miles or km of range will be +added. It allows user interfaces to display to the user simpler terms that they can relate to com­ +pared to kWh. + +This is value is stored in km per kWh multiplied by a scaling factor of 1000. + +A null value indicates that the EV efficiency is unknown and the NextChargeRequiredEnergy +attribute cannot be converted from Wh to miles or km. + +``` +To convert from Wh into Range: +``` +``` +AddedRange (km) = AddedEnergy (Wh) x ApproxEVEfficiency (km/kWh x 1000) +AddedRange (Miles) = AddedEnergy (Wh) x ApproxEVEfficiency (km/kWh x 1000) x +0.6213 +``` +``` +Example: +``` +``` +ApproxEVEfficiency (km/kWh x 1000): 4800 (i.e. 4.8km/kWh x 1000) +AddedEnergy (Wh): 10,000 +``` +``` +AddedRange (km) = 10,000 x 4800 / 1,000,000 = 48 km +AddedRange (Miles) = AddedEnergy (Wh) x ApproxEVEfficiency (km/kWh x 1000) x +0.6213 += 29.82 Miles +``` +**9.3.8.17. StateOfCharge Attribute** + +This attribute SHALL indicate the state of charge of the EV battery in steps of 1%. The values are in +the 0-100%. This attribute is only available on EVSEs which can read the state of charge from the +vehicle and that support the SOC feature. If the StateOfCharge cannot be read from the vehicle it +SHALL be returned with a NULL value. + +**9.3.8.18. BatteryCapacity Attribute** + +This attribute SHALL indicate the capacity of the EV battery in mWh. This value is always positive. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 665 +``` + +**9.3.8.19. VehicleID Attribute** + +This attribute SHALL indicate the vehicle ID read by the EVSE via ISO-15118 using the PNC feature, if +the EVSE supports this capability. + +The field may be based on the e-Mobility Account Identifier (EMAID). + +A null value SHALL indicate that this is unknown. + +**9.3.8.20. Session Attributes** + +The following set of attributes provides information about a charging session, defined as the period +from the EVSE detecting an EV plug-in to when it is unplugged. + +### NOTE + +``` +the session attributes hold their values from the previous session and are reset +when the next plug-in event happens. +``` +Whenever the State leaves the NotPluggedIn state and moves to any ‘Plugged’ state (see the State +attribute), the SessionID attribute SHALL be incremented. The SessionDuration, SessionEnergy­ +Charged and SessionEnergyDischarged attributes SHALL be reset to zero. + +**9.3.8.20.1. SessionID Attribute** + +This attribute SHALL indicate a unique identifier for the current or last session. A value of null indi­ +cates no sessions have occurred. The SessionID SHALL be incremented each time a plugin is +detected. A session begins when the vehicle is plugged in and ends when the vehicle is unplugged. + +SessionIDs are allowed to roll over, although the range of SessionID is a large number and it is +unlikely that the EVSE will have this many sessions in its lifetime unless there is a electrical fault +causes sessions to be detected at a rapid rate. + +If there is no session in progress, the Session ID attribute will remain at the value for the last ses­ +sion. + +**9.3.8.20.2. SessionDuration Attribute** + +This attribute SHALL indicate the duration in seconds for the current or last charging session. A +default value of null indicates no sessions have occurred. A charge session begins when the vehicle +is plugged in and ends when the vehicle is unplugged. + +The SessionDuration can be calculated from the start time of the session. Manufacturers SHALL +ensure this can be correctly calculated if there has been an power failure or reboot since the start +of the session. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once every 10 seconds on changes, or +- When it changes from null to any other value and vice versa, such as at the beginning and end + of a charging session. + +``` +Page 666 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.3.8.20.3. SessionEnergyCharged Attribute** + +This attribute SHALL indicate the energy, in mWh, delivered by the EVSE to the EV for the current +or last charging session. A default value of null indicates no sessions have occurred. + +The SessionEnergyCharged value can be calculated by knowing the initial value of the energy meter +at the start time of the session. Manufacturers SHALL ensure this can be correctly calculated if +there has been an power failure or reboot since the start of the session. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once every 10 seconds on changes, or +- When it changes from null to any other value and vice versa, such as at the beginning and end + of a charging session. + +**9.3.8.20.4. SessionEnergyDischarged Attribute** + +This attribute SHALL indicate the energy, in mWh, received by the EVSE from the EV for the current +or last charging session. A default value of null indicates no sessions have occurred. + +The SessionEnergyDischarged value can be calculated by knowing the initial value of the energy +meter at the start time of the session. Manufacturers SHALL ensure this can be correctly calculated +if there has been an power failure or reboot since the start of the session. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once every 10 seconds on changes, or +- When it changes from null to any other value and vice versa, such as at the beginning and end + of a charging session. + +**9.3.9. Commands** + +``` +ID Name Direction Response Access Conformance +0x01 Disable client ⇒ server Y O T M +0x02 EnableCharg­ +ing +``` +``` +client ⇒ server Y O T M +``` +``` +0x03 EnableDis­ +charging +``` +``` +client ⇒ server Y O T V2X +``` +``` +0x04 StartDiagnos­ +tics +``` +``` +client ⇒ server Y O T O +``` +``` +0x05 SetTargets client ⇒ server Y O T PREF +0x06 GetTargets client ⇒ server GetTargetsRe­ +sponse +``` +### O T PREF + +``` +0x07 ClearTargets client ⇒ server Y O T PREF +0x00 GetTargetsRe­ +sponse +``` +``` +client ⇐ server N PREF +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 667 +``` + +**9.3.9.1. Disable Command** + +Allows a client to disable the EVSE from charging and discharging. + +**9.3.9.1.1. Effect on Receipt** + +On receipt of this command, the EVSE will stop any power flow between the EV and EVSE. + +If the command cannot be handled, a status of FAILURE SHALL be returned. + +If the SupplyState attribute is already Disabled, a response with status of SUCCESS SHALL be +returned. + +Otherwise, if successful, the ChargingEnabledUntil and DischargingEnabledUntil attributes SHALL +be set to 0x0, the SupplyState attribute changed to Disabled, and a response with status of SUCCESS +SHALL be returned. + +If any energy was being transferred, then a corresponding EnergyTransferStopped event SHALL be +generated. + +**9.3.9.2. EnableCharging Command** + +This command allows a client to enable the EVSE to charge an EV, and to provide or update the +maximum and minimum charge current. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ChargingEn­ +abledUntil +``` +``` +epoch-s all X null M +``` +``` +1 Minimum­ +ChargeCur­ +rent +``` +``` +amperage- +mA +``` +``` +min 0 M +``` +``` +2 Maximum­ +ChargeCur­ +rent +``` +``` +amperage- +mA +``` +``` +min 0 M +``` +**9.3.9.2.1. ChargingEnabledUntil Field** + +This field SHALL indicate the expiry time, in UTC, when charging will be automatically disabled. + +A value in the past in this field SHALL disable the EVSE charging whereas a null value SHALL +enable it permanently. + +**9.3.9.2.2. MinimumChargeCurrent Field** + +This field SHALL indicate the minimum current that can be delivered by the EVSE to the EV in +trickle mode. The EVSE current limit can be advertised to an EV in 0.6A steps. + +The value of the MinimumChargeCurrent attribute SHALL be set to the value of this field (see Mini­ +mumChargeCurrent attribute for further details). + +``` +Page 668 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.3.9.2.3. MaximumChargeCurrent Field** + +This field SHALL indicate the maximum current that can be delivered by the EVSE to the EV. The +EVSE current limit can be advertised to an EV in 0.6A steps. + +The value of the this field SHALL be stored by the EVSE to determine the value of MaximumCharge­ +Current attribute. For example, if the UserMaximumChargeCurrent attribute is adjusted below then +this value, and then later adjusted above this value, the resulting MaximumChargeCurrent attribute +will be limited to this value. + +**9.3.9.2.4. Effect on Receipt** + +On receipt of this command, this SHALL allow the EVSE to charge the EV until the specified time­ +stamp within the current limits specified in the fields of the command. + +If there is currently an error present on the EVSE, or Diagnostics are currently active, then the com­ +mand SHALL be ignored and a response with a status of FAILURE SHALL be returned. + +If successful, the SupplyState attribute SHALL be set to ChargingEnabled (if previously Disabled) or +Enabled (if previously DischargingEnabled), and a response with status of SUCCESS SHALL be +returned. + +The timestamp indicated in the ChargingEnabledUntil attribute SHALL be updated to the time­ +stamp of the ChargingEnabledUntil field if the command is successful. + +If the ChargingEnabledUntil is null (i.e. should be permanently enabled), then the EVSE should +enable charging indefinitely. + +If the ChargingEnabledUntil time is not null, then when this time expires then the EVSE SHALL stop +charging and SHALL update the State attribute to indicate it is no longer charging, and SHALL +update the SupplyState attribute to Disabled (if DischargingEnabledUntil is also in the past) or Dis­ +chargingEnabled (if DischargingEnabledUntil is in the future or null). + +**9.3.9.3. EnableDischarging Command** + +Upon receipt, this SHALL allow a client to enable the discharge of an EV, and to provide or update +the maximum discharge current. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Dischargin­ +gEnable­ +dUntil +``` +``` +epoch-s all X null M +``` +``` +1 Maxi­ +mumDis­ +chargeCur­ +rent +``` +``` +amperage- +mA +``` +``` +min 0 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 669 +``` + +**9.3.9.3.1. DischargingEnabledUntil Field** + +This field SHALL indicate the expiry time, in UTC, when discharging will be automatically disabled. + +A value in the past in this field SHALL disable the EVSE discharging whereas a null value SHALL +enable EVSE discharging permanently. + +**9.3.9.3.2. MaximumDischargeCurrent Field** + +This field SHALL indicate the maximum current that can be received by the EVSE from the EV. The +EVSE current limit can be advertised to an EV in 0.6A steps. The value of the MaximumDischarge­ +Current attribute SHALL be stored and persisted across reboots by the EVSE to the value of this +field. + +**9.3.9.3.3. Effect on Receipt** + +On receipt of this command, this SHALL allow the EVSE to discharge the EV until the specified time­ +stamp, and allows a maximum current limit to be specified in the fields of the command. + +If there is currently an error present on the EVSE, or Diagnostics are currently active, then the com­ +mand SHALL be ignored and a response with a status of FAILURE SHALL be returned. + +If successful, the SupplyState attribute SHALL be set to DischargingEnabled (if previously Disabled) +or Enabled (if previously ChargingEnabled), and a response with status of SUCCESS SHALL be +returned. + +The timestamp indicated in the DischargingEnabledUntil attribute SHALL be updated to the time­ +stamp of the DischargingEnabledUntil field if the command is successful. + +If the DischargingEnabledUntil is null (i.e. should be permanently enabled), then the EVSE should +enable discharging indefinitely. + +If the DischargingEnabledUntil time is not null, then when this time expires then the EVSE SHALL +stop discharging and SHALL update the State attribute to indicate it is no longer discharging, and +SHALL update the SupplyState attribute to Disabled (if ChargingEnabledUntil is also in the past) or +ChargingEnabled (if ChargingEnabledUntil is in the future or null). + +**9.3.9.4. StartDiagnostics Command** + +Allows a client to put the EVSE into a self-diagnostics mode. + +**9.3.9.4.1. Effect on Receipt** + +On receipt of this command, the EVSE SHALL enter a Diagnostics state only if the SupplyState +attribute is in the Disabled state. + +If the EVSE cannot start diagnostics, a response SHALL be generated with a status of FAILURE. + +If successful, the SupplyState attribute SHALL be set to DisabledDiagnostics, and a response with +status of SUCCESS SHALL be returned. + +The diagnostics are at the discretion of the manufacturer and usually include internal checks. Upon + +``` +Page 670 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +completion of the diagnostics, the EVSE SHALL restore SupplyState to the Disabled state (see Sup­ +plyState attribute for further details). + +**9.3.9.5. SetTargets Command** + +Allows a client to set the user specified charging targets. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ChargingTar­ +getSchedules +``` +``` +list[Charg­ +ingTar­ +getSched­ +uleStruct] +``` +``` +max 7 M +``` +**9.3.9.5.1. ChargingTargetSchedules Field** + +This field SHALL indicate a list of up to 7 sets of daily charging targets together with their associ­ +ated days of the week. Each of the days of the week may only be included in a single ChargingTar­ +getSchedule within this list field. + +**9.3.9.5.2. Effect on Receipt** + +On receipt of this command, the EVSE SHALL validate that all of the charging targets are within a +valid range, and that each day of the week is included in at most one of the ChargingTargetSched­ +ule, if they are not then the response SHALL be CONSTRAINT_ERROR. + +When a command is received that requires a total number of charging targets greater than the +device supports, the status of the response SHALL be RESOURCE_EXHAUSTED. + +If the charging targets are accepted, then the charging targets SHALL be stored for all of days that +are set in the DayOfWeekForSequence bitmap fields in all the ChargingTargetSchedules. If a Charg­ +ingTargetSchedule is defined with no ChargingTargets then the ChargingTargets are cleared for +those days defined in the DayOfWeekForSequence + +The SetTargets command is used to update the EVSE’s weekly charging schedule. If the EVSE +already has some stored weekly charging targets, then it SHALL replace each daily charging target +as it receives the updates from the client. For example, if the EVSE has 2 charging targets for every +day of the week and is sent a SetTargets command with one target for Saturday then the EVSE +SHALL remove both charging targets for Saturday and replace those with the updated charging tar­ +get but leave all other days unchanged. + +### NOTE + +``` +the EVSE may not be able to compute the schedules by itself, or may rely upon an +EMS or other optimizer to do this. +``` +In a standalone mode (e.g. without using a ToU tariff from the Pricing Cluster) the EVSE should be +able to compute the latest NextChargeStartTime based on the preset MaximumChargeCurrent +attribute and local grid voltage to determine the charging duration required. It should automati­ +cally begin charging and following the charging schedule if the EVSE is plugged in (and the EVSE is +enabled for charging). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 671 +``` + +If the EVSE supports the PFR (PowerForecastReporting) feature in the Device Energy Management +cluster, it SHALL auto update the Forecast with the indicative power forecast. + +If the EVSE supports the FA (ForecastAdjustment) feature in the Device Energy Management cluster, +it SHALL indicate its adjustment capability in each of the Forecast slots (see Device Energy Manage­ +ment Cluster for more details). + +The EVSE SHALL be responsible for updating the NextChargeEndTime, NextChargeRequiredEnergy +and/or NextChargeTargetSoC attributes as it runs through its internal schedule. For example, as a +scheduled charging session is completed or as it transitions to the next day, it should compute the +next time it expects to start charging, and then update the corresponding attributes accordingly. + +**9.3.9.6. GetTargets Command** + +Allows a client to retrieve the current set of charging targets. + +**9.3.9.6.1. Effect on Receipt** + +On receipt of this command, the EVSE SHALL send the GetTargetsResponse command to the client. + +**9.3.9.7. GetTargetsResponse Command** + +The GetTargetsResponse is sent in response to the GetTargets Command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ChargingTar­ +getSchedules +``` +``` +list[Charg­ +ingTar­ +getSched­ +uleStruct] +``` +``` +max 7 M +``` +**9.3.9.7.1. ChargingTargetSchedules Field** + +This field SHALL indicate a list of up to 7 sets of daily charging targets together with their associ­ +ated days of the week. + +**9.3.9.8. ClearTargets Command** + +Allows a client to clear all stored charging targets. + +**9.3.9.8.1. Effect on Receipt** + +On receipt of this command, all weekly targets that are currently stored SHALL be cleared and a +default response of SUCCESS SHALL be sent in response. There are no error responses to this com­ +mand. + +If the EVSE is currently charging based on being in automatic mode, then it SHALL stop the EVSE +charging. + +``` +Page 672 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.3.10. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 EVConnected INFO V M +0x01 EVNotDe­ +tected +``` +### INFO V M + +``` +0x02 EnergyTrans­ +ferStarted +``` +### INFO V M + +``` +0x03 EnergyTrans­ +ferStopped +``` +### INFO V M + +``` +0x04 Fault CRITICAL V M +0x05 RFID INFO V [RFID] +``` +**9.3.10.1. EVConnected Event** + +This event SHALL be generated when the EV is plugged in. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SessionID uint32 all M +``` +**9.3.10.1.1. SessionID Field** + +This is the new session ID created after the vehicle is plugged in. + +**9.3.10.2. EVNotDetected Event** + +This event SHALL be generated when the EV is unplugged or not detected (having been previously +plugged in). When the vehicle is unplugged then the session is ended. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SessionID uint32 all M +1 State StateEnum all M +2 Session­ +Duration +``` +``` +elapsed-s all M +``` +``` +3 SessionEn­ +ergy­ +Charged +``` +``` +energy-mWh min 0 M +``` +``` +4 SessionEn­ +ergyDis­ +charged +``` +``` +energy-mWh min 0 V2X +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 673 +``` + +**9.3.10.2.1. SessionID Field** + +This field SHALL indicate the current value of the SessionID attribute. + +**9.3.10.2.2. State Field** + +This field SHALL indicate the value of the State attribute prior to the EV not being detected. + +**9.3.10.2.3. SessionDuration Field** + +This field SHALL indicate the total duration of the session, from the start of the session when the EV +was plugged in, until it was unplugged. + +**9.3.10.2.4. SessionEnergyCharged Field** + +This field SHALL indicate the total amount of energy transferred from the EVSE to the EV during +the session. + +Note that if bi-directional charging occurs during the session, then this value SHALL only include +the sum of energy transferred from the EVSE to the EV, and SHALL NOT be a net value of charging +and discharging energy. + +**9.3.10.2.5. SessionEnergyDischarged Field** + +This field SHALL indicate the total amount of energy transferred from the EV to the EVSE during +the session. + +Note that if bi-directional discharging occurs during the session, then this value SHALL only include +the sum of energy transferred from the EV to the EVSE, and SHALL NOT be a net value of charging +and discharging energy. + +**9.3.10.3. EnergyTransferStarted Event** + +This event SHALL be generated whenever the EV starts charging or discharging, except when an EV +has switched between charging and discharging under the control of the PowerAdjustment feature +of the Device Energy Management cluster of the associated Device Energy Management device. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SessionID uint32 all M +1 State StateEnum all M +2 Maximum­ +Current +``` +``` +amperage- +mA +``` +``` +min 0 M +``` +``` +3 Maxi­ +mumDis­ +chargeCur­ +rent +``` +``` +amperage- +mA +``` +``` +min 0 V2X +``` +``` +Page 674 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.3.10.3.1. SessionID Field** + +This field SHALL indicate the value of the SessionID attribute at the time the event was generated. + +**9.3.10.3.2. State Field** + +This field SHALL indicate the value of the State attribute at the time the event was generated. + +**9.3.10.3.3. MaximumCurrent Field** + +This field SHALL indicate the value of the maximum charging current at the time the event was +generated. + +A non-zero value indicates that the EV has been enabled for charging and the value is taken directly +from the MaximumChargeCurrent attribute. A zero value indicates that the EV has not been +enabled for charging. + +**9.3.10.3.4. MaximumDischargeCurrent Field** + +This field SHALL indicate the value of the maximum discharging current at the time the event was +generated. + +A non-zero value indicates that the EV has been enabled for discharging and the value is taken +directly from the MaximumDischargeCurrent attribute. A zero value indicates that the EV has not +been enabled for discharging. + +**9.3.10.4. EnergyTransferStopped Event** + +This event SHALL be generated whenever the EV stops charging or discharging, except when an EV +has switched between charging and discharging under the control of the PowerAdjustment feature +of the Device Energy Management cluster of the associated Device Energy Management device. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SessionID uint32 all M +1 State StateEnum all M +2 Reason Energy­ +Transfer­ +StoppedRea­ +sonEnum +``` +``` +all M +``` +``` +4 Energy­ +Transferred +``` +``` +energy-mWh min 0 M +``` +``` +5 EnergyDis­ +charged +``` +``` +energy-mWh min 0 V2X +``` +**9.3.10.4.1. SessionID Field** + +This field SHALL indicate the value of the SessionID attribute prior to the energy transfer stopping. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 675 +``` + +**9.3.10.4.2. State Field** + +This field SHALL indicate the value of the State attribute prior to the energy transfer stopping. + +**9.3.10.4.3. Reason Field** + +This field SHALL indicate the reason why the energy transferred stopped. + +**9.3.10.4.4. EnergyTransferred Field** + +This field SHALL indicate the amount of energy transferred from the EVSE to the EV since the previ­ +ous EnergyTransferStarted event, in mWh. + +**9.3.10.4.5. EnergyDischarged Field** + +This field SHALL indicate the amount of energy transferred from the EV to the EVSE since the previ­ +ous EnergyTransferStarted event, in mWh. + +**9.3.10.5. Fault Event** + +If the EVSE detects a fault it SHALL generate a Fault Event. The SupplyState attribute SHALL be set +to DisabledError and the type of fault detected by the EVSE SHALL be stored in the FaultState +attribute. + +This event SHALL be generated when the FaultState changes from any error state. i.e. if it changes +from NoError to any other state and if the error then clears, this would generate 2 events. + +It is assumed that the fault will be cleared locally on the EVSE device. When all faults have been +cleared, the EVSE device SHALL set the FaultState attribute to NoError and the SupplyState +attribute SHALL be set back to its previous state. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SessionID uint32 all X M +1 State StateEnum all M +2 Fault­ +StatePrevi­ +ousState +``` +``` +FaultSta­ +teEnum +``` +``` +all M +``` +``` +4 FaultState­ +Cur­ +rentState +``` +``` +FaultSta­ +teEnum +``` +``` +all M +``` +**9.3.10.5.1. SessionID Field** + +This field SHALL indicate the value of the SessionID attribute prior to the Fault State being changed. +A value of null indicates no sessions have occurred before the fault occurred. + +``` +Page 676 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.3.10.5.2. State Field** + +This field SHALL indicate the value of the State attribute prior to the Fault State being changed. + +**9.3.10.5.3. FaultStatePreviousState Field** + +This field SHALL indicate the value of the FaultState attribute prior to the Fault State being +changed. + +**9.3.10.5.4. FaultStateCurrentState Field** + +This field SHALL indicate the current value of the FaultState attribute. + +**9.3.10.6. RFID Event** + +This event SHALL be generated when a RFID card has been read. This allows a controller to register +the card ID and use this to authenticate and start the charging session. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UID octstr max 10 M +``` +**9.3.10.6.1. UID Field** + +The UID field (ISO 14443A UID) is either 4, 7 or 10 bytes. + +**9.4. Energy EVSE Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for EVSE devices. + +**9.4.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Disallowed DEPONOFF feature and OnMode and +StartUpMode attributes +``` +**9.4.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint EEVSEM +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 677 +``` + +**9.4.3. Cluster ID** + +``` +ID Name +0x009D Energy EVSE Mode +``` +**9.4.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**9.4.5. Data Types** + +**9.4.5.1. ModeOptionStruct Type** + +The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOption­ +Struct type. A blank field indicates no change. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label M +1 Mode M +2 ModeTags 1 to 8 M +``` +**9.4.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +0x0001 Current­ +Mode +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +**9.4.6.1. SupportedModes Attribute** + +At least one entry in the SupportedModes attribute SHALL include the Manual mode tag in the +ModeTags field list. + +Modes with entries in the SupportedModes attribute which contain multiple mode tags permitting + +``` +Page 678 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +charging or discharging under different conditions SHALL permit the charging or discharging to +occur if any of the conditions are satisfied. + +Modes SHALL NOT have both the Manual tag and the TimeOfUse or SolarCharging tags defined in +the SupportedModes attribute. + +**9.4.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**9.4.7.1. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +0x4000 Manual +0x4001 TimeOfUse +0x4002 SolarCharging +0x4003 V2X +``` +**9.4.7.1.1. Manual Tag** + +While in modes with this tag, and once enabled with the EnableCharging command, the EVSE will +permit charging based on demand from the EV. + +**9.4.7.1.2. TimeOfUse Tag** + +While in modes with this tag, and once enabled with the EnableCharging command, the EVSE will +attempt to automatically start charging based on the user’s charging targets (for example, set based +on a Time of Use tariff to charge at the cheapest times of the day). + +**9.4.7.1.3. SolarCharging Tag** + +While in modes with this tag, and once enabled with the EnableCharging, the EVSE will attempt to + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 679 +``` + +automatically start charging based on available excess solar PV generation, limiting the charging +power to avoid importing energy from the grid. + +**9.4.7.1.4. V2X Tag** + +While in modes with this tag, and once enabled with the EnableDischarging command, the EVSE +will permit discharging based on the current charge state of the EV, and its control from an associ­ +ated Device Energy Management cluster. + +### NOTE + +``` +being in a mode with this tag set or not does not affect the handling of the +EnableDischarging command by the Energy EVSE cluster, but once enabled, only +modes with this tag enable the discharging to actually occur. +``` +**9.4.8. Mode Examples** + +A few examples of EVSE modes and their mode tags are provided below. + +- For the "Manual" mode, tags: 0x4000 (Manual) +- For the "Auto-scheduled" mode, tags: 0x4001 (TimeOfUse) +- For the "Solar" mode, tags: 0x4002 (SolarCharging) +- For the "Auto-scheduled with Solar charging" mode, tags: 0x4001 (TimeOfUse), 0x4002 (Solar­ + Charging) +- For the "Vehicle-to-home with Solar charging" mode, tags: 0x4002 (SolarCharging), 0x4003 (V2X) + +**9.5. Water Heater Management Cluster** + +This cluster is used to allow clients to control the operation of a hot water heating appliance so that +it can be used with energy management. + +Heating of hot water is one of the main energy uses in homes, and when coupled with the Energy +Management cluster, it can help consumers save cost (e.g. using power at cheaper times or from +local solar PV generation). + +**9.5.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Added events and simplified data types +``` +**9.5.2. Classification** + +``` +Page 680 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint EWATERHTR +``` +**9.5.3. Cluster ID** + +``` +ID Name +0x0094 Water Heater Management +``` +**9.5.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 EM EnergyManage­ +ment +``` +``` +O Allows energy +management con­ +trol of the tank +1 TP TankPercent O Supports monitor­ +ing the percentage +of hot water in the +tank +``` +**9.5.5. Dependencies** + +This cluster SHALL be on an endpoint that also includes the Thermostat cluster as this cluster is +dependent on the Thermostat cluster. + +**9.5.6. Data Types** + +**9.5.6.1. WaterHeaterHeatSourceBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 ImmersionElement1 Immersion Heating Ele­ +ment 1 +``` +### M + +``` +1 ImmersionElement2 Immersion Heating Ele­ +ment 2 +``` +### M + +``` +2 HeatPump Heat pump Heating M +3 Boiler Boiler Heating (e.g. Gas +or Oil) +``` +### M + +``` +4 Other Other Heating M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 681 +``` + +**9.5.6.2. BoostStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Inactive Boost is not currently +active +``` +### M + +``` +1 Active Boost is currently +active +``` +### M + +**9.5.6.3. WaterHeaterBoostInfoStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Duration elapsed-s min 1 M +1 OneShot bool all False [!TP], +[TP].a- +2 Emergen­ +cyBoost +``` +``` +bool all False O +``` +``` +3 Tempo­ +rarySet­ +point +``` +``` +tempera­ +ture +``` +``` +desc O +``` +``` +4 TargetPer­ +centage +``` +``` +percent all TargetRe­ +heat, [TP] +5 TargetRe­ +heat +``` +``` +percent max Tar­ +getPercent­ +age +``` +``` +[TP].a- +``` +**9.5.6.3.1. Duration Field** + +This field SHALL indicate the time period, in seconds, for which the boost state is activated. + +**9.5.6.3.2. OneShot Field** + +This field SHALL indicate whether the boost state SHALL be automatically canceled once the hot +water has reached either: + +- the set point temperature (from the thermostat cluster) +- the TemporarySetpoint temperature (if specified) +- the TargetPercentage (if specified). + +**9.5.6.3.3. EmergencyBoost Field** + +This field SHALL indicate that the consumer wants the water to be heated quickly. This MAY cause +multiple heat sources to be activated (e.g. a heat pump and direct electric immersion heating ele­ +ment). + +``` +Page 682 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The choice of which heat sources are activated is manufacturer specific. + +**9.5.6.3.4. TemporarySetpoint Field** + +This field SHALL indicate the target temperature to which the water will be heated. + +If included, it SHALL be used instead of the thermostat cluster set point temperature whilst the +boost state is activated. + +The value of this field SHALL be within the constraints of the MinHeatSetpointLimit and MaxHeat­ +SetpointLimit attributes (inclusive), of the thermostat cluster. + +**9.5.6.3.5. TargetPercentage Field** + +This field SHALL indicate the target percentage of hot water in the tank that the TankPercentage +attribute must reach before the heating is switched off. + +**9.5.6.3.6. TargetReheat Field** + +This field SHALL indicate the percentage to which the hot water in the tank SHALL be allowed to +fall before again beginning to reheat it. + +For example if the TargetPercentage was 80%, and the TargetReheat was 40%, then after initial +heating to 80% hot water, the tank may have hot water drawn off until only 40% hot water remains. +At this point the heater will begin to heat back up to 80% of hot water. If this field and the OneShot +field were both omitted, heating would begin again after any water draw which reduced the +TankPercentage below 80%. + +This field SHALL be less than or equal to the TargetPercentage field. + +**9.5.7. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Heater­ +Types +``` +``` +Water­ +Heater­ +Heat­ +SourceBit +map +``` +``` +all F 0 R V M +``` +``` +0x0001 HeatDe­ +mand +``` +``` +Water­ +Heater­ +Heat­ +SourceBit +map +``` +``` +all 0 R V M +``` +``` +0x0002 TankVol­ +ume +``` +``` +uint16 all 0 R V EM +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 683 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0003 Estimated­ +HeatRe­ +quired +``` +``` +energy- +mWh +``` +``` +min 0 0 R V EM +``` +``` +0x0004 TankPer­ +centage +``` +``` +percent all 0 R V TP +``` +``` +0x0005 BoostState BoostSta­ +teEnum +``` +``` +all Inactive R V M +``` +**9.5.7.1. HeaterTypes Attribute** + +This attribute SHALL indicate the heat sources that the water heater can call on for heating. If a bit +is set then the water heater supports the corresponding heat source. + +**9.5.7.2. HeatDemand Attribute** + +This attribute SHALL indicate if the water heater is heating water. If a bit is set then the corre­ +sponding heat source is active. + +**9.5.7.3. TankVolume Attribute** + +This attribute SHALL indicate the volume of water that the hot water tank can hold (in units of +Litres). This allows an energy management system to estimate the required heating energy needed +to reach the target temperature. + +**9.5.7.4. EstimatedHeatRequired Attribute** + +This attribute SHALL indicate the estimated heat energy needed to raise the water temperature to +the target setpoint. This can be computed by taking the specific heat capacity of water (4182 J/kg °C) +and by knowing the current temperature of the water, the tank volume and target temperature. + +``` +For example, if the target temperature was 60°C, the current temperature was 20°C and the +tank volume was 100L: +``` +``` +Mass of water = 1kg per Litre +Total Mass = 100 x 1kg = 100kg +Δ Temperature = (target temperature - current temperature) += (60°C - 20°C) = 40°C +``` +``` +Energy required to +heat the water to 60°C = 4182 x 40 x 100 = 16,728,000 J +``` +``` +Converting Joules in to Wh of heat (divide by 3600): +``` +``` +Page 684 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### = 16,728,000 J / 3600 + +``` += 4647 Wh (4.65kWh) +``` +If the TankPercent feature is supported, then this estimate SHALL also take into account the per­ +centage of the water in the tank which is already hot. + +### NOTE + +``` +The electrical energy required to heat the water depends on the heating system +used to heat the water. For example, a direct electric immersion heating element +can be close to 100% efficient, so the electrical energy needed to heat the hot water +is nearly the same as the EstimatedHeatEnergyRequired. However some forms of +heating, such as an air-source heat pump which extracts heat from ambient air, +requires much less electrical energy to heat hot water. Heat pumps can be produce +3kWh of heat output for 1kWh of electrical energy input. The conversion between +heat energy and electrical energy is outside the scope of this cluster. +``` +**9.5.7.5. TankPercentage Attribute** + +This attribute SHALL indicate an approximate level of hot water stored in the tank, which might +help consumers understand the amount of hot water remaining in the tank. The accuracy of this +attribute is manufacturer specific. + +In most hot water tanks, there is a stratification effect where the hot water layer rests above a +cooler layer of water below. For this reason cold water is fed in at the bottom of the tank and the +hot water is drawn from the top. + +Some water tanks might use multiple temperature probes to estimate the level of the hot water +layer. A water heater with multiple temperature probes is likely to implement an algorithm to esti­ +mate the hot water tank percentage by taking into account the temperature values of each probe to +determine the height of the hot water. + +However it might be possible with a single temperature probe to estimate how much hot water is +left using a simpler algorithm: + +``` +For example, if the target temperature was 60°C, the CurrentTemperature was 40°C from a +single temperature probe measuring the average water temperature and the temperature of +incoming cold water (COLD_WATER_TEMP) was assumed to be 20°C: +``` +``` +TankPercentage = int(((current temperature - COLD_WATER_TEMP) / (target +temperature - COLD_WATER_TEMP)) * 100) +TankPercentage = min( max(TankPercentage,0), 100) +``` +``` +TankPercentage = 50% +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 685 +``` + +**9.5.7.6. BoostState Attribute** + +This attribute SHALL indicate whether the Boost, as triggered by a Boost command, is currently +Active or Inactive. + +See Boost and CancelBoost commands for more details. + +**9.5.8. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Boost client ⇒ server Y M M +0x01 CancelBoost client ⇒ server Y M M +``` +**9.5.8.1. Boost Command** + +Allows a client to request that the water heater is put into a Boost state. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 BoostInfo Water­ +HeaterBoost­ +InfoStruct +``` +``` +all M +``` +**9.5.8.1.1. Effect on receipt** + +On receipt of this command, this SHALL allow the water heater to attempt to heat the water, which +may override other settings, for example, if the Water Heater Mode is set to Off, or Timed and it is +during one of the Off periods. + +If the duration field is too short for the water heater to accept, for example a heat pump may take +several minutes to ramp up in operation, then the boost command SHALL be rejected with a status +of INVALID_IN_STATE. + +If successful, the value of the BoostState attribute SHALL transition to Active, and a response with +status of SUCCESS SHALL be returned, and a BoostStarted event SHALL be generated to include the +field values received in the command. + +The water in the tank SHALL be heated until one of the following conditions is met: + +- the temperature reaches the set point in the corresponding thermostat cluster or the Tempo­ + rarySetpoint (if included) +- the TankPercentage attribute value reaches the TargetPercentage (if it was included) + +If OneShot is specified then once the hot water has reached the set point temperature (or the Tem­ +porarySetpoint temperature, if specified) or the TargetPercentage (if specified), or the boost com­ +mand’s duration times out after the specified Duration, then BoostState transitions to Inactive. This +SHALL cause the BoostEnded event to be generated. + +If the Water Heater was already in the BoostState 'Active' when this command is received, it SHALL + +``` +Page 686 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +continue in this BoostState, but SHALL discard the effect of the values of the fields from the previ­ +ous Boost commands, and SHALL continue with the values of the fields from the new Boost com­ +mand. A new BoostStarted event SHALL be generated to include the field values received in the +new command. + +**9.5.8.2. CancelBoost Command** + +Allows a client to cancel an ongoing Boost operation. + +This command has no payload. + +**9.5.8.2.1. Effect on receipt** + +If the BoostState attribute value was already Inactive when this command is received, the Boost­ +State attribute value shall remain Inactive and the server SHALL return SUCCESS. + +Otherwise the Water Heater SHALL transition the BoostState to Inactive, generate a BoostEnded +event, and the water heating reverts to being controlled through the current Water Heater Mode +(e.g. Off, Manual or Timed). + +**9.5.9. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 BoostStarted INFO V M +0x01 BoostEnded INFO V M +``` +**9.5.9.1. BoostStarted Event** + +This event SHALL be generated whenever a Boost command is accepted. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 BoostInfo Water­ +HeaterBoost­ +InfoStruct +``` +``` +all M +``` +The corresponding structure fields within the WaterHeaterBoostInfoStruct are copied from the +Boost command. + +**9.5.9.2. BoostEnded Event** + +This event SHALL be generated whenever the BoostState transitions from Active to Inactive. + +**9.6. Water Heater Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for water heater devices. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 687 +``` + +**9.6.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**9.6.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint WHM +``` +**9.6.3. Cluster ID** + +``` +ID Name +0x009E Water Heater Mode +``` +**9.6.4. Features** + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**9.6.5. Data Types** + +**9.6.5.1. ModeOptionStruct Type** + +The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOption­ +Struct type. A blank field indicates no change. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label M +1 Mode M +2 ModeTags 1 to 8 M +``` +**9.6.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +``` +``` +Page 688 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0001 Current­ +Mode +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +**9.6.6.1. SupportedModes Attribute** + +At least one entry in the SupportedModes attribute SHALL include the Manual mode tag in the +ModeTags field list. + +At least one entry in the SupportedModes attribute SHALL include the Off mode tag in the Mode­ +Tags field list. + +An entry in the SupportedModes attribute that includes one of an Off, Manual, or Timed tag SHALL +NOT also include an additional instance of any one of these tag types. + +**9.6.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**9.6.7.1. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +0x4000 Off +0x4001 Manual +0x4002 Timed +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 689 +``` + +**9.6.7.1.1. Off Tag** + +While in modes with this tag, the device will not attempt to keep the water warm. + +**9.6.7.1.2. Manual Tag** + +While in modes with this tag, the device will attempt to keep the water warm based on the Occu­ +piedHeatingSetpoint attribute of the associated Thermostat cluster. + +**9.6.7.1.3. Timed Tag** + +While in modes with this tag, the device will attempt to keep the water warm based on the Sched­ +ules attribute of the associated Thermostat cluster. + +**9.6.8. Mode Examples** + +A few examples of Water Heater modes and their mode tags are provided below. + +- For the "Off " mode, tags: 0x4000 (Off ) +- For the "Manual" mode, tags: 0x4001 (Manual) +- For the "Timed" mode, tags: 0x4002 (Timed) + +**9.7. Energy Preference Cluster** + +This cluster provides an interface to specify preferences for how devices should consume energy. + +``` +NOTE Support for Energy Preference cluster is provisional. +``` +**9.7.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**9.7.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint EPREF +``` +**9.7.3. Cluster ID** + +``` +ID Name Conformance +0x009B Energy Preference P +``` +``` +Page 690 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.7.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 BALA EnergyBalance O.a+ Device can bal­ +ance energy con­ +sumption vs. +another priority +1 LPMS LowPowerMode­ +Sensitivity +``` +``` +O.a+ Device can adjust +the conditions for +entering a low +power mode +``` +**9.7.4.1. EnergyBalance Feature** + +This feature allows a user to select from a list of energy balances with associated descriptions of +which strategies a device will use to target the specified balance. + +**9.7.4.2. LowPowerModeSensitivity Feature** + +This feature allows the user to select a condition or set of conditions which will cause the device to +switch to a mode using less power. For example, a device might provide a scale of durations that +must elapse without user interaction before it goes to sleep. + +**9.7.5. Data Types** + +**9.7.5.1. EnergyPriorityEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Comfort User comfort M +1 Speed Speed of operation M +2 Efficiency Amount of Energy con­ +sumed by the device +``` +### M + +``` +3 WaterConsumption Amount of water con­ +sumed by the device +``` +### M + +**9.7.5.1.1. Comfort Value** + +This value SHALL emphasize user comfort; e.g. local temperature for a thermostat. + +**9.7.5.1.2. Speed Value** + +This value SHALL emphasize how quickly a device accomplishes its targeted use; e.g. how quickly a +robot vacuum completes a cleaning cycle. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 691 +``` + +**9.7.5.1.3. Efficiency Value** + +This value SHALL emphasize how much energy a device uses; e.g. electricity usage for a Pump. + +**9.7.5.1.4. Water consumption Value** + +This value SHALL emphasize how much water is consumed during device use; e.g. how much water +a dishwasher uses during a cleaning cycle. + +**9.7.5.2. BalanceStruct Type** + +This represents a step along a scale of preferences. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Step percent all F MS M +1 Label string max 64 F O +``` +**9.7.5.2.1. Step Field** + +This field SHALL indicate the relative value of this step. + +**9.7.5.2.2. Label Field** + +This field SHALL indicate an optional string explaining which actions a device might take at the +given step value. + +**9.7.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Energy­ +Balances +``` +``` +list[Bal­ +anceStruct] +``` +``` +2 to 10 F R V BALA +``` +``` +0x0001 Cur­ +rentEner­ +gyBalance +``` +``` +uint8 all N RW VO BALA +``` +``` +0x0002 EnergyPri­ +orities +``` +``` +list[Ener­ +gyPriori­ +tyEnum] +``` +### 2 F R V BALA + +``` +0x0003 LowPow­ +erMode­ +Sensitivi­ +ties +``` +``` +list[Bal­ +anceStruct] +``` +``` +2 to 10 F R V LPMS +``` +``` +0x0004 Current­ +LowPow­ +erMode­ +Sensitivity +``` +``` +uint8 all N RW VO LPMS +``` +``` +Page 692 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.7.6.1. EnergyBalances Attribute** + +This attribute SHALL indicate a list of BalanceStructs, each representing a step along a linear scale +of relative priorities. A Step field with a value of zero SHALL indicate that the device SHOULD +entirely favor the priority specified by the first element in EnergyPriorities; whereas a Step field +with a value of 100 SHALL indicate that the device SHOULD entirely favor the priority specified by +the second element in EnergyPriorities. The midpoint value of 50 SHALL indicate an even split +between the two priorities. + +This SHALL contain at least two BalanceStructs. + +Each BalanceStruct SHALL have a Step field larger than the Step field on the previous BalanceStruct +in the list. + +The first BalanceStruct SHALL have a Step value of zero, and the last BalanceStruct SHALL have a +Step value of 100. + +**9.7.6.2. CurrentEnergyBalance Attribute** + +This attribute SHALL indicate the current preference of the user for balancing different priorities +during device use. The value of this attribute is the index, 0-based, into the EnergyBalances +attribute for the currently selected balance. + +If an attempt is made to set this attribute to an index outside the maximum index for EnergyBal­ +ances, a response with the status code CONSTRAINT_ERROR SHALL be returned. + +If the value of EnergyBalances changes after an update, the device SHALL migrate the value of the +CurrentEnergyBalance attribute to the index which the manufacturer specifies most closely +matches the previous value, while preserving extreme preferences as follows: + +1. If the previous value of CurrentEnergyBalance was zero, indicating a total preference for the + priority specified by the first element in EnergyPriorities, the new value of CurrentEnergyBal­ + ance SHALL also be zero. +2. If the previous value of CurrentEnergyBalance was the index of the last BalanceStruct in the + previous value of EnergyBalances, indicating a total preference for the priority specified by the + last element in EnergyPriorities, the new value of CurrentEnergyBalance SHALL be the index of + the last element in the updated value of EnergyBalances. + +**9.7.6.3. EnergyPriorities Attribute** + +This attribute SHALL indicate two extremes for interpreting the values in the EnergyBalances +attribute. These two priorities SHALL be in opposition to each other; e.g. Comfort vs. Efficiency or +Speed vs. WaterConsumption. + +If the value of EnergyPriorities changes after an update to represent a new balance between priori­ +ties, the value of the CurrentEnergyBalance attribute SHALL be set to its default. + +**9.7.6.4. LowPowerModeSensitivities Attribute** + +This attribute SHALL indicate a list of BalanceStructs, each representing a condition or set of condi­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 693 +``` + +tions for the device to enter a low power mode. + +This SHALL contain at least two BalanceStructs. + +Each BalanceStruct SHALL have a Step field larger than the Step field on the previous BalanceStruct +in the list. + +**9.7.6.5. CurrentLowPowerModeSensitivity Attribute** + +This attribute SHALL indicate the current preference of the user for determining when the device +should enter a low power mode. The value of this attribute is the index, 0-based, into the LowPow­ +erModeSensitivities attribute for the currently selected preference. + +If an attempt is made to set this attribute to an index outside the maximum index for LowPower­ +ModeSensitivities, a response with the status code CONSTRAINT_ERROR SHALL be returned. + +If the value of LowPowerModeSensitivities changes after an update, the device SHALL migrate the +value of the LowPowerModeSensitivity attribute to the index which the manufacturer specifies +most closely matches the previous value. + +**9.8. Device Energy Management Mode Cluster** + +This cluster is derived from the Mode Base cluster and defines additional mode tags and name­ +spaced enumerated values for Device Energy Management devices. + +**9.8.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Disallowed DEPONOFF feature and OnMode and +StartUpMode attributes +``` +**9.8.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Mode Base Application Endpoint DEMM +``` +**9.8.3. Cluster ID** + +``` +ID Name +0x009F Device Energy Management Mode +``` +``` +Page 694 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.8.4. Features** + +``` +Bit Code Feature Conformance Summary +0 DEPONOFF OnOff X Dependency with +the OnOff cluster +``` +**9.8.5. Data Types** + +**9.8.5.1. ModeOptionStruct Type** + +The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOption­ +Struct type. A blank field indicates no change. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label M +1 Mode M +2 ModeTags 1 to 8 M +``` +**9.8.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Support­ +edModes +0x0001 Current­ +Mode +0x0002 StartUp­ +Mode +``` +### X + +``` +0x0003 OnMode X +``` +**9.8.6.1. SupportedModes Attribute** + +At least one entry in the SupportedModes attribute SHALL include the NoOptimization mode tag in +the ModeTags field. + +At least one entry in the SupportedModes attribute SHALL include the LocalOptimization mode tag +in the ModeTags field list. + +At least one entry in the SupportedModes attribute SHALL include the GridOptimization mode tag +in the ModeTags field list. + +An entry in the SupportedModes attribute that includes one of an DeviceOptimization, LocalOpti­ +mization, or GridOptimization tags SHALL NOT also include NoOptimization tag. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 695 +``` + +**9.8.7. Derived Cluster Namespace** + +This namespace includes definitions for data associated exclusively with the derived cluster. + +**9.8.7.1. Mode Tags** + +The following table defines the base and derived-cluster-specific ModeTag values. + +``` +Mode Tag Value Name +0x0000 Auto +0x0001 Quick +0x0002 Quiet +0x0003 LowNoise +0x0004 LowEnergy +0x0005 Vacation +0x0006 Min +0x0007 Max +0x0008 Night +0x0009 Day +0x4000 NoOptimization +0x4001 DeviceOptimization +0x4002 LocalOptimization +0x4003 GridOptimization +``` +**9.8.7.1.1. NoOptimization Tag** + +The device prohibits optimization of energy usage management: its energy usage is determined +only by the user configuration and internal device needs. + +**9.8.7.1.2. DeviceOptimization Tag** + +The device is permitted to manage its own energy usage. For example, using tariff information it +may obtain. + +**9.8.7.1.3. LocalOptimization Tag** + +The device permits management of energy usage by an energy manager to optimize the local +energy usage. + +**9.8.7.1.4. GridOptimization Tag** + +The device permits management of energy usage by an energy manager to optimize the grid energy +usage. + +``` +Page 696 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.8.8. Mode Examples** + +A few examples of Device Energy Management modes and their mode tags are provided below. + +- For the "No Energy Management (Forecast reporting only)" mode, tags: 0x4000 (NoOptimiza­ + tion). +- For the "Device Energy Management" mode, tags: 0x4001 (DeviceOptimization). +- For the "Home Energy Management" mode, tags: 0x4001 (DeviceOptimization), 0x4002 + (LocalOptimization). +- For the "Grid Energy Management" mode, tags: 0x4003 (GridOptimization). +- For the "Full Energy Management" mode, tags: 0x4001 (DeviceOptimization), 0x4002 (LocalOpti­ + mization), 0x4003 (GridOptimization). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 697 +``` + +Page 698 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 10. Network Infrastructure** + +The Cluster Library is made of individual chapters such as this one. See Document Control in the +Cluster Library for a list of all chapters and documents. References between chapters are made +using a _X.Y_ notation where _X_ is the chapter and _Y_ is the sub-section within that chapter. + +**10.1. General Description** + +**10.1.1. Introduction** + +The clusters specified in this section are used to control network infrastructure devices, such as +home internet gateways, Wi-Fi access points, Thread Border Routers, etc. + +**10.1.2. Cluster List** + +This section lists the clusters specified in this document, and gives examples of typical usage for the +purpose of clarification. + +_Table 17. Clusters Specified in the Network Infrastructure Functional Domain_ + +``` +Cluster ID Cluster Name Description +0x0451 Wi-Fi Network Management Request Wi-Fi network details +0x0452 Thread Border Router Manage­ +ment +``` +``` +Management of a Thread Bor­ +der Router / Network +0x0453 Thread Network Directory Clus­ +ter +``` +``` +Directory of Thread networks +and Border Routers +``` +**10.2. Wi-Fi Network Management Cluster** + +This cluster provides an interface for getting information about the Wi-Fi network that a Network +Infrastructure Manager device type provides. Privileged nodes within the same fabric as a Network +Infrastructure Manager can use these interfaces to request information related to the Wi-Fi Net­ +work such as SSID and Passphrase. + +**10.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**10.2.2. Classification** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 699 +``` + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint WIFINM +``` +**10.2.3. Cluster ID** + +``` +ID Name +0x0451 Wi-Fi Network Management +``` +**10.2.4. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 SSID octstr 1 to 32 XN null R V M +0x0001 Passphras­ +eSurro­ +gate +``` +``` +uint64 all XN null R M M +``` +**10.2.4.1. SSID Attribute** + +This attribute SHALL indicate the SSID of the primary Wi-Fi network provided by this device. + +A value of null SHALL indicate that no primary Wi-Fi network is available (e.g. because the Wi-Fi +network has not yet been configured by the user). + +### NOTE + +``` +The SSID in Wi-Fi is a collection of 1-32 bytes, the text encoding of which is not spec­ +ified. Implementations must be careful to support transferring these byte strings +without requiring a particular encoding. The most common encoding is UTF-8, how­ +ever this is just a convention. Some configurations may use Latin-1 or other charac­ +ter sets. +``` +**10.2.4.2. PassphraseSurrogate Attribute** + +This attribute SHALL contain an arbitrary numeric value; this value SHALL increase whenever the +passphrase or PSK associated with the primary Wi-Fi network provided by this device changes. + +A value of null SHALL indicate that no primary Wi-Fi network is available. + +Clients can subscribe to this attribute or compare its value to a locally cached copy to detect if a +cached passphrase value has become stale. + +It is RECOMMENDED that servers implement this attribute as either a timestamp or a counter. +When implemented as a counter it SHOULD be initialized with a random value. + +### NOTE + +``` +The passphrase itself is not exposed as an attribute to avoid its unintentional +retrieval or caching by clients that use wildcard reads or otherwise routinely read +all available attributes. It can be retrieved using the NetworkPassphraseRequest +``` +``` +Page 700 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +command. +``` +**10.2.5. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Network­ +PassphraseRe +quest +``` +``` +client ⇒ server Network­ +PassphraseRe­ +sponse +``` +### M M + +``` +0x01 Network­ +PassphraseRe­ +sponse +``` +``` +client ⇐ server N M +``` +**10.2.5.1. NetworkPassphraseRequest Command** + +This command is used to request the current WPA-Personal passphrase or PSK associated with the +Wi-Fi network provided by this device. + +If the command is not executed via a CASE session, the command SHALL be rejected with a status +of UNSUPPORTED_ACCESS. + +If no primary Wi-Fi network is available (the SSID attribute is null), the command SHALL be +rejected with a status of INVALID_IN_STATE. + +Otherwise a NetworkPassphraseResponse SHALL be generated. + +**10.2.5.2. NetworkPassphraseResponse Command** + +This command SHALL be generated in response to a NetworkPassphraseRequest command. The +data for this command SHALL be as follows: + +``` +Name Type Constraint Conformance +Passphrase octstr max 64 M +``` +**10.2.5.2.1. Passphrase Field** + +This field SHALL indicate the current WPA-Personal passphrase or PSK associated with the primary +Wi-Fi network provided by this device, in one of the following formats: + +- 8..63 bytes: WPA/WPA2/WPA3 passphrase. +- 64 bytes: WPA/WPA2/WPA3 raw hex PSK. Each byte SHALL be a ASCII hexadecimal digit. + +This matches the formats defined for WPA networks by the Credentials field in the Network Com­ +missioning cluster (see [MatterCore]). + +### NOTE + +``` +WPA3-Personal permits passphrases shorter than 8 or longer than 63 characters, +however the Network Commissioning cluster does not currently support configur­ +ing Matter devices to connect to operational networks utilizing such a passphrase. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 701 +``` + +**10.3. Thread Border Router Management Cluster** + +This cluster provides an interface for managing a Thread Border Router and the Thread network +that it belongs to. Privileged nodes within the same fabric as a Thread Border Router can use these +interfaces to request and set credentials information to the Thread network. + +**10.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**10.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint TBRM +``` +**10.3.3. Cluster ID** + +``` +ID Name +0x0452 Thread Border Router Management +``` +**10.3.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 PC PANChange O The ability to +change PAN con­ +figuration with +pending dataset +setting request. +``` +**10.3.4.1. PANChange Feature** + +This feature SHALL indicate the ability of the Border Router to change its already configured PAN +to another, by setting a pending dataset. + +### NOTE + +``` +This feature flag can be used to protect an already-configured network from acci­ +dental configuration change, e.g. when the Thread Border Router serves non-Matter +devices that do not support PAN change for an implementation-specific reason. +``` +``` +Page 702 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.3.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Border­ +Router­ +Name +``` +``` +string 1 to 63 R V M +``` +``` +0x0001 BorderA­ +gentID +``` +``` +octstr 16 R V M +``` +``` +0x0002 Thread­ +Version +``` +``` +uint16 all F MS R V M +``` +``` +0x0003 Inter­ +faceEn­ +abled +``` +``` +bool all N false R V M +``` +``` +0x0004 Active­ +Dataset­ +Time­ +stamp +``` +``` +uint64 all XN 0 R V M +``` +``` +0x0005 Pending­ +Dataset­ +Time­ +stamp +``` +``` +uint64 all XN 0 R V M +``` +**10.3.5.1. BorderRouterName Attribute** + +This attribute SHALL indicate a user-friendly name identifying the device model or product of the +Border Router in MeshCOP (DNS-SD service name) as defined in the Thread specification, and has +the following recommended format: ._meshcop._udp. An example name +would be ACME Border Router (74be)._meshcop._udp. + +**10.3.5.2. BorderAgentID Attribute** + +This attribute SHALL indicate a 16-byte globally unique ID for a Thread Border Router device. This +ID is manufacturer-specific, and it is created and managed by the border router’s implementation. + +**10.3.5.3. ThreadVersion Attribute** + +This attribute SHALL indicate the Thread version supported by the Thread interface configured by +the cluster instance. + +The format SHALL match the value mapping defined in the "Version TLV" section of the Thread +specification. For example, Thread 1.3.0 would have ThreadVersion set to 4. + +**10.3.5.4. InterfaceEnabled Attribute** + +This attribute SHALL indicate whether the associated IEEE 802.15.4 Thread interface is enabled or +disabled. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 703 +``` + +**10.3.5.5. ActiveDatasetTimestamp Attribute** + +This attribute SHALL be null if the Thread Border Router has no dataset configured, otherwise it +SHALL be the timestamp value extracted from the Active Dataset value configured by the Thread +Node to which the border router is connected. This attribute SHALL be updated when a new Active +dataset is configured on the Thread network to which the border router is connected. + +**10.3.5.6. PendingDatasetTimestamp Attribute** + +This attribute SHALL be null if the Thread Border Router has no Pending dataset configured, other­ +wise it SHALL be the timestamp value extracted from the Pending Dataset value configured by the +Thread Node to which the border router is connected. This attribute SHALL be updated when a +new Pending dataset is configured on the Thread network to which the border router is connected. + +**10.3.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 GetActive­ +DatasetRe­ +quest +``` +``` +client ⇒ server DatasetRe­ +sponse +``` +### M M + +``` +0x01 GetPending­ +DatasetRe­ +quest +``` +``` +client ⇒ server DatasetRe­ +sponse +``` +### M M + +``` +0x02 DatasetRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x03 SetActive­ +DatasetRe­ +quest +``` +``` +client ⇒ server Y M T M +``` +``` +0x04 SetPending­ +DatasetRe­ +quest +``` +``` +client ⇒ server Y M T PC +``` +**10.3.6.1. GetActiveDatasetRequest Command** + +This command SHALL be used to request the active operational dataset of the Thread network to +which the border router is connected. + +If the command is not executed via a CASE session, the command SHALL fail with a status code of +UNSUPPORTED_ACCESS. + +If an internal error occurs, then this command SHALL fail with a FAILURE status code sent back to +the initiator. + +Otherwise, this SHALL generate a DatasetResponse command. + +``` +Page 704 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.3.6.2. GetPendingDatasetRequest Command** + +This command SHALL be used to request the pending dataset of the Thread network to which the +border router is connected. + +If the command is not executed via a CASE session, the command SHALL fail with a status code of +UNSUPPORTED_ACCESS. + +If an internal error occurs, then this command SHALL fail with a FAILURE status code sent back to +the initiator. + +Otherwise, this SHALL generate a DatasetResponse command. + +**10.3.6.3. DatasetResponse Command** + +This command is sent in response to GetActiveDatasetRequest or GetPendingDatasetRequest com­ +mand. The data for this command SHALL be as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Dataset octstr max 254 M +``` +**10.3.6.3.1. Dataset field** + +If no dataset (active or pending as requested) is configured, this field SHALL be set to empty. + +Otherwise, this field SHALL contain the active or pending dataset of the Thread network to which +the Border Router is connected as an octet string containing the raw Thread TLV value of the +dataset, as defined in the Thread specification. + +**10.3.6.4. SetActiveDatasetRequest Command** + +This command SHALL be used to set the active Dataset of the Thread network to which the Border +Router is connected, when there is no active dataset already. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Active­ +Dataset +``` +``` +octstr max 254 M +``` +``` +1 Bread­ +crumb +``` +``` +uint64 all O +``` +**10.3.6.4.1. ActiveDataset Field** + +This field SHALL contain the active dataset to set of the Thread network to configure in the Border +Router as an octet string containing the raw Thread TLV value of the dataset, as defined in the +Thread specification. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 705 +``` + +**10.3.6.4.2. Breadcrumb Field** + +See Breadcrumb Attribute section of General Commissioning Cluster in [MatterCore] for usage. + +**10.3.6.4.3. Effect on receipt** + +If the command is not executed via a CASE session, the command SHALL fail with a status code of +UNSUPPORTED_ACCESS. + +If this command is received without a Fail Safe Context (see ArmFailSafe Command of General Com­ +missioning Cluster in [MatterCore]), then this command SHALL fail with a FAILSAFE_REQUIRED +status code sent back to the initiator. + +If any of the parameters in the ActiveDataset is invalid, the command SHALL fail with a status code +of INVALID_COMMAND. + +If this command is invoked when the ActiveDatasetTimestamp attribute is not null, the command +SHALL fail with a status code of INVALID_IN_STATE. The administrator MAY use the SetPending­ +DatasetRequest command to modify the future active dataset. + +If this command is invoked and the ActiveDatasetTimestamp attribute is null, the Thread Border +Router SHALL configure and activate its active dataset using the ActiveDataset parameter. + +The activation process SHALL be a time-bound process that completes before expiration of a fail- +safe timer. The fail-safe timer SHALL be set at the beginning of the activation process. + +If the fail-safe timer expires prior to activation process completion, the command SHALL respond +with TIMEOUT, and the Border Router state SHALL revert to the configuration set prior to the fail- +safe timer being armed, see ArmFailSafe Command of General Commissioning Cluster in [Matter­ +Core]. + +After successfully creating or joining a Thread network with the new active dataset, the Inter­ +faceEnabled attribute SHALL be updated to TRUE, indicating that the associated Thread Interface is +active and functioning. The ActiveDatasetTimestamp attribute SHALL be updated with the Active­ +Dataset timestamp. If the Adjacent Infrastructure Link of the Border Router is connected, then the +device SHOULD also enable and operate Thread Border Routing functionality using the Thread and +Adjacent Infrastructure Link interfaces. + +If this command is received during the activation process triggered by a previous SetActiveDatase­ +tRequest command, then the command SHALL fail with a status code of BUSY. + +**10.3.6.5. SetPendingDatasetRequest Command** + +This command SHALL be used to set or update the pending Dataset of the Thread network to which +the Border Router is connected, if the Border Router supports PAN Change. + +If the command is not executed via a CASE session, the command SHALL fail with a status code of +UNSUPPORTED_ACCESS. + +``` +Page 706 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Pending­ +Dataset +``` +``` +octstr max 254 M +``` +This PendingDataset field SHALL contain the pending dataset to which the Thread network should +be updated. The format of the data SHALL be an octet string containing the raw Thread TLV value +of the pending dataset, as defined in the Thread specification. + +If any of the parameters in the PendingDataset is invalid, the command SHALL fail with a status of +INVALID_COMMAND. + +Otherwise, this command SHALL configure the pending dataset of the Thread network to which the +Border Router is connected, with the value given in the PendingDataset parameter. The Border +Router will manage activation of the pending dataset as defined in the Thread specification. + +**10.4. Thread Network Directory Cluster** + +This cluster stores a list of Thread networks (including the credentials required to access each net­ +work), as well as a designation of the user’s preferred network, to facilitate the sharing of Thread +networks across fabrics. + +**10.4.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**10.4.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint THNETDIR +``` +**10.4.3. Cluster ID** + +``` +ID Name +0x0453 Thread Network Directory +``` +**10.4.4. Data Types** + +**10.4.4.1. ThreadNetworkStruct Type** + +Represents the data associated with a Thread Network. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 707 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Extended­ +PanID +``` +``` +octstr 8 M +``` +``` +1 Network­ +Name +``` +``` +string 1 to 16 M +``` +``` +2 Channel uint16 all M +3 Active­ +Time­ +stamp +``` +``` +uint64 all M +``` +**10.4.4.1.1. ExtendedPanID Field** + +This field SHALL indicate the Extended PAN ID from the OperationalDataset for the given Thread +network. + +**10.4.4.1.2. NetworkName Field** + +This field SHALL indicate the Network Name from the OperationalDataset for the given Thread net­ +work. + +**10.4.4.1.3. Channel Field** + +This field SHALL indicate the Channel from the OperationalDataset for the given Thread network. + +**10.4.4.1.4. ActiveTimestamp Field** + +This field SHALL indicate the Active Timestamp from the OperationalDataset for the given Thread +network. + +**10.4.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Preferre­ +dExtend­ +edPanID +``` +``` +octstr 8 XN null RW VM M +``` +``` +0x0001 Thread­ +Networks +``` +``` +list[Thread +Network­ +Struct] +``` +``` +max +ThreadNet­ +workTable­ +Size +``` +### N R V M + +``` +0x0002 Thread­ +Network­ +TableSize +``` +``` +uint8 desc F 10 R V M +``` +``` +Page 708 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.4.5.1. PreferredExtendedPanID Attribute** + +This attribute SHALL represent the Thread Extended PAN ID value for the Thread network desig­ +nated by the user to be their preferred network for commissioning of Thread devices. If not null, +the value of this attribute SHALL match the ExtendedPanID of a network in the ThreadNetworks +attribute. A write operation with a non-null value that does not match any network in the Thread­ +Networks list SHALL be rejected with a status of CONSTRAINT_ERROR. + +The purpose of designating one Thread network as preferred is to help a commissioner to select a +Thread network when a Thread device is within suitable range of more than one Thread network +which appears in the ThreadNetworks list. A value of null indicates that there is no current pre­ +ferred network: All networks MAY be treated as equally preferred by a commissioner with access to +this cluster. + +This attribute MAY be automatically set to the ExtendedPanID of the first Thread network added to +the ThreadNetworks list. + +A client SHALL obtain user consent before changing the value of this attribute from a non-null +value. + +On a factory reset this attribute SHALL be reset to null. + +**10.4.5.2. ThreadNetworks Attribute** + +This attribute SHALL indicate the list of Thread Networks known about by this cluster. If the node +hosting this cluster includes a Thread Border Router, then an entry for its Thread Network SHALL +be included in this list. + +The list can be modified via the AddNetwork and RemoveNetwork commands. + +For each entry in the list, the cluster server also stores a Thread Operational Dataset. Clients use the +GetOperationalDataset command to obtain the Operational Dataset for an entry in this list. + +On a factory reset this list SHALL be cleared, and any Thread Operational datasets previously +stored SHALL be removed from the Node. + +**10.4.5.3. ThreadNetworkTableSize Attribute** + +This attribute SHALL indicate the maximum number of entries that can be held in the ThreadNet­ +works list; it SHALL be at least 2 times the number of SupportedFabrics advertised in the Opera­ +tional Credentials Cluster on the root endpoint of this node. + +**10.4.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 AddNetwork client ⇒ server Y M T M +0x01 RemoveNet­ +work +``` +``` +client ⇒ server Y M T M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 709 +``` + +``` +ID Name Direction Response Access Conformance +0x02 GetOpera­ +tionalDataset +``` +``` +client ⇒ server Operational­ +DatasetRe­ +sponse +``` +### M M + +``` +0x03 Operational­ +DatasetRe­ +sponse +``` +``` +server ⇒ client N M +``` +**10.4.6.1. AddNetwork Command** + +Adds an entry to the ThreadNetworks attribute with the specified Thread Operational Dataset. + +If there is an existing entry with the Extended PAN ID then the Thread Operational Dataset for that +entry is replaced. As a result, changes to the network parameters (e.g. Channel, Network Name, +PSKc, ...) of an existing entry with a given Extended PAN ID can be made using this command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Opera­ +tional­ +Dataset +``` +``` +octstr max 254 M +``` +**10.4.6.1.1. OperationalDataset Field** + +This field SHALL represent the Operational Dataset for the network, using the encoding defined in +the Thread specification. It SHALL contain at least the following sub-TLVs: Active Timestamp, Chan­ +nel, Channel Mask, Extended PAN ID, Network Key, Network Mesh-Local Prefix, Network Name, +PAN ID, PSKc, and Security Policy. + +**10.4.6.1.2. Effect on Receipt** + +1. If the TLV structure of the Operational Dataset is invalid, or if any of the required sub-TLVs are + missing, the command SHALL be rejected with a status of CONSTRAINT_ERROR. However, inclu­ + sion of unknown sub-TLVs SHALL NOT be treated as an error, as future versions of the Thread + specification MAY define additional sub-TLVs. +2. If there is an existing ThreadNetworks entry with an Extended PAN ID matching the received + dataset, then that entry SHALL be replaced with the received dataset. However, if the received + dataset has an Active Timestamp that is less than or equal to that of the existing entry, then the + update SHALL be rejected with a status of INVALID_IN_STATE. +3. Otherwise, a new entry SHALL be added based on the received dataset. If this would cause the + size of the ThreadNetworks list to exceed the ThreadNetworkTableSize, then a RESOURCE_EX­ + HAUSTED status SHALL be returned. + +**10.4.6.2. RemoveNetwork Command** + +Removes the network with the given Extended PAN ID from the ThreadNetworks attribute. + +``` +Page 710 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Extended­ +PanID +``` +``` +octstr 8 M +``` +**10.4.6.2.1. Effect on Receipt** + +1. If no network with the given Extended PAN ID exists in the ThreadNetworks attribute, the com­ + mand SHALL be rejected with a status of NOT_FOUND. +2. If the given Extended PAN ID matches the PreferredExtendedPanID attribute, the command + SHALL be rejected with a status of CONSTRAINT_ERROR. +3. Otherwise, the network with the matching Extended PAN ID SHALL be removed from the + ThreadNetworks attribute. + +**10.4.6.3. GetOperationalDataset Command** + +Retrieves the Thread Operational Dataset with the given Extended PAN ID. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Extended­ +PanID +``` +``` +octstr 8 M +``` +**10.4.6.3.1. Effect on Receipt** + +1. If the command is not executed via a CASE session, the command SHALL be rejected with a sta­ + tus of UNSUPPORTED_ACCESS. +2. If no network with the given Extended PAN ID exists in the ThreadNetworks attribute, the com­ + mand SHALL be rejected with a status of NOT_FOUND. +3. Otherwise, an OperationalDatasetResponse command containing the operational dataset for the + requested network SHALL be generated. + +**10.4.6.4. OperationalDatasetResponse Command** + +Contains the Thread Operational Dataset for the Extended PAN specified in GetOperationalDataset. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Opera­ +tional­ +Dataset +``` +``` +octstr max 254 M +``` +**10.4.7. Guidance for Fabrics / Commissioners** + +This cluster allows fabrics (via their Administrators or Nodes with Manage privilege) to collabora­ +tively share and manage a directory of ThreadNetworks, as well as a designation of one of those + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 711 +``` + +networks as the user’s preferred network via the PreferredExtendedPanID attribute. + +It is RECOMMENDED that fabrics only interact with instances of this cluster hosted on endpoints +that declare a device type that explicitly allows this cluster; currently this includes the Network +Infrastructure Manager and Thread Border Router device types. Networks from the ThreadNet­ +works list of any such directory instance, as well as the Active Dataset made available by any +Thread Border Router via the Thread Border Router Management Cluster, SHOULD be considered +as potentially available networks. + +In determining the user’s preferred network, a directory instance on a Network Infrastructure +Manager device SHOULD take precedence over other instances. Where a fabric has access to multi­ +ple Network Infrastructure Manager devices, it MAY give precedence to the directory instance on +the Network Infrastructure Manager device considered to be acting as the primary Internet gate­ +way device for the network. + +Due to the sensitive nature of Thread network credentials, it is RECOMMENDED that fabrics obtain +user consent before starting to contribute credentials to a particular directory instance. Contribu­ +tions to a directory instance SHOULD be restricted to those Thread networks that are likely to be +reachable from the infrastructure network to which the device hosting that directory is connected. + +``` +Page 712 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + diff --git a/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_CORE_SPEC.md b/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_CORE_SPEC.md new file mode 100644 index 000000000..cc05b219b --- /dev/null +++ b/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_CORE_SPEC.md @@ -0,0 +1,66712 @@ +# Matter Specification + +# Version 1.4. + +``` +Document: 23-27349-007_Matter-1.4.1-Core-Specification.pdf +March 17, 2025 +Sponsored by: Connectivity Standards Alliance +Accepted by: This document has been accepted for release by the Connectivity +Standards Alliance Board of Directors on March 17, 2025 +Abstract: The Matter specification defines fundamental requirements to +enable an interoperable application layer solution for smart home +devices over the Internet Protocol. +Keywords: Referenced in Chapter 1. +``` +Copyright © 2022-2025 Connectivity Standards Alliance, Inc. +508 Second Street, Suite 109B Davis, CA 95616 - USA +[http://www.csa-iot.org](http://www.csa-iot.org) +All rights reserved. + +Permission is granted to members of the Connectivity Standards Alliance to reproduce this +document for their own use or the use of other Connectivity Standards Alliance members only, +provided this notice is included. All other rights reserved. Duplication for sale, or for commercial or +for-profit use is strictly prohibited without the prior written consent of the Connectivity Standards +Alliance. + + + +# Matter Specification + +``` +Version 1.4.1, 2025-03-12 06:42:16 -0700: Approved +``` + + +**Copyright Notice, License and Disclaimer** + +Copyright © Connectivity Standards Alliance (2021-2023). All rights reserved. The information +within this document is the property of the Connectivity Standards Alliance and its use and disclo­ +sure are restricted, except as expressly set forth herein. + +Connectivity Standards Alliance hereby grants you a fully-paid, non-exclusive, nontransferable, +worldwide, limited and revocable license (without the right to sublicense), under Connectivity Stan­ +dards Alliance’s applicable copyright rights, to view, download, save, reproduce and use the docu­ +ment solely for your own internal purposes and in accordance with the terms of the license set +forth herein. This license does not authorize you to, and you expressly warrant that you shall not: +(a) permit others (outside your organization) to use this document; (b) post or publish this docu­ +ment; (c) modify, adapt, translate, or otherwise change this document in any manner or create any +derivative work based on this document; (d) remove or modify any notice or label on this docu­ +ment, including this Copyright Notice, License and Disclaimer. The Connectivity Standards Alliance +does not grant you any license hereunder other than as expressly stated herein. + +Elements of this document may be subject to third party intellectual property rights, including +without limitation, patent, copyright or trademark rights, and any such third party may or may not +be a member of the Connectivity Standards Alliance. Connectivity Standards Alliance members +grant other Connectivity Standards Alliance members certain intellectual property rights as set +forth in the Connectivity Standards Alliance IPR Policy. Connectivity Standards Alliance members +do not grant you any rights under this license. The Connectivity Standards Alliance is not responsi­ +ble for, and shall not be held responsible in any manner for, identifying or failing to identify any or +all such third party intellectual property rights. Please visit [http://www.csa-iot.org](http://www.csa-iot.org) for more information +on how to become a member of the Connectivity Standards Alliance. + +This document and the information contained herein are provided on an “AS IS” basis and the Con­ +nectivity Standards Alliance DISCLAIMS 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 INTELLEC­ +TUAL PROPERTY RIGHTS INCLUDING PATENT, COPYRIGHT OR TRADEMARK RIGHTS); OR (B) ANY +IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR +NONINFRINGEMENT. IN NO EVENT WILL THE CONNECTIVITY STANDARDS ALLIANCE BE LIABLE +FOR ANY LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF BUSI­ +NESS, OR FOR ANY OTHER DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTAL, 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 in this document may be trademarks that are the sole prop­ +erty of their respective owners. + +This notice and disclaimer must be included on all copies of this document. + +Connectivity Standards Alliance +508 Second Street, Suite 206 +Davis, CA 95616, USA + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1 +``` + +Page 2 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Participants** + +``` +Agrawal, Amit Alexander, Rob Ananthakrishnan, +Krithika +``` +``` +Axelsson, Ulf +``` +``` +Azria, Shana Bak, Naama Balducci, Alex Bao, Yongming +Bartolome, Diego Bauer-Schwan, Stefan Beach, Chris Beck, Austin +Becker, Markus Beliveau, Louis-Philip Ben, Thomas Bhetanabottla, Sriram +Binjola, Sharad Boehl, Florian Bonnell, Corey Bultman, Rob +C, Rajashree Carlin, Broderick Carmel-Veilleux, Ten­ +nessee +``` +``` +Casallas, Ricardo +``` +``` +Cave, Tony Chalmers, Andrew Chan, Osborn Chandarana, Janak +Chen, Shu Cheshire, Stuart Chudinov, Adrian Chung, Cliff +Chupp, Anton Coppock, Kevin Cowan, Michael Cragie, Robert +Crettenand, Alexander Cullen, Sam Cuyckens, Thomas Damle, Makarand +Darling, Don De, Pradip Decenzo, Chris Delplancke, Julien +Dhayagude, Hrishikesh Ding, Li-An Dok, Hrishikesh Dolan, David +Dong, Kangping Drake, Jeff Duda, Łukasz Dyck, Nathan +Erickson, Grant Farnum, Robert Feraru, Eugen Fominaya, Antonio +Freeman, Cecille Fu, Kenneth Fuentes, Pedro Fyall, Ian +Garbus, Mathias Kiel­ +gast +``` +``` +Garg, Pankaj Graf, Tobias Granbery, Hasty +``` +``` +Gucea, Doru Guiheneuf, Robin- +Charles +``` +``` +Guo, Jiacheng Guo, Song +``` +``` +Haefner, Kyle Hamilton, Ryan Hampson, Terence Hanna, John +Hanna, Steve Haque, Asad Harris, Will Harrow, James +Hartwig, Thomas Harvey, Gene Hazley, Matt Heide, Janus +Hernandez-Palomares, +Martin +``` +``` +Hicklin, William Hilal, Rawad Ho, Nguyen +``` +``` +Hoang, Minhhoa Holbrook, Trevor Hollebeek, Tim Houtepen, Rob +Huang, Xiaolong Hui, Jonathan Hui, Li Hui, Yang +Jain, Amit Jain, Ankur Jandhyala, Chaitanya Jayakumar, Liju +Johns, Jerry Josefsen, René KVS, Mohan KY, Suma +Karabashov, Aziz Kardous, Mathieu Kasperczyk, Kamil Kassel, Gabe +Katira, Utsav Khatri, Shivam Knörzer, Clemens Kohr, John +Kommareddi, Naveen Kontra, Andrew Koos, Chris Kovacic, Lazar +Krawetz, Bryan Królik, Damian Kumar, Sandeep Kumar, Saurabh +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 3 +``` + +``` +Lauric, Petru Lazar, Alin Le Tutour, Jean Lea, Thomas +Lee, Byungjoo Lepage, Marc Letnick, Chris Levkov, Stoycho +Liang, Deng Lindeman, Ryan Litvin, Andrei Lyu, Rashid +Ma, Longfei Maes, Timothy Makdissi, Shadi Mamo, Fesseha +Manley, Tom Mann, Bryan Mansour, Peter Mapp, Chris +Marche, Mikael Margolis, Evgeni Martinez, Junior Matignon, Florent +Matosian, Dan Meissner, Bryan Melo, Sara Menzopol, Andrei +Mikolits, Marc Moneta, Daniel Montenegro, Gabriel Morales, Victor +Morozov, Evgeniy Morris, Simon Mouquet, Antoine Mégevand, Jonathan +Nadathur, Anush Nagappan, Ramesh Nicolas, Vivien Nuyts, Wim +Oleson, Kiel Olson, Rodney P, Aswathy Pan, Liam +Pan, Shaofeng Pansy, Jürgen Page, Jason Parausanu, Dragos +Patil, Shubham Patwardhan, Aditya Penven, Jean-Francois Perumal, Saravana +Po, Kevin Powell, Ken Pyasi, Madhur Rahman, Mo +Rempel, David Rhees, Jon Richard, Arnaud Rosenberg, Aron +Rozendaal, Leo Rupp, Michael Ryan, Kyle S, Sowmya +Sallas, Sal Sambles, Philip Sandstedt, Michael Sarkar, Nivi +Sarma, Bhaskar Scherbakov, Alex Schiller, Bill Schoinas, Yannis +Schultze, Juliane Seenivasan, Suraj Segal, Oren Selviraj, Vijay +Sena, Joe She, Chengqiang Shreve, Erik Siu, Irene +Smirl, Jon Smith, Bill Smith, David Smith, Matt +Soloway, Alan Son, Jae Spade, Lorey Sperling, Karsten +Struchtrup, Sebastian +Schulze +``` +``` +Surnin, Dmitry Swan, James Szablowski, Michał +``` +``` +Szatmary-Ban, Zoltan Szczodrak, Marcin Szewczyk, Robert Tabassum, Nadira +Taleb, Ali Trayer, Mark Truskovsky, Alexander Tung, Berkat +Turon, Martin Umesh, Deepakumar Vauclair, Marc Verma, Lochan +Wais, Jackie Wang Qixiang Wang, David Wang, Yufeng +Wang, Yunhan Wei, Qingyun Weil, Jason Weinshel, Ben +Weir, Tristan Williams, Cam Wood, Justin Wyseur, Brecht +Xu, Yakun Yang, Carol Zang, Mingjie Zbarsky, Boris +Zgrablic, Leonard Zhang, Xili Zhao, Betty Zhao, Ru +``` +Page 4 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Document Control** + +The Matter specification is made of individual chapters such as this one. See Chapter 1 for the list of +all chapters. References between chapters are made using a _X.Y_ notation where _X_ is the chapter and +Y is the sub-section within that chapter. References to external documents are contained in Chapter +1 and are made using _[Rn]_ notation. An update to any of these chapters will be reflected in an +update to the source document list below. + +``` +Chapter 01 — Introduction Document # [./Ch01_Introduction.adoc] +Chapter 02 — Architecture Document # [./Ch02_Architecture.adoc] +Chapter 03 — Cryptographic Primitives Document # [./Ch03_Cryptography.adoc] +Chapter 04 — Secure Channel Document # [./Ch04_Secure_Channel.adoc] +Chapter 05 — Commissioning Document # [./Ch05_Commissioning.adoc] +Chapter 06 — Device Attestation Document # [./Ch06_Attestation.adoc] +Chapter 07 — Data Model Document # [./Ch07_Data_Model.adoc] +Chapter 08 — Interaction Model Document # [./Ch08_Interaction_Model.adoc] +Chapter 09 — System Model Document # [./Ch09_System_Model.adoc] +Chapter 10 — Interaction Encoding Document # [./Ch10_Interaction_Encoding.adoc] +Chapter 11 — Device Management Document # [./Ch07_Management.adoc] +Chapter 12 — Multiple Fabrics Document # [./Ch09_MultipleAdmins.adoc] +Chapter 13 — Security Requirements Document # [./Ch10_Security_Requirements.adoc] +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 5 +``` + +Page 6 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Revision History** + +``` +Revision Date Details Editor +1 May 11, 2020 Initial draft Robert Szewczyk +2 September 23, 2022 Version 1.0 Robert Szewczyk +3 May 17, 2023 Version 1.1 Robert Szewczyk +4 October 18, 2023 Version 1.2 Robert Szewczyk +5 April 17, 2024 Version 1.3 Robert Szewczyk +6 November 4, 2024 Version 1.4 Robert Szewczyk +7 March 17, 2025 Version 1.4.1 Robert Szewczyk +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 7 +``` + +Page 8 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +## Table of Contents + + + + + + + + +- Copyright Notice, License and Disclaimer.   +- Participants.   +- Document Control   +- Revision History.   +- 1. Introduction.   + - 1.1. Scope and Purpose.   + - 1.2. Acronyms and Abbreviations.   + - 1.3. Definitions.   + - 1.4. Standards Terminology Mapping.   + - 1.5. Conformance Levels.   + - 1.6. References.   + - 1.6.1. CSA Reference Documents.   + - 1.6.2. External Reference Documents.   + - 1.7. Informative References.   + - 1.7.1. CSA Reference Documents.   + - 1.8. Conventions.   + - 1.8.1. Enumerations and Reserved Values.   + - 1.8.2. Reserved Bit Fields.   + - 1.8.3. Number Format.   + - 1.8.4. Provisional.   +- 2. Architecture.   + - 2.1. Overview   + - 2.2. Layered Architecture.   + - 2.3. Network Topology.   + - 2.3.1. Single network.   + - 2.3.2. Star network topology.   + - 2.4. Scoped names.   + - 2.5. Identifiers.   + - 2.5.1. Fabric References and Fabric Identifier.   + - 2.5.2. Vendor Identifier (Vendor ID, VID).   + - 2.5.3. Product Identifier (Product ID, PID).   + - 2.5.4. Group Identifier (GID).   + - 2.5.5. Node Identifier.   + - 2.5.6. IPv6 Addressing.   + - 2.6. Device identity.   + - 2.7. Security.   + - 2.8. Device Commissioning.   + - 2.9. Intermittently Connected Device (ICD).   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 2.9.1. Sleepy End Device (SED).   + - 2.10. Data Model Root.   + - 2.11. Stack Limits.   + - 2.11.1. System Model Limits.   + - 2.11.2. Interaction Model Limits   + - 2.12. List of Provisional Items.   + - 2.12.1. Invoke Multiple Paths.   + - 2.12.2. WildcardPathFlags options.   + - 2.12.3. Proxy Service.   + - 2.12.4. Tag compression encoding for AttributePathIB, EventPathIB, and AttributeDataIB.   + - 2.12.5. TCP support flags in TXT records.   + - 2.12.6. CacheAndSync Feature on the GroupKeyManagement cluster.   + - 2.12.7. VendorID Validation Procedure   + - 2.12.8. Joint Fabric.   + - 2.12.9. Wi-Fi Public Action Frame commissioning.   +- 3. Cryptographic Primitives.   + - 3.1. Deterministic Random Bit Generator (DRBG).   + - 3.2. True Random Number Generator (TRNG).   + - 3.3. Hash function (Hash).   + - 3.4. Keyed-Hash Message Authentication Code (HMAC).   + - 3.5. Public Key Cryptography.   + - 3.5.1. Group.   + - 3.5.2. Key generation.   + - 3.5.3. Signature and verification.   + - 3.5.4. ECDH.   + - 3.5.5. Certificate validation.   + - 3.5.6. Time and date considerations for certificate path validation.   + - 3.6. Data Confidentiality and Integrity.   + - 3.6.1. Generate and encrypt.   + - 3.6.2. Decrypt and verify.   + - 3.7. Message privacy.   + - 3.7.1. Privacy encryption.   + - 3.7.2. Privacy decryption.   + - 3.8. Key Derivation Function (KDF).   + - 3.9. Password-Based Key Derivation Function (PBKDF).   + - 3.10. Password-Authenticated Key Exchange (PAKE).   + - 3.10.1. Computation of pA.   + - 3.10.2. Computation of pB.   + - 3.10.3. Computation of transcript TT   + - 3.10.4. Computation of cA, cB and Ke.   +- 4. Secure Channel.   +- 4.1. General Description.   + - 4.1.1. Messages.   +- 4.2. IPv6 Reachability.   + - 4.2.1. Stub Router Behavior.   + - 4.2.2. Matter Node Behavior.   +- 4.3. Discovery.   + - 4.3.1. Commissionable Node Discovery.   + - 4.3.2. Operational Discovery.   + - 4.3.3. Commissioner Discovery.   + - 4.3.4. Common TXT Key/Value Pairs.   +- 4.4. Message Frame Format.   + - 4.4.1. Message Header Field Descriptions.   + - 4.4.2. Message Footer Field Descriptions.   + - 4.4.3. Protocol Header Field Descriptions.   + - 4.4.4. Message Size Requirements.   +- 4.5. Message Framing Over Stream-Oriented Transports.   + - 4.5.1. Message Length (16/32 bits).   +- 4.6. Message Counters.   + - 4.6.1. Message Counter Types.   + - 4.6.2. Secure Session Message Counters.   + - 4.6.3. Check-In Counter.   + - 4.6.4. Message Counters as Encryption Nonces.   + - 4.6.5. Replay Prevention and Duplicate Message Detection.   + - 4.6.6. Counter Processing of Outgoing Messages.   + - 4.6.7. Counter Processing of Incoming Messages.   +- 4.7. Message Processing.   + - 4.7.1. Message Transmission.   + - 4.7.2. Message Reception.   +- 4.8. Message Security.   + - 4.8.1. Data confidentiality and integrity with data origin authentication parameters.   + - 4.8.2. Security Processing of Outgoing Messages.   + - 4.8.3. Security Processing of Incoming Messages.   +- 4.9. Message Privacy.   + - 4.9.1. Privacy Key.   + - 4.9.2. Privacy Nonce.   + - 4.9.3. Privacy Processing of Outgoing Messages.   + - 4.9.4. Privacy Processing of Incoming Messages.   +- 4.10. Message Exchanges.   + - 4.10.1. Exchange Role.   + - 4.10.2. Exchange ID.   + - 4.10.3. Exchange Context.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 4.10.4. Exchange Message Dispatch.   + - 4.10.5. Exchange Message Processing.   +- 4.11. Secure Channel Protocol.   + - 4.11.1. Secure Channel Protocol Messages.   + - 4.11.2. Parameters and Constants.   +- 4.12. Message Reliability Protocol (MRP).   + - 4.12.1. Reliable Messaging Header Fields.   + - 4.12.2. Reliable transfer.   + - 4.12.3. Peer Exchange Management.   + - 4.12.4. Transport Considerations.   + - 4.12.5. Reliable Message Processing.   + - 4.12.6. Reliable Message State.   + - 4.12.7. MRP Messages.   + - 4.12.8. Parameters and Constants.   +- 4.13. Unicast Communication.   + - 4.13.1. Session Parameters.   + - 4.13.2. Session Establishment Phase.   + - 4.13.3. Application Data Phase.   +- 4.14. Session Establishment.   + - 4.14.1. Passcode-Authenticated Session Establishment (PASE).   + - 4.14.2. Certificate Authenticated Session Establishment (CASE).   +- 4.15. Secure Communications over TCP.   + - 4.15.1. Secure Session Establishment.   + - 4.15.2. TCP Connection Management.   +- 4.16. Group Communication.   + - 4.16.1. Groupcast Session Context.   + - 4.16.2. Sending a group message.   + - 4.16.3. Receiving a group message.   +- 4.17. Group Key Management.   + - 4.17.1. Operational Groups.   + - 4.17.2. Operational Group Key Derivation   + - 4.17.3. Epoch Keys.   + - 4.17.4. Distribution of Key Material.   +- 4.18. Message Counter Synchronization Protocol (MCSP).   + - 4.18.1. Message Counter Synchronization Methods.   + - 4.18.2. Group Peer State.   + - 4.18.3. MCSP Messages.   + - 4.18.4. Unsynchronized Message Processing.   + - 4.18.5. Message Counter Synchronization Exchange.   + - 4.18.6. Message Counter Synchronization Session Context.   + - 4.18.7. Sequence Diagram.   + - 4.19. Bluetooth Transport Protocol (BTP).   + - 4.19.1. BTP Session Interface   + - 4.19.2. BTP Frame Format.   + - 4.19.3. BTP Control Frames.   + - 4.19.4. BTP GATT Service.   + - 4.19.5. Parameters and Constants.   + - 4.19.6. Bluetooth SIG Considerations.   + - 4.20. Check-In Protocol.   + - 4.20.1. Requirements.   + - 4.20.2. Message Content.   + - 4.20.3. Algorithms.   + - 4.20.4. Protocol Operation.   +- 5. Commissioning.   + - 5.1. Onboarding Payload.   + - 5.1.1. Onboarding Payload Contents.   + - 5.1.2. Onboarding Material Representation.   + - 5.1.3. QR Code.   + - 5.1.4. Manual Pairing Code.   + - 5.1.5. TLV Content.   + - 5.1.6. Concatenation.   + - 5.1.7. Generation of the Passcode.   + - 5.1.8. NFC Tag.   + - 5.2. Initiating Commissioning.   + - 5.2.1. Purpose and Scope.   + - 5.2.2. User Journey Details.   + - 5.3. User Directed Commissioning.   + - 5.3.1. Overview.   + - 5.3.2. UDC Protocol Messages.   + - 5.3.3. Message format.   + - 5.3.4. Message Exchanges.   + - 5.3.5. IdentificationDeclaration Message.   + - 5.3.6. CommissionerDeclaration Message.   + - 5.3.7. Example Message Exchanges.   + - 5.4. Device Discovery.   + - 5.4.1. Purpose and Scope.   + - 5.4.2. Announcement by Device.   + - 5.4.3. Discovery by Commissioner.   + - 5.5. Commissioning Flows.   + - 5.5.1. Commissioning Flows Error Handling.   + - 5.5.2. Commissioning Flow Diagrams.   + - 5.6. Administrator Assisted Commissioning Flows.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 5.6.1. Introduction.   + - 5.6.2. Basic Commissioning Method (BCM).   + - 5.6.3. Enhanced Commissioning Method (ECM).   + - 5.6.4. Open Commissioning Window.   + - 5.7. Device Commissioning Flows.   + - 5.7.1. Standard Commissioning Flow.   + - 5.7.2. User-Intent Commissioning Flow.   + - 5.7.3. Custom Commissioning Flow.   + - 5.7.4. Enhanced Setup Flow (ESF).   + - 5.7.5. Commissioning Fallback Mechanism.   + - 5.7.6. Manual Pairing Code and QR Code Inclusion.   + - 5.8. In-field Upgrade to Matter.   +- 6. Device Attestation and Operational Credentials.   + - 6.1. Certificate Common Conventions.   + - 6.1.1. Encoding of Matter-specific RDNs.   + - 6.1.2. Key Identifier Extension Constraints.   + - 6.1.3. Certificate Sizes.   + - 6.1.4. Presentation of example certificates.   + - 6.2. Device Attestation.   + - 6.2.1. Introduction.   + - 6.2.2. Device Attestation Certificate (DAC).   + - 6.2.3. Device Attestation Procedure.   + - 6.2.4. Device attestation revocation.   + - 6.3. Certification Declaration.   + - 6.3.1. Certification Declaration (CD) Format.   + - 6.3.2. Firmware Information.   + - 6.3.3. Firmware information validation examples.   + - 6.4. Node Operational Credentials Specification.   + - 6.4.1. Introduction.   + - 6.4.2. Node Operational Credentials Management.   + - 6.4.3. Node Operational Identifier Composition   + - 6.4.4. Node Operational Key Pair.   + - 6.4.5. Node Operational Credentials Certificates.   + - 6.4.6. Node Operational Credentials Procedure.   + - 6.4.7. Node Operational Certificate Signing Request (NOCSR).   + - 6.4.8. Node Operational Certificate Renewal.   + - 6.4.9. Node Operational Certificate Revocation.   + - 6.4.10. VendorID Validation Procedure.   + - 6.4.11. Security Considerations.   + - 6.5. Operational Certificate Encoding.   + - 6.5.1. Introduction.   + - 6.5.2. Matter certificate.   + - 6.5.3. Version Number.   + - 6.5.4. Serial Number.   + - 6.5.5. Signature Algorithm.   + - 6.5.6. Issuer and Subject.   + - 6.5.7. Validity.   + - 6.5.8. Public Key Algorithm.   + - 6.5.9. EC Curve Identifier.   + - 6.5.10. Public Key.   + - 6.5.11. Extensions.   + - 6.5.12. Matter certificate Extensions Encoding Rules.   + - 6.5.13. Signature.   + - 6.5.14. Invalid Matter certificates.   + - 6.5.15. Examples.   + - 6.6. Access Control.   + - 6.6.1. Scope and Purpose.   + - 6.6.2. Model.   + - 6.6.3. Access Control List Examples.   + - 6.6.4. Access Control Cluster update side-effects.   + - 6.6.5. Access Control Cluster handling of Access Restrictions.   + - 6.6.6. Conceptual Access Control Privilege Granting Algorithm.   + - 6.6.7. Applying Privileges to Action Paths.   +- 7. Data Model Specification.   + - 7.1. Practical Information.   + - 7.1.1. Revision History.   + - 7.1.2. Scope & Purpose.   + - 7.1.3. Origin Story.   + - 7.1.4. Overview.   + - 7.1.5. Glossary.   + - 7.1.6. Conventions.   + - 7.2. Data Qualities.   + - 7.2.1. Common Data Table Columns.   + - 7.2.2. Description Section.   + - 7.2.3. Other Data Table Columns.   + - 7.3. Conformance.   + - 7.3.1. Operands in Conformance.   + - 7.3.2. Feature Code in Conformance.   + - 7.3.3. Element in Conformance.   + - 7.3.4. Optional Conformance.   + - 7.3.5. Provisional Conformance.   + - 7.3.6. Mandatory Conformance.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 7.3.7. Disallowed Conformance.   + - 7.3.8. Deprecated Conformance.   + - 7.3.9. Exclusivity Conformance.   + - 7.3.10. Otherwise Conformance.   + - 7.3.11. Quality Conformance.   + - 7.3.12. Expressions and Optionality.   + - 7.3.13. Choice Conformance.   + - 7.3.14. Blank Conformance.   + - 7.3.15. Feature Conformance.   +- 7.4. Element.   + - 7.4.1. Encoded Element Processing.   +- 7.5. Fabric.   + - 7.5.1. Accessing Fabric.   + - 7.5.2. Fabric-Index.   + - 7.5.3. Fabric-Scoped Data.   + - 7.5.4. Fabric-Scoped IDs.   +- 7.6. Access.   + - 7.6.1. Read Access   + - 7.6.2. Write Access.   + - 7.6.3. Invoke Access.   + - 7.6.4. Fabric-Scoped Quality.   + - 7.6.5. Fabric-Sensitive Quality.   + - 7.6.6. View Privilege.   + - 7.6.7. Operate Privilege.   + - 7.6.8. Manage Privilege.   + - 7.6.9. Administer Privilege.   + - 7.6.10. Timed Interaction.   +- 7.7. Other Qualities.   + - 7.7.1. Changes Omitted Quality   + - 7.7.2. Fixed Quality.   + - 7.7.3. Singleton Quality.   + - 7.7.4. Diagnostics Quality.   + - 7.7.5. Large Message Quality.   + - 7.7.6. Non-Volatile Quality.   + - 7.7.7. Reportable Quality.   + - 7.7.8. Quieter Reporting Quality   + - 7.7.9. Scene Quality.   + - 7.7.10. Nullable Quality.   + - 7.7.11. Atomic Quality.   +- 7.8. Node.   +- 7.9. Endpoint.   + + +7.10. Cluster............................................................................  434 + +``` +7.10.1. Cluster Revision...............................................................  434 +7.10.2. Cluster Optional Features.......................................................  435 +7.10.3. Cluster Data Version...........................................................  435 +7.10.4. New Cluster...................................................................  435 +7.10.5. Cluster Aliasing................................................................  436 +7.10.6. Cluster Inheritance.............................................................  436 +7.10.7. Status Codes...................................................................  437 +7.10.8. Cluster Classification...........................................................  438 +``` +7.11. Command.........................................................................  439 + +``` +7.11.1. Command Fields...............................................................  440 +``` +7.12. Attribute..........................................................................  441 + +``` +7.12.1. Persistence....................................................................  441 +``` +7.13. Global Elements...................................................................  442 + +``` +7.13.1. ClusterRevision Attribute.......................................................  443 +7.13.2. FeatureMap Attribute..........................................................  443 +7.13.3. AttributeList Attribute..........................................................  444 +7.13.4. AcceptedCommandList Attribute................................................  444 +7.13.5. GeneratedCommandList Attribute...............................................  445 +7.13.6. FabricIndex Field..............................................................  445 +7.13.7. AtomicRequest Command......................................................  445 +7.13.8. AtomicResponse Command.....................................................  445 +``` +7.14. Event.............................................................................  445 + +``` +7.14.1. Event Record..................................................................  446 +7.14.2. Buffering......................................................................  447 +7.14.3. Event Filtering.................................................................  447 +7.14.4. Fabric-Sensitive Event..........................................................  447 +``` +7.15. Atomic Writes.....................................................................  447 + +``` +7.15.1. Atomic Write Flow.............................................................  448 +7.15.2. Atomic Writer ID..............................................................  448 +7.15.3. Atomic Write State.............................................................  449 +7.15.4. AtomicRequestTypeEnum Type.................................................  449 +7.15.5. AtomicAttributeStatusStruct Type...............................................  450 +7.15.6. AtomicRequest Command......................................................  450 +7.15.7. AtomicResponse Command.....................................................  454 +``` +7.16. Device Type.......................................................................  454 + +``` +7.16.1. Device Type Revision...........................................................  455 +7.16.2. Device Type Composition.......................................................  455 +7.16.3. Device Type Classification......................................................  456 +7.16.4. Extra Clusters on an Endpoint...................................................  457 +7.16.5. Primary Device Type...........................................................  457 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 17 +``` + +``` +7.17. Non-Standard.....................................................................  458 +7.18. Data Field.........................................................................  458 +7.18.1. Nullable.......................................................................  459 +7.18.2. Optional or Deprecated.........................................................  459 +7.18.3. Constraint & Value.............................................................  459 +7.18.4. Default Column................................................................  463 +7.19. Data Types........................................................................  464 +7.19.1. Base Data Types...............................................................  464 +7.19.2. Derived Data Types............................................................  472 +7.20. Manufacturer Specific Extensions...................................................  488 +7.20.1. Manufacturer Extensible Identifiers.............................................  489 +7.20.2. Manufacturer Extensible Identifier (MEI)........................................  489 +7.20.3. Manufacturer Extensions.......................................................  491 +7.20.4. Discoverability................................................................  495 +``` +8. Interaction Model Specification..........................................................  497 + +``` +8.1. Practical Information...............................................................  497 +8.1.1. Revision History................................................................  497 +8.1.2. Scope & Purpose................................................................  497 +8.1.3. Origin Story....................................................................  497 +8.1.4. Purpose........................................................................  498 +8.1.5. Glossary........................................................................  498 +8.1.6. Conventions & Conformance.....................................................  499 +8.2. Concepts...........................................................................  499 +8.2.1. Path...........................................................................  499 +8.2.2. Interaction.....................................................................  503 +8.2.3. Transaction.....................................................................  504 +8.2.4. Action..........................................................................  504 +8.2.5. Common Action Behavior........................................................  505 +8.3. Status and Interaction...............................................................  507 +8.3.1. Status Response Action..........................................................  507 +8.4. Read Interaction....................................................................  508 +8.4.1. Read Transaction...............................................................  509 +8.4.2. Read Request Action.............................................................  509 +8.4.3. Report Data Action..............................................................  510 +8.5. Subscribe Interaction...............................................................  513 +8.5.1. Subscribe Transaction...........................................................  515 +8.5.2. Subscribe Request Action........................................................  515 +8.5.3. Subscribe Response Action.......................................................  517 +8.6. Report Transaction..................................................................  518 +8.6.1. Report Transaction Non-Empty...................................................  518 +8.6.2. Report Transaction Empty.......................................................  518 +``` +``` +Page 18 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +8.7. Write Interaction...................................................................  519 +8.7.1. Write Transaction...............................................................  519 +8.7.2. Write Request Action............................................................  519 +8.7.3. Write Response Action..........................................................  521 +8.7.4. Timed Request Action...........................................................  523 +8.8. Invoke Interaction..................................................................  523 +8.8.1. Invoke Transaction..............................................................  523 +8.8.2. Invoke Request Action...........................................................  524 +8.8.3. Invoke Response Action.........................................................  528 +8.9. Common Action Information Blocks and Paths........................................  529 +8.9.1. Path Information...............................................................  529 +8.9.2. Attribute Information Blocks.....................................................  529 +8.9.3. Event Information Blocks and Paths..............................................  535 +8.9.4. Command Information Blocks and Paths..........................................  537 +8.9.5. Status Information Blocks and Paths..............................................  538 +8.10. Status Codes.......................................................................  540 +8.10.1. Status Code Table..............................................................  540 +``` +9. System Model Specification..............................................................  545 + +``` +9.1. Practical Information...............................................................  545 +9.1.1. Revision History................................................................  545 +9.1.2. Scope and Purpose..............................................................  545 +9.1.3. Origin Story....................................................................  545 +9.1.4. Overview.......................................................................  545 +9.2. Endpoint Composition...............................................................  545 +9.2.1. Endpoint Composition Patterns..................................................  547 +9.2.2. Root Node Endpoint.............................................................  548 +9.2.3. Disambiguation.................................................................  549 +9.2.4. Dynamic Endpoint Allocation....................................................  551 +9.2.5. Superset Device Types...........................................................  552 +9.3. Interaction Model Relationships......................................................  553 +9.3.1. Subscription....................................................................  553 +9.4. Binding Relationship................................................................  553 +9.5. Descriptor Cluster...................................................................  554 +9.5.1. Revision History................................................................  554 +9.5.2. Classification...................................................................  555 +9.5.3. Cluster ID......................................................................  555 +9.5.4. Features........................................................................  555 +9.5.5. Data Types.....................................................................  555 +9.5.6. Attributes......................................................................  556 +9.6. Binding Cluster.....................................................................  557 +9.6.1. Binding Mutation...............................................................  558 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 19 +``` + +``` +9.6.2. Revision History................................................................  558 +9.6.3. Classification...................................................................  558 +9.6.4. Cluster ID......................................................................  558 +9.6.5. Data Types.....................................................................  558 +9.6.6. Attributes......................................................................  559 +9.7. Label Cluster.......................................................................  560 +9.7.1. Revision History................................................................  560 +9.7.2. Classification...................................................................  560 +9.7.3. Cluster ID......................................................................  560 +9.7.4. Data Types.....................................................................  561 +9.7.5. Attributes......................................................................  561 +9.8. Fixed Label Cluster.................................................................  561 +9.8.1. Revision History................................................................  562 +9.8.2. Classification...................................................................  562 +9.8.3. Cluster ID......................................................................  562 +9.8.4. Attributes......................................................................  562 +9.9. User Label Cluster..................................................................  562 +9.9.1. Revision History................................................................  562 +9.9.2. Classification...................................................................  563 +9.9.3. Cluster ID......................................................................  563 +9.9.4. Attributes......................................................................  563 +9.10. Access Control Cluster..............................................................  563 +9.10.1. Revision History...............................................................  563 +9.10.2. Classification..................................................................  564 +9.10.3. Cluster ID.....................................................................  564 +9.10.4. Features.......................................................................  564 +9.10.5. Data Types....................................................................  565 +9.10.6. Attributes.....................................................................  575 +9.10.7. Error handling.................................................................  580 +9.10.8. Commands....................................................................  580 +9.10.9. Events........................................................................  582 +9.11. Group Relationship................................................................  588 +9.12. Bridge for non-Matter devices......................................................  589 +9.12.1. Introduction...................................................................  589 +9.12.2. Exposing functionality and metadata of Bridged Devices..........................  589 +9.12.3. Discovery of Bridged Devices...................................................  594 +9.12.4. Configuration of Bridged Devices................................................  594 +9.12.5. New features for Bridged Devices...............................................  596 +9.12.6. Changes to the set of Bridged Devices............................................  596 +9.12.7. Changes to device names and grouping of Bridged Devices........................  597 +9.12.8. Setup flow for a Bridge (plus Bridged Devices)....................................  597 +``` +Page 20 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +9.12.9. Access Control.................................................................  597 +9.12.10. Software update (OTA)........................................................  597 +9.12.11. Best practices for Bridge Manufacturers........................................  598 +9.12.12. Best practices for Administrators...............................................  599 +``` +9.13. Bridged Device Basic Information Cluster............................................  599 + +``` +9.13.1. Revision History...............................................................  599 +9.13.2. Classification..................................................................  600 +9.13.3. Cluster ID.....................................................................  600 +9.13.4. Features.......................................................................  600 +9.13.5. Attributes.....................................................................  600 +9.13.6. Commands....................................................................  602 +9.13.7. Events........................................................................  604 +``` +9.14. Actions Cluster....................................................................  605 + +``` +9.14.1. Revision History...............................................................  606 +9.14.2. Classification..................................................................  606 +9.14.3. Cluster ID.....................................................................  606 +9.14.4. Data Types....................................................................  606 +9.14.5. Attributes.....................................................................  611 +9.14.6. Commands....................................................................  612 +9.14.7. Events........................................................................  618 +9.14.8. Examples.....................................................................  620 +``` +9.15. Proxy Architecture.................................................................  626 + +``` +9.15.1. Motivation....................................................................  626 +9.15.2. Subscription Proxy: Overview...................................................  626 +9.15.3. Composition & Paths...........................................................  627 +9.15.4. Proxy Subscriptions............................................................  628 +9.15.5. Schemas and Data Serialization/Deserialization..................................  630 +9.15.6. Indirect Proxies................................................................  630 +9.15.7. Proxy Discovery & Assignment Flow.............................................  630 +9.15.8. Constraints....................................................................  637 +9.15.9. Certification...................................................................  638 +9.15.10. Security & Privacy............................................................  638 +9.15.11. Parameters and Constants.....................................................  639 +9.15.12. Proxy Discovery Cluster.......................................................  639 +9.15.13. Proxy Configuration Cluster...................................................  641 +9.15.14. Valid Proxies Cluster..........................................................  643 +``` +9.16. Intermittently Connected Devices Behavior..........................................  644 + +``` +9.16.1. ICD Server Behavior............................................................  644 +9.16.2. ICD Client Behavior............................................................  652 +``` +9.17. ICD Management Cluster...........................................................  658 + +``` +9.17.1. Revision History...............................................................  658 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 21 +``` + +``` +9.17.2. Classification..................................................................  659 +9.17.3. Cluster ID.....................................................................  659 +9.17.4. Features.......................................................................  659 +9.17.5. Data Types....................................................................  660 +9.17.6. Attributes.....................................................................  663 +9.17.7. Commands....................................................................  669 +9.18. Ecosystem Information Cluster.....................................................  675 +9.18.1. Revision History...............................................................  675 +9.18.2. Classification..................................................................  676 +9.18.3. Cluster ID.....................................................................  676 +9.18.4. Data Types....................................................................  676 +9.18.5. Attributes.....................................................................  678 +9.18.6. Examples.....................................................................  679 +``` +10. Interaction Model Encoding Specification................................................  681 + +``` +10.1. Overview.........................................................................  681 +10.2. Messages..........................................................................  681 +10.2.1. IM Protocol Messages..........................................................  681 +10.2.2. Common Action Information Encoding..........................................  681 +10.2.3. Chunking.....................................................................  682 +10.2.4. Transaction Flows.............................................................  683 +10.3. Data Types........................................................................  686 +10.3.1. Analog - Integer................................................................  687 +10.3.2. Analog - Floating Point.........................................................  687 +10.3.3. Discrete - Enumeration.........................................................  687 +10.3.4. Discrete - Bitmap...............................................................  688 +10.3.5. Composite - String.............................................................  688 +10.3.6. Composite - Octet String........................................................  688 +10.3.7. Collection - Struct..............................................................  688 +10.3.8. Collection - List................................................................  688 +10.3.9. Derived Types.................................................................  688 +10.3.10. Field IDs.....................................................................  688 +10.4. Sample Clusters...................................................................  688 +10.4.1. Disco Ball Cluster..............................................................  688 +10.4.2. Super Disco Ball Cluster........................................................  698 +10.5. Sample Device Types...............................................................  700 +10.5.1. Disco Ball Device Type..........................................................  700 +10.5.2. Super Disco Ball Device Type....................................................  702 +10.5.3. Disco Spot Device Type.........................................................  703 +10.5.4. Disco Dance System Device Type................................................  704 +10.5.5. Weather Station Device Type....................................................  705 +10.6. Information Blocks................................................................  706 +``` +``` +Page 22 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +10.6.1. Tag Rules......................................................................  706 +10.6.2. AttributePathIB................................................................  706 +10.6.3. DataVersionFilterIB............................................................  710 +10.6.4. AttributeDataIB................................................................  710 +10.6.5. AttributeReportIB..............................................................  713 +10.6.6. EventFilterIB..................................................................  714 +10.6.7. ClusterPathIB..................................................................  714 +10.6.8. EventPathIB...................................................................  714 +10.6.9. EventDataIB...................................................................  715 +10.6.10. EventReportIB................................................................  716 +10.6.11. CommandPathIB..............................................................  717 +10.6.12. CommandDataIB.............................................................  717 +10.6.13. InvokeResponseIB............................................................  718 +10.6.14. CommandStatusIB............................................................  719 +10.6.15. EventStatusIB................................................................  719 +10.6.16. AttributeStatusIB.............................................................  719 +10.6.17. StatusIB......................................................................  719 +10.7. Message Definitions................................................................  720 +10.7.1. StatusResponseMessage........................................................  720 +10.7.2. ReadRequestMessage...........................................................  720 +10.7.3. ReportDataMessage............................................................  721 +10.7.4. SubscribeRequestMessage......................................................  723 +10.7.5. SubscribeResponseMessage.....................................................  724 +10.7.6. WriteRequestMessage..........................................................  724 +10.7.7. WriteResponseMessage.........................................................  725 +10.7.8. TimedRequestMessage.........................................................  725 +10.7.9. InvokeRequestMessage.........................................................  725 +10.7.10. InvokeResponseMessage......................................................  725 +``` +11. Service and Device Management........................................................  727 + +``` +11.1. Basic Information Cluster..........................................................  727 +11.1.1. Revision History...............................................................  727 +11.1.2. Classification..................................................................  727 +11.1.3. Cluster ID.....................................................................  727 +11.1.4. Data Types....................................................................  727 +11.1.5. Attributes.....................................................................  730 +11.1.6. Events........................................................................  736 +11.2. Group Key Management Cluster.....................................................  737 +11.2.1. Revision History...............................................................  738 +11.2.2. Classification..................................................................  738 +11.2.3. Cluster ID.....................................................................  738 +11.2.4. Features.......................................................................  738 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 23 +``` + +``` +11.2.5. Data Types....................................................................  738 +11.2.6. Attributes.....................................................................  742 +11.2.7. Commands....................................................................  743 +11.3. Localization Configuration Cluster..................................................  747 +11.3.1. Revision History...............................................................  747 +11.3.2. Classification..................................................................  747 +11.3.3. Cluster ID.....................................................................  747 +11.3.4. Attributes.....................................................................  747 +11.4. Time Format Localization Cluster...................................................  748 +11.4.1. Revision History...............................................................  748 +11.4.2. Classification..................................................................  748 +11.4.3. Cluster ID.....................................................................  748 +11.4.4. Features.......................................................................  748 +11.4.5. Data Types....................................................................  749 +11.4.6. Attributes.....................................................................  750 +11.5. Unit Localization Cluster...........................................................  751 +11.5.1. Revision History...............................................................  751 +11.5.2. Classification..................................................................  751 +11.5.3. Cluster ID.....................................................................  751 +11.5.4. Features.......................................................................  751 +11.5.5. Data Types....................................................................  752 +11.5.6. Attributes.....................................................................  752 +11.6. Power Source Configuration Cluster.................................................  752 +11.6.1. Revision History...............................................................  752 +11.6.2. Classification..................................................................  752 +11.6.3. Cluster ID.....................................................................  753 +11.6.4. Attributes.....................................................................  753 +11.7. Power Source Cluster..............................................................  753 +11.7.1. Revision History...............................................................  753 +11.7.2. Classification..................................................................  754 +11.7.3. Cluster ID.....................................................................  754 +11.7.4. Features.......................................................................  754 +11.7.5. Dependencies.................................................................  754 +11.7.6. Data Types....................................................................  754 +11.7.7. Attributes.....................................................................  764 +11.7.8. Events........................................................................  772 +11.7.9. Configuration Examples........................................................  774 +11.8. Power Topology Cluster............................................................  776 +11.8.1. Revision History...............................................................  776 +11.8.2. Classification..................................................................  776 +11.8.3. Cluster ID.....................................................................  776 +``` +Page 24 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +11.8.4. Features.......................................................................  776 +11.8.5. Attributes.....................................................................  777 +``` +11.9. Network Commissioning Cluster....................................................  777 + +``` +11.9.1. Revision History...............................................................  778 +11.9.2. Classification..................................................................  778 +11.9.3. Cluster ID.....................................................................  778 +11.9.4. Features.......................................................................  778 +11.9.5. Data Types....................................................................  778 +11.9.6. Attributes.....................................................................  783 +11.9.7. Commands....................................................................  786 +11.9.8. Usage of networking configurations.............................................  800 +``` +11.10. General Commissioning Cluster....................................................  802 + +``` +11.10.1. Revision History..............................................................  802 +11.10.2. Classification.................................................................  802 +11.10.3. Cluster ID....................................................................  802 +11.10.4. Features.....................................................................  802 +11.10.5. Data Types...................................................................  803 +11.10.6. Attributes....................................................................  805 +11.10.7. Commands...................................................................  808 +``` +11.11. Diagnostic Logs Cluster............................................................  816 + +``` +11.11.1. Revision History..............................................................  816 +11.11.2. Classification.................................................................  816 +11.11.3. Cluster ID....................................................................  817 +11.11.4. Data Types...................................................................  817 +11.11.5. Commands...................................................................  819 +``` +11.12. General Diagnostics Cluster........................................................  821 + +``` +11.12.1. Revision History..............................................................  821 +11.12.2. Classification.................................................................  821 +11.12.3. Cluster ID....................................................................  821 +11.12.4. Features.....................................................................  822 +11.12.5. Data Types...................................................................  822 +11.12.6. Attributes....................................................................  827 +11.12.7. Commands...................................................................  829 +11.12.8. Events.......................................................................  833 +``` +11.13. Software Diagnostics Cluster.......................................................  835 + +``` +11.13.1. Revision History..............................................................  835 +11.13.2. Classification.................................................................  835 +11.13.3. Cluster ID....................................................................  835 +11.13.4. Features.....................................................................  836 +11.13.5. Data Types...................................................................  836 +11.13.6. Attributes....................................................................  837 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 25 +``` + +``` +11.13.7. Commands...................................................................  837 +11.13.8. Events.......................................................................  838 +11.14. Thread Network Diagnostics Cluster................................................  839 +11.14.1. Revision History..............................................................  839 +11.14.2. Classification.................................................................  839 +11.14.3. Cluster ID....................................................................  839 +11.14.4. Features.....................................................................  839 +11.14.5. Data Types...................................................................  840 +11.14.6. Attributes....................................................................  847 +11.14.7. Commands...................................................................  859 +11.14.8. Events.......................................................................  859 +11.15. Wi-Fi Network Diagnostics Cluster.................................................  860 +11.15.1. Revision History..............................................................  860 +11.15.2. Classification.................................................................  861 +11.15.3. Cluster ID....................................................................  861 +11.15.4. Features.....................................................................  861 +11.15.5. Data Types...................................................................  861 +11.15.6. Attributes....................................................................  863 +11.15.7. Commands...................................................................  865 +11.15.8. Events.......................................................................  866 +11.16. Ethernet Network Diagnostics Cluster..............................................  867 +11.16.1. Revision History..............................................................  867 +11.16.2. Classification.................................................................  868 +11.16.3. Cluster ID....................................................................  868 +11.16.4. Features.....................................................................  868 +11.16.5. Data Types...................................................................  868 +11.16.6. Attributes....................................................................  869 +11.16.7. Commands...................................................................  870 +11.17. Time Synchronization Cluster......................................................  871 +11.17.1. Revision History..............................................................  871 +11.17.2. Classification.................................................................  871 +11.17.3. Cluster ID....................................................................  871 +11.17.4. Terminology..................................................................  872 +11.17.5. Features.....................................................................  872 +11.17.6. Data Types...................................................................  873 +11.17.7. Status Codes..................................................................  878 +11.17.8. Attributes....................................................................  878 +11.17.9. Commands...................................................................  882 +11.17.10. Events......................................................................  885 +11.17.11. Time Synchronization at Commissioning......................................  887 +11.17.12. Time Synchronization during operation.......................................  887 +``` +Page 26 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +11.17.13. Time source prioritization....................................................  887 +11.17.14. Time synchronization maintenance...........................................  888 +11.17.15. Acting as an NTP Server......................................................  888 +11.17.16. Implementation Guidance....................................................  888 +``` +11.18. Node Operational Credentials Cluster..............................................  891 + +``` +11.18.1. Revision History..............................................................  891 +11.18.2. Classification.................................................................  891 +11.18.3. Cluster ID....................................................................  891 +11.18.4. Data Types...................................................................  891 +11.18.5. Attributes....................................................................  898 +11.18.6. Commands...................................................................  900 +``` +11.19. Administrator Commissioning Cluster..............................................  913 + +``` +11.19.1. Revision History..............................................................  914 +11.19.2. Classification.................................................................  914 +11.19.3. Cluster ID....................................................................  914 +11.19.4. Features.....................................................................  914 +11.19.5. Data Types...................................................................  914 +11.19.6. Status Codes..................................................................  915 +11.19.7. Attributes....................................................................  915 +11.19.8. Commands...................................................................  916 +``` +11.20. Over-the-Air (OTA) Software Update................................................  920 + +``` +11.20.1. Scope & Purpose..............................................................  920 +11.20.2. Functional overview..........................................................  920 +11.20.3. Software update workflow....................................................  921 +11.20.4. Security considerations........................................................  940 +11.20.5. Some special situations........................................................  941 +11.20.6. OTA Software Update Provider Cluster..........................................  942 +11.20.7. OTA Software Update Requestor Cluster........................................  952 +``` +11.21. Over-the-Air (OTA) Software Update File Format....................................  963 + +``` +11.21.1. Scope & Purpose..............................................................  963 +11.21.2. General Structure.............................................................  963 +11.21.3. Security considerations........................................................  966 +``` +11.22. Bulk Data Exchange Protocol (BDX)................................................  967 + +``` +11.22.1. Overview....................................................................  967 +11.22.2. Terminology..................................................................  967 +11.22.3. Protocol Opcodes and Status Report Values......................................  968 +11.22.4. Security and Transport Constraints.............................................  970 +11.22.5. Transfer Management Messages...............................................  971 +11.22.6. Data Transfer Messages.......................................................  980 +11.22.7. Synchronous Transfers Message Flows.........................................  985 +11.22.8. Asynchronous Transfers Message Flows........................................  993 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 27 +``` + +``` +11.23. Distributed Compliance Ledger....................................................  995 +11.23.1. Scope & Purpose..............................................................  995 +11.23.2. Schemas.....................................................................  996 +11.23.3. Vendor Schema...............................................................  997 +11.23.4. Product Attestation Authority and Intermediate Certificate Schema...............  999 +11.23.5. Operational Root and Intermediate Certificate Schema..........................  1001 +11.23.6. DeviceModel Schema........................................................  1003 +11.23.7. DeviceSoftwareVersionModel Schema.........................................  1008 +11.23.8. DeviceSoftwareCompliance / Compliance test result Schema.....................  1011 +11.23.9. Device Attestation PKI Revocation Distribution Points Schema...................  1013 +11.23.10. APIs / CLI..................................................................  1019 +11.24. Joint Fabric Datastore Cluster.....................................................  1019 +11.24.1. Revision History.............................................................  1019 +11.24.2. Classification................................................................  1020 +11.24.3. Cluster ID...................................................................  1020 +11.24.4. Usage Requirements.........................................................  1020 +11.24.5. Data Types..................................................................  1024 +11.24.6. Attributes...................................................................  1031 +11.24.7. Commands..................................................................  1033 +11.25. Joint Fabric PKI Cluster..........................................................  1049 +11.25.1. Revision History.............................................................  1049 +11.25.2. Classification................................................................  1049 +11.25.3. Cluster ID...................................................................  1049 +11.25.4. Data Types..................................................................  1050 +11.25.5. Commands..................................................................  1051 +11.26. Commissioner Control Cluster....................................................  1052 +11.26.1. Revision History.............................................................  1053 +11.26.2. Classification................................................................  1053 +11.26.3. Cluster ID...................................................................  1053 +11.26.4. Data Types..................................................................  1053 +11.26.5. Attributes...................................................................  1054 +11.26.6. Commands..................................................................  1054 +11.26.7. Events......................................................................  1057 +``` +12. Multiple Fabrics......................................................................  1059 + +``` +12.1. Introduction.....................................................................  1059 +12.2. Joint Fabric......................................................................  1059 +12.2.1. Introduction..................................................................  1059 +12.2.2. Node ID Generation...........................................................  1059 +12.2.3. Anchor ICAC requirements....................................................  1059 +12.2.4. Joint Fabric ACL Architecture..................................................  1060 +12.2.5. Joint Commissioning Method (JCM).............................................  1061 +``` +``` +Page 28 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +12.2.6. Anchor Administrator Selection................................................  1065 +12.2.7. Administrator Removal........................................................  1067 +12.3. User Consent.....................................................................  1067 +12.4. Administrator-Assisted Commissioning Method.....................................  1067 +12.5. Node Behavior...................................................................  1068 +12.6. Fabric Synchronization...........................................................  1068 +12.6.1. Introduction..................................................................  1068 +12.6.2. Terminology..................................................................  1068 +12.6.3. Fabric Synchronization Composition...........................................  1069 +12.6.4. Preventing Device Duplication.................................................  1070 +12.6.5. Changes to device and locations of Synchronized Devices........................  1071 +12.6.6. Changes to the set of Synchronized Devices.....................................  1072 +12.6.7. Fabric Synchronized Relationships.............................................  1072 +12.6.8. Setup flow for Fabric Synchronization..........................................  1072 +``` +13. Security Requirements................................................................  1079 + +``` +13.1. Overview........................................................................  1079 +13.2. Device vs. Node...................................................................  1079 +13.3. Commissioning...................................................................  1079 +13.4. Factory Reset.....................................................................  1080 +13.5. Firmware........................................................................  1080 +13.6. Security Best Practices............................................................  1081 +13.6.1. Cryptography.................................................................  1081 +13.6.2. Commissioning and Administration............................................  1081 +13.6.3. Firmware....................................................................  1082 +13.6.4. Manufacturing...............................................................  1082 +13.6.5. Resiliency....................................................................  1082 +13.6.6. Battery Powered Devices......................................................  1082 +13.6.7. Tamper Resistance............................................................  1082 +13.6.8. Bridging.....................................................................  1082 +13.6.9. Distributed Compliance Ledger................................................  1083 +13.6.10. Safety.......................................................................  1083 +13.7. Threats and Countermeasures.....................................................  1083 +``` +Appendix A: Tag-length-value (TLV) Encoding Format.......................................  1103 + +``` +A.1. Scope & Purpose...................................................................  1103 +A.2. Tags..............................................................................  1103 +A.2.1. Profile-Specific Tags...........................................................  1103 +A.2.2. Context-Specific Tags...........................................................  1103 +A.2.3. Anonymous Tags..............................................................  1104 +A.2.4. Canonical Ordering of Tags.....................................................  1104 +A.3. Lengths...........................................................................  1104 +A.4. Primitive Types...................................................................  1104 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 29 +``` + +``` +A.5. Container Types...................................................................  1105 +A.5.1. Structures.....................................................................  1105 +A.5.2. Arrays........................................................................  1105 +A.5.3. Lists..........................................................................  1105 +A.6. Element Encoding.................................................................  1106 +A.7. Control Octet Encoding.............................................................  1106 +A.7.1. Element Type Field............................................................  1106 +A.7.2. Tag Control Field..............................................................  1108 +A.8. Tag Encoding......................................................................  1108 +A.8.1. Fully-Qualified Tag Form.......................................................  1108 +A.8.2. Implicit Profile Tag Form.......................................................  1109 +A.8.3. Common Profile Tag Form......................................................  1109 +A.8.4. Context-Specific Tag Form......................................................  1109 +A.8.5. Anonymous Tag Form..........................................................  1109 +A.9. Length Encoding..................................................................  1109 +A.10. End of Container Encoding........................................................  1110 +A.11. Value Encodings..................................................................  1110 +A.11.1. Integers......................................................................  1110 +A.11.2. UTF-8 and Octet Strings.......................................................  1110 +A.11.3. Booleans.....................................................................  1110 +A.11.4. Arrays, Structures and Lists...................................................  1111 +A.11.5. Floating Point Numbers.......................................................  1111 +A.11.6. Nulls........................................................................  1111 +A.12. TLV Encoding Examples...........................................................  1111 +``` +Appendix B: Tag-length-value (TLV) Schema Definitions.....................................  1115 + +``` +B.1. Introduction......................................................................  1115 +B.1.1. Basic Structure................................................................  1115 +B.1.2. Keywords.....................................................................  1115 +B.1.3. Naming.......................................................................  1115 +B.1.4. Namespaces...................................................................  1116 +B.1.5. Qualifiers.....................................................................  1116 +B.1.6. Tagging.......................................................................  1117 +B.2. Definitions........................................................................  1117 +B.2.1. Type Definition (type-def )......................................................  1117 +B.2.2. FIELD GROUP Definition (field-group-def ).......................................  1118 +B.2.3. Namespace Definition (namespace-def )..........................................  1120 +B.2.4. PROTOCOL Definition (protocol-def ).............................................  1121 +B.2.5. VENDOR Definition (vendor-def )................................................  1122 +B.3. Types.............................................................................  1123 +B.3.1. ARRAY / ARRAY OF.............................................................  1123 +B.3.2. BOOLEAN.....................................................................  1125 +``` +``` +Page 30 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### B.3.3. FLOAT32 / FLOAT64............................................................  1125 + +### B.3.4. SIGNED INTEGER / UNSIGNED INTEGER.........................................  1126 + +### B.3.5. LIST / LIST OF.................................................................  1127 + +### B.3.6. OCTET STRING................................................................  1128 + +### B.3.7. NULL.........................................................................  1128 + +### B.3.8. STRING.......................................................................  1129 + +### B.3.9. STRUCTURE...................................................................  1129 + +``` +B.4. Pseudo-Types.....................................................................  1132 +B.4.1. ANY..........................................................................  1132 +B.4.2. CHOICE OF....................................................................  1132 +B.5. Qualifiers.........................................................................  1135 +B.5.1. any-order / schema-order / tag-order............................................  1135 +B.5.2. extensible.....................................................................  1135 +B.5.3. id.............................................................................  1136 +B.5.4. length........................................................................  1137 +B.5.5. nullable.......................................................................  1137 +B.5.6. optional.......................................................................  1138 +B.5.7. range.........................................................................  1138 +B.5.8. tag............................................................................  1139 +B.5.9. Documentation and Comments.................................................  1141 +``` +Appendix C: Tag-length-value (TLV) Payload Text Representation Format.....................  1143 + +``` +C.1. Introduction......................................................................  1143 +C.2. Format Specification...............................................................  1143 +C.2.1. Tag/Value.....................................................................  1143 +C.2.2. Context-Specific Tags...........................................................  1143 +C.2.3. Protocol-Specific Tags..........................................................  1143 +C.2.4. Anonymous Tags..............................................................  1144 +C.2.5. Primitive Types................................................................  1144 +C.2.6. Complex Types: Structure......................................................  1145 +C.2.7. Complex Types: Arrays.........................................................  1145 +C.2.8. Complex Types: List............................................................  1145 +C.3. Examples.........................................................................  1145 +C.3.1. TLV Schema...................................................................  1145 +C.3.2. TLV Payloads..................................................................  1146 +``` +Appendix D: Status Report Messages......................................................  1149 + +``` +D.1. Overview.........................................................................  1149 +D.2. Status Report elements.............................................................  1149 +D.3. Message Format...................................................................  1149 +D.3.1. General status codes (GeneralCode)..............................................  1150 +D.3.2. Protocol-specific codes (ProtocolId and ProtocolCode).............................  1150 +D.3.3. Protocol-specific data (ProtocolData).............................................  1151 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 31 +``` + +``` +D.4. Presenting StatusReport messages in protocol specifications..........................  1151 +``` +Appendix E: Matter-Specific ASN.1 Object Identifiers (OIDs).................................  1153 + +Appendix F: Cryptographic test vectors for some procedures................................  1155 + +``` +F.1. Certification Declaration CMS test vector............................................  1155 +F.2. Device Attestation Response test vector..............................................  1158 +F.3. Node Operational CSR Response test vector..........................................  1162 +F.4. Check-In Protocol test vectors.......................................................  1166 +``` +Appendix G: Minimal Resource Requirements..............................................  1171 + +``` +Page 32 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 1. Introduction** + +The Matter specification defines fundamental requirements to enable an interoperable application +layer solution for smart home devices over the Internet Protocol. + +**1.1. Scope and Purpose** + +This specification details everything necessary to implement an application and transport layer +stack. It is intended to be used by implementers as a complete specification but where necessary +other references are noted with details on how these references apply to this specification. + +In case of discrepancies between this specification and the SDK [https://github.com/project-chip/connect­ +edhomeip/], this specification SHALL take precedence. + +**1.2. Acronyms and Abbreviations** + +``` +Acronym Definition +ACL Access Control List +AGID Application Group Identifier +AEAD Authenticated Encryption with Associated Data +AES Advanced Encryption Standard (from FIPS 197) +AP Access Point (from IEEE 802.11-2020) +API Application Programming Interface +ASN.1 Abstract Syntax Notation 1 (from ITU ASN.1) +BLE Bluetooth Low Energy +BDX Bulk Data Exchange +BSS Basic Service Set (from IEEE 802.11-2020) +BSSID Basic Service Set Identifier (from IEEE 802.11-2020) +BTP Bluetooth Transport Protocol +CA Certificate Authority (also known as Certification Authority) +CASE Certificate Authenticated Session Establishment +CAT CASE Authenticated Tag +CBC-MAC Cipher Block Chaining Message Authentication Code +CCM Counter mode of encryption with CBC-MAC (AEAD mode) (from +NIST 800-38C) +CD Certification Declaration +CMS Cryptographic Message Syntax +CN Common Name (from X.520) +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 33 +``` + +``` +Acronym Definition +CSR Certificate Signing Request +CTR Counter Mode (AES block cipher mode) (from NIST 800-38A) +DAC Device Attestation Certificate +DER Distinguished Encoding Rule (from X.690) +DN Distinguished Name (from X.520) +DNS Domain Name System +DNS-SD DNS Based Service Discovery (from RFC 6763) +DRBG Deterministic Random Bit Generator (from NIST 800-90A) +ECC Elliptic Curve Cryptography (from SEC 1) (also "Error Correction +Code") +ECDHE Elliptic Curve Ephemeral Diffie-Hellman (from SEC 1) +ECDSA Elliptic Curve Digital Signature Algorithm (from SEC 1) +EUI Extended Unique Identifier +EUI-64 64-bit EUI +GATT Bluetooth Generic Attribute Profile +GID Group Identifier (also referred to as "Group ID") +GKH Group Key Hash +GUA Global Unicast Address +HMAC Keyed-Hash Message Authentication Code (from FIPS 198-1) +ICD Intermittently Connected Device +ID Identifier +IP Internet Protocol +IPK Identity Protection Key (a Universal Group key shared across a Fab­ +ric) +KDF Key Derivation Function (from RFC 5869) +KDM Key Derivation Method (from RFC 5869) +LLA Link local address +LLN Low power and Lossy Network +MAC Medium Access Control (or "Message Authentication Code") +MCSP Message Counter Synchronization Protocol +MIC Message Integrity Code (used as synonym for MAC (Message Authen­ +tication Code) to avoid confusion with MAC (Medium Access Control) +as used in network addressing contexts) +MRP Message Reliability Protocol +``` +Page 34 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Acronym Definition** + +NFC Near Field Communication + +NOC Node Operational Certificate + +NOCSR Node Operational Certificate Signing Request + +OID Object Identifier (from ITU ASN.1) + +OTA Over-the-air (used mostly in context of "Over-the-air Software +Update") + +PAA Product Attestation Authority + +PAI Product Attestation Intermediate + +PAKE Password-Authenticated Key Exchange (from SPAKE2+) + +PASE Passcode-Authenticated Session Establishment + +PBKDF Password-Based Key Derivation Function (from NIST 800-132) + +PDU Protocol Data Unit + +PID Product Identifier (also Product ID) + +PIN Personal Identification Number + +PKI Public Key Infrastructure + +PSK Pre-Shared Key + +QR code Quick Response (code) + +SDU Service Data Unit + +SED Sleepy End Device + +SHA Secure Hash Algorithm (from FIPS 180-4) + +SRP Service Registration Protocol (from SRP) + +TCP Transmission Control Protocol + +TFTP Trivial File Transfer Protocol (from RFC 1350) + +TLV Tag Length Value (refers mostly to Tag-length-value (TLV) Encoding +Format) + +TRNG True Random Number Generator (from NIST 800-90B) + +TU Transmission Unit + +UDP User Datagram Protocol + +UGID Universal Group Identifier + +ULA Unique local address + +UTC Universal Time Coordinated + +UUID Universally Unique Identifier + +VID Vendor Identifier (also Vendor ID) + +ZCL Zigbee Cluster Library + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 35 +``` + +**1.3. Definitions** + +``` +Term Definition +Access Control List A list of entries in the Access Control Cluster expressing individual rules which +grant privileges to access cluster elements. +Administrator A Node having Administer privilege over at least the Access Control Cluster of +another Node. +Advertising Data A data container used in BLE Advertisements to convey a logical grouping of +information. +Anchor CA This RCAC belongs to Anchor Fabric and is trusted by all devices in Joint Fab­ +ric. It also signs ICA belonging to other fabrics that participate in Joint Fabric. +Identical with the TRCA of the Joint Fabric. +Anchor Fabric This is the fabric that “anchors” Joint Fabric because its operational root CA is +trusted by all other fabrics in the Joint Fabric. +Anchor Adminis­ +trator +``` +``` +Administrator that has the ability to interact with the Anchor CA. +``` +``` +Attribute A data entity which represents a physical quantity or state. This data is com­ +municated to other Nodes using commands. +Binding A persistent attachment between an instance on one Node to one-or-more cor­ +responding instances on another (or the same) Node. +Border Router A router, also known as Edge Router, that provides routing services between +two IP subnets (typically, between a hub network and a peripheral network). +Bridge A Node that represents one or more non-Matter devices on the Fabric. +Bridged Device A non-Matter device that is represented on the Fabric by a Bridge so it can be +used by Nodes on the Fabric. +Broadcast The transmission of a message to every Node in a particular broadcast +domain, be it all Nodes on a Ethernet or Wi-Fi link, and/or all Nodes on a +Thread mesh. +Certificate Author­ +ity (CA) +``` +``` +An entity that issues digital certificates such as a DAC or NOC +``` +``` +Certification Dec­ +laration +``` +``` +A digitally signed token that conveys Matter certification status of a vendor’s +certified Device. +Client A Cluster interface that typically sends commands that manipulate the attrib­ +utes on the corresponding server cluster. A client cluster communicates with a +corresponding remote server cluster with the same cluster identifier. +Cluster A specification defining one or more attributes, commands, behaviors and +dependencies, that supports an independent utility or application function. +The term may also be used for an implementation or instance of such a specifi­ +cation on an endpoint. +``` +``` +Page 36 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Term Definition** + +Command Requests for action on a value with an expected response which may have +parameters and a response with a status and parameters. + +Commission To bring a Node into a Fabric. + +Commissionable +Node + +``` +A Node that is able to be commissioned. Specific actions such as a button press +may be required to put a Commissionable Node into Commissioning Mode in +order for it to allow Commissioning. +``` +Commissionable +Node Discovery + +``` +Discovery of a Node that is able to be Commissioned, but not necessarily in +Commissioning Mode, for the purpose of performing Commissioning. The +Node may be brand new, after factory reset, or it may have already been Com­ +missioned. +``` +Commissioner A Role of a Node that performs Commissioning. + +Commissioner Dis­ +covery + +``` +Discovery of a Commissioner. +``` +Commissionee An entity that is being Commissioned to become a Node. + +Commissioning Sequence of operations to bring a Node into a Fabric by assigning an Opera­ +tional Node ID and Node Operational credentials. + +Commissioning +Channel + +``` +A Secure Channel used to perform Commissioning. +``` +Commissioning +Mode + +``` +The mode of a Node in which it allows Commissioning. +``` +Controller A Role of a Node that has permissions to enable it to control one or more +Nodes. + +Controlee A Role of a Node that has permissions defined to enable it to be controlled by +one or more Nodes. + +Device A piece of equipment containing one or more Nodes. + +Device Attestation +Certificate + +``` +An RFC 5280 [https://www.rfc-editor.org/rfc/rfc5280] compliant X.509 v3 document +with attestable attributes. +``` +Discriminator A 12-bit value used to discern between multiple commissionable Matter device +advertisements. See Discriminator value. + +Ecosystem A collaborative set of functional entities (proximal- or cloud-based) that pro­ +vide user-facing configuration and information tools and services, which is +provided by one or more cooperating companies. An “ecosystem” to the user is +the vendor of the “functional entities” which include, but are not limited to, a +smartphone OS, tablet, smartphone app, tablet app, computer app, voice assis­ +tant, TV interface, wall display/switch, cloud service, or an integrated service +across hardware and software platforms. + +Endpoint A particular component within a Node that is individually addressable. + +Endpoint Address The address assigned to an Endpoint. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 37 +``` + +``` +Term Definition +Fabric A logical collection of communicating Nodes, sharing a common root of trust, +and a common distributed configuration state. +Information Ele­ +ment +``` +``` +A Wi-Fi (IEEE 802.11-2020) data container used to convey various information +regarding a particular Wi-Fi network’s capabilities and operation. +Joint Fabric As part of the Ecosystem to Ecosystem solution, a Joint Fabric is a single fabric +with a single root of trust that is administered by one or more Ecosystems +which each provide a Node implementing the Joint Fabric Administrator +device type. +Key Center A system component which takes the NOCSR from a Commissioner and allo­ +cates an Operational Node ID that is unique to the Fabric, inserts this Opera­ +tional Node ID as the DN into the NOC, and signs the NOC. +Manual Pairing +Code +``` +``` +An 11-digit or 21-digit numeric code that can be manually entered/spoken +instead of scanning a QR code, which contains the information needed to com­ +mission a Matter device. +Network A set of nodes that have addressability, connectivity, and reachability to one +another via Internet Protocol. +Node An addressable entity which supports the Matter protocol stack and (once +Commissioned) has its own Operational Node ID and Node Operational cre­ +dentials. A Device MAY host multiple Nodes. +Operational Dis­ +covery +``` +``` +Discovery of a previously commissioned Node for the purpose of performing +operations with that Node. +Onboarding Pay­ +load +``` +``` +The information needed to start the process of commissioning a Device. +``` +``` +OTA Provider A Node implementing the OTA Software Update Provider role (see OTA Soft­ +ware Update Provider Cluster). +OTA Requestor A Node implementing the OTA Software Update Requestor role (see OTA Soft­ +ware Update Requestor Cluster). +Product Attesta­ +tion Authority +``` +``` +An entity which operates a root level Certificate Authority for the purpose of +Device Attestation. +Product Attesta­ +tion Intermediate +``` +``` +An entity which operates an intermediate level Certificate Authority for the +purpose of Device Attestation. +Product ID (PID) A 16-bit number that identifies the type of a Device, uniquely among the prod­ +uct types made by a given vendor. See Product ID. +QR Code A machine-readable optical label that contains information about the item to +which it is attached (see QR Code). +Rendezvous The process for commissioner and commissionee to establish an initial com­ +munication channel. +Role Some set of (related) behaviors of a Node. Each Node can have multiple roles. +``` +Page 38 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +Term Definition +Router A device that provides routing services in its network in cooperation with +other Routers. +Secure Channel A channel in which messages are encrypted and authenticated. Unicast secure +channels also provide authentication of each peer. +Server A Cluster interface that typically supports all or most of the attributes of the +Cluster. A Server Cluster communicates with a corresponding remote Client +Cluster with the same Cluster identifier. +Service Discovery The ability of a Node to locate services of interest. +Setup Code The low-entropy passcode used to secure commissioning. +Software Image A data blob, equivalent to a file, utilized by a Node to update its software. For +the purposes of OTA Software Update, this further refers to files conforming to +the OTA Software Image File Format. +Thread A low-power IEEE 802.15.4-based IPv6 mesh networking technology (see +Thread specification). +Vendor The organization that made a Device. +Vendor ID (VID) A 16-bit number that uniquely identifies the Vendor of the Device. See Vendor +ID. +``` +**1.4. Standards Terminology Mapping** + +``` +Matter HomeKit Weave Thread Zigbee +Administrator Admin Fabric provisioner Commissioner Coordinator +Attribute Characteristics Property Attribute +Binding Event subscription Subscription Link Binding +Broadcast Broadcast Broadcast +Client Service client Client Client +Cluster Services interface Cluster +Cluster Trait Service Cluster +Command Command Command Command Command +Commissioning Pairing Pairing Commissioning Association +Commissioner Admin Fabric provisioner Commissioner Coordinator +Device Accessory Device Device Device +End Device End Device End Device +Endpoint Profile Resource Interface Endpoint +Endpoint Address Device ID Resource ID Endpoint Identi­ +fier +``` +``` +Endpoint address +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 39 +``` + +``` +Matter HomeKit Weave Thread Zigbee +Fabric Network Fabric Partition Network +Network Manager Device / Controller Nest Service Leader Network manager +Node Accessory Node Node Node +Router Router Router +Server Service host Server Server +Service Discovery Service directory Service Discovery +``` +**1.5. Conformance Levels** + +The key words below are usually capitalized in the document to make the requirement clear. + +``` +Key Word Description +MAY A key word that indicates flexibility of choice with no implied preference. +NOT A key word that used to describe that the requirement is the inverse of the behav­ +ior specified (i.e. SHALL NOT, MAY NOT, etc) +SHALL A key word indicating a mandatory requirement. Designers are required to imple­ +ment all such mandatory requirements. +SHOULD A key word indicating flexibility of choice with a strongly preferred alternative. +Equivalent to the phrase is recommended. +``` +**1.6. References** + +The following standards and specifications contain provisions, which through reference in this doc­ +ument constitute provisions of this specification. All the standards and specifications listed are nor­ +mative references. At the time of publication, the editions indicated were valid. All standards and +specifications are subject to revision, and parties to agreements based on this specification are +encouraged to investigate the possibility of applying the most recent editions of the standards and +specifications indicated below. + +**1.6.1. CSA Reference Documents** + +``` +Reference Reference Location/URL Description +[CSA-05- +03874] +``` +``` +https://groups.csa-iot.org/wg/ +members-all/document/ +10905 +``` +``` +CSA Manufacturer Code Database +``` +``` +[DeviceLi­ +brary] +``` +``` +https://groups.csa-iot.org/wg/ +members-all/document/ +27351 +``` +``` +Device Library +``` +``` +Page 40 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Reference Reference Location/URL Description +[AppClusters] https://groups.csa-iot.org/wg/ +members-all/document/ +27350 +``` +``` +Application Clusters +``` +``` +[Standard­ +Namespaces] +``` +``` +https://github.com/CHIP- +Specifications/connected­ +homeip-spec/raw/build-sam­ +ple/pdf/standard-name­ +spaces.pdf +``` +``` +Standard Namespaces +``` +``` +[Matter +Brand Guide­ +lines] +``` +``` +https://groups.csa-iot.org/wg/ +members-all/document/ +22901 +``` +``` +Matter Brand Guidelines +``` +**1.6.2. External Reference Documents** + +``` +Reference Reference Location/URL Description +[AdProx] https://tools.ietf.org/html/draft- +sctl-advertising-proxy +``` +``` +Advertising Proxy for DNS-SD +SRP +[ANSI C18] https://ansi.org ANSI C18 Standards on Portable +Cells and Batteries +[BCP47] https://tools.ietf.org/rfc/bcp/ +bcp47.txt +``` +``` +Best Current Practice 47 +``` +``` +[Bluetooth®] https://www.bluetooth.org/doc­ +man/handlers/download­ +doc.ashx?doc_id=441541 +``` +``` +Bluetooth® Core Specification +4.2 +``` +``` +[Bluetooth®] https://www.bluetooth.org/Doc­ +Man/handlers/Download­ +Doc.ashx?doc_id=556598 +``` +``` +Bluetooth® Core Specification +Supplement 11 +``` +``` +[FIPS 180-4] https://csrc.nist.gov/publica­ +tions/detail/fips/180/4/final +``` +``` +NIST FIPS 180-4 Secure Hash +Standard (SHS), August 2015 +[FIPS 186-4] https://csrc.nist.gov/publica­ +tions/detail/fips/186/4/final +``` +``` +NIST FIPS 186-4 Digital Signa­ +ture Standard (DSS), July 2013 +[FIPS 197] https://doi.org/10.6028/ +NIST.FIPS.197 +``` +``` +NIST FIPS 197 Advanced +Encryption Standard (AES), +November 2001 +[FIPS 198-1] https://csrc.nist.gov/publica­ +tions/detail/fips/198/1/final +``` +``` +NIST FIPS 198-1 The Keyed- +Hash Message Authentication +Code (HMAC), July 2008 +[IANA Time Zone Database] https://www.iana.org/time- +zones +``` +``` +IANA Time Zone Database +``` +``` +[IEC 60086] https:///www.iec.ch IEC 60086 standard for Primary +Batteries +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 41 +``` + +``` +Reference Reference Location/URL Description +[IEEE 754-2019] https://ieeexplore.ieee.org/docu­ +ment/8766229 +``` +``` +"IEEE Standard for Floating- +Point Arithmetic," in IEEE Std +754-2019 (Revision of IEEE 754- +2008) July 2019, doi: +10.1109/IEEESTD.2019.8766229. +[IEEE 802.11-2020] https://standards.ieee.org/stan­ +dard/802_11-2020.html +``` +``` +IEEE 802.11-2020 - IEEE Stan­ +dard for Information Technol­ +ogy - Telecommunications and +Information Exchange between +Systems - Local and Metropoli­ +tan Area Networks - Specific +Requirements - Part 11: Wire­ +less LAN Medium Access Con­ +trol (MAC) and Physical Layer +(PHY) Specifications +[IEEE 1588-2008] https://standards.ieee.org/stan­ +dard/1588-2008.html +``` +``` +IEEE Standard for a Precision +Clock Synchronization Protocol +for Networked Measurement +and Control Systems +[ISO 639] https://www.iso.org/iso-639-lan­ +guage-codes.html +``` +``` +Language Codes +``` +``` +[ISO/IEC 18004:2015] https://www.iso.org/standard/ +62021.html +``` +``` +Information technology - Auto­ +matic identification and data +capture techniques - QR Code +bar code symbology specifica­ +tion +[ITU ASN.1] https://www.itu.int/en/ITU-T/ +asn1/Pages/asn1_project.aspx +``` +``` +ITU ASN.1 Project +``` +``` +[NFCForum-TS-NDEF 1.0] https://nfc-forum.org/our-work/ +specification-releases/specifica­ +tions/nfc-forum-technical-speci­ +fications +``` +``` +Data Exchange Format (NDEF) +Technical Specification, NFC +Forum +``` +``` +[NFCForum-TS-RTD 1.0] https://nfc-forum.org/our-work/ +specification-releases/specifica­ +tions/nfc-forum-technical-speci­ +fications/ +``` +``` +Record Type Definition (RTD) +Technical Specification, NFC +Forum +``` +``` +[NFCForum-TS-RTD URI 1.0] https://nfc-forum.org/our-work/ +specification-releases/specifica­ +tions/nfc-forum-technical-speci­ +fications/ +``` +``` +URI Record Type Definition +Technical Specification, NFC +Forum +``` +Page 42 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Reference Reference Location/URL Description** + +[NIST 800-38A] https://nvlpubs.nist.gov/nist­ +pubs/Legacy/SP/nistspecialpub­ +lication800-38a.pdf + +``` +NIST SP 800-38A Recommenda­ +tion for Block Cipher Modes of +Operation: Methods and Tech­ +niques, December 2001 +``` +[NIST 800-38C] https://nvlpubs.nist.gov/nist­ +pubs/Legacy/SP/nistspecialpub­ +lication800-38c.pdf + +``` +NIST SP 800-38C Recommenda­ +tions for Block Cipher Mode of +Operation: The CCM Mode for +Authentication and Confiden­ +tiality, Morris Dworkin, May +2004 (errata update 2007) +``` +[NIST 800-90A] https://csrc.nist.gov/publica­ +tions/detail/sp/800-90a/rev-1/ +final + +``` +NIST SP 800-90A Rev. 1 Recom­ +mendation for Random Number +Generation Using Deterministic +Random Bit Generators +``` +[NIST 800-90B] https://csrc.nist.gov/publica­ +tions/detail/sp/800-90b/final + +``` +NIST SP 800-90B Recommenda­ +tion for the Entropy Sources +Used for Random Bit Genera­ +tion +``` +[NIST 800-132] https://nvlpubs.nist.gov/nist­ +pubs/Legacy/SP/nistspecialpub­ +lication800-132.pdf + +``` +NIST SP 800-132 Recommenda­ +tion for Password-Based Key +Derivation, Part 1: Storage +Applications, December 2010 +``` +[NIST 800-186] https://nvlpubs.nist.gov/nist­ +pubs/SpecialPublications/ +NIST.SP.800-186-draft.pdf + +``` +NIST Draft SP 800-186 Recom­ +mendation for Discrete Loga­ +rithm-Based Cryptography, +October 2019 +``` +[RFC 1350] https://www.rfc-editor.org/rfc/ +rfc1350 + +``` +The TFTP Protocol (Revision 2) +``` +[RFC 1738] https://www.rfc-editor.org/rfc/ +rfc1738 + +``` +Uniform Resource Locators +(URL) +``` +[RFC 2119] https://www.rfc-editor.org/rfc/ +rfc2119 + +``` +Bradner, S., "Key words for use +in RFCs to Indicate Require­ +ment Levels", BCP 14, RFC 2119, +DOI 10.17487/RFC2119, March +1997 +``` +[RFC 2782] https://www.rfc-editor.org/rfc/ +rfc2782 + +``` +A DNS RR for specifying the +location of services (DNS SRV) +``` +[RFC 2986] https://www.rfc-editor.org/rfc/ +rfc2986 + +``` +PKCS #10: Certification Request +Syntax Specification Version 1.7 +``` +[RFC 3306] https://www.rfc-editor.org/rfc/ +rfc3306 + +``` +Unicast-Prefix-based IPv6 Multi­ +cast Addresses +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 43 +``` + +``` +Reference Reference Location/URL Description +[RFC 3587] https://www.rfc-editor.org/rfc/ +rfc3587 +``` +``` +IPv6 Global Unicast Address +Format +[RFC 3986] https://www.rfc-editor.org/rfc/ +rfc3986 +``` +``` +Uniform Resource Identifier +(URI) +[RFC 4007] https://www.rfc-editor.org/rfc/ +rfc4007 +``` +``` +IPv6 Scoped Address Architec­ +ture +[RFC 4191] https://www.rfc-editor.org/rfc/ +rfc4191 +``` +``` +Default Router Preferences and +More-Specific Routes +[RFC 4193] https://www.rfc-editor.org/rfc/ +rfc4193 +``` +``` +Unique Local IPv6 Unicast +Addresses (ULA) +[RFC 4291] https://www.rfc-editor.org/rfc/ +rfc4291 +``` +``` +IPv6 Addressing Architecture +``` +``` +[RFC 4506] https://www.rfc-editor.org/rfc/ +rfc4506 +``` +``` +XDR: External Data Representa­ +tion Standard +[RFC 4648] https://www.rfc-editor.org/rfc/ +rfc4648 +``` +``` +The Base16, Base32, and Base64 +Data Encodings +[RFC 4861] https://www.rfc-editor.org/rfc/ +rfc4861 +``` +``` +Neighbor Discovery for IP ver­ +sion 6 (IPv6) +[RFC 4862] https://www.rfc-editor.org/rfc/ +rfc4862 +``` +``` +IPv6 Stateless Address Autocon­ +figuration +[RFC 5280] https://www.rfc-editor.org/rfc/ +rfc5280 +``` +``` +Internet X.509 Public Key Infra­ +structure Certificate and Certifi­ +cate Revocation List (CRL) Pro­ +file +[RFC 5505] https://www.rfc-editor.org/rfc/ +rfc5505 +``` +``` +Principles of Internet Host Con­ +figuration +[RFC 5646] https://tools.ietf.org/html/ +rfc5646 +``` +``` +Tags for Identifying Languages +``` +``` +[RFC 5652] https://www.rfc-editor.org/rfc/ +rfc5652 +``` +``` +Cryptographic Message Syntax +(CMS) +[RFC 5869] https://www.rfc-editor.org/rfc/ +rfc5869 +``` +``` +HMAC-based Extract-and- +Expand Key Derivation Func­ +tion (HKDF) +[RFC 5905] https://www.rfc-editor.org/rfc/ +rfc5905 +``` +``` +Network Time Protocol Version +4 +[RFC 5952] https://www.rfc-editor.org/rfc/ +rfc5952 +``` +``` +A Recommendation for IPv6 +Address Text Representation +[RFC 6335] https://www.rfc-editor.org/rfc/ +rfc6335 +``` +``` +Service Name and Port Number +Procedures +``` +Page 44 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Reference Reference Location/URL Description** + +[RFC 6760] https://www.rfc-editor.org/rfc/ +rfc6760 + +``` +Replacement of AppleTalk NBP +``` +[RFC 6762] https://www.rfc-editor.org/rfc/ +rfc6762 + +``` +Multicast DNS +``` +[RFC 6763] https://www.rfc-editor.org/rfc/ +rfc6763 + +``` +DNS-Based Service Discovery +``` +[RFC 6920] https://www.rfc-editor.org/rfc/ +rfc6920 + +``` +Naming Things with Hashes +``` +[RFC 6960] https://www.rfc-editor.org/rfc/ +rfc6960 + +``` +X.509 Internet Public Key Infra­ +structure Online Certificate Sta­ +tus Protocol - OCSP +``` +[RFC 7230] https://www.rfc-editor.org/rfc/ +rfc7230 + +``` +Hypertext Transfer Protocol +(HTTP/1.1): Message Syntax and +Routing +``` +[RFC 7346] https://www.rfc-editor.org/rfc/ +rfc7346 + +``` +IPv6 Multicast Address Scopes +``` +[RFC 7468] https://www.rfc-editor.org/rfc/ +rfc7468 + +``` +Textual Encodings of PKIX, +PKCS, and CMS Structures +``` +[RFC 7558] https://www.rfc-editor.org/rfc/ +rfc7558 + +``` +Scalable DNS-SD Requirements +``` +[RFC 8305] https://www.rfc-editor.org/rfc/ +rfc8305 + +``` +Happy Eyeballs Version 2: Bet­ +ter Connectivity Using Concur­ +rency +``` +[RFC 8490] https://www.rfc-editor.org/rfc/ +rfc8490 + +``` +DNS Stateful Operations +``` +[RFC 8765] https://www.rfc-editor.org/rfc/ +rfc8765 + +``` +DNS Push Notifications +``` +[RFC 8766] https://www.rfc-editor.org/rfc/ +rfc8766 + +``` +Discovery Proxy +``` +[RFC 8915] https://www.rfc-editor.org/rfc/ +rfc8915 + +``` +Network Time Security for the +Network Time Protocol +``` +[draft-lemon-stub-networks] https://datatracker.ietf.org/doc/ +html/draft-lemon-stub-net­ +works-02 + +``` +Connecting Stub Networks to +Existing Infrastructure +``` +[SEC 1] https://www.secg.org/sec1- +v2.pdf + +``` +SEC 1: Elliptic Curve Cryptogra­ +phy, Version 2.0, Certicom +Research, May 2009 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 45 +``` + +``` +Reference Reference Location/URL Description +[SEC 2] https://secg.org/sec2-v2.pdf SEC 2: Recommended Elliptic +Curve Domain Parameters, Ver­ +sion 2.0, Certicom Research, +January 2010 +[SIGMA] https://doi.org/10.1007/978-3- +540-45146-4_24 +``` +``` +Krawczyk H. (2003) SIGMA: The +‘SIGn-and-MAc’ Approach to +Authenticated Diffie-Hellman +and Its Use in the IKE Protocols. +In: Boneh D. (eds) Advances in +Cryptology - CRYPTO 2003. +CRYPTO 2003. Lecture Notes in +Computer Science, vol 2729. +Springer, Berlin, Heidelberg. +[SPAKE2+] https://tools.ietf.org/pdf/draft- +bar-cfrg-spake2plus-02.pdf +``` +``` +SPAKE2+, an Augmented PAKE +(Draft 02, 10 December 2020) +[SRP] https://tools.ietf.org/html/draft- +ietf-dnssd-srp +``` +``` +Service Registration Protocol +``` +``` +[Thread] https://www.threadgroup.org Thread 1.3.0 Specification +[Verhoeff ] https://ir.cwi.nl/pub/13045 Verhoeff, J. (1969). Error detect­ +ing decimal codes. MC Tracts. +Centrum Voor Wiskunde en +Informatica. +[WFA Unsynchronized Service +Discovery] +``` +``` +https://www.wi-fi.org/discover- +wi-fi/wi-fi-aware +``` +``` +Wi-Fi Alliance Wi-Fi Aware +Specification. +[X.501] https://www.itu.int/rec/T-REC- +X.501/en +``` +``` +ITU X.501 : Information technol­ +ogy - Open Systems Intercon­ +nection - The Directory: Models +[X.509] https://www.itu.int/rec/T-REC- +X.509/en +``` +``` +ITU X.509 : Information technol­ +ogy - Open Systems Intercon­ +nection - The Directory: Public- +key and attribute certificate +frameworks +[X.520] https://www.itu.int/rec/T-REC- +X.520/en +``` +``` +ITU X.520 : Information technol­ +ogy - Open Systems Intercon­ +nection - The Directory: +Selected attribute types +[X.680] https://www.itu.int/rec/T-REC- +X.680/en +``` +``` +ITU X.680 : Information technol­ +ogy - Abstract Syntax Notation +One (ASN.1): Specification of +basic notation +``` +Page 46 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +Reference Reference Location/URL Description +[X.690] https://www.itu.int/rec/T-REC- +X.690/en +``` +``` +ITU X.690 : Information technol­ +ogy - ASN.1 encoding rules: +Specification of Basic Encoding +Rules (BER), Canonical Encod­ +ing Rules (CER) and Distin­ +guished Encoding Rules (DER) +``` +**1.7. Informative References** + +**1.7.1. CSA Reference Documents** + +``` +Reference Reference Location/URL Description +[DotdotArch] https://groups.csa-iot.org/wg/ +matter-tsg/document/18649 +``` +``` +Dotdot Architecture Model, document 13-0589, revi­ +sion 14, February 2019 +[ZCL] https://groups.csa-iot.org/wg/ +members-all/document/ +23019 +``` +``` +Zigbee Cluster Library Specification, document 07- +5123, revision 8, December 2019 +``` +``` +[CSA-PNP] https://groups.csa-iot.org/wg/ +members/document/21624 +``` +``` +Organizational Processes and Procedures, 13-0625, +revision 8, November 2021 +``` +**1.8. Conventions** + +The following conventions are used in this document. + +**1.8.1. Enumerations and Reserved Values** + +An undefined value or range of an enumeration, field, or identifier SHALL be considered reserved +for future revisions of this standard and SHALL NOT be available for implementation. It is RECOM­ +MENDED that a value stay undefined, rather than defining it as "reserved". + +A value or range of an enumeration, field, or identifier that is available for non-standard imple­ +mentation SHALL be defined as manufacturer specific ("MS"). + +A value or range of an enumeration, field, or identifier that is available for other parts of this stan­ +dard SHALL be defined as such. + +A value or range of an enumeration, field, or identifier that is deprecated, and not available for +implementation, SHALL be defined as deprecated ("D"). + +**1.8.2. Reserved Bit Fields** + +An undefined bit or bit field SHALL be considered reserved for future revisions of this standard +and SHALL NOT be available for implementation. + +It is RECOMMENDED that a bit stay undefined, rather than defining it as "reserved". + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 47 +``` + +An implementation of a revision where a bit is reserved SHALL indicate that bit as zero when con­ +veying that bit in an interaction, and ignore that bit when conveyed from another implementation. + +**1.8.3. Number Format** + +In this specification, hexadecimal numbers are prefixed with the designation “0x” and binary num­ +bers are prefixed with the designation “0b”. All other numbers are assumed to be decimal unless +indicated otherwise within the associated text. + +When a hexadecimal number is longer than 4 nibbles, the underscore ("_") character SHALL be +used to separate the number into groups of 4 nibbles. If the number of nibbles is not evenly divisi­ +ble by 4, the most significant group SHALL contain less than 4 nibbles and any lesser significant +groups SHALL contain 4 nibbles. + +``` +Examples of valid hexadecimal groups separated by an underscore: +``` +- "0xAA_33CC" +- “0x1234_ABCD” +- “0x1234_ABCD_526E_6242” + +Binary numbers are specified as successive groups of bits, and SHALL be separated by a space (“ “) +or underscore ("_") character at least every 4 bits from the most significant bit (next to the 0b prefix +and leftmost on the page) to the least significant bit (rightmost on the page), e.g. the binary number +0b0000_1111 represents the decimal number 15 and hexadecimal 0x0F. + +Where individual bits are indicated (e.g. bit 3) the bit numbers are relative to the least significant +bit which is bit 0. + +When a digit is specified as having any value in the range of that digit, it is specified with an “x” +(this should not be confused with the "x" in the prefix "0x" for hexadecimal notation). + +``` +For example: +``` +- “0b0000 0xxx” indicates that the lower 3 bits can take any value but the upper 5 bits must + each be set to 0. +- “0x0000_0xxx” indicates that the lower 3 nibbles can take any value but the upper 5 nib­ + bles must each be set to 0. + +Bit ranges are always indicated starting with the most significant bit number. Therefore bits 7..4 are +equivalent to the mask 0b1111_0000 or 0xF0. + +**1.8.4. Provisional** + +Per [CSA-PNP], when a specification is completed there may be sections of specification text (or +smaller pieces of a section) that are not certifiable at this stage. These sections (or smaller pieces of +a section) are marked as provisional prior to publishing the specification. This specification uses + +``` +Page 48 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +well-defined notation to mark Provisional Conformance or notes a section of text with the term +"provisional". + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 49 +``` + +Page 50 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 2. Architecture** + +**2.1. Overview** + +Matter aims to build a universal IPv6-based communication protocol for smart home devices. The +protocol defines the application layer that will be deployed on devices as well as the different link +layers to help maintain interoperability. The following diagram illustrates the normal operational +mode of the stack: + +_Figure 1. Application and Network Stack_ + +**2.2. Layered Architecture** + +The architecture is divided into layers to help separate the different responsibilities and introduce a +good level of encapsulation amongst the various pieces of the protocol stack. The vast majority of +interactions flow through the stack captured in the following Figure. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 51 +``` + +_Figure 2. Layered Architecture_ + +The _Application_ layer corresponds to the high order business logic of a device. For example, an +application that is focused on lighting might contain logic to handle turning on/off a light bulb, as +well as its color characteristics. + +The _Data Model_ layer corresponds to the data and verb elements that help support the functionality +of the application. The Application operates on these data structures when there is intent to interact +with the device. + +The _Interaction Model_ layer defines a set of interactions that can be performed between a client and +server device. For example, reading or writing attributes on a server device would correspond to +application behavior on the device. These interactions operate on the elements defined at the data +model layer. + +Once an action is constructed using the _Interaction Model_ , it is serialized into a prescribed packed +binary format to encode for network transmission. This process is handled in the _Action Framing_ +layer. + +An encoded action frame is then processed by the _Security Layer_ : the message is encrypted and +appended with a message authentication code. These actions ensure the data remain confidential +and authentic between sender and receiver of the message. + +With an interaction now serialized, encrypted, and signed, the _Message Layer_ constructs the pay­ +load format with required and optional header fields, which specify properties of the message as +well logical routing information. + +After the final payload has been constructed by the _Message Layer_ , it is sent to the underlying trans­ +port protocol (TCP or Matter’s Message Reliability Protocol) for IP management of the data. + +Once the data is received on the peer device, it travels up the protocol stack, where the various lay­ +ers reverse the operations on the data performed by the sender, to finally deliver the message to +the Application for consumption. + +``` +Page 52 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +In addition to the data flows captured above, this specification defines secure session establishment +protocols based on operational certificates (see Section 4.14.2, “Certificate Authenticated Session +Establishment (CASE)”), or passcodes (see Section 4.14.1, “Passcode-Authenticated Session Establish­ +ment (PASE)”), group communication (see Section 4.16, “Group Communication”), a bulk data trans­ +fer protocol (BDX) suitable for sending bulk data between Nodes, and provisions for defining manu­ +facturer-specific protocols. + +**2.3. Network Topology** + +In principle, any IPv6-bearing network is suitable for Matter deployment, subject to supporting a +few core IPv6 standards. In this version of the specification, we focus on three link layer technolo­ +gies: Ethernet, Wi-Fi and Thread. We restrict the specification to the above so that the specification +can suitably cover provisioning of these link layers, and so that the amount of testing in certifica­ +tion is suitably bounded. + +Matter treats networks as shared resources: it makes no stipulation of exclusive network owner­ +ship or access. As a result, it is possible to overlay multiple Matter networks over the same set of +constituent IP networks. + +This protocol may operate in the absence of globally routable IPv6 infrastructure. This requirement +enables operation in a network disconnected or firewalled from the global Internet. It also enables +deployment in situations where the Internet Service Provider either does not support IPv6 on con­ +sumer premises or where the support proves otherwise limiting, for example, if the delegated pre­ +fix cannot accommodate all the networks and devices on premises. + +This protocol supports local communications spanning one or more IPv6 subnets. Canonical net­ +works supporting a fabric may include a Wi-Fi/Ethernet subnet, or one or more low power and +lossy networks (LLN) subnets. In this version of the specification, Thread is the supported LLN stan­ +dard. + +**2.3.1. Single network** + +_Figure 3. Single Thread network_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 53 +``` + +_Figure 4. Single Wi-Fi network_ + +In the single network topology, all Matter devices are connected to a single logical network. This +could be a Thread/802.15.4 network, a Wi-Fi network or an Ethernet network. In the case of Wi- +Fi/Ethernet, the network could in fact span multiple Wi-Fi and/or Ethernet segments provided that +all the segments are bridged at the link layer. A Node is a single instance of a Matter device within a +fabric, operationally available on an IP network. + +Each Node in the single-network topology communicates with every other Node in the Fabric via a +single network interface. + +**2.3.2. Star network topology** + +_Figure 5. Star network topology_ + +The star network topology consists of multiple peripheral networks joined together by a central +hub network. The hub network will typically be the customer’s home network (Wi-Fi/Ethernet net­ +work), while the peripheral networks can be of any supported network type. A peripheral network +MUST always be joined directly to the hub network via one or more Border Routers. + +``` +Page 54 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Architecturally, any number of peripheral networks may be present in a single Fabric, including +multiple networks of the same type. Nodes MAY have interfaces onto any network (hub or periph­ +eral), and MAY communicate directly to other Nodes on the same network. However, any communi­ +cation that must cross a network boundary to reach its destination MUST flow through a Border +Router. + +This protocol places a set of requirements on the Border Router. These requirements pertain to +address assignment, route assignment and advertisement, multicast support, and discovery proxy­ +ing. + +Note that in this version of the specification, Thread is the primary supported LLN. In many cases, +customer installations will attempt to maintain a simple network topology, with a single Wi-Fi/Eth­ +ernet subnet, and a single Thread network. However, more than one Thread network is possible +and supported. + +To support home automation interoperability, this protocol supports the concept of bridging which +makes available, through a data model node, devices implementing other home automation tech­ +nologies, transports and link layers. + +**2.4. Scoped names** + +The Matter protocol explicitly supports multiple administrators, unrelated by any common roots of +trust (multi-admin). This functionality is addressed via multiple fabrics and is enabled by the core +aspects of name scoping (see below), and key considerations enabling multiple fabrics in onboard­ +ing, secure communication, and aspects of the data model (such as fabric-scoped data). + +A Fabric is a collection of Matter devices sharing a trusted root. The root of trust in Matter is the +Root CA that issues the NOCs which underpin node identities. Within the fabric, each node is +uniquely identified by a stable Node ID. The scoped selection and allocation of these constructs +within Matter ensures the uniqueness of identifiers and gives clear guidance on ownership and +management of namespaces. + +The operational root of trust — the root certificate authority (CA) as identified by its public key +(Root PK) — is responsible for the allocation of correctly scoped fabric identifiers. The security of all +public key infrastructures (PKI) depends on the private key of the CA being protected and neither +guessable nor obtainable; that property, in turn, implies that the public key is globally unique. +Within any root CA, the fabrics — identified by a 64-bit number — are unique. The uniqueness +mechanism emerges from the collaboration of the commissioner and the root CA associated with +that particular commissioner. Matter wraps the collaboration between the commissioner and its +associated root CA and other possible data stores into a concept called the "administrative domain +manager" (ADM). The algorithmic details and policies within the administrative domain manager +are out of the scope of the specification as long as the allocation of all identifiers obeys the unique­ +ness and scoping criteria. Fabrics are uniquely identified by the tuple of their root CA’s public key +and a Fabric ID. Similarly, within each fabric, the administrative domain manager is responsible for +assigning a unique and stable Operational Node ID to every node. + +The scoping strategy as outlined here ensures that each scoped identifier can be allocated solely by +the entities responsible for the scoping, without consideration for collisions or forgeries. For exam­ +ple, two different CAs may allocate the same fabric identifiers and this would not create any prob­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 55 +``` + +lems for the devices within the network. Scoped delegation of responsibility also provides for clear +guidelines for the removal of specific identifiers. + +A Matter device may be a member of multiple fabrics and thus have multiple associated node IDs. +The scoping strategy also naturally lends itself towards unambiguous resolution of names and cre­ +dentials and places a clearly defined responsibility for managing the namespaces on each fabric’s +associated administrative domain manager service. + +Prior to the first commissioning, such as in factory-reset state, a typical device contains no pre-allo­ +cated operational roots of trust, and no operational identities in the form of fabric IDs and node +IDs. Yet, various interactions expect the fabric ID, or a node ID. These identifiers emerge in a num­ +ber of internal constructs — from address discovery, through identifying secure sessions, to evaluat­ +ing access control privileges. In order to regularize all interactions with the device and solve the +bootstrapping problem, a special primordial fabric ID is reserved, and associates a set of initial +access control privileges with any communication that would be associated with the initial commis­ +sioning sessions. + +**2.5. Identifiers** + +**2.5.1. Fabric References and Fabric Identifier** + +As described above, a Fabric ID is a 64-bit number that uniquely identifies the Fabric within the +scope of a particular root CA. Conceptually, the fully qualified fabric reference consists of the tuple +containing the public key of the root certificate authority, and the Fabric ID. Because the fully quali­ +fied fabric reference is cumbersome to use, a number of mechanisms for compression of the refer­ +ence are defined. The Fabric reference, in compressed form, is used during operational discovery to +provide operational naming separation, a form of namespacing, between unrelated collections of +devices. + +Fabric ID 0 is reserved across all fabric root public key scopes. This fabric ID SHALL NOT be used as +the identifier of a fabric. + +A fabric is defined in the Data Model as a set of nodes that interact by accessing Data Model ele­ +ments as defined in the Interaction Model (see Section 7.5, “Fabric”). + +The layers below the data model, that convey data model interactions as messages, SHALL always +indicate either the fabric associated with the message, or that there is no fabric associated with the +message. + +For example: A Data Model message that is conveyed over a message channel that uses the reserved +fabric ID '0' does not have a fabric associated with it. + +**2.5.2. Vendor Identifier (Vendor ID, VID)** + +A Vendor Identifier (Vendor ID or VID) is a 16-bit number that uniquely identifies a particular prod­ +uct manufacturer, vendor, or group thereof. Each Vendor ID is statically allocated by the Connectiv­ +ity Standards Alliance (see [CSA Manufacturer Code Database]). + +The following Vendor IDs are reserved: + +``` +Page 56 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Table 1. Vendor ID Allocations_ + +``` +Range Type +0x0000 Matter Standard +0x0001 - 0xFFF0 reserved for individual Manufacturer Codes as per +CSA Manufacturer Code Database +0xFFF1 Test Vendor #1 +0xFFF2 Test Vendor #2 +0xFFF3 Test Vendor #3 +0xFFF4 Test Vendor #4 +``` +All other allocations of Vendor ID are specified in CSA Manufacturer Code Database. + +### NOTE + +``` +The Test Vendor IDs are reserved for test and development by device manufacturers +or hobbyists. Commissioners SHOULD NOT commission devices using one of these +VIDs onto an operational Fabric under normal operation unless the user is made +fully aware of the security risks of providing an uncertified device with operational +and networking credentials. +``` +**2.5.3. Product Identifier (Product ID, PID)** + +A Product Identifier (Product ID or PID) is a 16-bit number that uniquely identifies a product of a +vendor. The Product ID is assigned by the vendor and SHALL be unique for each product within a +Vendor ID. Once a Product ID has been used, it SHALL NOT be reused by a different product type +under the same Vendor ID. These Product IDs SHOULD NOT be specific to a unique physical device; +rather they describe the product type, which might have many manufactured instances (e.g. multi­ +ple colors of the same product type). + +A value of 0x0000 SHALL NOT be assigned to a product since Product ID = 0x0000 is used for these +specific cases: + +- To announce an anonymized Product ID as part of device discovery (see Section 5.4.2, + “Announcement by Device”). +- To indicate an OTA software update file applies to multiple Product IDs equally. +- To avoid confusion when presenting the Onboarding Payload for ECM with multiple nodes. + +**2.5.4. Group Identifier (GID)** + +A Group Identifier (Group ID or GID) is a 16-bit number that identifies a set of Nodes across a Fabric +at the message layer (see Section 4.17, “Group Key Management”). A Group ID can further be bound +to one or more Endpoints within each Node in the group at the interaction layer. + +The Group ID space is allocated as described in Table 2, “Group ID Allocations”: + +_Table 2. Group ID Allocations_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 57 +``` + +``` +Range Type +0xFF00 - 0xFFFF Universal Group ID range reserved for static multi­ +cast and anycast identifiers +0x0001 - 0xFEFF Application Group ID, assigned by fabric Administra­ +tor +0x0000 Null or unspecified Group ID +``` +**2.5.4.1. Universal Group ID** + +A Universal Group ID (UGID) is one that resides in the 16-bit subrange of Group ID that is reserved +for groups that are common across this standard. These special multicast, groupcast, or anycast des­ +tinations are constant and known to all Nodes on any Fabric. The Universal Group ID space is allo­ +cated as described in Table 3, “Universal Group ID Allocations”: + +_Table 3. Universal Group ID Allocations_ + +``` +Range Type +0xFFFF All Nodes +0xFFFE All non-ICD Nodes +0xFFFD All Proxies +0xFF00-0xFFFC Reserved for future use +``` +Because the keys and IPv6 multicast prefixes are different across Fabrics, Universal Groups only +enable communication within a specific Fabric. + +**All Nodes Group** + +This group is used to message all Nodes in a Fabric. + +**All non-ICD Nodes Group** + +This group is used to message all power-capable Nodes in a Fabric. ICD Nodes SHALL NOT sub­ +scribe to this group. + +**All Proxies Group** + +This group is used to discover Proxy Nodes during Section 9.15.4, “Proxy Subscriptions”. + +**2.5.5. Node Identifier** + +A Node Identifier (Node ID) is a 64-bit number that uniquely identifies an individual Node or a +group of Nodes on a Fabric. The Node Identifier space is allocated as described in Table 4, “Node +Identifier Allocations”: + +_Table 4. Node Identifier Allocations_ + +``` +Range Type +0xFFFF_FFFF_FFFF_xxxx Group Node ID +``` +``` +Page 58 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Range Type +0xFFFF_FFFF_0000_0000 to 0xFFFF_FFF­ +F_FFFE_FFFF +``` +``` +Reserved for future use +``` +``` +0xFFFF_FFFE_xxxx_xxxx Temporary Local Node ID +0xFFFF_FFFD_xxxx_xxxx CASE Authenticated Tag +0xFFFF_FFFC_xxxx_xxxx to 0xFFFF_FF­ +FC_FFFF_FFFF +``` +``` +Reserved for future use +``` +``` +0xFFFF_FFFB_xxxx_xxxx PAKE key identifiers +0xFFFF_FFF0_0000_0000 to 0xFFFF_FF­ +FA_FFFF_FFFF +``` +``` +Reserved for future use +``` +``` +0x0000_0000_0000_0001 to 0xFFFF_FFE­ +F_FFFF_FFFF +``` +``` +Operational Node ID +``` +``` +0x0000_0000_0000_0000 Unspecified Node ID +``` +Node IDs are used for core messaging, within the internal APIs, within the data model, and to +resolve the operational IPv6 addresses of Nodes (see Section 4.3.2, “Operational Discovery”). + +The span of Node IDs from 0xFFFF_FFF0_0000_0000 to 0xFFFF_FFFF_FFFF_FFFF, as well as the +value 0x0000_0000_0000_0000 are both reserved for special uses. + +**2.5.5.1. Operational Node ID** + +An Operational Node ID is a 64-bit number that uniquely identifies an individual Node on a Fabric. +All messages must have an Operational Node ID as the source address. All unicast messages must +have an Operational Node ID as the destination address. + +While source or destination address MAY be elided from a message, it MUST remain unambigu­ +ously derivable from the Session ID. + +**2.5.5.2. Group Node ID** + +A Group Node ID is a 64-bit Node ID that contains a particular Group ID in the lower half of the +Node ID. + +**2.5.5.3. Temporary Local Node ID** + +A Temporary Local Node ID is a 64-bit Node ID that contains an implementation-dependent value in +its lower 32 bits. This allows implementations to keep track of connections or transport-layer links +and similar housekeeping internal usage purposes in contexts where an Operational Node ID is +unavailable. + +**2.5.5.4. PAKE key identifiers** + +This subrange of Node ID is used to assign an access control subject to a particular PAKE key as +specified in Section 6.6.2.1.1, “PASE and Group Subjects”. An example usage would be to create an +ACL entry to provide administrative access to any commissioner communicating via a PASE session + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 59 +``` + +established with a particular pincode. + +**2.5.5.5. CASE Authenticated Tag** + +This subrange of Node ID is used to assign an access control subject to a group of peer nodes that +share a single CASE session as specified in Section 6.6.2.1.2, “Subjects identified by CASE Authenti­ +cated Tag”. + +**2.5.5.6. Unspecified Node ID** + +The Unspecified Node ID (0x0000_0000_0000_0000) is a reserved value that never appears in mes­ +sages or protocol usage. It exists to mark or detect the presence of uninitialized, missing, or invalid +Node IDs. + +**2.5.6. IPv6 Addressing** + +This protocol uses IPv6 addressing for its operational communication. Node IDs and Fabric IDs are +resolved to various types of IPv6 addresses [RFC 4291]. + +**2.5.6.1. IPv6 Unicast Address** + +An IPv6 Unicast Address is one that uniquely identifies and addresses a single Node on an IPv6 net­ +work. A primary design goal for this standard is to allow Nodes to leverage native IPv6 technolo­ +gies. As such, an operational IPv6 Unicast address that provides connectivity and routability +between Nodes SHALL be used. This includes a global unicast address (GUA), a link-local address +(LLA), or a unique local address (ULA). + +**2.5.6.2. IPv6 Multicast Address** + +An IPv6 Multicast Address is formed using Unicast-Prefix-based IPv6 Multicast Addresses [ +RFC 3306]: + +- The first 12 bits are defined by [RFC 3306] and are 0xFF3. +- The next 4 bits are "scop" (scope) and set based on [RFC 7346] Section 2 to: + ◦ _Site-Local_ (0x5) - spans all networks in the Fabric, including Thread, Ethernet, and Wi-Fi. +- The next 8 bits are reserved (0x00). +- The next 8 bits are "plen", and set to 0x40 to indicate a 64-bit long network prefix field. + +The network prefix portion of the Multicast Address is the 64-bit bitstring formed by concatenating: + +- 0xFD to designate a locally assigned ULA prefix per [RFC 4193] Section 3.1 +- The upper 56-bits of the Fabric ID for the network in big-endian order + +The 32-bit group identifier portion of the Multicast Address is the 32-bits formed by: + +- The lower 8-bits of the Fabric ID +- 0x00 +- The next 16-bits are the Group Identifier for the group, as specified in Group Identifier in big- + +``` +Page 60 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +endian order +``` +An example of the site local scoped multicast address for a given and : + +``` +FF35:0040:FD00: +``` +### NOTE + +``` +though Site-Local scope is always used, the effective scope MAY be limited by setting +the IPv6 hop count. +``` +The Multicast Address formation ensures a low probability of a node receiving a multicast message +it is not interested in. If a collision does occur on the multicast address (which requires two identi­ +cal 64-bit Fabric IDs and two identical 16-bit Group IDs), processing of the message disambiguates +which fabric and group is relevant by checking which operational group key leads to the message’s +64-bit MIC. + +**2.5.6.3. IPv6 Multicast Port Number** + +The IANA assigned port number is 5540. + +**2.5.6.4. IPv4 Coexistence** + +Matter devices SHALL be tolerant of IPv4 addresses and MAY ignore those addresses for the pur­ +poses of Matter operations. + +**2.6. Device identity** + +Each Matter device holds a number of certificate chains. + +A Device Attestation Certificate (DAC) proves the authenticity of the manufacturer and a certifica­ +tion status of the device’s hardware and software. The Device Attestation Certificate is used during +the commissioning process by the Commissioner to ensure that only trustworthy devices are admit­ +ted into a Fabric. The details of the device attestation process are captured in Section 6.2, “Device +Attestation”. + +Each Matter device is issued an Operational Node ID and a Node Operational Certificate (NOC) for +that Operational Node ID. The NOC enables a Node to identify itself within a Fabric by cryptographi­ +cally binding a unique Node Operational Key Pair to the operational identity of its subject, +attestable through the signature of a trusted Certificate Authority (CA). Operational Node IDs are +removed on factory reset or removal of Fabrics. A NOC is issued during the commissioning process +of a device into a Fabric. These steps help to protect the privacy of the end-user and to adapt to dif­ +ferent trust models. + +The format of the Node Operational credentials and protocols for generating those credentials are +detailed in Section 6.4, “Node Operational Credentials Specification” and Section 6.5, “Operational +Certificate Encoding” sections. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 61 +``` + +**2.7. Security** + +Matter deploys modern security practices to protect the Fabric. Matter designates a core set of secu­ +rity primitives detailed in Chapter 3, _Cryptographic Primitives_ to provide comprehensive protection. +Elliptic curve cryptography, based on the NIST P-256 curve (secp256r1) serves as the foundation for +public key cryptography and digital signatures. Commonly available AES modes of operation have +been selected to provide shared key cryptographic operations. In scenarios involving an out-of- +band passcode-based authentication, Matter uses SPAKE2+, an efficient augmented PAKE algorithm. + +The core cryptographic primitives form the basis of a number of complementary secure protocols +used within Matter. All unicast Node-to-Node messages are secured, authenticated, and provide +replay protection. Building on top of IPv6 multicast, Matter also provides group messaging facilities, +useful for efficiently addressing on an LLN. The group messaging features prioritize low latency of +packet processing. + +**2.8. Device Commissioning** + +Device commissioning (see Chapter 5, _Commissioning_ ) is the process of joining a device to a Fabric. +The device being commissioned is referred to as the Commissionee and the device administering +commissioning is referred to as the Commissioner. Device commissioning consists of the following +steps: + +1. Device discovery (see Section 5.4, “Device Discovery” and see Section 5.1, “Onboarding Pay­ + load”): The Commissioner discovers commissionable devices on network interfaces such as + Bluetooth Low Energy, Wi-Fi, or other connected IP network. The Commissioner obtains the out- + of-band secret (Passcode) from the commissionable device’s QR Code, Manual Pairing Code, NFC + Tag or other means. This secret is used by Passcode-Authenticated Session Establishment (PASE) + to establish a secure commissioning session. The order of discovering commissionable devices + and obtaining the out-of-band secret from commissionable device is not critical. +2. Security setup with PASE (see Section 4.14.1, “Passcode-Authenticated Session Establishment + (PASE)”): Establish encryption keys between the Commissioner and Commissionee using PASE. + All messages exchanged between the Commissioner and Commissionee are encrypted using + these PASE-derived keys. The process also establishes an attestation challenge used during the + device attestation procedure. +3. Device attestation verification (see Section 6.2, “Device Attestation”): Commissioner establishes + the authenticity of the Commissionee as a certified device, notifying the user if the device is not + certified. +4. Information configuration (see Section 6.4, “Node Operational Credentials Specification”, Sec­ + tion 11.10, “General Commissioning Cluster” and Section 11.18, “Node Operational Credentials + Cluster”): The Commissioner provides Commissionee with information such as regulatory + domain, UTC time, Operational Certificate and network interfaces configuration. +5. Join network (see Section 11.9, “Network Commissioning Cluster” and Section 4.3.2, “Opera­ + tional Discovery”): The Commissioner triggers the Commissionee to connect to the operational + network unless the Commissionee is already on the operational network. The Node’s/Commis­ + sionee’s IPv6 address is then either used (if already known) or discovered (if not known) by the + Commissioner or Administrator. + +``` +Page 62 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +6. Security setup with CASE (see Section 4.14.2, “Certificate Authenticated Session Establishment + (CASE)”): Derive encryption keys used to establish secure communication between the Commis­ + sioner or Administrator and Node with CASE. All unicast messages between a Commissioner or + Administrator and a Node are encrypted using these CASE-derived keys. +7. Commissioning complete message exchange (see Section 11.10, “General Commissioning Clus­ + ter”): A message exchange encrypted using CASE-derived encryption keys on the operational + network that indicates successful completion of commissioning process. + +A commissioner can reconfigure the Commissionee multiple times over the operational network +after the commissioning is complete or over the commissioning channel after PASE-derived encryp­ +tion keys are established during commissioning. The commissioning flows are described in Section +5.5, “Commissioning Flows”. + +**2.9. Intermittently Connected Device (ICD)** + +One goal of this standard is to provide support for communicating with devices that are intermit­ +tently connected to the network or unreachable for periods of time. The Intermittently Connected +Device operating mode behavior is specified in the Section 9.16, “Intermittently Connected Devices +Behavior” section. The Intermittently Connected Device (ICD) operating mode is defined to help +optimize network traffic, reachability, and power consumption for such nodes. Intermittent connec­ +tions can be caused by a number of factors, including duty cycling to minimize power consumption, +intermittent availability of network connectivity, device mobility, or intermittent availability of +power. + +The ICD operating mode is designed to be agnostic to underlying network layer mechanisms and +may be leveraged over any supported IP interfaces, including Thread and Wi-Fi. + +### NOTE + +``` +Because clients and infrastructure devices may have limited buffering space to +cache messages on behalf of intermittently connected devices, ICD communication +patterns SHOULD be designed such that the ICD is predominantly the initiator. +``` +**2.9.1. Sleepy End Device (SED)** + +The Sleepy End Device (SED) operating mode is defined by the Thread standard to help extend and +optimize battery lifetimes for Thread devices running on limited power sources such as batteries or +limited energy scavenging. While the Matter ICD operating mode can leverage Thread Sleepy End +Device (SED) behavior for Thread ICD devices, it SHOULD NOT be confused with it. + +**2.10. Data Model Root** + +- Endpoint 0 (zero) SHALL be the root node endpoint. +- Endpoint 0 (zero) SHALL support the Root Node device type. + +**2.11. Stack Limits** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 63 +``` + +**2.11.1. System Model Limits** + +**2.11.1.1. Access Control Limits** + +- A node SHALL guarantee that there are at least four Access Control Entries available for every + fabric supported by the node. + +``` +For example: A node that supports 5 fabrics must support at least 20 ACL entries, and if it sup­ +ports N entries must enforce that any K fabrics together do not use more than N - 4*(5-K) +entries. +``` +- Device types MAY impose additional constraints on the number of ACL entries that need to be + supported. + +**2.11.1.2. Group Limits** + +- A node SHALL support at least one group key per fabric for managing the IPK. +- If the node implements one or more device types with support for the Groups cluster, the node + SHALL additionally support the maximum number of the required groups as specified by all of + these implemented device types, without going below the following mandatory minima: + ◦ The node SHALL support at least three group keys per fabric. + ◦ The node SHALL support at least four group table entries per fabric per endpoint having a + Groups cluster instance. + ◦ Each Groups cluster instance SHALL support adding the endpoint to at least four groups. + +``` +For example: A node that supports 5 fabrics and has 1 endpoint with a Groups cluster must +support at least 20 group table entries. A node that supports 5 fabrics and has 2 endpoints +with a Groups cluster must support at least 40 group table entries. +``` +- A node SHALL support one IPv6 multicast group membership for every operational group it + supports. +- Support for GroupKeyMulticastPolicy field in GroupKeySetStruct is provisional. + +**2.11.2. Interaction Model Limits** + +**2.11.2.1. Read Interaction Limits** + +- A server SHALL ensure that every fabric the node is commissioned into can handle a single + Read Interaction from a client on that fabric containing up to 9 paths. +- A server MAY permit Read Interactions even when there is no accessing fabric, subject to avail­ + able resources (e.g over PASE). + +``` +Page 64 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.11.2.2. Subscribe Interaction Limits** + +- A publisher SHALL ensure that every fabric the node is commissioned into can support at least + three Subscribe Interactions to the publisher and that each subscription SHALL support at least + 3 attribute/event paths. +- A server MAY permit Subscribe Interactions even when there is no accessing fabric, subject to + available resources (e.g over PASE). +- Device type specifications MAY require a larger number of supported subscriptions or paths. +- SUBSCRIPTION_MAX_INTERVAL_PUBLISHER_LIMIT defines the upper limit for the publisher-selected + maximum interval for any subscription. + ◦ If the publisher is an ICD, this SHALL be set to the Idle Mode Duration. + ◦ If not, this SHALL be set to 60 minutes. +- The minimal supported capabilities, subject to the minimal constraints above, are reported in + the CapabilityMinima attribute of the Basic Information cluster. + +**2.11.2.3. Invoke Interaction Limits** + +- An Invoke Request action MAY contain multiple concrete command paths, if supported by the + server, but the total number of commands included in a single Invoke Request action is still lim­ + ited by the maximum message size constraints. + +**2.12. List of Provisional Items** + +The following is a list of provisional items. + +**2.12.1. Invoke Multiple Paths** + +Support for an Invoke Interaction with wildcard paths is provisional. + +**2.12.2. WildcardPathFlags options** + +Support for WildcardPathFlags option in wildcard expansion is provisional. + +**2.12.3. Proxy Service** + +The Proxy Architecture, the Proxy Config and Proxy Discovery clusters are provisional. + +**2.12.4. Tag compression encoding for AttributePathIB, EventPathIB, and** + +**AttributeDataIB** + +The Section 10.6.2.1, “EnableTagCompression” mechanism for encoding the interaction model is +provisional. + +**2.12.5. TCP support flags in TXT records** + +TCP server and TCP client bits in the DNS-SD TXT record is provisional (see [ref_DiscoveryT]). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 65 +``` + +**2.12.6. CacheAndSync Feature on the GroupKeyManagement cluster** + +Support for the CacheAndSync feature on the GroupKeyManagement cluster is provisional (see Sec­ +tion 11.2.4, “Features”). + +**2.12.7. VendorID Validation Procedure** + +Support for the VendorID Validation Procedure is provisional (see Section 6.4.10, “VendorID Valida­ +tion Procedure”). + +**2.12.8. Joint Fabric** + +Support for Joint Fabric, Joint Commissioning Method, policies for ID management within Joint Fab­ +ric, policies for management of the joint fabric administrator and cluster enhancements pertaining +to the creation and operation of a Joint Fabric is provisional. Specifically: + +- Joint Fabric Node ID Generation is a provisional requirement. +- TXT key for Joint Fabric is a provisional key. +- Joint Fabric Datastore cluster is provisional. +- Joint Fabric PKI cluster is provisional. + +**2.12.9. Wi-Fi Public Action Frame commissioning** + +Support for commissioning using Wi-Fi Public Action Frame transport, including references to Wi- +Fi public Action Frames in the Discovery Capabilities Bitmask, discovery, and WFA-USD Service Dis­ +covery Frame (SDF) Follow-up messages for transport of Matter messages is provisional. + +``` +Page 66 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 3. Cryptographic Primitives** + +This chapter introduces the various cryptographic primitives, algorithms and protocol building +blocks used in this protocol. It introduces for each of them a functional abstraction that can be +referred to in the other chapters of this specification. This chapter also maps those cryptographic +primitives to specific instances with the corresponding appropriate informative or normative refer­ +ences. Wherever relevant, it also gives necessary or relevant information about the use of these +mappings in a specific context to achieve a compliant implementation. + +Given a version of the Message Format, the cryptographic primitives are mapped to specific +instances. There is no cryptosuite negotiation in this protocol: one version of the Message Format +has one cryptosuite as defined in this chapter. + +Each section defines cryptographic primitives generically, together with concrete mappings to spe­ +cific instances of these cryptographic primitives for version 1.0 of the Message Format. This chapter +can also be used as guidance about which cryptographic primitives need to be supported by a +device, but it must be noted that not all devices will have to support all of them. For example, a +device may not require the Crypto_PBKDF() primitive, as values based on this operation could in +some instances be precomputed and stored during the manufacturing process of the device. The +proposed functional mapping in this chapter is normative with respect to the values computed by +the functions but informative with respect to the way the functions are interfaced within imple­ +mentations. For example, a function returning both a boolean to indicate success and a value if the +operation is successful could also be implemented using exception mechanisms instead of return­ +ing a boolean. + +It must also be noted that not all cryptographic primitives are exposed to the other parts of the +specification. For example, the Crypto_TRNG() primitive SHALL NOT be called outside of the Crypto_­ +DRBG() implementation. + +The cryptographic primitives discussed below operate on data local to the host. Where more com­ +plex data types are present and their external representation is applicable, the chapter notes the +details of the encoding. Simple multi-byte data types without any additional context are assumed to +be in host byte order when they are used internally to a procedure, unless otherwise stated. + +All octet strings are presented with first octet having index 0, and presented from left to right for +indices 0 through N-1 for an octet string of length N. + +**3.1. Deterministic Random Bit Generator (DRBG)** + +This protocol relies on random numbers for many security purposes. For example, random num­ +bers are used in generating secret keys, counters, cryptographic signature generation random +secrets, etc. Those random numbers SHALL be generated using the Crypto_DRBG() function. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 67 +``` + +``` +Function and description +``` +``` +bit[len] +Crypto_DRBG(int len) +``` +``` +Returns an array of len random bits. +``` +``` +Mapping (Version 1.0) +Crypto_DRBG() SHALL be implemented with one of the following DRBG algorithms as defined in +NIST 800-90A (the choice of which one is left to the manufacturer because the choice has no +impact on the interoperability): +``` +- CTR DRBG (with AES-CTR) +- HMAC DRBG (with SHA-256) +- HMAC DRBG (with SHA-512) +- Hash DRBG (with SHA-256) +- Hash DRBG (with SHA-512) + +``` +Crypto_DRBG() SHALL be seeded and reseeded using Crypto_TRNG() with at least 256 bits of entropy +(see among others Chapter 4, Section 8.4, and Section 8.6.8 of NIST 800-90A). +``` +**3.2. True Random Number Generator (TRNG)** + +A TRNG (a.k.a. Entropy Source) is required to provide an entropy seed as an input to the DRBG algo­ +rithm. + +``` +Function and description +``` +``` +bit[len] +Crypto_TRNG(int len) +``` +``` +Returns an array of len random bits. +``` +``` +Mapping (Version 1.0) +Crypto_TRNG() MAY be implemented according to the NIST 800-90B implementation guidelines but +alternate implementations MAY be used. +``` +In accordance with good security practices, the Crypto_TRNG() SHALL never be called directly but +rather SHALL be used in the implementation of Crypto_DRBG(). + +**3.3. Hash function (Hash)** + +Crypto_Hash() computes the cryptographic hash of a message. + +``` +Page 68 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Function and description +``` +``` +byte[CRYPTO_HASH_LEN_IN_BYTES] +Crypto_Hash(byte[] message) +``` +``` +Returns the cryptographic hash digest of the message. +``` +``` +Mapping (Version 1.0) +int CRYPTO_HASH_LEN_BITS := 256 +int CRYPTO_HASH_LEN_BYTES := 32 +int CRYPTO_HASH_BLOCK_LEN_BYTES := 64 +``` +``` +Crypto_Hash(message) := +byte[CRYPTO_HASH_LEN_BYTES] SHA-256(M := message) +``` +``` +SHA-256() SHALL be computed as defined in Section 6.2 of FIPS 180-4. +``` +**3.4. Keyed-Hash Message Authentication Code (HMAC)** + +Crypto_HMAC() computes the cryptographic keyed-hash message authentication code of a message. + +``` +Function and description +``` +``` +byte[CRYPTO_HASH_LEN_BYTES] +Crypto_HMAC(byte[] key, byte[] message) +``` +``` +Returns the cryptographic keyed-hash message authentication code of a message using the given +key. +``` +``` +Mapping (Version 1.0) +``` +``` +Crypto_HMAC(key, message) := +byte[CRYPTO_HASH_LEN_BYTES] HMAC(K := key, text := message) +``` +``` +HMAC() SHALL be computed as defined in FIPS 198-1 using Crypto_Hash() as the underlying hash +function H (this is also referred to as HMAC-SHA256()) and CRYPTO_HASH_LEN_BYTES is defined in Section +3.3, “Hash function (Hash)”. +``` +**3.5. Public Key Cryptography** + +Matter specifies the following scheme and parameters for public key cryptography. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 69 +``` + +**3.5.1. Group** + +The public key cryptography of Matter relies on the group defined in the following mapping table. + +``` +Mapping (Version 1.0) +Matter public key cryptography SHALL be based on Elliptic Curve Cryptography (ECC) with the +elliptic curve: secp256r1 defined in Section 2.4.2 of SEC 2. (This curve is also referred to as NIST P- +256 or prime256v1 in FIPS 186-4 and NIST 800-186.) +PrivateKey is an opaque data type to hold either the private key or any handle or reference that +allows other primitives to access the corresponding private key. +PublicKey is an opaque data type to hold the public key or any handle or reference that allows +other primitives to access the corresponding public key. A public key is a point on the elliptic +curve. (At places in the specification where public keys are to be explicitly transmitted, the format +in which they are transmitted is specified.) +int CRYPTO_GROUP_SIZE_BITS := 256 +int CRYPTO_GROUP_SIZE_BYTES := 32 +int CRYPTO_PUBLIC_KEY_SIZE_BYTES : = (2 * CRYPTO_GROUP_SIZE_BYTES) + 1 = 65 is the size in bytes +of the public key representation when encoded using the uncompressed public key format as spec­ +ified in section 2.3 of SEC 1. +``` +``` +struct { +PublicKey publicKey; +PrivateKey privateKey; +} KeyPair; +``` +**3.5.2. Key generation** + +Crypto_GenerateKeyPair() is the function to generate a key pair. + +``` +Function and description +``` +``` +KeyPair +Crypto_GenerateKeyPair() +``` +``` +Generates a key pair and returns a KeyPair. +``` +``` +Mapping (Version 1.0) +``` +``` +Crypto_GenerateKeypair() := +KeyPair ECCGenerateKeypair() +``` +``` +ECCGenerateKeypair() SHALL generate a key pair according to Section 3.2.1 of SEC 1. +``` +``` +Page 70 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**3.5.3. Signature and verification** + +Crypto_Sign() is used to sign a message, and Crypto_Verify() is used to verify a signature on a mes­ +sage. + +These functions either generate or verify a signature of type Signature defined by the following +mapping. + +``` +Mapping (Version 1.0) +``` +``` +struct { +byte[CRYPTO_GROUP_SIZE_BYTES] r, +byte[CRYPTO_GROUP_SIZE_BYTES] s +} Signature +``` +**3.5.3.1. Signature** + +``` +Function and description +``` +``` +Signature +Crypto_Sign( +PrivateKey privateKey, +byte[] message) +``` +``` +Returns the signature of the message using the privateKey. +``` +``` +Mapping (Version 1.0) +``` +``` +Crypto_Sign(privateKey, message) := +Signature ECDSASign(dU := privateKey, M := message) +``` +``` +ECDSASign() SHALL be the ECDSA signature function as defined in Section 4.1 of SEC 1 using Cryp­ +to_Hash() as the underlying hash Hash() function. +``` +**3.5.3.2. Signature verification** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 71 +``` + +``` +Function and description +``` +``` +boolean +Crypto_Verify( +PublicKey publicKey, +byte[] message, +Signature signature) +``` +``` +Verifies the signature of the message using the publicKey, returns TRUE if the verification succeeds, +FALSE otherwise. +``` +``` +Mapping (Version 1.0) +``` +``` +Crypto_Verify(publicKey, message, signature) := +boolean ECDSAVerify(QU := publicKey, M := message, S := signature) +``` +``` +ECDSAVerify() SHALL be the ECDSA signature verification function as defined in Section 4.1.4 of +SEC 1 using Crypto_Hash() as the underlying hash function Hash(); returns TRUE if the verification +succeeds and FALSE otherwise. +``` +**3.5.4. ECDH** + +Crypto_ECDH() is used to compute a shared secret from the Elliptic Curve Diffie-Hellman (ECDH) pro­ +tocol. + +``` +Function and description +``` +``` +byte[CRYPTO_GROUP_SIZE_BYTES] +Crypto_ECDH( +PrivateKey myPrivateKey, +PublicKey theirPublicKey) +``` +``` +Computes a shared secret using Elliptic Curve Diffie-Hellman. +``` +``` +Mapping (Version 1.0) +``` +``` +Crypto_ECDH(myPrivateKey, theirPublicKey) := +byte[CRYPTO_GROUP_SIZE_BYTES] ECDH(dU := myPrivateKey, QV := theirPublicKey) +``` +``` +The output of ECDH() SHALL be the serialization of the x-coordinate of the resultant point as +defined in Section 3.3.1 of SEC 1. +``` +**3.5.5. Certificate validation** + +Crypto_VerifyChain() is used to verify Matter certificates. + +``` +Page 72 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Crypto_VerifyChainDER() is used to verify public key X.509 v3 certificates in X.509 v3 DER format. + +``` +Function and description +``` +``` +boolean +Crypto_VerifyChain(MatterCertificate[] certificates) +``` +``` +Given Matter certificates, Crypto_VerifyChain() performs all the necessary validity checks on cer­ +tificates, taking in account that the notion of "current time" for the purposes of validation SHALL +abide by the rules in Section 3.5.6, “Time and date considerations for certificate path validation”. +``` +``` +boolean +Crypto_VerifyChainDER(DERCertificate[] certificates) +``` +``` +Given a list of DER-encoded certificates in RFC 5280 format, starting at the end-entity (leaf ) certifi­ +cate, and following the chain of trust towards the root, Crypto_VerifyChainDER() performs all the +necessary validity checks on certificates. +The Validity period validation for the root and optional intermediate certificates is performed +against the notBefore timestamp of the end-entity (leaf certificate) used as value for the current +time. +``` +``` +Mapping (Version 1.0) +``` +``` +Crypto_VerifyChain(certificates) := +boolean verified +``` +``` +verified is TRUE if the Matter certificates are verified as prescribed by RFC 5280. +``` +``` +Crypto_VerifyChainDER(certificates) := +boolean verified +``` +``` +verified is TRUE if the certificates are verified as prescribed by RFC 5280. +``` +The primitives as described above verify cryptographic integrity of the certificate chains. This spec­ +ification imposes a number of additional constraints on certificates discussed below in sections on +Device Attestation Certificates, Node Operational Certificates and Certificate Common Conventions. + +**3.5.6. Time and date considerations for certificate path validation** + +The Basic Path Validation algorithm in RFC 5280 mandates the consideration of the "current time" +against the validity period (notBefore, notAfter fields) when validating paths. The usage of "current +time" assumes that such a time is available and correct, which is a strong assumption when consid­ +ering some constrained devices or devices only locally reachable on a network in the absence of +infrastructure to synchronize time against a global real-time reference. + +When the Crypto_VerifyChain primitive is used, rather than overriding the Basic Path Validation + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 73 +``` + +algorithm of RFC 5280, Nodes SHALL consider the following definition of "current time" that +accounts for the possible lack of a real time reference: + +- If a Node has a current real-time clock value which is trusted according to implementation- + defined means to be accurate with regard to global real-time, whether using Time Synchroniza­ + tion features of this specification or other means, then it SHALL use that time; +- Otherwise, the current time SHALL be set to the last-known-good UTC time. + +Upon failure to validate a certificate path, where the only reason for failure is an invalid validity +period of a path element, a Node MAY apply a policy of its choice to determine whether to ignore +this failure and still consider the path valid. + +**3.5.6.1. Last Known Good UTC Time** + +Nodes SHALL maintain a stored Last Known Good UTC Time. This time is used as a fallback for +cryptographic credentials expiry enforcement, if all other available time synchronization mecha­ +nisms fail. + +The last known good UTC time SHALL be updated at commissioning and MAY be updated after a +successful time synchronization, or by an embedded time in an OTA. Nodes SHOULD store a Last +Known Good UTC Time value to persistent storage at least once a month. A Node’s initial out-of-box +Last Known Good UTC time SHALL be the compile-time of the firmware. + +A Node MAY adjust the Last Known Good UTC Time backwards if it believes the current Last Known +Good UTC Time is incorrect and it has a good time value from a trusted source. The Node SHOULD +NOT adjust the Last Known Good UTC to a time before the later of: + +- The build timestamp of its currently running software image +- The not-before timestamp of any of its operational certificates (see Section 6.4.5, “Node Opera­ + tional Credentials Certificates”). + +If a Node has used the Last Known Good UTC Time, it SHOULD recheck its security materials and +existing connections if it later achieves time synchronization. + +**3.6. Data Confidentiality and Integrity** + +Symmetric block ciphers are used to provide message security. + +All unicast and multicast messages between Nodes requiring protection for confidentiality and +integrity with data origin authentication SHALL use Authenticated Encryption with Associated Data +(AEAD) as primitive to protect those messages. + +``` +Page 74 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Mapping (Version 1.0) +Data confidentiality and integrity SHALL use the AES-CCM mode as defined in NIST 800-38C with +the following parameters: +``` +- int CRYPTO_SYMMETRIC_KEY_LENGTH_BITS := 128 (this is the key length of the underlying block + cipher in bits) +- int CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES := 16 (this is the key length of the underlying block + cipher in bytes) +- int CRYPTO_AEAD_MIC_LENGTH_BITS := 128 (this is the MIC length in bits) +- int CRYPTO_AEAD_MIC_LENGTH_BYTES := 16 (this is the MIC length in bytes) +- int CRYPTO_AEAD_NONCE_LENGTH_BYTES := 13 +- Key length SHALL be CRYPTO_SYMMETRIC_KEY_LENGTH_BITS bits. +- MIC length SHALL be CRYPTO_AEAD_MIC_LENGTH_BITS bits. +- The parameter q SHALL be 2 (length of encoding of maximum length) as specified in Appendix + A.1 of NIST 800-38C. +- The parameter n SHALL be CRYPTO_AEAD_NONCE_LENGTH_BYTES (length of nonce in bytes) as speci­ + fied in Appendix A.1 of NIST 800-38C. +SymmetricKey is an opaque data type to hold a symmetric block cipher key or any handle or refer­ +ence that allows other primitives to access the corresponding key. + +**3.6.1. Generate and encrypt** + +``` +Function and description +``` +``` +byte[lengthInBytes(P) + CRYPTO_AEAD_MIC_LENGTH_BYTES] +Crypto_AEAD_GenerateEncrypt( +SymmetricKey K, +byte[lengthInBytes(P)] P, +byte[] A, +byte[CRYPTO_AEAD_NONCE_LENGTH_BYTES] N) +``` +``` +Performs the generate and encrypt computation on payload P and the associated data A using the +key K and a nonce N; the output contains the ciphertext and the tag truncated to Tlen bits (the +encoding of the output depends on the mapping to the specific instance of the cryptographic prim­ +itive). +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 75 +``` + +``` +Mapping (Version 1.0) +``` +``` +Crypto_AEAD_GenerateEncrypt(K, P, A, N) := +byte[lengthInBytes(P) + CRYPTO_AEAD_MIC_LENGTH_BYTES] AES-CCM-GenerateEncrypt(K +:= K, P := P, A := A, N := N, Tlen := CRYPTO_AEAD_MIC_LENGTH_BITS) +``` +``` +AES-CCM-GenerateEncrypt() SHALL be the function described in Section 6.1 of NIST 800-38C with the +counter generation function of Appendix A.3 of NIST 800-38C and the formatting function as +defined in Appendix A.2 of NIST 800-38C; returns the encoding of the ciphertext and the tag of +length Tlen bits, as specified in Section 6.1 of NIST 800-38C as a byte array. +``` +**3.6.2. Decrypt and verify** + +``` +Function and description +``` +``` +{boolean success, byte[lengthInBytes(P)] payload} +Crypto_AEAD_DecryptVerify( +SymmetricKey K, +byte[lengthInBytes(P) + CRYPTO_AEAD_MIC_LENGTH_BYTES] C, +byte[] A, +byte[CRYPTO_AEAD_NONCE_LENGTH_BYTES] N) +``` +``` +Performs the decrypt and verify computation on the combined ciphertext and tag C and the associ­ +ated data A using the key K and a nonce N. Note that the encoding of C depends on the mapping of +the specific instance of the cryptography primitive. +``` +``` +This function has two outcomes: +``` +- If tag verification succeeds, the success output is TRUE and the payload array contains the + decrypted payload P. +- If tag verification fails, the success output is FALSE and the contents of the payload array is + undefined. + +``` +Page 76 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Mapping (Version 1.0) +``` +``` +Crypto_AEAD_DecryptVerify(K, C, A, N) := +{boolean, byte[lengthInBytes(P)]} AES-CCM-DecryptVerify(K := K, C := C, A := A, +N := N, Tlen := CRYPTO_AEAD_MIC_LENGTH_BITS) +``` +``` +AES-CCM-DecryptVerify() SHALL be the function described in Section 6.2 of NIST 800-38C with the +counter generation function of Appendix A.3 of NIST 800-38C and the formatting function as +defined in Appendix A.2 of NIST 800-38C and C SHALL be a byte array containing the ciphertext as +specified in Section 6.2 of NIST 800-38C. +``` +- If tag verification succeeds, the success output is TRUE and the payload array contains the + decrypted payload P. +- If tag verification fails, the success output is FALSE and the contents of the payload array is + undefined. + +**3.7. Message privacy** + +Message privacy is implemented using a block cipher in CTR mode. + +``` +Mapping (Version 1.0) +Message privacy SHALL use the AES-CTR mode as defined in NIST 800-38A with the following +parameters: +``` +- int CRYPTO_PRIVACY_NONCE_LENGTH_BYTES := 13 +- Key length SHALL be CRYPTO_SYMMETRIC_KEY_LENGTH_BITS bits. + +**3.7.1. Privacy encryption** + +``` +Function and description +``` +``` +byte[lengthInBytes(M)] +Crypto_Privacy_Encrypt( +SymmetricKey K, +byte[lengthInBytes(M)] M, +byte[CRYPTO_PRIVACY_NONCE_LENGTH_BYTES] N) +``` +``` +Performs the encryption of the message M using the key K and a nonce N; the output contains the +data M encrypted. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 77 +``` + +``` +Mapping (Version 1.0) +``` +``` +Crypto_Privacy_Encrypt(K, M, N) := +byte[lengthInBytes(M)] +AES-CTR-Encrypt(K := K, P := M, N := N) +``` +``` +AES-CTR-Encrypt() SHALL be the encryption function described in Section 6.5 of NIST 800-38A with +the sequence of counters T being generated according to the counter generation function of +Appendix A.3 of NIST 800-38C using N and the value of q = 2; returns the encrypted message as a +byte array. +``` +**3.7.2. Privacy decryption** + +``` +Function and description +``` +``` +byte[lengthInBytes(C)] +Crypto_Privacy_Decrypt( +SymmetricKey K, +byte[lengthInBytes(C)] C, +byte[CRYPTO_PRIVACY_NONCE_LENGTH_BYTES] N) +``` +``` +Performs the decryption of C using the key K and a nonce N; the output M is the decryption of C +``` +``` +Mapping (Version 1.0) +``` +``` +Crypto_Privacy_Decrypt(K, C, N) := +byte[lengthInBytes(C)] +AES-CTR-Decrypt(K := K, C := C, N := N) +``` +``` +AES-CTR-Decrypt() SHALL be the decryption function described in Section 6.5 of NIST 800-38A with +the sequence of counters T being generated according to the counter generation function of +Appendix A.3 of NIST 800-38C using N and the value of q = 2; returns the decrypted message as a +byte array. +``` +**3.8. Key Derivation Function (KDF)** + +Matter specifies the following key derivation function to generate encryption keys. + +``` +Page 78 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Function and description +``` +``` +bit[len] +Crypto_KDF( +byte[] inputKey, +byte[] salt, +byte[] info, +int len) +``` +``` +Returns the key of len bits derived from inputKey using the salt and the info; len SHALL be a mul­ +tiple of 8. +``` +``` +Mapping (Version 1.0) +``` +``` +Crypto_KDF(inputKey, salt, info, len) := +bit[len] HKDF-Expand( +PRK := HKDF-Extract(salt := salt, IKM := inputKey), +info := info, L := (len / 8)) +``` +``` +HKDF-Extract SHALL be the HKDF-Extract primitive from RFC 5869 section 2.2 using Crypto_HMAC +(i.e. HMAC-SHA256) as the auxiliary HMAC-Hash function. +``` +``` +HKDF-Expand SHALL be the HKDF-Expand primitive from RFC 5869 section 2.3 using Crypto_HMAC +(i.e. HMAC-SHA256) as the auxiliary HMAC-Hash function. +``` +``` +The primitive returns a bit array of len bits. +``` +When multiple keys of the same length are generated by a single KDF call, the following shorthand +notation can be used: + +``` +Key1 || Key2 || Key3 = Crypto_KDF +( +inputKey = inputKeyMaterial, +salt = [], +info = [], +// 3 below matches number of keys expressed in concatenated output +len = 3 * CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +This is equivalent to the following: + +``` +Keys = Crypto_KDF +( +inputKey = inputKeyMaterial, +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 79 +``` + +``` +salt = [], +info = [], +len = 3 * CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +1. Set Key1 to the CRYPTO_SYMMETRIC_KEY_LENGTH_BITS most significant bits of Keys. +2. Set Key2 to the next CRYPTO_SYMMETRIC_KEY_LENGTH_BITS significant bits of Keys. +3. Set Key3 to the CRYPTO_SYMMETRIC_KEY_LENGTH_BITS least significant bits of Keys. + +**3.9. Password-Based Key Derivation Function (PBKDF)** + +Matter specifies the following password-based key derivation function to compute a derived key +from a cryptographically weak password. + +``` +Function and description +``` +``` +bit[len] +Crypto_PBKDF( +byte[] input, +byte[] salt, +int iterations, +int len) +``` +``` +Returns a value of len bits derived from the input using the salt and iterations iterations. +``` +``` +Type and description +``` +``` +STRUCTURE Crypto_PBKDFParameterSet +``` +``` +Maintains the set of parameters exchanged between a Commissioner and a Commissionee during +their pairing. +``` +``` +Mapping (Version 1.0) +int CRYPTO_PBKDF_ITERATIONS_MIN := 1000 +int CRYPTO_PBKDF_ITERATIONS_MAX := 100000 +``` +``` +Crypto_PBKDF(input, salt, iterations, len) := +bit[len] PBKDF2(P := input, S := salt, C := iterations, kLen := len) +``` +``` +PBKDF2() SHALL be the HMAC-based PBKDF function with Crypto_HMAC(key := P, message := U[j- +1]) as the auxiliary function HMAC as defined in Section 5.3 of NIST 800-132; it returns a bit array of +len bits. +``` +``` +Page 80 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Mapping (Version 1.0) +``` +``` +Crypto_PBKDFParameterSet => STRUCTURE [ tag-order ] +{ +iterations [1] : UNSIGNED INTEGER [ range 32-bits ], +salt [2] : OCTET STRING [ length 16..32 ], +} +``` +- iterations: An integer value specifying the number of PBKDF2 iterations: CRYPTO_PBKDF_ITERA­ + TIONS_MIN <= iterations <= CRYPTO_PBKDF_ITERATIONS_MAX. +- salt: A random value per device of at least 16 bytes and at most 32 bytes used as the PBKDF2 + salt. + +**3.10. Password-Authenticated Key Exchange (PAKE)** + +This protocol uses password-authenticated key exchange (PAKE) for the PASE protocol. + +``` +Mapping (Version 1.0) +Matter uses SPAKE2+ as described in SPAKE2+ as PAKE with: +``` +- The SPAKE2+ verifier is the Commissionee/Responder and the SPAKE2+ prover is the Commis­ + sioner/Initiator +- Crypto_PBKDF() as underlying PBKDF (see Section 3.9, “Password-Based Key Derivation Func­ + tion (PBKDF)”), with arguments as described in the definition of Crypto_PAKEValues_Initiator +- NIST P-256 elliptic curve as underlying group (see Section 3.5.1, “Group”). + ◦ SPAKE2+ requires two additional points on the curve: M and N. The values of M and N are + taken from the draft version 2 of the SPAKE2+ specification (SPAKE2+) and are listed below + in compressed format (format defined in section 2.3 of SEC 1): + ▪ M = 02886e2f97ace46e55ba9dd7242579f2993b64e16ef3dcab95afd497333d8fa12f + ▪ N = 03d8bbd6c639c62937b04d997f38c3770719c629d7014d49a24b4f98baa1292b49 +- Crypto_Hash() as underlying hash function (see Section 3.3, “Hash function (Hash)”). +- Crypto_HMAC() as underlying HMAC function (see Section 3.4, “Keyed-Hash Message Authentica­ + tion Code (HMAC)”). +- KDF(info, key, salt) := Crypto_KDF(key, salt, info, CRYPTO_HASH_LEN_BITS) as underlying + KDF function (see Section 3.8, “Key Derivation Function (KDF)”). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 81 +``` + +``` +Mapping (Version 1.0) +Crypto_PAKEValues_Initiator := (w0, w1) where w0 and w1 SHALL be computed as follows: +``` +### CRYPTO_W_SIZE_BYTES := CRYPTO_GROUP_SIZE_BYTES + 8 + +### CRYPTO_W_SIZE_BITS := CRYPTO_W_SIZE_BYTES * 8 + +``` +byte w0s[CRYPTO_W_SIZE_BYTES] || byte w1s[CRYPTO_W_SIZE_BYTES] = +(byte[2 * CRYPTO_W_SIZE_BYTES]) +bit[2 * CRYPTO_W_SIZE_BITS] +Crypto_PBKDF(passcode, salt, iterations, 2 * CRYPTO_W_SIZE_BITS) +byte w0[CRYPTO_GROUP_SIZE_BYTES] = w0s mod p +byte w1[CRYPTO_GROUP_SIZE_BYTES] = w1s mod p +``` +``` +where: +``` +- mod is the mathematical modulo operation and || is the string concatenation or split operator. +- passcode, is the Passcode defined in Section 5.1.1.6, “Passcode”, serialized as little-endian over 4 + octets. For example, passcode 18924017 would be encoded as the octet string f1:c1:20:01 and + the passcode 00000005 would be encoded as the octet string 05:00:00:00. +- p is the order of the underlying elliptic curve. +- Both w0s and w1s SHALL have a length equal to (CRYPTO_GROUP_SIZE_BYTES + 8). +- salt and iterations are extracted from the Crypto_PBKDFParameterSet values. +- The pair (w0,w1) is also referred to as Commissioner PAKE input + +Page 82 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +Mapping (Version 1.0) +Crypto_PAKEValues_Responder := (w0, L) where w0 and L SHALL be computed as follows: +``` +``` +byte w0s[CRYPTO_W_SIZE_BYTES] || byte w1s[CRYPTO_W_SIZE_BYTES] = +(byte[2 * CRYPTO_W_SIZE_BYTES]) +bit[2 * CRYPTO_W_SIZE_BITS] +Crypto_PBKDF(passcode, salt, iterations, 2 * CRYPTO_W_SIZE_BITS) +byte w0[CRYPTO_GROUP_SIZE_BYTES] = w0s mod p +byte w1[CRYPTO_GROUP_SIZE_BYTES] = w1s mod p +byte L[CRYPTO_PUBLIC_KEY_SIZE_BYTES] = w1 * P +``` +``` +where: +``` +- passcode, is the Passcode defined in Section 5.1.1.6, “Passcode”. +- p is the order of the elliptic curve to be used. +- Both w0s and w1s SHALL have a length equal to (CRYPTO_GROUP_SIZE_BYTES + 8). +- salt and iterations are extracted from the Crypto_PBKDFParameterSet values. +- P is the generator of the underlying elliptic curve. +- When the computation of Crypto_PAKEValues_Responder is done, fields w0 and L SHALL be stored + in the Responder and w1 SHALL NOT be stored in the Responder. +- The pair (w0,L) is also referred to as Commissionee PAKE input or verification value + +**3.10.1. Computation of pA** + +``` +Mapping (Version 1.0) +``` +``` +Crypto_pA(Crypto_PAKEValues_Initiator) := +byte pA[CRYPTO_PUBLIC_KEY_SIZE_BYTES] +``` +``` +pA is in uncompressed public key format as specified in section 2.3 of SEC 1. pA SHALL be com­ +puted as specified in SPAKE2+. +``` +**3.10.2. Computation of pB** + +``` +Mapping (Version 1.0) +``` +``` +Crypto_pB(Crypto_PAKEValues_Responder) := +byte pB[CRYPTO_PUBLIC_KEY_SIZE_BYTES] +``` +``` +pB is in uncompressed public key format as specified in section 2.3 of SEC 1. pB SHALL be com­ +puted as specified in SPAKE2+. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 83 +``` + +**3.10.3. Computation of transcript TT** + +``` +Mapping (Version 1.0) +``` +``` +Crypto_Transcript(PBKDFParamRequest, PBKDFParamResponse, pA, pB) := +byte[] TT +``` +``` +Crypto_Transcript() SHALL compute TT as specified in SPAKE2+ with: +``` +``` +byte ContextPrefixValue [26] = { +0x43, 0x48, 0x49, 0x50, 0x20, 0x50, 0x41, 0x4b, 0x45, 0x20, 0x56, 0x31, 0x20, 0x43, +0x6f, 0x6d, +0x6d, 0x69, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x69, 0x6e, 0x67 +} // "CHIP PAKE V1 Commissioning" - The usage of CHIP here is intentional and due to +implementation in the SDK before the name change, should not be renamed to Matter. +``` +``` +Context := Crypto_Hash(ContextPrefixValue || PBKDFParamRequest || PBKDFParamResponse) +``` +### TT := + +``` +lengthInBytes(Context) || Context || +0x0000000000000000 || 0x0000000000000000 || +lengthInBytes(M) || M || +lengthInBytes(N) || N || +lengthInBytes(pA) || pA || +lengthInBytes(pB) || pB || +lengthInBytes(Z) || Z || +lengthInBytes(V) || V || +lengthInBytes(w0) || w0 +``` +``` +Z and V SHALL be computed from pA and pB as specified in SPAKE2+. +``` +``` +Note the two 0x0000000000000000 null-lengths indicate that no identities are present and each null- +lengths is 8 bytes wide since it is specified by the SPAKE2+ specification that lengths are eight-byte +little-endian numbers. The SPAKE2+ specification indicates that we must include these length +fields. +``` +``` +Note in case PBKDFParamRequest and PBKDFParamResponse messages are not exchanged, they SHALL +be replaced by empty strings in the Context computation. +``` +**3.10.4. Computation of cA, cB and Ke** + +``` +Page 84 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Mapping (Version 1.0)** + +``` +Crypto_P2(TT, pA, pB) := +{byte cA[CRYPTO_HASH_LEN_BYTES], +byte cB[CRYPTO_HASH_LEN_BYTES], +byte Ke[CRYPTO_HASH_LEN_BYTES/2]} +``` +Crypto_P2() SHALL compute cA, cB and Ke as specified in SPAKE2+ with cA := CRYPTO_HMAC(KcA,pB) +and cB := CRYPTO_HMAC(KcB,pA). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 85 +``` + +Page 86 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 4. Secure Channel** + +**4.1. General Description** + +The Secure Channel and Message Layer provides a consistent networking service substrate to allow +Nodes to communicate securely with one another. + +During commissioning and unicast communication, a discovery mechanism is provided to deter­ +mine peer IPv6 addresses and operational parameters. Secure session establishment mechanisms +are provided using either certificates (CASE) or shared passcodes (PASE). + +**4.1.1. Messages** + +Communication is performed using messages. Messages are either secured or unsecured. + +Each message has a Session Type and Session ID in order to identify whether it is secured and how +it is to be decrypted and authenticated if it is. Each message has a Message Counter field in order to +uniquely identify the message for the purposes of security and duplicate detection. + +Operational communication is defined as traffic that uses the secured Matter message format +between commissioned nodes over an IP transport. All operational communication has message +security enabled. Operational communication between Nodes can be either unicast or multicast. + +Unsecured communication is strictly limited to: + +- Discovery, which does not use the Matter message format. +- User Directed Commissioning (UDC), which uses unsecured messages to initiate the commission­ + ing process. +- Session establishment, which uses unsecured messages to establish a CASE or PASE session. + +**4.1.1.1. Message Types** + +Messages are defined as either a _control message_ or _data message_. Most messages are data mes­ +sages. Control messages are reserved for internal protocols such as MCSP to initialize security. Both +message types are identical in format, but use separate message counter domains so they can oper­ +ate securely over the same security key. + +**4.1.1.2. Message Transports** + +Messages are of finite size and are sent as individual packets over the supported transports: + +- UDP transports each message as a separate datagram. Messages support a basic reliability pro­ + tocol called MRP for use when the underlying transport (in this case UDP) doesn’t provide such + features. +- TCP transports each message with a length prepended, performing segmentation and reassem­ + bly as needed. +- BTP transports each message over BLE as a separate SDU, performing segmentation and + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 87 +``` + +``` +reassembly as needed. +``` +- Wi-Fi Public Action Frame transports each message over Wi-Fi by encapsulating it into a Wi-Fi + Public Action Frame as defined in Wi-Fi Alliance Unsynchronized Service Discovery (WFA-USD). + +BTP is provided as a transport protocol for commissioning using a BLE interface. Wi-Fi Public +Action Frame is provided as a transport protocol for commissioning using a Wi-Fi interface. TCP +and MRP (UDP with added reliability) are provided as transport protocols for operational messag­ +ing. + +**4.1.1.3. Message Exchanges** + +Messages provide an Exchange Layer to track related messages that make up small, discrete trans­ +actions. The Exchange Layer provides this transaction tracking facility to the Interaction Model +Layer above, providing a means to multiplex multiple such concurrent transactions over a given +underlying session. The Exchange Layer also integrates the Message Reliability Protocol (MRP) as a +service for use over UDP transports. This Message Layer architecture is shown below in Figure 6, +“Message Layer Stack”: + +_Figure 6. Message Layer Stack_ + +**4.2. IPv6 Reachability** + +This section describes IPv6 network configuration requirements to enable IPv6 reachability +between Nodes. As described in Section 2.3, “Network Topology”, a Matter network may be com­ +posed of one or more IPv6 networks. + +In a single network configuration, all Matter Nodes are attached to the same IPv6 link. A single net­ +work configuration may consist of a single bridged Wi-Fi / Ethernet network where all nodes +attached to that network are part of the same broadcast domain. When all Matter Nodes are +attached to the same Wi-Fi / Ethernet network, link-local IPv6 addressing is sufficient - no addi­ +tional IPv6 network infrastructure is required. + +In a multiple network configuration, a Matter network is composed of (typically one) infrastructure +network and one or more stub networks. Unlike an infrastructure network, stub networks do not +serve as transit networks. Typically, the infrastructure network is a bridged Wi-Fi / Ethernet net­ + +``` +Page 88 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +work and the Thread networks are stub networks. A stub router connects a stub network to an +infrastructure network and provides IPv6 reachability between the two networks. + +**4.2.1. Stub Router Behavior** + +A stub router SHALL implement [draft-lemon-stub-networks]. In a multiple network configuration, +both the infrastructure and stub networks require routable IPv6 addresses to communicate across +networks. A routable IPv6 address SHALL have global scope (e.g. GUA or ULA) [RFC 4007] and +SHALL be constructed out of a prefix advertised as on-link. If there is no routable prefix on a given +network, the stub router SHALL provide its own routable prefix. Note that Thread’s "on-mesh pre­ +fix" is equivalent to Wi-Fi / Ethernet’s "on-link prefix". + +Stub routers SHALL advertise reachability to all routable prefixes on the adjacent network. A stub +router connecting a Thread network SHALL advertise reachability to all of the Thread network’s +routable prefixes to the adjacent infrastructure network using Route Information Options +[RFC 4191] contained in Router Advertisements [RFC 4861]. That same stub router SHALL also +advertise reachability to all of the infrastructure network’s routable prefixes to the adjacent Thread +network in the Thread Network Data [Thread specification]. + +**4.2.2. Matter Node Behavior** + +Matter Nodes SHALL configure a link-local IPv6 address. In addition, Nodes SHALL support configu­ +ration of at least three routable IPv6 addresses (in addition to the link-local and, in the case of +Thread, mesh-local addresses). On a Wi-Fi / Ethernet interface, ICMPv6 Router Advertisement (RA) +messages advertise prefixes for use on the link [RFC 4861]. On a Thread interface, the Thread Net­ +work Data contains prefixes for use on the link [Thread specification]. If a Node receives an on-link +prefix that allows autonomous configuration on a given interface and the Node has fewer than +three routable IPv6 addresses configured, the Node SHALL autonomously configure an IPv6 +address out of that prefix. + +Matter Nodes SHALL also configure routes to adjacent networks. On Wi-Fi / Ethernet networks, +Nodes SHALL process Route Information Options [RFC 4191] and configure routes to IPv6 prefixes +assigned to stub networks via stub routers. Wi-Fi / Ethernet interfaces SHALL support maintaining +at least 16 different routes configured using Route Information Options. On Thread networks, +Nodes SHALL route according to routing information provided in the Thread Network Data [Thread +specification]. Thread devices SHALL support as many routes as can be encoded in the Thread Net­ +work Data. + +Matter Nodes SHALL support a number of IPv6 neighbor cache entries at least as large as the num­ +ber of supported CASE sessions plus the number of supported routes. + +**4.3. Discovery** + +This section describes Service Advertising and Discovery for Matter. + +Service Advertising and Discovery is used within Matter in the following contexts: + +- Commissionable Node Discovery + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 89 +``` + +- Operational Discovery +- Commissioner Discovery +- User Directed Commissioning + +Service Advertising and Discovery for Matter uses IETF Standard DNS-Based Service Discovery +(DNS‑SD) [RFC 6763]. Matter requires no modifications to IETF Standard DNS‑SD. + +Using DNS‑SD means that both the unicast IPv6 address and port of the offered service are discov­ +ered, freeing Matter from requiring a single preallocated fixed port. This also makes it possible to +run multiple instances of Matter software on a single device, because each instance has its own +dynamically allocated port, instead of conflicting over attempting to use the same preallocated +fixed port. + +On Wi‑Fi and Ethernet networks today, DNS‑SD [RFC 6763] uses Multicast DNS [RFC 6762] for zero- +configuration operation. + +Since Matter protocols must support IPv6 at a minimum, Matter software discovering other Matter +instances SHALL process DNS AAAA (IPv6 address) records, but also MAY process DNS A (IPv4 +address) records. + +Because of this, where feasible in the underlying service discovery API, Matter software advertising +the availability of a service SHOULD indicate that announcements and answers for this service +need include only IPv6 address records, not IPv4 address records. On a general-purpose dual-stack +host that supports both IPv4 and IPv6, this can be achieved by having Matter-related SRV records +reference a Matter-specific target hostname that has only IPv6 address records attached. This +allows a general-purpose dual-stack host to offer discoverable IPv4 addresses for legacy client soft­ +ware that still requires IPv4, while offering optimized IPv6-only address discovery for Matter pur­ +poses. + +Similarly, since Matter does not use IPv4, Matter software discovering other Matter instances +SHOULD NOT expect any IPv4 addresses included in responses. + +These two items address the _content_ of service discovery messages. When using Multicast DNS simi­ +lar efficiency questions arise related to the _delivery_ of those service discovery messages, sent over +IPv4, IPv6, or both. + +Where supported in the underlying service discovery API, Matter software using Multicast DNS to +advertise the availability of a service SHOULD indicate that announcements and answers for this +service need only be performed over IPv6. + +Similarly, where supported in the underlying service discovery API, Matter application software +using Multicast DNS to issue service discovery queries SHOULD indicate that these queries need +only be performed over IPv6. + +These optimizations reduce both the size and the number of multicast packets, which is particularly +beneficial on Wi‑Fi networks. A Matter device that only supports IPv6 gets these optimizations auto­ +matically, simply by virtue of not supporting IPv4 at all. + +For Thread mesh networks, where excessive use of multicast would be detrimental [RFC 7558], + +``` +Page 90 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +DNS‑SD uses Unicast DNS instead, leveraging capabilities of the Thread Service Registry on the +Thread Border Router [draft-lemon-stub-networks]. + +Conceptually, the DNS‑SD [RFC 6763] information being communicated is identical to when Multi­ +cast DNS [RFC 6762] is being used, except that the information is communicated in unicast packets +to and from a designated Service Registry, rather than being communicated in multicast packets to +and from every other Node in the same broadcast domain. + +Using Service Registration Protocol [SRP] and an Advertising Proxy [AdProx] running on the Thread +Border Router, Matter Nodes on a Thread mesh can be discovered by other Matter Nodes on an +adjacent Ethernet or Wi‑Fi link, without the cost of using multicast on the Thread mesh. All Thread- +connected Matter Nodes SHALL implement Service Registration Protocol. + +Thread Border Routers advertise available SRP servers in the Thread Network Data [Thread specifi­ +cation]. Thread devices SHALL register their services using an available SRP server [Thread specifi­ +cation]. + +When Matter Nodes issue short-lived requests to other Matter Nodes, the response is sent back to +the source IPv6 address and port of the request. When Matter Nodes issue long-lived requests to +other Matter Nodes, by the time the response is generated the requester may have changed IPv6 +address or port, so the responder may have to discover the current IPv6 address and port of the ini­ +tiator in order to send the response. + +A Thread Border Router SHALL implement DNS‑SD Discovery Proxy [RFC 8766] to enable clients on +the Thread mesh (e.g., other Nodes) to discover services (e.g., Matter Nodes) advertised using Multi­ +cast DNS on an adjacent Ethernet or Wi‑Fi link, also without the cost of using multicast on the +Thread mesh [draft-lemon-stub-networks]. For short-lived instantaneous queries, these queries can +be performed using unicast DNS over UDP to the DNS‑SD Discovery Proxy. For long-lived queries +with ongoing change notification, DNS Push Notifications [RFC 8765] with DNS Stateful Operations +[RFC 8490] allows clients on the Thread mesh to be notified of changes to the set of discovered ser­ +vices without expensive polling. + +In principle, the Thread mesh Service Registry can be run on any capable Node(s) within (or even +outside) the Thread mesh, though in practice the Thread Border Router is an attractive candidate to +offer the Service Registry. Thread Border Router devices are typically AC-powered, and typically +have more capable CPUs with greater flash storage and RAM than more constrained battery-pow­ +ered Thread Nodes. Matter devices on Thread are dependent on Thread providing reliable service +for those Thread devices on the Thread mesh. This is similar to how Matter devices on Wi‑Fi are +dependent on the Wi‑Fi access point (AP) providing reliable service for those Wi‑Fi devices using +that Wi‑Fi access point. + +**4.3.1. Commissionable Node Discovery** + +The Matter protocol family supports UDP and TCP for Matter commissioning of Commissionees +already on the customer’s IP network (such as Ethernet-connected Nodes, or Wi‑Fi Nodes already +associated to the Wi‑Fi network via other means). + +For these Commissionees, Matter Commissionable Node Discovery is performed using IETF Stan­ +dard DNS-Based Service Discovery (DNS‑SD) [RFC 6763] as described below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 91 +``` + +For Matter Commissionable Node Discovery in the _already-on-network_ case, the DNS‑SD instance +name SHALL be a dynamic, pseudo-randomly selected, 64-bit temporary unique identifier, +expressed as a fixed-length sixteen-character hexadecimal string, encoded as ASCII (UTF-8) text +using capital letters, e.g., DD200C20D25AE5F7. A new instance name SHALL be selected when the Node +boots. A new instance name SHALL be selected whenever the Node enters Commissioning mode. A +new instance name MAY be selected at other times, as long as the instance name does not change +while the Node is in commissioning mode. + +A commissionable Node that is already connected to an IP-bearing network SHALL only make itself +discoverable on the IP network and SHALL use the relevant DNS-SD service (_matterc._udp) +described below. + +If a Node is connected to multiple IP-bearing networks, and it receives either the OpenCommission­ +ingWindow or the OpenBasicCommissioningWindow command, it MAY make itself discoverable +only on the network on which the command was received. Otherwise, a commissionable Node that +is connected to multiple IP-bearing networks SHALL make itself discoverable on all of its connected +IP-bearing networks. + +The Matter Commissionable Node Discovery DNS‑SD instance name SHALL be unique within the +namespace of the local network (the .local link-local namespace of the Ethernet and Wi‑Fi links +[RFC 6762], or the unicast domain selected by the Thread Border Router for devices on the Thread +mesh). + +In the rare event of a collision in the selection of the 64-bit temporary unique identifier, the existing +DNS‑SD name conflict detection mechanism will detect this collision, and a new pseudo-randomly +selected 64-bit temporary unique identifier SHALL be generated by the Matter Commissionee that +is preparing for commissioning. Name conflict detection is described in Section 9 ("Conflict Resolu­ +tion") of the Multicast DNS specification [RFC 6762] and Section 2.4.3.1 ("Validation of Adds") of the +Service Registration Protocol specification [SRP]. + +The DNS‑SD service type [RFC 6335] for Matter Commissionable Node Discovery is _matterc._udp. + +For link-local Multicast DNS the service domain SHALL be local. For Unicast DNS such as used on +Thread the service domain SHALL be as configured automatically by the Thread Border Router. + +**4.3.1.1. Host Name Construction** + +For DNS‑SD a target host name is required, in addition to the instance name. The target host name +SHALL be constructed using one of the available link-layer addresses, such as a 48-bit device MAC +address (for Ethernet and Wi‑Fi) or a 64-bit MAC Extended Address (for Thread) expressed as a +fixed-length twelve-character (or sixteen-character) hexadecimal string, encoded as ASCII (UTF-8) +text using capital letters, e.g., B75AFB458ECD.. In the event that a device performs MAC +address randomization for privacy, then the target host name SHALL use the privacy-preserving +randomized version and the hostname SHALL be updated in the record every time the underlying +link-layer address rotates. Note that it is legal to reuse the same hostname on more than one inter­ +face, even if the underlying link-layer address does not match the hostname on that interface, since +the goal of using a link-layer address is to ensure local uniqueness of the generated hostname. If +future link layers are supported by Matter that do not use 48-bit MAC addresses or 64-bit MAC +Extended Address identifiers, then a similar rule will be defined for those technologies. + +``` +Page 92 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.1.2. Extended Discovery** + +A Matter Commissionee that advertises Commissionable Node Discovery service records is not nec­ +essarily in a state that will allow Commissioning (this state is referred to below as "in Commission­ +ing Mode"). While Section 5.4.2.3, “Announcement Duration” is limited for some forms of device +advertisement, a Matter device MAY advertise Matter Commissionable Node Discovery service +records for longer periods, possibly permanently. Advertising Commissionable Node Discovery +when not in Commissioning Mode is referred to here as Extended Discovery. Extended Discovery is +allowed only for DNS-SD advertisements and not for the other forms of Device Discovery such as +BLE Commissioning Discovery. + +To protect customer privacy on public networks, a Matter Commissionee SHALL provide a way for +the customer to set a timeout on Extended Discovery, or otherwise disable Extended Discovery. The +default behavior for Commissionable Node Discovery SHOULD default to limiting announcement as +defined in Section 5.4.2.3, “Announcement Duration” unless the Manufacturer wishes to enable +longer periods for specific use cases. + +**4.3.1.3. Commissioning Subtypes** + +The following subtypes for Matter Commissionable Node Discovery are defined: + +1. _L, where provides the full 12-bit discriminator, encoded as a variable-length deci­ + mal number in ASCII text, omitting any leading zeroes. +2. _S
, where
provides the upper 4 bits of the discriminator, encoded as a variable-length + decimal number in ASCII text, omitting any leading zeroes. +3. _V, where provides the 16-bit Vendor ID, encoded as a variable-length decimal + number in ASCII text, omitting any leading zeroes. +4. _T, where provides the device type identifier for the device, encoded as a variable- + length decimal number in ASCII (UTF-8) text, omitting any leading zeroes. In case the device + combines multiple device types, the manufacturer SHOULD choose the device type identifier of + the primary function of the device for which the device wishes to be discoverable. +5. _CM, which represents "currently in Commissioning Mode" (due to any method, for example, a + factory new device that has just been put into commissioning mode by the user, or an already- + commissioned device which has just received the Open Commissioning Window command). + +The _long discriminator_ subtype (e.g., _L840) enables filtering of results to find only Commissionees +that match the full discriminator code, as provided in the onboarding payload. + +The _short discriminator_ subtype (e.g., _S3) enables filtering of results to find only Commissionees +that match the upper 4 bits of the discriminator code, as provided in the manual pairing code. + +The optional _Vendor ID_ subtype (e.g., _V123) enables a vendor-specific app to achieve filtering of +results to find only Nodes that match that Vendor ID. + +The _Commissioning Mode_ subtype (e.g., _CM) enables filtering of results to find only Nodes that are +currently in Commissioning Mode. Note that the subtype is _CM regardless of whether the TXT +record for commissioning mode is set to 1 (CM=1) or 2 (CM=2). A Commissionee that is not in commis­ +sioning mode (CM=0) SHALL NOT publish this subtype. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 93 +``` + +The optional _device type_ subtype (e.g., _T10) enables filtering of results to find only Nodes that match +the device type, generally used for the User-Initiated Beacon Detection, Not Yet Commissioned +Device and the User-Initiated Beacon Detection, Already Commissioned Device use cases. + +In the event that a vendor-specific app wishes to show the user only some of that vendor’s Commis­ +sionees awaiting commissioning but not all of them, any desired filtering logic (based upon arbi­ +trary criteria, not only Product ID) MAY be implemented within that vendor’s proprietary commis­ +sioning app. + +**4.3.1.4. TXT Records** + +After discovery, IPv6 addresses are returned in the AAAA records and key/value pairs are returned +in the DNS‑SD TXT record. + +Nodes SHALL publish AAAA records for all available IPv6 addresses upon which they are willing to +accept Matter commissioning messages. + +TXT records available for Commissionable Node Discovery include the common TXT record +key/value pairs defined in Section 4.3.4, “Common TXT Key/Value Pairs”. + +Commissioners SHALL silently ignore TXT record keys that they do not recognize. This is to facili­ +tate future evolution of this specification without breaking backwards compatibility with existing +Commissioners that do not implement the new functionality. + +The following subsections describe key/value pairs that are defined specifically for Commissionable +Node discovery. + +**4.3.1.5. TXT key for discriminator (** D **)** + +The key D SHALL provide the full 12-bit discriminator for the Commissionable Node and SHALL be +present in the DNS-SD TXT record. + +The discriminator value SHALL be encoded as a variable-length decimal number in ASCII text, with +up to four digits, omitting any leading zeroes. + +Any key D with a value mismatching the aforementioned format SHALL be silently ignored. + +As an example, value D=840 would indicate that this Commissionable Node has decimal long dis­ +criminator 840. When needed, the upper 4 bits of the discriminator provided by the manual pairing +code can be algorithmically derived from the full discriminator. + +**4.3.1.6. TXT key for Vendor ID and Product ID (** VP **)** + +The optional key VP, if present, MAY provide Vendor ID and Product ID information of the device. + +A vendor MAY choose not to include it at all, for privacy reasons. + +If the VP key is present then it MAY take two forms: + +1. VP=123 gives Vendor ID +2. VP=123+456 gives Vendor ID + Product ID + +``` +Page 94 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The Vendor ID and Product ID SHALL both be expressed as variable-length decimal numbers, +encoded as ASCII text, omitting any leading zeroes, and of maximum length of 5 characters each to +fit their 16-bit numerical range. + +If the Product ID is present, it SHALL be separated from the Vendor ID using a ‘+’ character. + +If the VP key is present without a Product ID, the value SHALL contain only the Vendor ID alone, +with no ‘+’ character. + +If the VP key is present, the value SHALL contain at least the Vendor ID. + +If the VP key is present, it SHALL NOT have a missing or empty value. + +**4.3.1.7. TXT key for commissioning mode (** CM **)** + +The key CM (Commissioning Mode) SHALL indicate whether or not the publisher of the record is cur­ +rently in Commissioning Mode and available for immediate commissioning. When in commission­ +ing mode, the value associated with the CM key indicates the source of the passcode. + +Four situations are legal: + +1. The absence of key CM SHALL imply a value of 0 (CM=0). +2. The key/value pair CM=0 SHALL indicate that the publisher is not currently in Commissioning + Mode. +3. The key/value pair CM=1 SHALL indicate that the publisher is currently in Commissioning Mode + and requires use of a passcode for commissioning provided by the Commissionee (e.g., printed + on a label or displayed on screen), such as when the device is in a factory-new state or when the + Open Basic Commissioning Window command has been used to enter commissioning mode. +4. The key/value pair CM=2 SHALL indicate that the publisher is currently in Commissioning Mode + and requires use of a dynamically generated passcode for commissioning corresponding to the + verifier that was passed to the device using the Open Commissioning Window command. + +A key value of 2 MAY be used to disambiguate collisions of discriminators between uncommis­ +sioned Nodes and commissioned Nodes announcing after a commissioning window was opened. A +key value of 2 serves as a hint to Commissioners to possibly expect multiple Nodes with the same +discriminator (see Commissioning Discriminator), and to instruct the user to enter the Onboarding +Payload presented by another Administrator rather than a code provided by the Commissionee. + +Since Extended Discovery can be disabled by the customer, a key value of 0 may not ever be +returned by a publisher. When Extended Discovery is disabled and the publisher is not in commis­ +sioning mode, then the publisher will not respond to Commissionable Node Discovery. + +**4.3.1.8. TXT key for device type (** DT **)** + +The optional key DT MAY be used to provide the publisher’s Primary Device Type. If present, it +SHALL be encoded as a variable-length decimal number in ASCII text, omitting any leading zeroes. + +For example, the DT=10 key/value pair would indicate that the primary device type is 10 (0x000A), +which is the device type identifier for a Door Lock. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 95 +``` + +**4.3.1.9. TXT key for device name (** DN **)** + +The optional key DN MAY provide a device advertisement name. If present, it SHALL be encoded as a +valid UTF-8 string with a maximum length of 32 bytes (matching the maximum length of the Node­ +Label string in the Basic Information Cluster). + +When provided, the source of this value SHALL be editable by the user with use clearly designated +as being for on-network advertising and MAY be the value stored in the NodeLabel attribute of the +Basic Information Cluster) of the Node. + +To protect customer privacy on public networks, if a Commissionee supports this key/value pair, +then the Commissionee SHALL provide a way for the customer to disable its inclusion. + +A Commissionee SHOULD NOT include this field unless doing so for specific use cases which call for +it. + +For example, the DN=Living Room key/value pair indicates that the advertisement name specified by +the user is 'Living Room'. + +**4.3.1.10. TXT key for rotating device identifier (** RI **)** + +The optional key RI MAY provide a Rotating Device Identifier. + +If present, the value associated with the RI key SHALL contain the octets of the Rotating Device +Identifier octet string encoded as the concatenation of each octet’s value as a 2-digit uppercase +hexadecimal number. + +The resulting ASCII string SHALL NOT be longer than 100 characters, which implies a Rotating +Device Identifier of at most 50 octets. + +**4.3.1.11. TXT key for pairing hint (** PH **)** + +The optional key PH MAY provide a _pairing hint_. + +If present, it SHALL be encoded as a variable-length decimal number in ASCII text, omitting any +leading zeroes. + +The pairing hint represents a base-10 numeric value for a bitmap of methods supported by the +Commissionee in its current state for putting it in Commissioning Mode. + +For example, the PH=5 key/value pair represents a hint value with bits 0 and 2 are set. + +This value MAY change during the lifecycle of the device. + +For example, a device may have a value with bit 0 (Power Cycle) set and bit 2 (Administrator app) +unset when in a factory reset state, and then have a value with bit 0 unset and bit 2 set after it has +been Commissioned. + +The bitmap of methods is defined in Table 5, “Pairing Hint Values”. + +If the Commissionee has enabled Extended Discovery, then it SHALL include the key/value pair for +PH in the DNS‑SD TXT record when not in Commissioning Mode (CM=0). + +``` +Page 96 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +This key/value pair MAY be returned when in Commissioning Mode (CM=1). + +If the Commissioner does not recognize this value, for example, if the value indicates bit indices +defined in a newer version of this specification than the version which the Commissioner imple­ +ments, then the Commissioner MAY utilize the bits that it does understand and MAY utilize addi­ +tional data sets available for assisting the user. For example, when a Vendor ID and Product ID are +available to the Commissioner, the Section 11.23, “Distributed Compliance Ledger” may also pro­ +vide a URL for the Device User Guide which can contain additional information to help in Commis­ +sioning this Commissionee. + +Some of the pairing hints MAY require additional information to be encoded for proper expression +of their meaning. This is accomplished with the PI TXT key, described in a following section. Depen­ +dency on usage of the PI key is expressed by the PI Dependency column in the table below. + +The following fields in the bitmap are defined for values of the PH key: + +_Table 5. Pairing Hint Values_ + +``` +Bit index Name PI Dependency Description +0 Power Cycle False The Device will auto­ +matically enter Com­ +missioning Mode upon +power cycle (unplug/re- +plug, remove/re-insert +batteries). This bit +SHALL be set to 1 for +devices using Standard +Commissioning Flow, +and set to 0 otherwise. +1 Device Manufacturer +URL +``` +``` +False This SHALL be set to 1 +for devices requiring +Custom Commissioning +Flow before they can +be available for Com­ +missioning by any Com­ +missioner. For such a +flow, the user SHOULD +be sent to the URL spec­ +ified in the Commission­ +ingCustomFlowUrl of the +DeviceModel schema +entry indexed by the +Vendor ID and Product +ID ( e.g. , as found in the +announcement) in the +Distributed Compliance +Ledger. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 97 +``` + +``` +Bit index Name PI Dependency Description +2 Administrator False The Device has been +commissioned. Any +Administrator that +commissioned the +device provides a user +interface that may be +used to put the device +into Commissioning +Mode. +3 Settings menu on the +Node +``` +``` +False The settings menu on +the Device provides +instructions to put it +into Commissioning +Mode. +4 Custom Instruction True The PI key/value pair +describes a custom way +to put the Device into +Commissioning Mode. +This Custom Instruc­ +tion option is NOT rec­ +ommended for use by a +Device that does not +have knowledge of the +user’s language prefer­ +ence. +5 Device Manual False The Device Manual pro­ +vides special instruc­ +tions to put the Device +into Commissioning +Mode (see Section +11.23.6.15, “UserManu­ +alUrl”). This is a catch- +all option to capture +user interactions that +are not codified by +other options in this ta­ +ble. +6 Press Reset Button False The Device will enter +Commissioning Mode +when reset button is +pressed. +``` +Page 98 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Bit index Name PI Dependency Description** + +7 Press Reset Button with +application of power + +``` +False The Device will enter +Commissioning Mode +when reset button is +pressed when applying +power to it. +``` +8 Press Reset Button for +N seconds + +``` +True The Device will enter +Commissioning Mode +when reset button is +pressed for N seconds. +The exact value of N +SHALL be made avail­ +able via PI key. +``` +9 Press Reset Button until +light blinks + +``` +True The Device will enter +Commissioning Mode +when reset button is +pressed until associated +light blinks. Informa­ +tion on color of light +MAY be made available +via PI key (see Note 1). +``` +10 Press Reset Button for +N seconds with applica­ +tion of power + +``` +True The Device will enter +Commissioning Mode +when reset button is +pressed for N seconds +when applying power +to it. The exact value of +N SHALL be made +available via PI key. +``` +11 Press Reset Button until +light blinks with appli­ +cation of power + +``` +True The Device will enter +Commissioning Mode +when reset button is +pressed until associated +light blinks when +applying power to the +Device. Information on +color of light MAY be +made available via PI +key (see Note 1). +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 99 +``` + +``` +Bit index Name PI Dependency Description +12 Press Reset Button N +times +``` +``` +True The Device will enter +Commissioning Mode +when reset button is +pressed N times with +maximum 1 second +between each press. +The exact value of N +SHALL be made avail­ +able via PI key. +13 Press Setup Button False The Device will enter +Commissioning Mode +when setup button is +pressed. +14 Press Setup Button with +application of power +``` +``` +False The Device will enter +Commissioning Mode +when setup button is +pressed when applying +power to it. +15 Press Setup Button for +N seconds +``` +``` +True The Device will enter +Commissioning Mode +when setup button is +pressed for N seconds. +The exact value of N +SHALL be made avail­ +able via PI key. +16 Press Setup Button +until light blinks +``` +``` +True The Device will enter +Commissioning Mode +when setup button is +pressed until associated +light blinks. Informa­ +tion on color of light +MAY be made available +via PI key (see Note 1). +17 Press Setup Button for +N seconds with applica­ +tion of power +``` +``` +True The Device will enter +Commissioning Mode +when setup button is +pressed for N seconds +when applying power +to it. The exact value of +N SHALL be made +available via PI key. +``` +Page 100 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +Bit index Name PI Dependency Description +18 Press Setup Button +until light blinks with +application of power +``` +``` +True The Device will enter +Commissioning Mode +when setup button is +pressed until associated +light blinks when +applying power to the +Device. Information on +color of light MAY be +made available via PI +key (see Note 1). +19 Press Setup Button N +times +``` +``` +True The Device will enter +Commissioning Mode +when setup button is +pressed N times with +maximum 1 second +between each press. +The exact value of N +SHALL be made avail­ +able via PI key. +``` +Note 1: When the PH key indicates a light to blink (one or more of bits 9, 11, 16 or 18 is set), informa­ +tion on color of light MAY be made available via PI key. When using such color indication in PI key, +only basic primary and secondary colors that could unambiguously be decoded by a commissioner +and understood by an end-user, but without worry of localization, SHOULD be used, e.g. white, red, +green, blue, orange, yellow, purple. + +Note 2: Any undefined values are reserved for future use. + +Note 3: A Commissionee can indicate multiple ways of being put into Commissioning Mode by set­ +ting multiple bits in the bitmap at the same time. However, only one method can be specified which +has a dependency on the PI key (PI Dependency=True) at a time. + +For example: + +- A PH value of 33 (bits 0 and 5 are set) indicates that the user can cause the Commissionee to + enter Commissioning Mode by either power cycling it or by following special instructions pro­ + vided in the Device Manual. +- A PH value of 9 (bits 0 and 3 are set) indicates that the user can cause the Commissionee to enter + Commissioning Mode by either power cycling it or going to the settings menu and following + instructions there. +- A PH value of 1 (bit 0 is set) indicates that the user can cause the Commissionee to enter Commis­ + sioning Mode only by power cycling it. +- A PH value of 16 (bit 4 is set) indicates that the user can cause the Commissionee to enter Com­ + missioning Mode following a custom procedure described by the value of the PI key. +- A PH value of 256 (bits 8 is set) indicates that the user can cause the Commissionee to enter Com­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 101 +``` + +``` +missioning Mode by pressing the reset button for a duration of time in seconds specified via by +the value of the PI key. +``` +When the PH key is provided, at least one bit in the above bitmap SHALL be set. That is, a PH value of +0 is undefined and illegal. + +When the PH key is provided, the Commissioner SHOULD take its value into account when provid­ +ing guidance to the user regarding steps required to put the Commissionee into Commissioning +Mode. + +**4.3.1.12. TXT key for pairing instructions (** PI **)** + +The optional key PI MAY give the _pairing instruction_. + +If present, the value SHALL be encoded as a valid UTF-8 string with a maximum length of 128 bytes. + +The meaning of this key is dependent upon the PH key value, see Table 5, “Pairing Hint Values”. + +For example, given PH=256, bit 8 is set which indicates "Press Reset Button for N seconds". Therefore, +a value of PI=10 would indicate that N is 10 in that context. + +When bit 4 of the value expressed by the PH key is set, indicating presence of a custom string, the +Commissionee SHALL be responsible for localization (translation to user’s preferred language) as +required using the Device’s currently configured locale. The Custom Instruction option is NOT rec­ +ommended for use by a Commissionee that does not have knowledge of the user’s language prefer­ +ence. + +It is RECOMMENDED to keep the length of PI field small and adhere to the guidance given in section +6.2 of [RFC 6763]. + +This key/value pair SHALL only be returned in the DNS‑SD TXT record if the PH bitmap value has a +bit set which has PI Dependency = True, see Table 5, “Pairing Hint Values”. The PH key SHALL NOT +not have more than one bit set which has a dependency on the PI key (PI Dependency = True) to +avoid ambiguity in PI key usage. + +**4.3.1.13. TXT key for Joint Fabric** + +The optional key JF indicates the capabilities of an Ecosystem Administrator that is participating in +the Joint Fabric. + +The JF key SHALL be present in the DNS‑SD TXT record if and only if the Node is capable of being a +Joint Fabric Administrator. + +The JF key SHALL be encoded as a variable-length decimal number in ASCII text, omitting any lead­ +ing zeroes. + +The JF key represents a base-10 numeric value for a bitmap of capabilities for a Joint Fabric Admin­ +istrator device. + +The bitmap of the Joint Fabric key values is defined in Table 6, “Joint Fabric Key Values”. + +``` +Page 102 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Table 6. Joint Fabric Key Values_ + +``` +Bit index Capability Description +0 Available This device is capable of acting +as a Joint Fabric Administrator. +(See Note 1) +1 Administrator This device is acting as a Joint +Fabric Administrator +2 Anchor This device is acting as a Joint +Fabric Anchor Administrator. +(See Note 2) +3 Datastore This device is acting as a Joint +Fabric Datastore. (See Note 3) +``` +Note 1: bit 0 (Available) SHALL be unset for any of bits 1, 2 or 3 to be set. bit 0 (Available) SHALL be +set as the default value prior to the Administrator Node being commissioned onto the Joint Fabric. +Once an Administrator device is commissioned on the Joint Fabric, bit 0 (Available) SHALL be unset. + +Note 2: bit 1 (Administrator) SHALL be set for bit 2 (Anchor) to be set. A device SHALL be a Joint +Fabric Administrator to be a Joint Fabric Root CA Anchor. A single device for the Ecosystem (Ven­ +dor) which is the Joint Fabric Anchor SHALL have bit 3 (Datastore) set. This means 1 or more +devices may have bit 1 (Administrator) and bit 2 (Anchor) set, but not have bit 3 (Datastore) set, but +at most 1 device SHALL have bit 3 (Datastore) set. + +Note 3: bit 1 (Administrator), bit 2 (Anchor), and bit 3 (Datastore) SHALL all be set for the single +device which is the Joint Fabric Datastore. + +For example: + +- A JF=1 key/value pair indicates that the Administrator Node is capable of being a Joint Fabric + Administrator but has not been commissioned onto the Joint Fabric. +- A JF=14 key/value pair (bits 1, 2, and 3 are set) indicates that the device is a Joint Fabric Adminis­ + trator, the Joint Fabric Anchor, and a Joint Fabric Datastore device. +- A JF=1 key/value pair (bit 1 is set) indicates that the device is a Joint Fabric Administrator but + NOT the Joint Fabric Anchor or a Joint Fabric Datastore device. + +This value MAY change during the lifecycle of the device. + +For example, a device might have a value with bit 0 (Available) set and bit 1 (Administrator) unset +and bit 2 (Anchor) unset and bit 3 (Datastore) unset prior to being commissioned onto the Joint Fab­ +ric, and then have a value with bit 0 (Available) unset and bit 1 (Administrator) set after it has been +commissioned onto the Joint Fabric. + +The VP key SHALL be present in the DNS‑SD TXT record if the JF key is present and SHALL provide +the Vendor ID of the device. + +For example: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 103 +``` + +VP=123 gives the Vendor ID associated with the Joint Fabric Administrator device. + +**4.3.1.14. Examples** + +The examples below simulate a Node in commissioning mode advertising its availability for com­ +missioning. + +Examples are shown using both the dns-sd command-line test tool and the avahi command-line test +tool. The dns-sd command-line test tool is included in all versions of macOS. It is installed as a DOS +command with Bonjour for Windows, and is available on Linux by installing the mDNSResponder +package [https://github.com/balaji-reddy/mDNSResponder]. The Avahi package of command line tools is +available from the Avahi project [https://github.com/lathiat/avahi] for most Linux distributions. + +These examples are given for illustrative purposes only. Real Matter Commissionees and Commis­ +sioners would not use a command-line test tool for advertising and discovery. Real Matter Commis­ +sionees and Commissioners would use the appropriate DNS‑SD APIs in their respective chosen pro­ +gramming languages. + +Consider a device on Wi-Fi using the 48-bit device MAC address of B75AFB458ECD as its host name and +a value of DD200C20D25AE5F7 as its commissionable service instance name. DNS-SD records for it can +be set up as follows: + +``` +dns-sd -R DD200C20D25AE5F7 _matterc._udp,_S3,_L840,_CM. 11111 D=840 CM=2 +``` +or + +``` +avahi-publish-service --subtype=_S3._sub._matterc._udp +--subtype=_L840._sub._matterc._udp DD200C20D25AE5F7 --subtype=_CM._sub._matterc._udp +_matterc._udp 11111 D=840 CM=2 +``` +- Short discriminator is filterable through _S3 subtype and algorithmically through D=840 TXT key. +- Long discriminator is filterable through _L840 subtype and directly through D=840 TXT key. +- The Commissionee is currently in Commissioning Mode after an Administrator having opened a + commissioning window (see Section 4.3.1.7, “TXT key for commissioning mode (CM)”), as shown + by CM=2 TXT key and availability by browsing the _CM subtype. + ◦ Had the Commissionee been discoverable for initial commissioning rather than subsequent + additional commissioning, a CM=1 TXT key would have been published instead. + +Avahi only sends a single AAAA record. To force the link-local address to be used, use avahi-pub­ +lish-address. For example: + +``` +avahi-publish-address B75AFB458ECD.local fe80::f515:576f:9783:3f30 +``` +The DNS‑SD service registration commands shown above results in the creation of the following +Multicast DNS records: + +``` +Page 104 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +_matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +_S3._sub._matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +_L840._sub._matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +_CM._sub._matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +DD200C20D25AE5F7._matterc._udp.local. SRV 0 0 11111 B75AFB458ECD.local. +DD200C20D25AE5F7._matterc._udp.local. TXT "D=840" "CM=2" +B75AFB458ECD.local. AAAA fe80::f515:576f:9783:3f30 +``` +Consider a device on Wi-Fi using the 48-bit device MAC address of B75AFB458ECD as its host name. +DNS-SD records for it can be set up as follows, when it is in Commissionable Node Discovery. + +``` +dns-sd -R DD200C20D25AE5F7 _matterc._udp,_S3,_L840,_V123,_CM,_T81. 11111 D=840 +VP=123+456 CM=2 DT=266 DN="Kitchen Plug" PH=256 PI=5 +``` +or + +``` +avahi-publish-service --subtype=_S3._sub._matterc._udp +--subtype=_L840._sub._matterc._udp --subtype=_V123._sub._matterc._udp +--subtype=_CM._sub._matterc._udp --subtype=_T81._sub._matterc._udp DD200C20D25AE5F7 +_matterc._udp 11111 D=840 VP=123+456 CM=2 DT=81 DN="Kitchen Plug" PH=256 PI=5 +``` +- Short discriminator is 3 , long discriminator is 840. +- Vendor ID is 123 , Product ID is 456. +- Commissioning Mode is 2 , indicating the Commissionee is currently in Commissioning Mode + due to the Open Commissioning Window command. +- Device type is 266 which is a smart plug (On/Off Plugin Unit, Device Type Identifier 0x010A). +- Device name is Kitchen Plug. +- Pairing hint is 256 which indicates that the Commissionee’s reset button must be held down for + 5 seconds to enter Commissioning Mode where the value 5 is obtained by reading the value of + the PI key. +- Pairing instruction is 5. + +Avahi only sends a single AAAA record. To force the link-local address to be used, use avahi-pub­ +lish-address. For example: + +``` +avahi-publish-address B75AFB458ECD.local fe80::f515:576f:9783:3f30 +``` +The DNS‑SD service registration commands shown above results in the creation of the following +Multicast DNS records: + +``` +_matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 105 +``` + +``` +_S3._sub._matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +_L840._sub._matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +_V123._sub._matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +_CM._sub._matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +_T81._sub._matterc._udp.local. PTR DD200C20D25AE5F7._matterc._udp.local. +DD200C20D25AE5F7._matterc._udp.local. TXT "D=840" "VP=123+456" "CM=1" "DT=81" +"DN=Kitchen Plug" "PH=256" "PI=5" +DD200C20D25AE5F7._matterc._udp.local. SRV 0 0 11111 B75AFB458ECD.local. +B75AFB458ECD.local. AAAA fe80::f515:576f:9783:3f30 +``` +The port number 11111 is given here purely as an example. One of the benefits of using DNS‑SD is +that services are not constrained to use a single predetermined well-known port. The port, along +with the IPv6 address, is discovered by Commissioners at run time. + +A Commissioner can discover all available Commissionees awaiting commissioning: + +``` +dns-sd -B _matterc._udp +``` +or + +``` +avahi-browse _matterc._udp -r +``` +A Commissioner can discover Commissionees awaiting commissioning with short discriminator 3: + +``` +dns-sd -B _matterc._udp,_S3 +``` +or + +``` +avahi-browse _S3._sub._matterc._udp -r +``` +A Commissioner can discover Commissionees awaiting commissioning with long discriminator 840: + +``` +dns-sd -B _matterc._udp,_L840 +``` +or + +``` +avahi-browse _L840._sub._matterc._udp -r +``` +A Commissioner can discover Commissionees awaiting commissioning with Vendor ID 123: + +``` +dns-sd -B _matterc._udp,_V123 +``` +``` +Page 106 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +or + +``` +avahi-browse _V123._sub._matterc._udp -r +``` +A Commissioner can discover all Commissionees in commissioning mode: + +``` +dns-sd -B _matterc._udp,_CM +``` +or + +``` +avahi-browse _CM._sub._matterc._udp -r +``` +A commissioner can discover Matter Nodes with Device Type 81: + +``` +dns-sd -B _matterc._udp,_T81 +``` +or + +``` +avahi-browse _T81._sub._matterc._udp -r +``` +A Commissioner can discover Nodes that are currently in Commissioning Mode as a result of a com­ +missioning window opened by a current Administrator as a result of invoking either the Open Com­ +missioning Window command or the Open Basic Commissioning Window command, using the +presence of the _CM subtype as a browsing filter: + +``` +dns-sd -B _matterc._udp,_CM +``` +or + +``` +avahi-browse _CM._sub._matterc._udp -r +``` +**4.3.1.15. Efficiency Considerations** + +Discovering and using an offered service on the network typically involves several steps: + +1. Enumeration of instances available on the network ("browsing") +2. Lookup of a selected instance’s port number, host name, and other additional information, com­ + municated in DNS‑SD using SRV and TXT records ("resolving") +3. Lookup of the IPv6 address(es) associated with the desired target host. +4. Use of IPv6 Neighbor Discovery and/or IPv6 routing to translate from destination IPv6 address + to the next-hop link-layer address for that communication. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 107 +``` + +5. Establishing a cryptographically secure communication channel between the two endpoints, + and then engaging in useful communication. + +Although the first three steps are exposed in some APIs as separate steps, at a protocol level they +usually require only a single network round-trip. When a PTR query is issued to discover service +instances, the usual DNS Additional Record mechanism, where packet space permits, automatically +places the related SRV, TXT, and address records into the Additional Record section of the reply. +These additional records are stored by the client, to enable subsequent steps in the sequence to be +performed without additional redundant network operations to learn the same information a sec­ +ond time. + +DNS‑SD over Multicast DNS works by receiving replies from other Nodes attached to the same local +link, Nodes that may have been previously completely unknown to the requester. Because of this, +Multicast DNS, like IPv6 Neighbor Discovery, does not have any easy way to distinguish genuine +replies from malicious or fraudulent replies. Consequently, application-layer end-to-end security is +essential. Should a malicious device on the same local link give deliberately malicious or fraudulent +replies, the misbehavior will be detected when the device is unable to establish a cryptographically +secure application-layer communication channel. This reduces the threat to a Denial-of-Service +attack, which can be remedied by physically removing the offending device. + +**4.3.2. Operational Discovery** + +For Matter Nodes that have already been commissioned onto a Matter Fabric, run-time dynamic +discovery of operational Matter Nodes is used, rather than assuming a fixed unchanging IPv6 +address and port for the lifetime of the product. This is done to allow for greater flexibility, so that +the underlying IPv6 network can grow and evolve over time as needed without breaking Matter +functionality. This is the same reason that other networked consumer electronics products do not +assume a single fixed unchanging IP address for the lifetime of the product [RFC 5505]. + +**4.3.2.1. Operational Instance Name** + +For Matter operational discovery the DNS‑SD instance name is constructed from a 64-bit com­ +pressed Fabric identifier, and a 64-bit Node identifier, as assigned by the commissioner, each +expressed as a fixed-length sixteen-character hexadecimal string, encoded as ASCII (UTF-8) text +using capital letters, separated by a hyphen. For example, a Matter Node with Matter compressed +fabric identifier 2906-C908-D115-D362 and Matter Node identifier 8FC7-7724-01CD-0696 has Matter +operational discovery DNS‑SD instance name 2906C908D115D362-8FC7772401CD0696. + +The Matter operational discovery DNS‑SD instance name needs to be unique within the namespace +of the local network (the .local link-local namespace of the Ethernet and Wi‑Fi links [RFC 6762], or +the unicast domain selected by the Thread Border Router for devices on the Thread mesh). This +uniqueness is assumed to be guaranteed by appropriate selection of a unique Matter fabric identi­ +fier and unique Node identifier within that Matter fabric. + +**4.3.2.2. Compressed Fabric Identifier** + +In order to reduce the very large size of a full Fabric Reference which would need to be used as the +scoping construct in the instance name, a 64-bit compressed version of the full Fabric Reference +SHALL be used. The computation of the Compressed Fabric Identifier SHALL be as follows: + +``` +Page 108 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +byte CompressedFabricInfo[16] = /* "CompressedFabric" */ +{0x43, 0x6f, 0x6d, 0x70, 0x72, 0x65, 0x73, 0x73, +0x65, 0x64, 0x46, 0x61, 0x62, 0x72, 0x69, 0x63} +``` +``` +CompressedFabricIdentifier = +Crypto_KDF( +inputKey := TargetOperationalRootPublicKey, +salt:= TargetOperationalFabricID, +info := CompressedFabricInfo, +len := 64) +``` +Where: + +- TargetOperationalRootPublicKey is the raw uncompressed elliptical curve public key of the root + certificate for the advertised Node’s Operational Certificate chain, without any format marker + prefix byte (i.e. after removing the first byte of the ec-pub-key field in the Operational Certifi­ + cate’s root). +- TargetOperationalFabricID is the octet string for the Fabric ID as it appears in the advertised + Node’s Operational Certificate's subject field, under the 1.3.6.1.4.1.37244.1.5 RDN, that is, a 64-bit + unsigned integer scalar in big-endian byte order. + +For example, if the root public key for a given Operational Certificate chain containing the identity +to be advertised were the following: + +``` +pub: +04:4a:9f:42:b1:ca:48:40:d3:72:92:bb:c7:f6:a7:e1: +1e:22:20:0c:97:6f:c9:00:db:c9:8a:7a:38:3a:64:1c: +b8:25:4a:2e:56:d4:e2:95:a8:47:94:3b:4e:38:97:c4: +a7:73:e9:30:27:7b:4d:9f:be:de:8a:05:26:86:bf:ac: +fa +``` +Then the value for TargetOperationalRootPublicKey to use in the derivation of the compressed Fab­ +ric Identifier would be without the leading 04 : + +``` +4a:9f:42:b1:ca:48:40:d3:72:92:bb:c7:f6:a7:e1:1e: +22:20:0c:97:6f:c9:00:db:c9:8a:7a:38:3a:64:1c:b8: +25:4a:2e:56:d4:e2:95:a8:47:94:3b:4e:38:97:c4:a7: +73:e9:30:27:7b:4d:9f:be:de:8a:05:26:86:bf:ac:fa +``` +If using the above TargetOperationalRootPublicKey and a TargetOperationalFabricID value of +0x2906_C908_D115_D362 (octet string 29:06:c9:08:d1:15:d3:62 in big-endian), then the Compressed­ +FabricIdentifier to use in advertising would be 87E1B004E235A130 (octet string +87:e1:b0:04:e2:35:a1:30). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 109 +``` + +**4.3.2.3. Operational Service Type** + +The DNS‑SD service type [RFC 6335] for Matter Operational Discovery is _matter._tcp. Note that the +string _tcp is boilerplate text inherited from the original DNS SRV specification [RFC 2782], and +doesn’t necessarily mean that the advertised application-layer protocol runs only over TCP. It is +merely mnemonic text which is there to help human readers, and in no way affects software adver­ +tising or using the application-layer protocol identified by that unique IANA-recorded service type +string. + +The following subtype is defined: + +1. Compressed Fabric Identifier _I, where is the Compressed Fabric Identifier + encoded as exactly 16 uppercase hexadecimal characters, for example _I87E1B004E235A130 for + the Compressed Fabric Identifier example of the previous section. This subtype enables filtering + of devices per Fabric if service enumeration (browsing) is attempted, to reduce the set of results + to Nodes of interest with operational membership in a given Fabric.. + +**4.3.2.4. Operational Service Domain and Host Name** + +For link-local Multicast DNS the service domain SHALL be local. For Unicast DNS such as used on +Thread the service domain SHALL be as configured automatically by the Thread Border Router. + +For DNS‑SD a target host name is required, in addition to the instance name. The target host name +SHALL be constructed using one of the available link-layer addresses, such as a 48-bit device MAC +address (for Ethernet and Wi‑Fi) or a 64-bit MAC Extended Address (for Thread) expressed as a +fixed-length twelve-character (or sixteen-character) hexadecimal string, encoded as ASCII (UTF-8) +text using capital letters, e.g., B75AFB458ECD.. In the event that a device performs MAC +address randomization for privacy, then the target host name SHALL use the privacy-preserving +randomized version and the hostname SHALL be updated in the record every time the underlying +link-layer address rotates. Note that it is legal to reuse the same hostname on more than one inter­ +face, even if the underlying link-layer address does not match the hostname on that interface, since +the goal of using a link-layer address is to ensure local uniqueness of the generated hostname. If +future link layers are supported by Matter that do not use 48-bit MAC addresses or 64-bit MAC +Extended Address identifiers, then a similar rule will be defined for those technologies. + +**4.3.2.5. Operational Discovery Service Records** + +After discovery, IPv6 addresses are returned in the AAAA records and key/value pairs are returned +in the DNS-SD TXT record. The TXT record MAY be omitted if no keys are defined. + +Nodes SHALL publish AAAA records for all available IPv6 addresses upon which they are willing to +accept operational messages. + +Only the common TXT record key/value pairs defined in Section 4.3.4, “Common TXT Key/Value +Pairs” are defined for use in Operational Discovery. + +Nodes SHALL silently ignore TXT record keys that they do not recognize. + +``` +Page 110 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.3.2.6. Performance Recommendations** + +To improve overall performance of operational discovery, especially in large installations, the fol­ +lowing recommendations SHOULD be taken in account: + +1. Nodes SHOULD cache the last-known IPv6 address and port for each peer Node with which they + interact from their SRV record resolved using DNS-SD, to save the cost of a run-time network + lookup operation when not needed. When the IPv6 address and port for a peer Node is not + known, or an attempt to communicate with a peer Node at its last-known IPv6 address and port + does not appear to be succeeding within the expected network round-trip time (i.e., the retrans­ + mission timeout value for the first message packet) a Node SHOULD then perform a run-time + discovery in parallel, to determine whether the desired Node has acquired a new IPv6 address + and/or port [RFC 8305]. +2. Nodes SHOULD respond to nonspecific service enumeration queries for the generic Matter + Operational Discovery service type (_matter._tcp), but these queries SHOULD NOT be used in + routine operation, and instead it is RECOMMENDED that they only be used for diagnostics pur­ + poses or to determine new membership within a fabric. When used, it is RECOMMENDED that + service enumeration employ the _I Fabric-specific subtype to only enumerate the desired + Nodes on the Fabric of interest in the local network. Moreover, Known Answer Suppression + [RFC 6762] SHOULD be employed in such cases to further minimize the number of unnecessary + responses to such a query. +3. When resolving the operational service record of another Node, a Node SHOULD use an SRV + query for the desired operational service instance rather than doing general enumeration of all + nodes (e.g. PTR query) followed by filtering for the desired service instance. This recommenda­ + tion reduces the amount of multicast traffic generated on-link when Multicast DNS is used, and + reduces latency to successful service resolution. +4. Since proxied DNS-SD service discovery MAY be in use within a given network, and service + record caching is expected of DNS-SD clients, Nodes SHOULD NOT use DNS-SD as an operational + liveness determination method. This is because there may be stale records not yet expired after + a Node becomes unreachable which may still be available. + +**4.3.2.7. Operational Discovery DNS-SD Examples** + +The example below simulates a commissioned Matter Node advertising its availability for control +via the Matter protocol. + +Examples are shown using both the dns-sd command-line test tool and the avahi command-line test +tool. The dns-sd command-line test tool is included in all versions of macOS. It is installed as a DOS +command with Bonjour for Windows, and is available on Linux by installing the mDNSResponder +package [https://github.com/balaji-reddy/mDNSResponder]. The avahi command line-test tool is available +from the Avahi project [https://github.com/lathiat/avahi] for most Linux distributions. + +This example is given for illustrative purposes only. Real Matter Nodes and controllers would not +use a command-line test tool for advertising and discovery. Real Matter Nodes and controllers +would use the appropriate DNS‑SD APIs in their respective chosen programming languages. + +Consider a device on Wi-Fi using the 48-bit device MAC address of B75AFB458ECD as its host name. +DNS-SD records for can be set up as follows: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 111 +``` + +``` +dns-sd -R 87E1B004E235A130-8FC7772401CD0696 _matter._tcp. 22222 +``` +or + +``` +avahi-publish-service 87E1B004E235A130-8FC7772401CD0696 _matter._tcp 22222 +``` +The port number 22222 is given here purely as an example. One of the benefits of using DNS‑SD is +that services are not constrained to use a single predetermined well-known port. This means that +multiple instances of the Matter Node control service can run on the same device at the same time, +listening on different ports [RFC 6760]. The port, along with the IPv6 address, is discovered by the +Matter controller at run time. + +Avahi only sends a single AAAA record. To force the link-local address to be used, use avahi-pub­ +lish-address. For example: + +``` +avahi-publish-address B75AFB458ECD.local fe80::f515:576f:9783:3f30 +``` +A Matter controller can discover the current IPv6 address and port for a known commissioned Mat­ +ter Node: + +``` +dns-sd -L 87E1B004E235A130-8FC7772401CD0696 _matter._tcp +87E1B004E235A130-8FC7772401CD0696._matter._tcp.local. can be reached at +B75AFB458ECD.local.:22222 +``` +``` +dns-sd -Gv6 B75AFB458ECD.local +fe80::f515:576f:9783:3f30 +``` +or + +``` +avahi-browse _matter._tcp -r +``` +``` +hostname = [B75AFB458ECD.local] +address = [fe80::f515:576f:9783:3f30] +port = [22222] +``` +**4.3.3. Commissioner Discovery** + +A Commissionee MAY initiate the commissioning process by discovering Commissioners on the net­ +work (see Initiating Commissioning from an Existing Device). This MAY be done using _Commis­ +sioner Discovery_ described in this section. + +With Commissioner Discovery, a Commissionee, upon user interaction, MAY discover Commission­ +ers on the network and obtain a list of information for each which may include Vendor ID, Product + +``` +Page 112 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +ID and friendly name. A Commissionee with a user interface, such as a Television, Thermostat or +Video Player device, MAY display the list of discovered commissioners to the user for selection. +Once selected, the Commissionee MAY use the User Directed Commissioning protocol with the Com­ +missioner to indicate that the user has selected it for commissioning of the Commissionee. The +Commissioner Discovery service records thus enable a form of "door bell" protocol to allow a Com­ +missionee to request Commissioning. + +The Commissioner Discovery feature is optional for both the Commissionee and the Commissioner. +Any mandatory requirements described in this section SHALL apply only if the Node or the Com­ +missioner supports this feature. To protect customer privacy on public networks, a Matter Commis­ +sioner SHALL provide a way for the customer to set a timeout on Commissioner Discovery, or other­ +wise disable Commissioner Discovery. + +For Commissioner Discovery, the DNS-SD instance name is generated the same way it is done for +Commissionable Node Discovery and has the same requirements (uniqueness on local network, +and collision detection and recovery) as those in Commissionable Node Discovery, but the require­ +ments for when a new instance name is selected from Commissionable Node Discovery do not +apply to Commissioner Discovery. The instance name for Commissioner Discovery MAY be selected +whenever the Commissioner deems necessary. + +The DNS-SD service type [RFC 6335] is _matterd._udp. + +The port advertised by a _matterd._udp service record SHALL be different than any port associated +with other advertised _matterc._udp, _matter._tcp or _matterd._udp services, in order to ensure that +the session-less messaging employed by the User Directed Commissioning protocol does not cause +invalid message handling from fully operational Matter nodes at the same address. In other words, +each _matterd._udp service instance needs to be independent from other services to ensure unam­ +biguous processing of the incoming User Directed Commissioning messages. + +The following subtype is defined: + +- \_T where is the device type identifier (see Data Model Device Types), encoded as a + variable-length decimal number in ASCII (UTF-8) text, without leading zeroes. This optional + Device Type subtype enables filtering of results to find only Commissioners that match a device + type, for example, to discover Commissioners of type Video Player (35 is decimal representation + for Video Player device type identifier 0x0023). For such a Video Player filter, subtype _T35 + would be used. + +For link-local Multicast DNS the service domain SHALL be local. For Unicast DNS such as used on +Thread the service domain SHALL be as configured automatically by the Thread Border Router. + +The target host name is generated the same way it is done for Commissionable Node Discovery (see +Host Name Construction). + +After discovery, IPv6 addresses are returned in the AAAA records and key/value pairs are returned +in the DNS‑SD TXT record. The TXT record MAY be omitted if no keys are defined. + +Nodes SHALL publish AAAA records for all their available IPv6 addresses. + +In addition to the common TXT record key/value pairs defined in Section 4.3.4, “Common TXT + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 113 +``` + +Key/Value Pairs”, the following key/value pairs are defined specifically for Commissioner discovery: + +- The optional key VP gives vendor and product information. This key is optional for a vendor to + provide, and optional for a commissioner to use. This value takes the same format described for + the VP key in Commissionable Node Discovery (see Section 4.3.1.6, “TXT key for Vendor ID and + Product ID (VP)”). This key/value pair MAY be returned in the DNS‑SD TXT record. +- The optional key DT gives the device type identifier for the Commissioner (see Data Model + Device Types). This value takes the same format described for the DT key in Commissionable + Node Discovery (see Commissioning Device Type). This key/value pair MAY be returned in the + DNS‑SD TXT record. +- The optional key DN gives the device name. This value takes the same format described for the DN + key in Commissionable Node Discovery (see Commissioning Device Name). This key/value pair + MAY be returned in the DNS‑SD TXT record. To protect customer privacy on public networks, a + Matter Commissioner SHALL provide a way for the customer to disable inclusion of this key. +- The optional key CP indicates whether the Commissioner supports the Commissioner Passcode + feature. The absence of key CP SHALL imply a value of 0 (CP=0), and indicates that the publisher + does not support the Commissioner Passcode feature. The key/value pair CP=1 SHALL indicate + that the publisher supports the Commissioner Passcode feature. + +Commissionees SHALL silently ignore TXT record keys that they do not recognize. This is to facili­ +tate future evolution of the Matter Commissioner Discovery protocol specification without breaking +backwards compatibility with existing Commissionees that do not implement the new functionality. + +**4.3.3.1. Examples** + +The examples below simulate a Matter Commissioner advertising that it is present on the network. + +Examples are shown using both the dns-sd command-line test tool and the avahi command-line test +tool. The dns-sd command-line test tool is included in all versions of macOS. It is installed as a DOS +command with Bonjour for Windows, and is available on Linux by installing the mDNSResponder +package [https://github.com/balaji-reddy/mDNSResponder]. The avahi command line-test tool is available +from the Avahi project [https://github.com/lathiat/avahi] for most Linux distributions. + +These examples are given for illustrative purposes only. + +Consider a device on Wi-Fi using the 48-bit device MAC address of B75AFB458ECD as its host name. +DNS-SD records for can be set up as follows: + +``` +dns-sd -R DD200C20D25AE5F7 _matterd._udp,_V123,_T35. 33333 VP=123+456 DT=35 +DN="Living Room TV" +``` +or + +``` +avahi-publish-service --subtype=_V123._sub._matterd._udp DD200C20D25AE5F7 +_matterd._udp 33333 VP=123+456 DT=35 DN="Living Room TV" +``` +``` +Page 114 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +This produces DNS-SD messages with the following characteristics: + +- Vendor ID is 123 , Product ID is 456. +- Device type is 35 which is a Casting Video Player (Device Type Identifier 0x0023). +- Device name is Living Room TV. + +Avahi only sends a single AAAA record. To force the link-local address to be used, use avahi-pub­ +lish-address. For example: + +``` +avahi-publish-address B75AFB458ECD.local fe80::f515:576f:9783:3f30 +``` +The DNS‑SD service registration command shown above results in the creation of the following +Multicast DNS records: + +``` +_matterd._udp.local. PTR DD200C20D25AE5F7._matterd._udp.local. +_V123._sub._matterd._udp.local. PTR DD200C20D25AE5F7._matterd._udp.local. +_T35._sub._matterd._udp.local. PTR DD200C20D25AE5F7._matterd._udp.local. +DD200C20D25AE5F7._matterd._udp.local. TXT "VP=123+456" "DT=35" "DN=Living Room TV" +DD200C20D25AE5F7._matterd._udp.local. SRV 0 0 33333 B75AFB458ECD.local. +B75AFB458ECD.local. AAAA fe80::f515:576f:9783:3f30 +``` +The port number 33333 is given here purely as an example. + +A Commissionee can discover all Commissioners: + +``` +dns-sd -B _matterd._udp +``` +or + +``` +avahi-browse _matterd._udp -r +``` +A Commissionee can discover Commissioners with device type 35: + +``` +dns-sd -B _matterd._udp,_T35 +``` +or + +``` +avahi-browse _T35._sub._matterd._udp -r +``` +A Commissionee can discover Commissioners with Vendor ID 123: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 115 +``` + +``` +dns-sd -B _matterd._udp,_V123 +``` +or + +``` +avahi-browse _V123._sub._matterd._udp -r +``` +**4.3.4. Common TXT Key/Value Pairs** + +The TXT records provided during Commissionable, Operational and Commissioner discovery MAY +contain the following optional key/value pairs which are common to every discovery method: + +- The optional key SII indicates the SESSION_IDLE_INTERVAL of the Node. This key defines the + MRP retry interval for a Node that is Idle. This key MAY optionally be provided by a Node to + override the default setting. If the key is not included or invalid, the Node querying the service + record SHALL use the default MRP parameter value. The SII value is an unsigned integer with + units of milliseconds and SHALL be encoded as a variable-length decimal number in ASCII + encoding, omitting any leading zeros. The SII value SHALL NOT exceed 3600000 (1 hour in mil­ + liseconds). + ◦ Example: SII=5300 to override the initial retry interval value to 5.3 seconds. +- The optional key SAI indicates the SESSION_ACTIVE_INTERVAL of the Node. This key defines the + MRP retry interval for a Node that is Active. This key MAY optionally be provided by a Node to + override the default setting. If the key is not included or invalid, the Node querying the service + record SHALL use the default MRP parameter value. The SAI value is an unsigned integer with + units of milliseconds and SHALL be encoded as a variable-length decimal number in ASCII + encoding, omitting any leading zeros. The SAI value SHALL NOT exceed 3600000 (1 hour in mil­ + liseconds). + ◦ Example: SAI=1250 to override the active retry interval value to 1.25 seconds. +- The optional key SAT indicates the SESSION_ACTIVE_THRESHOLD of the Node. This key defines + the duration of time the Node stays Active after the last network activity. This key MAY option­ + ally be provided by a Node to override the default setting. If the key is not included or invalid, + the Node querying the service record SHALL use the default MRP parameter value. The SAT + value is an unsigned integer with units of milliseconds and SHALL be encoded as a variable- + length decimal number in ASCII encoding, omitting any leading zeros. The SAT value SHALL + NOT exceed 65535 (65.535 seconds). + ◦ Example: SAT=1250 to override the active retry interval value to 1.25 seconds. + +This key defines the duration of time the Node stays Active after the last network activity. + +- The optional key T indicates various additional transport protocol modes, apart from MRP over + UDP, that are supported by a Node. If the key is not included or invalid, the Node querying the + service record SHALL assume the default value of T=0 indicating that only MRP is supported as a + transport protocol. The T key, if included, SHALL be encoded as a decimal number in ASCII text, + omitting any leading zeroes. + ◦ It represents a base-10 numeric value for a bitmap of various additional transport protocol + +``` +Page 116 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +modes supported by the advertising Node. +◦ For example, the T=6 key/value pair represents a value with bits 1 and 2 set, and bit 0 +cleared. +◦ Bit index 0 is deprecated and SHALL always be set to 0 by the advertising node and ignored +by nodes processing this key. +◦ The fields in the bitmap for values of the T key are currently defined below in Table 7, “Sup­ +ported Transport Mode Values” below. +Thus, a Node advertising with key T=6 represents both a TCP client and a TCP server, but a +Node advertising with T=2 can only be a TCP client. +``` +``` +NOTE TCP client flag and TCP server flags are provisional. These flags SHALL NOT be set. +``` +_Table 7. Supported Transport Mode Values_ + +``` +Bit index Name Description +0 Reserved This bit index is deprecated and +SHALL be set to 0. Clients +SHALL silently ignore this bit. +1 TCP Client The advertising Node imple­ +ments the TCP Client mode and +MAY connect to a peer Node +that is a TCP Server. +2 TCP Server The advertising Node imple­ +ments the TCP Server mode and +SHALL listen for incoming TCP +connections. +``` +Because the information carried in DNS-SD records with Matter is not trustworthy (since the source +is not authenticated), the value of the T key SHOULD be regarded only as a hint. The only reliable +way to determine which transports are supported by a Node is to connect to it using CASE over MRP +and get the list of supported transports from the session parameters. + +- The optional key ICD indicates whether the Node is operating as a Long Idle Time ICD or as a + Short Idle Time ICD. The key SHALL NOT be provided by a Node that does not support the ICD + Long Idle Time operating mode. If the key is invalid or not included, the Node querying the ser­ + vice record SHALL assume the default value of ICD=0 indicating that the ICD is not in the Long + Idle Time operating mode. If the ICD key is included, it SHALL have one of the two valid values: + ◦ 0 to indicate "Long Idle Time ICD is not operating as a Long Idle Time ICD", + ◦ 1 to indicate "Long Idle Time ICD is operating as a Long Idle Time ICD". + ▪ Example: ICD=1 to announce that the ICD is in the Long Idle Time operating mode. + +### NOTE + +``` +Since the information carried by DNS-SD records are not authenticated in Matter’s +usage of this protocol, security-critical decisions SHOULD NOT be made solely on +the basis of them. Rather, this information SHOULD be regarded as a hint that needs +verification. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 117 +``` + +**4.4. Message Frame Format** + +This section describes the encoding of the Matter message format. The Matter message format pro­ +vides flexible support for various communication paradigms, including unicast secure sessions, +multicast group messaging, and session establishment itself. The process of encrypting Matter mes­ +sages is the same in all modes of communication, and assumes symmetric keys are shared between +communicating parties. Unencrypted messages are used only for protocols which bootstrap secure +messaging, such as session establishments. + +Matter messages are used by Matter applications, as well as the Matter protocol stack itself, to con­ +vey application-specific data and/or commands. The Protocol portion of a Matter message contains +a Protocol ID and Protocol Opcode which identify both the semantic meaning of the message as well +as the structure of any associated application payload data. Matter messages also convey an +Exchange ID, which relates the message to a particular exchange (i.e. conversation) taking place +between two nodes. Finally, certain types of Matter messages can convey information that acknowl­ +edges the reception of an earlier message. This is used as part of the Message Reliability Protocol to +provide guaranteed delivery of messages over unreliable transports. + +All multi-byte integer fields are transmitted in little-endian byte order unless otherwise noted in the +field description. + +Matter messages are structured as follows: + +``` +NOTE [] denotes the field is optional. +``` +_Table 8. Matter Message format definition_ + +``` +Length Field +Message Header +1 byte Message Flags +2 bytes Session ID +1 byte Security Flags +4 bytes Message Counter +0/8 bytes [ Source Node ID ] +0/2/8 bytes [ Destination Node ID ] +variable [ Message Extensions... ] +Message Payload +variable [ Message Payload... ] (encrypted) +Message Footer +variable [ Message Integrity Check ] +``` +The Message Payload of a Matter message SHALL contain a Protocol Message with format as fol­ +lows: + +``` +Page 118 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Table 9. Protocol Message format definition_ + +``` +Length Field +Protocol Header +1 byte Exchange Flags +1 byte Protocol Opcode +2 bytes Exchange ID +2 bytes [ Protocol Vendor ID ] +2 bytes Protocol ID +4 bytes [ Acknowledged Message Counter ] +variable [ Secured Extensions... ] +Application Payload +variable [ Application Payload... ] +``` +**4.4.1. Message Header Field Descriptions** + +**4.4.1.1. Message Flags (8 bits)** + +An unsigned integer bit field containing the following subfields: + +_Table 10. Message Flags field definition_ + +``` +bit^76543210 +Version - S DSIZ +``` +### NOTE + +``` +All unused bits in the Message Flags field are reserved and SHALL be set to zero on +transmission and SHALL be silently ignored on reception. +``` +**Version (4 bits, positions 4-7)** + +An unsigned integer specifying the version of the Matter Message format used to encode the mes­ +sage. Currently only one version is defined: + +- 0 — Matter Message Format version 1.0 +- 1-15 — Reserved for future use + +Messages with version field set to reserved values SHALL be dropped without sending a message- +layer acknowledgement. + +### NOTE + +``` +The Version field conveys information solely about the structure of the Matter mes­ +sage itself, not about the structure of the application payload or the interpretation +of the message’s type. Thus, changes to how an application handles or interprets a +message do not result in the creation of a new message format version number. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 119 +``` + +**S Flag (1 bit, position 2)** + +A single bit field which SHALL be set if and only if the Source Node ID field is present. + +**DSIZ Field (2 bits, position 0-1)** + +This field SHALL indicate the size and meaning of the Destination Node ID field. + +- 0 — Destination Node ID field is not present +- 1 — Destination Node ID field is present as a 64-bit Node ID +- 2 — Destination Node ID field is present as a 16-bit Group ID +- 3 — Reserved for future use + +Messages with DSIZ field set to reserved values SHALL be dropped without sending a message-layer +acknowledgement. + +**4.4.1.2. Session ID (16 bits)** + +An unsigned integer value identifying the session associated with this message. The session identi­ +fies the particular key used to encrypt a message out of the set of available keys (either session or +group), and the particular encryption/message integrity algorithm to use for the message. The Ses­ +sion ID field is always present. For details on derivation of this field, see respective sections on uni­ +cast and group session ID derivation. + +**4.4.1.3. Security Flags (8 bits)** + +An unsigned integer bit field containing the following subfields: + +_Table 11. Security Flags field definition_ + +``` +bit^76543210 +P C MX Reserved Session Type +``` +### NOTE + +``` +All unused bits in the Security Flags field are reserved and SHALL be set to zero on +transmission and SHALL be silently ignored on reception. +``` +**P Flag (1 bit, position 7)** + +The Privacy (P) flag is a single bit field which, when set, SHALL identify that the message is encoded +with privacy enhancements as specified in Section 4.9.3, “Privacy Processing of Outgoing Mes­ +sages”. + +**C Flag (1 bit, position 6)** + +The Control message (C) flag is a single bit field which, when set, SHALL identify that the message is +a control message, such as for the Message Counter Synchronization Protocol, and uses the control +message counter for the nonce field as specified in Section 4.8.1.1, “Nonce”. + +``` +Page 120 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**MX Flag (1 bit, position 5)** + +The Message Extensions (MX) flag is a single bit field which, when set, SHALL indicate that the Mes­ +sage Extensions portion of the message is present and has non-zero length. Version 1.0 Nodes +SHALL set this flag to zero. + +**Session Type (2 bit, position 0-1)** + +An unsigned integer specifying the type of session associated with the message. The following val­ +ues are defined: + +- 0 — Unicast Session +- 1 — Group Session +- 2-3 — Reserved for future use + +Messages with Session Type set to reserved values are not valid and SHALL be dropped without +sending a message-layer acknowledgement. + +The Session Type defines how the Session ID is to be interpreted. + +The _Unsecured Session_ SHALL be indicated when both Session Type and Session ID are set to 0. The +_Unsecured Session_ SHALL have no encryption, privacy, or message integrity checking. + +A _Secure Unicast Session_ SHALL be indicated when Session Type is Unicast Session and Session ID is +NOT 0. + +**4.4.1.4. Message Counter (32 bits)** + +An unsigned integer value uniquely identifying the message from the perspective of the sending +node. The message counter is generated based on the Session Type and increases monotonically for +each unique message generated. When messages are retransmitted, using the reliable messaging +capabilities, the counter remains the same, as logical retransmission is of a given message as identi­ +fied by its message counter. Similarly, acknowledgements refer to values of the message counter +being acknowledged. + +### NOTE + +``` +The Message Counter field is scoped to a given Encryption Key. Also, the Message +Counter values are independent for control messages and data messages, as indi­ +cated by the C Flag. So it is possible to have the same Message Counter for two mes­ +sages encrypted with different keys, as well as two messages encrypted with the +same key but different values of the C Flag. +``` +**4.4.1.5. Source Node ID (64 bits)** + +An optional sequence of 8 bytes containing the unique identifier of the source node. The Source +Node ID field SHALL only be present in a message when the S Flag in the Message Flags field is set +to 1. + +**4.4.1.6. Destination Node ID** + +The optional Destination Node ID field contains the unique Node Identifier of the destination Node + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 121 +``` + +or group to which the message is being sent. The size and encoding of the Destination Node ID field +depends on the value of the DSIZ field. + +**4.4.1.7. Message Extensions (variable)** + +The Message Extensions field is a variable length block of data for providing backwards compatible +extensibility. The format of the Message Extensions block is shown in Table 12, “Message Extensions +block format definition”. The Message Extensions block SHALL be present only if the MX Flag is set +to 1 in the Security Flags field. + +_Table 12. Message Extensions block format definition_ + +``` +Length Field +2 bytes Message Extensions Payload Length, in bytes +variable [ Message Extensions Payload ] +``` +If the MX Flag is set to 1, the Message Extensions Payload Length field SHALL be present and SHALL +contain the length of the Message Extensions Payload. The Message Extensions Payload Length field +SHALL NOT be privacy obfuscated. + +Version 1.0 Nodes SHALL ignore the contents of the Message Extensions payload, by skipping it, to +access the Message Payload. + +**4.4.2. Message Footer Field Descriptions** + +**4.4.2.1. Message Integrity Check (variable length)** + +A sequence of bytes containing the message integrity check value (a.k.a. tag or MIC) for the mes­ +sage. The length and byte order of the field depend on the integrity check algorithm in use as speci­ +fied in Section 3.6, “Data Confidentiality and Integrity”. + +The Message Integrity Check field SHALL be present for all messages except those of Unsecured Ses­ +sion Type. + +The MIC is calculated as described in Section 4.8.2, “Security Processing of Outgoing Messages”. + +**4.4.3. Protocol Header Field Descriptions** + +**4.4.3.1. Exchange Flags (8 bits)** + +An unsigned integer bit field containing the following subfields: + +_Table 13. Exchange Flags field definition_ + +``` +bit^76543210 +``` +- - - V SX R A I + +### NOTE + +``` +All unused bits in the Exchange Flags field are reserved and SHALL be set to zero on +transmission and SHALL be silently ignored on reception. +``` +``` +Page 122 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**I Flag (1 bit, position 0)** + +The Initiator (I) flag is a single bit field which, when set, SHALL indicate that the message was sent +by the initiator of the exchange. + +**A Flag (1 bit, position 1)** + +The Acknowledgement (A) flag is a single bit field which, when set, SHALL indicate that the mes­ +sage serves as an acknowledgement of a previous message received by the current message sender. + +**R Flag (1 bit, position 2)** + +The Reliability (R) flag is a single bit field which, when set, SHALL indicate that the message sender +wishes to receive an acknowledgement for the message. + +**SX Flag (1 bit, position 3)** + +The Secured Extensions (SX) flag is a single bit field which, when set, SHALL indicate that the +Secured Extensions portion of the message is present and has non-zero length. Version 1.0 Nodes +SHALL set this flag to zero. + +**V Flag (1 bit, position 4)** + +The Vendor (V) protocol flag is a single bit field which, when set, SHALL indicate whether the Proto­ +col Vendor ID is present. + +**4.4.3.2. Protocol Opcode (8 bits)** + +An unsigned integer value identifying the type of the message. The Protocol Opcode is interpreted +relative to the Matter protocol specified in the Protocol ID field. + +Opcodes are defined by the corresponding Protocol specification, for example Secure Channel Pro­ +tocol. + +**4.4.3.3. Exchange ID (16 bits)** + +An unsigned integer value identifying the exchange to which the message belongs. An Exchange ID +is allocated by the initiator of the exchange, and is unique within the initiator exchange number +space as specified in Section 4.10.2, “Exchange ID”. + +**4.4.3.4. Protocol ID (16 bits)** + +An unsigned integer value identifying the protocol in which the Protocol Opcode of the message is +defined. + +When the Protocol Vendor ID is the Matter Standard Vendor ID, the Protocol ID SHALL have one of +the values specified by Table 14, “Protocol IDs for the Matter Standard Vendor ID”. + +_Table 14. Protocol IDs for the Matter Standard Vendor ID_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 123 +``` + +``` +Range Type Message Specification +0x0000 PROTOCOL_ID_SECURE_CHAN­ +NEL +``` +``` +Section 4.11.1, “Secure Channel Protocol Messages” +``` +``` +0x0001 PROTOCOL_ID_INTERACTION_­ +MODEL +``` +``` +Section 10.2.1, “IM Protocol Messages” +``` +``` +0x0002 PROTOCOL_ID_BDX Section 11.22.3.1, “BDX Protocol Messages” +0x0003 PROTOCOL_ID_USER_DIRECTED_­ +COMMISSIONING +``` +``` +Section 5.3.2, “UDC Protocol Messages” +``` +``` +0x0004 PROTOCOL_ID_FOR_TESTING Reserved for bespoke protocols run in an isolated test +environment. +0x0005 - +0xFFFF +``` +``` +reserved reserved +``` +**4.4.3.5. Protocol Vendor ID (16 bits)** + +An optional, unsigned integer value that contains the Vendor ID namespacing for the Protocol ID +field. This field SHALL only be present when the V Flag is set; otherwise the default is 0, corre­ +sponding to the Matter Standard Vendor ID. + +**4.4.3.6. Acknowledged Message Counter (32 bits)** + +An optional, unsigned integer value containing the message counter of a previous message that is +being acknowledged by the current message. The Acknowledged Message Counter field is SHALL +only be present when the A Flag in the Exchange Flags field is 1. + +**4.4.3.7. Secured Extensions (variable)** + +The Secured Extensions field is a variable length block of data for providing backwards compatible +extensibility. The format of the Secured Extensions block is shown in Table 15, “Secured Extensions +block format definition”. The Secured Extensions block SHALL be present only if the SX Flag is set +to 1 in the Exchange Flags field. + +Version 1.0 Nodes SHALL ignore the contents of the Secured Extensions payload. + +The Secured Extensions block SHALL be encrypted and authenticated based on the Security Flags +settings. + +_Table 15. Secured Extensions block format definition_ + +``` +Length Field +2 bytes Secured Extensions Payload Length, in bytes. +variable [ Secured Extensions Payload ] +``` +**4.4.3.8. Application Payload (variable length)** + +A sequence of zero or more bytes containing the application data conveyed by the message. + +``` +Page 124 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.4.4. Message Size Requirements** + +Support for IPv6 fragmentation is not mandatory in Matter, and the expected supported MTU is +1280 bytes, the minimum required by IPv6. Therefore, all messages, including transport headers, +SHALL fit within that minimal IPv6 MTU. This message size limit SHALL apply to the UDP transport +and Wi-Fi Public Action Frame transport. A message received over UDP or Wi-Fi Public Action +Frame transport that exceeds this message size limit SHALL NOT be processed. Messages sent over +TCP or BTP transports MAY exceed the message size limit if both nodes are capable of supporting +larger message sizes. + +**4.5. Message Framing Over Stream-Oriented** + +**Transports** + +When Matter messages are transferred over stream-oriented transport protocols, such as TCP or +BTP, they need to be framed appropriately to enable the receiver to read each message from the +stream. To allow that, each Matter Message SHALL be prepended with a Message Length field. This +field SHALL only be present when the message is being transmitted over a stream-oriented chan­ +nel. When transmitted over a datagram channel, the message length SHALL be conveyed by the +underlying channel. For example, when transmitted over UDP, the message length SHALL be equal +to the payload length of the UDP datagram. + +**4.5.1. Message Length (16/32 bits)** + +An optional unsigned integer value, in little-endian byte order, specifying the overall length of the +message in bytes, not including the size of this field itself. The size of this field, when present, +SHALL depend on the transport protocol being used to transfer the message. For example, for TCP, +it SHALL be set to 4 bytes to allow for large payloads, whereas for BTP it SHALL be set to 2 bytes. + +``` +Protocol Size Location Description in Stream +TCP 4 bytes Field present before the Message Header of each Matter message. +BTP 2 bytes Field present before the segment payload in the beginning BTP +Packet PDU for each Matter message/BTP SDU. +MRP N/A Field not present. +``` +**4.6. Message Counters** + +All messages contain a 32-bit message counter assigned by the sender of the message. Message +counters are assigned sequentially, by monotonically increasing the counter value maintained by +the sender of the message. Message counters serve several purposes: + +- **Duplicate Message Detection** – Receiving systems use message counters to detect messages + that have been retransmitted by the sender, e.g. in response to packet loss in the network. +- **Message Acknowledgement** – In the Message Reliability Protocol (MRP), message counters pro­ + vide a way for receivers to identify messages for the purpose of acknowledging their receipt. +- **Encryption Nonces** – When encrypted messages are sent, message counters provide an encryp­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 125 +``` + +``` +tion nonce that ensures each message is encrypted in a unique manner. +``` +- **Replay Prevention** – Related to encryption, message counters also provide a means for detect­ + ing and preventing the replay of encrypted messages. + +**4.6.1. Message Counter Types** + +All Nodes implement three global 32-bit counters to generate message counters for certain types of +messages: + +- _Global Unencrypted Message Counter_ +- _Global Group Encrypted Data Message Counter_ +- _Global Group Encrypted Control Message Counter_ + +Additionally, Nodes implement a separate 32-bit counter for each session as part of secure session +state: + +- _Secure Session Message Counter_ + +Additionally, Nodes implement a separate 32-bit counter for each Check-In Protocol use case: + +- _Check-In Counter_ + +Technical details for how each counter type works are described in the following sections. Table 16, +“Message Counter Type Overview” is provided to summarize higher-level differences between Mes­ +sage Counter Types: + +_Table 16. Message Counter Type Overview_ + +``` +Message Counter Type Session Type Lifetime Rollover Pol­ +icy +``` +``` +Nonvolatile +``` +``` +Global Unencrypted Unsecured Unlimited Allowed Optional +Global Encrypted Data Group Operational Group Key Allowed Mandatory +Global Encrypted Con­ +trol +``` +``` +Group Operational Group Key Allowed Mandatory +``` +``` +Secure Session Unicast Session Key Expires Optional +Check-In Counter Unsecured Unlimited Allowed Mandatory +``` +**4.6.1.1. Message Counter Initialization** + +All message counters SHALL be initialized with a random value using the Crypto_DRBG(len = 28) + +1 primitive. Message counters are initialized to a random number to increase the difficulty of traffic +analysis attacks by making it harder to determine how long a particular session has been open. The +random initializer ranges from 1 to 2^28 in order to maximize initial entropy while still reserving the +vast majority of the range to actual counter values (roughly 2^32 - 2^28 ). + +``` +Page 126 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.6.1.2. Global Unencrypted Message Counter** + +All Nodes SHALL implement an unencrypted message counter, which is used to generate counters +for unencrypted messages. + +Typically, Nodes store the _Global Unencrypted Message Counter_ in RAM. This makes the counter sub­ +ject to loss whenever the system reboots or otherwise loses its state. This is permissible because +retaining the _Global Unencrypted Message Counter_ is not essential to the confidentiality or integrity +of the message. In the event that the _Global Unencrypted Message Counter_ for a Node is lost, Nodes +SHALL randomize the initial value of this counter on startup per Section 4.6.1.1, “Message Counter +Initialization”. + +**4.6.1.3. Global Group Encrypted Message Counters** + +The _Global Group Encrypted Message Counters_ are used to generate the counter for messages +encrypted using group keys. There are two such counters: + +- The _Global Group Encrypted Data Message Counter_ is used to encode regular data messages + encrypted with a group key. +- The _Global Group Encrypted Control Message Counter_ is used to encode control messages + encrypted with a group key. + +Some Nodes might not be required to implement communication using group keys, in which case +they MAY omit the _Global Group Encrypted Message Counters_. In contrast to the _Global Unencrypted +Message Counter_ , Nodes are required to persist the _Global Group Encrypted Message Counters_ in +durable storage. In particular, Nodes are required to ensure that the value of the _Global Group +Encrypted Message Counters_ never rolls back and that it is monotonic within the bounds of its range +for its use for a given group key. A Node SHALL randomize the initial value of this counter on fac­ +tory reset per Section 4.6.1.1, “Message Counter Initialization”. + +While _Global Group Encrypted Message Counters_ are shared by many group keys to generate +nonces, rollover is not an issue as long as the Epoch Key that generates each operational group key +rotates frequently enough. + +### NOTE + +``` +If a nonce is duplicated for a given key, the security consequences are isolated only +to the specific key with which the duplicate nonce occurred — a key that has not +been updated prior to rollover and has been presumably abandoned or aged out. +``` +**4.6.2. Secure Session Message Counters** + +A _Secure Session Message Counter_ is a per-session, 32-bit, ephemeral counter that is used by the +encoding of any encrypted messages using an associated session key. Each peer in a Secure Unicast +Session SHALL maintain its own message counters, with independent counters being used for each +unique session used. _Session Message Counters_ SHALL exist for as long as the associated security +session is in effect. A Node SHALL randomize the initial value of this counter on session establish­ +ment per Section 4.6.1.1, “Message Counter Initialization”. + +The _Secure Session Message Counter_ history window SHALL be maintained for the lifetime of the +session, and SHALL be deleted at the same time as the session keys, when the session ends. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 127 +``` + +Sessions SHALL be discarded and re-established before any _Secure Session Message Counter_ over­ +flow or repetition occurs. + +**4.6.3. Check-In Counter** + +The Check-In Counter is an unsigned 32-bit counter used during the encryption process of the +Check-In Protocol. The only purpose of the Check-In Counter is during the encryption process of the +Check-In Protocol. + +Each Check-In Protocol use-case implemented by a device SHALL be associated with a specific +Check-In counter to be used for each node identity (pair of fabric and node identifier). This MAY be +a single counter across all node identities, or MAY be one counter per node identity, or anything in +between, as long as each node identity uses a single specific instance of the counter. The device +SHALL randomize the initial value of the counter on factory reset per Section 4.6.1.1, “Message +Counter Initialization”. + +The Check-In Counter SHALL be monotonically increased each time a Check-In message is sent. This +monotonicity guarantee SHALL be preserved across idle and active states. The Check-In Counter +can roll over to zero when it exceeds the maximum value of the counter (32-bits). Nodes are +required to persist the _Check-In Counter_ in durable storage. + +When a node reboots, the _Check-In Counter_ MAY increase by a larger step than 1. Nodes do not need +to write every new value of the Check-In Counter to permanent storage each time it is increased +(e.g. to prevent flash wear due to many write operations). One example strategy to achieve reduc­ +tion of non-volatile storage updates is described below: + +1. Read the counter value at start-up. +2. Before processing the first message after startup, write counter + N to storage, where N is a + carefully chosen number (e.g. 1000). This number N should be chosen carefully in order not to + exhaust the lifetime 32-bit counter space. +3. Process messages normally until the counter has a value one less than the counter in storage. + When this happens, store counter + N to storage. + +### NOTE + +``` +The Check-In Counter has an unlimited lifetime until the device is factory reset. To +ensure that a nonce is not reused since it is derived from the Check-In Counter and +the ICD key, the key needs to be refreshed before using all valid counter values for +the key. +``` +**4.6.4. Message Counters as Encryption Nonces** + +In the context of encrypted messages, message counters serve as nonces for the encryption algo­ +rithm, ensuring that every message is encrypted in a unique manner. The uniqueness of an +encrypted message’s counter is vital to the confidentiality of the message, as the encryption algo­ +rithm makes it trivial for an eavesdropper to decrypt messages if the attacker can find two different +messages with the same message counter that were encrypted using the same key. Specifically, an +attacker can XOR the two different messages that share the same key and nonce to obtain a "block +key" which can be used to decrypt any message that uses that key and nonce. + +``` +Page 128 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Nodes SHOULD rotate their encryption keys on a regular basis, to ensure that old encryption keys +are retired before a _Global Group Encrypted Message Counter_ has a chance to wrap to a value previ­ +ously used with the encryption key. In practice, the frequency of message transmission is such that +encryption keys generally rotate at a rate that is much faster than the rate at which a _Global Group +Encrypted Message Counter_ wraps. In the event that a _Global Group Encrypted Message Counter_ +wraps before the associated keys are rotated, all keys associated with that _Global Group Encrypted +Message Counter_ are considered exhausted and are no longer valid to use. In such cases, a new uni­ +cast session SHALL be established to the Matter Node to rotate such retired keys before secure com­ +munication can resume. Given the importance of confidentiality and message integrity, every effort +SHOULD be made to ensure that keys are rotated on a regular basis. + +**4.6.5. Replay Prevention and Duplicate Message Detection** + +Beyond their role as encryption nonces, message counters also serve as a means to detect repeated +reception of the same message. Message duplication may occur for a number of reasons: out-of- +order arrival, network latency, malicious attack, or network error. For example, a duplicate can be +caused when a sender retransmits a message after failing to receive an acknowledgement, or +because a malicious third party attempted to replay an old message to gain some advantage. To +detect duplicate messages, Nodes maintain a history window of the message counters they have +received from a particular sender (see Message Reception State). Whenever a message is received, +its message counter is checked against the history window of message counters from that sender to +determine whether it is a duplicate. The Message Layer SHALL discard duplicate messages before +they reach the application layer. + +**4.6.5.1. Message Reception State** + +The state maintained by a Node about the messages it has received from a particular peer is +referred to as _message reception state_. Nodes use this state information to determine whether a +newly arrived message is a duplicate of a previous message. Message reception state is maintained +on a per-peer or per-session basis, depending on the type of message encryption being used. + +At a conceptual level, message reception state consists of a set of integers corresponding to the +counters of all the messages that have been received from a particular peer. To limit the amount of +memory required to store this state, Nodes employ a lossy compression scheme that takes advan­ +tage of the fact that message counters are generated sequentially by the sender. The scheme allows +for a limited amount of out-of-order message arrivals due to network effects without inducing false +detection of duplicates. + +In the compressed form, message reception state is structured as a pair of values: a integer repre­ +senting the largest valid, or maximum message counter received from the peer (max_message_­ +counter), and a bitmap of size _MSG_COUNTER_WINDOW_SIZE_ indicating which messages immedi­ +ately prior to the max message have been received. The offset into the bitmap equates to the differ­ +ence between the corresponding message counter and the max message counter, i.e. the first bit in +the bitmap indicates whether the message with the counter of max_message_counter - 1 has been +received, the second indicates whether message max_message_counter - 2 has been received, and so +on. A message counter is within the range of the bitmap, also known as the message counter win­ +dow, when the counter value is between [(max_message_counter - MSG_COUNTER_WINDOW_SIZE) to +(max_message_counter - 1) mod 2^32 ]. As messages arrive, the message reception state is queried to +determine if an arriving message is new or duplicate. If a message is new, the state is then updated + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 129 +``` + +to reflect the arrival of the message. When a message arrives with a message counter that is logi­ +cally greater than the current maximum message counter for that peer, the maximum message +counter value for the peer is updated and the bitmap shifted accordingly. + +_Figure 7. Message Reception State Example_ + +**4.6.5.2. Use of Message Reception State for Encrypted Messages** + +The algorithm for querying and updating message reception state varies slightly depending on +whether the system is tracking reception of encrypted messages or unencrypted messages. + +**Message Counters with maximum** + +For encrypted messages of Secure Unicast Session Type, any arriving message with a counter in the +range [(max_message_counter + 1) to (2^32 - 1)] SHALL be considered new, and cause the max_mes­ +sage_counter value to be updated. Message counters within the range of the bitmap SHALL be con­ +sidered duplicate if the corresponding bit offset is set to true. All other message counters SHALL be +considered duplicate. + +**Message Counters with rollover** + +A message counter with rollover is a free running message counter that monotonically increases, +but rolls over to zero when it exceeds the maximum value of the counter (32-bits). Group keys are +secured by a shared, global message counter with rollover as described in Section 4.6.1.3, “Global +Group Encrypted Message Counters”. + +For encrypted messages of Group Session Type, any arriving message with a counter in the range +[(max_message_counter + 1) to (max_message_counter + 2^31 - 1)] (modulo 2^32 ) SHALL be considered + +``` +Page 130 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +new, and cause the max_message_counter value to be updated. Messages with counters from +[(max_message_counter - 2^31 ) to (max_message_counter - MSG_COUNTER_WINDOW_SIZE - 1)] (modulo 2 + +(^32) ) SHALL be considered duplicate. A message counter equal to max_message_counter SHALL be con­ +sidered duplicate. Message counters within the range of the bitmap SHALL be considered duplicate +if the corresponding bit offset is set to true. +This scheme for encrypted messages effectively divides the message counter space in half: those +counters that are forward of the max message counter, which are considered new, and those coun­ +ters that are behind the max message counter, which are considered duplicates unless indicated +otherwise by the values in the bitmap. +**4.6.5.3. Use of Message Reception State for Unencrypted Messages** +For unencrypted messages, the algorithms for tracking messages and detecting duplicates are simi­ +lar to, but more permissive than for encrypted messages using Section 4.6.5.2.2, “Message Counters +with rollover”. This reflects the fact that duplicate detection of unencrypted messages is not done +for security reasons, but rather to catch duplicates caused by network errors (e.g. loss of an ack), +which are generally more bounded in time. The more relaxed algorithm for unencrypted duplicate +detection also relaxes the durability requirement on the sender’s message counter, allowing +senders to store the counter in RAM. +For unencrypted messages, any message counter equal to max_message_counter or within the mes­ +sage counter window, where the corresponding bit is set to true SHALL be considered duplicate. All +other message counters, whether behind the window or ahead of max_message_counter, are consid­ +ered new and SHALL update max_message_counter and shift the window accordingly. Messages with +a counter behind the window are likely caused by a node rebooting and are thus processed as +rolling back the window to the current location. Note that when max_message_counter is close to the +minimum of the range, the window SHALL roll back to cover message counters near the maximum +of the range. +**4.6.5.4. Message Reception State Initialization** +To initialize Message Reception State for a given Peer Node ID, initial max_message_counter, Message +Type (control or data), Encryption Level (encrypted or unencrypted), and Encryption Key (for any +Encryption Level except unencrypted): + +- The Message Reception State fields SHALL be set as follows: + ◦ The Peer Node ID SHALL reference the given Peer Node ID. + ◦ The Message Type SHALL be the given Message Type. + ◦ The Encryption Level SHALL be the given Encryption Level. + ◦ If the Encryption Level is NOT unencrypted, the Encryption Key SHALL reference the given + key. + ◦ The max_message_counter SHALL be set to the given max_message_counter. + ◦ The Message Counter bitmap SHALL be set to all 1 , indicating that only new messages with + counter greater than max_message_counter SHALL be accepted. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 131 +``` + +**4.6.6. Counter Processing of Outgoing Messages** + +1. Obtain the outgoing message counter of the sending Node for the given Security Flags, Session + Id, and Encryption Key: + a.A message of Unsecured Session Type SHALL use the current _Global Unencrypted Message_ + _Counter_. +b. A message of Secure Unicast Session Type SHALL use the current _Secure Session Message +Counter_ for the session associated with the Session ID. +c.A message of Group Session Type SHALL use: +i. The _Global Group Encrypted Data Message Counter_ if the Security Flags C Flag = 0. +ii.The _Global Group Encrypted Control Message Counter_ if the Security Flags C Flag = 1. +2. The outgoing message counter from step 1 SHALL be incremented by 1. +3. Store the incremented outgoing message counter in the _OutgoingMessageCounter_ element asso­ + ciated with the Session Context for the message. + a.If the message counter wraps around from 0xFFFF_FFFF to 0x0000_0000 and the message is + of Secure Unicast Session Type: + i. The Encryption Key SHALL be expired in the Session Context. The session will need to be + renegotiated to resume communication after transmission of this final message. + +**4.6.7. Counter Processing of Incoming Messages** + +1. Determine the Message Reception State for the sending peer and get the current max_message_­ + counter. + a.Given a decrypted message of Unicast Session Type: + i. Get the session-specific Message Reception State from the Secure Unicast Session Con­ + text. +b. Given a decrypted message of Group Session Type: +i. Extract the Source Node ID from the Message Header. +A. If there is no Source Node ID for the message, drop the message. +ii.Get the Message Reception State for the Source Node ID of the given message: +A. If the Security Flags C Flag = 0, get the Data Message Reception State for the peer +node. +B. If the Security Flags C Flag = 1, get the Control Message Reception State for the peer +node. +iii.If there is no Message Reception State for the groupcast message, initiate Section 4.18.4, +“Unsynchronized Message Processing”. +c.Given an unencrypted message: +i. Get the Message Reception State associated with the Unsecured Session Context. +ii.If there is no Message Reception State for the unencrypted message, create it with the +information from the given message. + +``` +Page 132 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +2. If the Message Counter is outside the valid message counter window, the message SHALL be + marked as a duplicate. Note that while messages may be outside of the window for reasons + other than being a duplicate, and we always mark them as such. +3. If the message is a duplicate: + a. If the message is marked as encrypted, follow Section 4.6.5.2, “Use of Message Reception + State for Encrypted Messages”. + b. If the message is marked as unencrypted, follow Section 4.6.5.3, “Use of Message Reception + State for Unencrypted Messages”. +c. If the message is encrypted and marked as a duplicate, i.e. Message Counter is outside the +valid message counter window or marked as previously received in the Message Reception +State: +i. Perform Section 4.12.5.2, “Reliable Message Processing of Incoming Messages” on the +duplicate message. + d. Otherwise, update the Message Reception State as detailed in Section 4.6.5.1, “Message + Reception State”, and accept the message for further processing. + +**4.7. Message Processing** + +This sub-clause describes the fundamental procedures for transmission and reception. + +**4.7.1. Message Transmission** + +To prepare a message for transmission with a given Session ID, Destination Node ID (which may be +a group node id or an operational node id) and Security Flags, the following steps SHALL be per­ +formed, in order: + +1. Process the message as described in Section 4.6.6, “Counter Processing of Outgoing Messages”. +2. If the message’s Session Type is a Unicast Session: + a. Set SessionTimestamp to a timestamp from a clock which would allow for the eventual deter­ + mination of the last session use relative to other sessions. + b. Process the message as described in Section 4.8.2, “Security Processing of Outgoing Mes­ + sages”. +c. Process the message as described in Section 4.9.3, “Privacy Processing of Outgoing Mes­ +sages”. + +**4.7.2. Message Reception** + +To process a received message, the following steps SHALL be performed in order: + +1. Perform validity checks on the message; if any fail, processing of the message SHALL stop, and a + 'message invalid' error SHOULD be indicated to the next higher layer: + a. The Version field SHALL be 0. + b. If the message is of Secure Unicast Session Type: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 133 +``` + +``` +i. The DSIZ field SHALL NOT indicate a Group ID is present. +c.If the message is of Group Session Type: +i. The DSIZ field SHALL NOT be 0. +ii.The S Flag field SHALL NOT be 0. +``` +2. If the message is NOT of Unsecured Session Type: + a.Obtain the Privacy and Encryption Keys associated with the given Session ID: + i. If no keys are found, security processing SHALL indicate a failure to the next higher + layer with a status of 'message security failed' and no further security processing SHALL + be done on this message. +b. For each Privacy and Encryption Key, of which there may be more than one in the case of +group messages: +i. If the P Flag is set, follow Section 4.9.4, “Privacy Processing of Incoming Messages” to +deobfuscate the message. +ii.Follow Section 4.8.3, “Security Processing of Incoming Messages” to decrypt and authen­ +ticate the message. +3. Follow Section 4.6.7, “Counter Processing of Incoming Messages” to enforce replay protection + and duplicate detection. +4. If the message transport is UDP, follow Section 4.12.5.2, “Reliable Message Processing of Incom­ + ing Messages” to process message reliability. +5. If the message’s Session Type is a Unicast Session: + a.Set SessionTimestamp and ActiveTimestamp to a timestamp from a clock which would allow for + the eventual determination of the last session use relative to other sessions. +6. The received message is then delivered to Section 4.10.5, “Exchange Message Processing”. + +**4.8. Message Security** + +The detailed steps involved in security processing of outgoing and incoming Matter messages are +described in Section 4.8.2, “Security Processing of Outgoing Messages” and Section 4.8.3, “Security +Processing of Incoming Messages” respectively. Section 4.8.1, “Data confidentiality and integrity +with data origin authentication parameters” defines how the cryptographic parameters are set for +securing Matter messages. + +**4.8.1. Data confidentiality and integrity with data origin authentication +parameters** + +This section specifies the parameters to use the data confidentiality and integrity cryptographic +primitive as defined in Section 3.6, “Data Confidentiality and Integrity”. + +The parameters in this section SHALL apply for all encrypted messages, i.e. all messages except +those of Unsecured Session Type. + +``` +Page 134 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.8.1.1. Nonce** + +The nonce SHALL be formatted as specified in Table 17, “Nonce”. + +_Table 17. Nonce_ + +``` +Octets: 1 4 8 +Security Flags Message Counter Source Node ID +``` +The nonce used for the Authenticated Encryption with Additional Data (AEAD) algorithm (see Sec­ +tion 3.6, “Data Confidentiality and Integrity”) for a given message SHALL be defined as the concate­ +nation of the Security Flags, the Message Counter, and the Source Node ID of that message. The +scalar fields in the nonce, namely the Message Counter and the Source Node ID SHALL be encoded +in little-endian byte order for the purposes of serialization within the nonce, that is, in the same +byte ordering as the segment of the message from which its data originates. + +The Source Node ID field used in the nonce SHALL be set to the Operational Node ID of the node +originating security protection of the message: + +- If the message is of Secure Unicast Session Type: + ◦ For a CASE session, the Nonce Source Node ID SHALL be determined via the Secure Session + Context associated with the Session Identifier. + ◦ For a PASE session, the Nonce Source Node ID SHALL be Unspecified Node ID. +- If the message is of Group Session Type: + ◦ The S Flag of the message SHALL be 1 and the Nonce Source Node ID SHALL be the Source + Node ID of the message. + ◦ If the S Flag of the message is 0 the message SHALL be dropped. + +### NOTE + +``` +Because PASE negotiates strong one-time keys per session and the I2RKey and R2IKey +are distinct for each direction of communication, the use of the Unspecified Node ID +as the Nonce Source Node ID remains semantically secure. +``` +**4.8.2. Security Processing of Outgoing Messages** + +The process for encrypting Matter messages is depicted graphically in Figure 8, “Matter Message +Encryption” with color code conventions described in Figure 9, “Matter Message Encryption Leg­ +end”. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 135 +``` + +_Figure 8. Matter Message Encryption_ + +_Figure 9. Matter Message Encryption Legend_ + +To prepare a secure message for transmission with a given Session ID, Destination Node ID (which +may be a group node id or an operational node id) and Security Flags, the Node SHALL perform the +following steps: + +1. Obtain the Encryption Key associated with the Session ID and Destination Node ID and the Ses­ + sion Type associated with the Destination Node ID: + a.If no key is found for the given Session ID, security processing SHALL fail and no further + security processing SHALL be done on this message. +2. Obtain the outgoing message counter of the sending Node as per Section 4.6.6, “Counter Process­ + +``` +Page 136 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ing of Outgoing Messages”. +``` +3. Set the Security fields as follows: + +``` +a. The Session ID field SHALL be set to the value provided to step 1. +b. The Security Flags field SHALL be set to the value provided to step 1 with the following sub­ +fields updated: +i. The Session Type field SHALL be set to the value obtained from step 1. +``` +4. Set the Message Flags, Destination Node ID, and Source Node ID fields as follows: + +``` +a. If the Session Type is a unicast session: +i. Set S Flag to 0. +ii. Set DSIZ to 0. +iii. Omit both Destination Node ID, and Source Node ID. +b. Else if the Session Type is a group session: +i. Set S Flag to 1. +ii. Set DSIZ to 2. +iii. Set Source Node ID field to the operational node id of the sending node. +iv. Set Destination Node ID field to the 16-bit Group ID derived from the Destination Node +ID. +``` +5. Set the Message Counter field to the outgoing message counter from step 2. +6. Execute the AEAD generate and encrypt operation, as specified in Section 3.6.1, “Generate and + encrypt”, with the following instantiations: + a. The bit string key _K_ SHALL be the Encryption Key obtained from step 1; + b. The nonce _N_ SHALL be the CRYPTO_AEAD_NONCE_LENGTH_BYTES-octet string constructed accord­ + ing to Table 17, “Nonce”; +c. The parameter _P_ SHALL be the Message Payload; + d. The additional data octet string _A_ SHALL be the Message Header contents, using little-endian + byte order for all scalars, exactly as they appear in the message segments from which they + originate: + +``` +Message Flags || Session ID || Security Flags || Message Counter +``` +``` +with the optional fields appended according to the Message Flags: +``` +``` +[Source Node ID] || [Destination Node ID] || [Message Extensions] +``` +``` +e. C = Crypto_AEAD_GenerateEncrypt(K, P, A, N) +``` +7. If the AEAD operation invoked in step 6 results in an error, then security processing SHALL fail + and no further security processing SHALL be done on this message. +8. Let _C_ be the output from step 6. _C_ contains the tag of CRYPTO_AEAD_MIC_LENGTH_BITS bits (Message + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 137 +``` + +``` +Integrity Check (MIC)) as specified by Section 3.6.1, “Generate and encrypt”. The secured outgo­ +ing message SHALL be: +``` +### A || C + +**4.8.3. Security Processing of Incoming Messages** + +All incoming message processing SHALL occur in a serialized manner. If an implementation +chooses to process messages in a parallel manner, it must ensure that the behavior is opaque-box +identical to a serialized processing implementation. + +If the transport layer receives a secured message as indicated by the Session ID, it SHALL perform +the following steps: + +1. Determine the Session Type, Session ID, and Message Counter from the message header of the + received message. +2. Obtain the Encryption Key associated with the Session Context of the given Session ID and Ses­ + sion Type: + a.If no key is found for the given Session ID, security processing SHALL indicate a failure to + the next higher layer with a status of 'message security failed' and no further security pro­ + cessing SHALL be done on this message. +3. Execute the AEAD decryption and verification operation as specified in Section 3.6.2, “Decrypt + and verify” with the following instantiations: + a.The bit string key _K_ SHALL be the Encryption Key obtained from step 2; +b. The nonce _N_ SHALL be the CRYPTO_AEAD_NONCE_LENGTH_BYTES-octet string constructed accord­ +ing to Table 17, “Nonce”; +c.The parameter _C_ SHALL be the encrypted and authenticated Message Payload; +d. The additional data octet string _A_ SHALL be the authenticated Message Header: +e. {success, P} = Crypto_AEAD_DecryptVerify(K, C, A, N) +4. Return the result {success, P} of the AEAD operation: + a.If the success is FALSE, security processing SHALL fail and further processing SHALL NOT be + performed on this message. An appropriate error SHOULD be raised to the upper layer to + indicate the error. +b. Otherwise, set the octet string _PlaintextMessage_ to the string + +### A || P + +5. _PlaintextMessage_ now represents the deciphered, authenticated, received message. + a.NOTE: The message has not yet undergone counter processing nor replay detection. +b. The _PlaintextMessage_ SHALL be marked as successfully security processed and SHALL be +released to the next processing layer. + +``` +Page 138 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.9. Message Privacy** + +Privacy processing of a message describes the obfuscation and deobfuscation of the message +header fields after encryption and before decryption. + +The detailed steps involved in privacy processing of outgoing and incoming Matter messages are +described in Section 4.9.3, “Privacy Processing of Outgoing Messages” and Section 4.9.4, “Privacy +Processing of Incoming Messages” respectively. They rely on the cryptographic primitives in Section +3.7, “Message privacy”. + +**4.9.1. Privacy Key** + +The Privacy Key is a symmetric key specifically used for Privacy Processing that is derived from the +EncryptionKey used for Security Processing of a given message. Given a Session ID reference to a +specific Encryption Key, the Privacy Key is derived as follows: + +``` +PrivacyKey = +Crypto_KDF +( +InputKey = EncryptionKey, +Salt = [], +Info = "PrivacyKey", +Length = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +**4.9.2. Privacy Nonce** + +The Privacy Nonce is a nonce specifically used for Privacy Processing that is derived from the Ses­ +sionId and MIC of the message. The Privacy Nonce SHALL be the CRYPTO_AEAD_NONCE_LENGTH_BYTES +-octet string constructed as the 16-bit Session ID (in big-endian format) concatenated with the lower +11 (i.e. CRYPTO_AEAD_MIC_LENGTH_BYTES-5) bytes of the MIC: + +``` +PrivacyNonce = Session ID || MIC[5..15] +``` +For example if Session ID is 42 (i.e. 0x002A) and the computed MIC is +c5:a0:06:3a:d5:d2:51:81:91:40:0d:d6:8c:5c:16:3b: + +``` +Session ID = 00:2a +MIC = c5:a0:06:3a:d5:d2:51:81:91:40:0d:d6:8c:5c:16:3b +MIC[5..15] = d2:51:81:91:40:0d:d6:8c:5c:16:3b +PrivacyNonce = SessionID || MIC[5..15] = 00:2a || d2:51:81:91:40:0d:d6:8c:5c:16:3b +PrivacyNonce = 00:2a:d2:51:81:91:40:0d:d6:8c:5c:16:3b +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 139 +``` + +**4.9.3. Privacy Processing of Outgoing Messages** + +The process for privacy encoding Matter message headers is depicted graphically in Figure 10, +“Matter Message Privacy”. + +_Figure 10. Matter Message Privacy_ + +To apply privacy obfuscation to an encrypted message prepared for transmission by Section 4.7.1, +“Message Transmission”, apply obfuscation steps as follows: + +1. If P Flag is not set, do nothing. +2. Obtain the Privacy Key for the Encryption Key used to secure the message. +3. Execute the encryption operation as specified in Section 3.7.1, “Privacy encryption” with the fol­ + lowing instantiations: + a.The bit string key _K_ SHALL be the Privacy Key obtained from step 1; +b. The MIC SHALL be the last CRYPTO_AEAD_MIC_LENGTH_BYTES bytes of the C outcome of the mes­ +sage security protection as specified in Section 4.8.2, “Security Processing of Outgoing Mes­ +sages” (MIC = C[(CRYPTO_AEAD_MIC_LENGTH_BYTES-1)..0]) +c.The nonce _N_ SHALL be the PrivacyNonce of the message. +d. The parameter _M_ SHALL be the message header fields where optional fields are only +present in _M_ if they are present in the message: + +``` +M = Message Counter || [Source ID] || [Destination ID] +``` +``` +e. CP = Crypto_Privacy_Encrypt(K, M, N) +``` +4. Let _CP_ be the obfuscated output from step 2. _CP_ SHALL be used in the final private message in + place of the message header fields. + +``` +Page 140 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.9.4. Privacy Processing of Incoming Messages** + +To deobfuscate a private message received by Section 4.7.2, “Message Reception” with a given Pri­ +vacy Key, perform security processing as follows: + +1. If P Flag is not set, do nothing. +2. With the given Privacy Key, execute the decryption as specified in Section 3.7.2, “Privacy decryp­ + tion” with the following instantiations: + a. The bit string key _K_ SHALL be the Privacy Key obtained from step 1; + b. The MIC SHALL be the last CRYPTO_AEAD_MIC_LENGTH_BYTES bytes of the C outcome of the mes­ + sage security protection as specified in Section 4.8.3, “Security Processing of Incoming Mes­ + sages” (MIC = C[(CRYPTO_AEAD_MIC_LENGTH_BYTES-1)..0]) +c. The nonce _N_ SHALL be the PrivacyNonce of the message. + d. The parameter _CP_ SHALL be the message header fields where optional fields are only + present in _CP_ if they are present in the message: + +``` +CP = Message Counter || [Source ID] || [Destination ID] +``` +``` +e. M = Crypto_Privacy_Decrypt(K, CP, N) +``` +3. Let _M_ be the deobfuscated output from step 2. + a. _M_ SHALL be used in the final private message in place of the message header fields. + b. The first successfully validated message, _M_ , by Section 4.8.3, “Security Processing of Incom­ + ing Messages” SHALL terminate iteration through Privacy Keys in step 2. + +**4.10. Message Exchanges** + +An Exchange provides a way to group related messages together, organize communication flows, +and enable higher levels of the communication stack to track semantically relevant groupings of +messages. + +An Exchange SHALL be bound to exactly one underlying session that will transport all associated +Exchange messages for the life of that Exchange. The underlying session SHALL be one of the fol­ +lowing session types: secure unicast (as established by PASE or CASE), unsecured (as is used for the +initial session establishment phase of a PASE/CASE session), secure group, or MCSP. + +When used with reliability, Exchanges assume basic flow control by the upper layer. The Exchange +Layer SHALL NOT accept a message from the upper layer when there is an outbound reliable mes­ +sage pending on the same Exchange. + +**4.10.1. Exchange Role** + +The first Node to send a message in an Exchange is said to be in the Initiator role, and all the other +Nodes that subsequently participate in the Exchange are said to be in a Responder role. An +Exchange is always between one Initiator and one or more peer Responder Nodes. An Exchange + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 141 +``` + +does not survive a reboot of one of the participants. Adjacent layers MAY close an Exchange at any +time. + +**4.10.2. Exchange ID** + +An Exchange of messages is identified by the Exchange ID field described in Section 4.4.3.3, +“Exchange ID (16 bits)”. The Exchange ID is allocated by the Initiator. The first message the Initiator +sends in a new Exchange SHALL contain a fresh value for the Exchange ID field. The Exchange is +then identified by the tuple {Session Context, Exchange ID, Exchange Role} where Session Context is +one of an Unsecured, Secured, Groupcast or MCSP session context. All messages that are part of a +given Exchange, whether they are sent by the Initiator or not, share the same Exchange ID, allow­ +ing the Initiator and Responder Nodes to match responses to requests or otherwise group messages +together that are part of more complex transactions. The first Exchange ID for a given Initiator +Node SHALL be a random integer. All subsequent Exchange IDs created by that Initiator SHALL be +the last Exchange ID it created incremented by one. An Exchange ID is an unsigned integer that +rolls over to zero when its maximum value is exceeded. + +**4.10.3. Exchange Context** + +An Exchange context is the metadata tracked for an Exchange by all exchange participants. An +Exchange context tracks the following data: + +1. Exchange ID: The Exchange ID assigned by the Initiator +2. Exchange Role: Initiator or Responder +3. Session Context: The underlying Unsecured, Secured, Groupcast or MCSP session context + ◦ Together, Session Context, Exchange ID and Role comprise a unique key allowing partici­ + pants to identify any exchange. + +**4.10.3.1. Protocol ID Registration** + +The Interaction Model layer indicates to the Exchange Layer which Protocols it will accept. Any +message for a Protocol ID that is not registered with the Exchange Layer SHALL be dropped. + +**4.10.4. Exchange Message Dispatch** + +When sending a message to the Exchange Layer, the next higher layer SHALL specify whether the +message is part of an existing Exchange, or the first of a new Exchange. For the case of a first mes­ +sage, the Initiator creates a new Exchange. The Node in the Initiator role SHALL always set the I +Flag in the Exchange Flags of every message it sends in that Exchange. + +Each Node in a Responder role for an Exchange SHALL use the Exchange ID received in previous +messages for the Exchange. Each Node in the Responder role SHALL NOT set the I Flag in the +Exchange Flags of every message it sends in that Exchange. Each Node in a Responder role SHALL +NOT set the Destination Node ID field to a value that identifies any Node other than the Node in the +Initiator role for the Exchange. + +Processing SHALL then proceed to Section 4.12.5.1, “Reliable Message Processing of Outgoing Mes­ +sages”. + +``` +Page 142 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.10.5. Exchange Message Processing** + +After completion of Section 4.7.2, “Message Reception”, if the message matches an existing +Exchange, it is dispatched to the appropriate protocol handler in the next higher layer. Messages +for an existing Exchange are dispatched to the handler for that Exchange. Otherwise, the unso­ +licited message that created the Exchange is dispatched to the unsolicited message handler. + +**4.10.5.1. Exchange Message Matching** + +Upon receipt of a message, the Exchange Layer attempts to match the message to an existing +Exchange. A given message is part of an Exchange if it satisfies all the following criteria: + +1. The message was received over the session associated with the Exchange. +2. The Exchange ID of the message matches the Exchange ID of the Exchange, +3. The message has the I Flag set and the Exchange Role of the Exchange is Responder, + OR the message does not have the I Flag set and the Exchange Role of the Exchange is Initiator. + +If the message does not match an existing Exchange, the message is considered an unsolicited mes­ +sage. + +**4.10.5.2. Unsolicited Message Processing** + +An unsolicited message is processed as follows: + +1. If the unsolicited message is not marked as having a duplicate message counter, has a registered + Protocol ID, and the I Flag is set: + a. Create a new exchange from the incoming message. + b. The new exchange will be used by the upper layer for generating responses and subsequent + processing of the message. +2. Otherwise, if the message has the R Flag set: + a. Create an _ephemeral exchange_ from the incoming message and send an immediate stand­ + alone acknowledgement. + b. The message SHALL NOT be forwarded to the upper layer, and excluding the sending of an + immediate standalone acknowledgment, SHALL be ignored. +c. The _ephemeral exchange_ created for such duplicate or unknown messages with R Flag set is +automatically closed in Section 4.12.5.2.2, “Standalone acknowledgement processing”. +3. Otherwise, processing of the message SHALL stop. + +**Creating an Exchange based on an Incoming Message** + +The steps to create a new Exchange based on an incoming message are as follows: + +1. A new Exchange and Exchange Context SHALL be created with the following settings: + a. The Exchange ID SHALL be set to the Exchange ID of the message. + b. The Exchange Role SHALL be set to the inverse of the incoming message I Flag, for example + set the Exchange Role to Responder if the message is from an Initiator. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 143 +``` + +``` +c.The Session Context SHALL be set to the Session on which the message was received. +``` +A node SHOULD limit itself to a maximum of 5 concurrent exchanges over a unicast session. This is +to prevent a node from exhausting the message counter window of the peer node. + +**4.10.5.3. Closing an Exchange** + +An Exchange MAY be closed by the application layer or a fatal connection error from the lower +message layer. The process of closing an Exchange follows: + +1. Any pending acknowledgements associated with the Exchange SHALL be flushed. If there is a + pending acknowledgment in the _acknowledgement table_ for the Exchange and it has Stand­ + aloneAckSent set to false: + a.Immediately send a standalone acknowledgement for the pending acknowledgement. +b. Remove the _acknowledgement table_ entry for the pending acknowledgement. +2. Wait for all pending retransmissions associated with the Exchange to complete. + a.If the retransmission list for the Exchange is empty, remove the Exchange. +b. Otherwise, leave the Exchange open and only close it once the retransmission list is empty. + +These steps are depicted in Figure 11, “Exchange close flow”. + +_Figure 11. Exchange close flow_ + +``` +Page 144 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.11. Secure Channel Protocol** + +This section specifies the formal protocol definition for the Secure Channel Protocol. Secure Chan­ +nel Protocol defines the control plane for secure channel communication and security. + +**4.11.1. Secure Channel Protocol Messages** + +Secure Channel Protocol is composed of a collection of sub-protocols, including: + +- Message Counter Synchronization Protocol (MCSP) +- Message Reliability Protocol (MRP) +- Passcode Based Session Establishment (PASE) +- Certificate Based Session Establishment (CASE) + +The protocol opcodes for messages within the Secure Channel Protocol are grouped based on the +underlying sub-protocol that uses the message type. Table 18, “Secure Channel Protocol Opcodes” +lists the messages defined by Secure Channel Protocol. + +_Table 18. Secure Channel Protocol Opcodes_ + +``` +Protocol +Opcode +``` +``` +Protocol Command +Name +``` +``` +Description +``` +``` +Protocol ID = PROTOCOL_ID_SECURE_CHANNEL +0x00 MsgCounterSyncReq The Message Counter Synchronization Request message +queries the current message counter from a peer to boot­ +strap replay protection. +0x01 MsgCounterSyncRsp The Message Counter Synchronization Response message +provides the current message counter from a peer to boot­ +strap replay protection. +0x10 MRP Standalone Acknowl­ +edgement +``` +``` +This message is dedicated for the purpose of sending a +stand-alone acknowledgement when there is no other data +message available to piggyback an acknowledgement on +top of. +0x20 PBKDFParamRequest The request for PBKDF parameters necessary to complete +the PASE protocol. +0x21 PBKDFParamResponse The PBKDF parameters sent in response to PBKDF­ +ParamRequest during the PASE protocol. +0x22 PASE Pake1 The first PAKE message of the PASE protocol. +0x23 PASE Pake2 The second PAKE message of the PASE protocol. +0x24 PASE Pake3 The third PAKE message of the PASE protocol. +0x30 CASE Sigma1 The first message of the CASE protocol. +0x31 CASE Sigma2 The second message of the CASE protocol. +0x32 CASE Sigma3 The third message of the CASE protocol. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 145 +``` + +``` +Protocol +Opcode +``` +``` +Protocol Command +Name +``` +``` +Description +``` +``` +0x33 CASE Sigma2_Resume The second resumption message of the CASE protocol. +0x40 StatusReport The Status Report message encodes the result of an opera­ +tion in the Secure Channel as well as other protocols. +0x50 ICD Check-In message The Check-in message notifies a client that the ICD is avail­ +able for communication. +``` +**4.11.1.1. Session Establishment - Out of Resources** + +After a successful session establishment using CASE or PASE, a responder may not have enough +resources to save all of the session context information. To free resources, a responder SHALL evict +an existing session using the following procedure: + +1. Use the SessionTimestamp to determine the least-recently used session. +2. Determine the session that was least-recently used then: + a.Send a status report: StatusReport(GeneralCode: SUCCESS, ProtocolId: SECURE_CHANNEL, Pro­ + tocolCode: CLOSE_SESSION) message to the peer node +b. Remove all state associated with the session (see Section 4.13.3.1, “Secure Session Context”). +The Node MAY save state necessary to perform Session Resumption, see Section 4.14.2.2.1, +“Session Resumption State” for more details. +3. Respond to the initiator with the appropriate session establishment message + +**4.11.1.2. Status Report** + +The Status Report message is sent from protocol handlers to convey the status of an operation using +a common format as defined in Appendix D, _Status Report Messages_. The _StatusReport_ message is a +part of the Secure Channel protocol, but embeds an additional context-specific ProtocolID field in +its message-specific payload. In this way, the _StatusReport_ can convey status for any protocol han­ +dler. + +**4.11.1.3. Secure Channel Status Report Messages** + +Status Reports specific to the Secure Channel are designated by embedding the PROTOCOL_ID_SE­ +CURE_CHANNEL in the ProtocolId field of the _StatusReport_ body. All Secure Channel Status Report Mes­ +sages SHALL use the PROTOCOL_ID_SECURE_CHANNEL protocol id. For example, a failure to find a com­ +mon root of trust may be written in the specification as follows: StatusReport(GeneralCode: FAILURE, +ProtocolId: SECURE_CHANNEL, ProtocolCode: NO_SHARED_TRUST_ROOTS). + +There are several cases for which the secure channel layer may emit a status report: + +1. To indicate successful session establishment +2. In response to errors during session establishment +3. In response to errors after session establishment +4. To indicate that a Node is terminating a session + +``` +Page 146 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +For each of these cases, a Secure Channel Status Report message SHALL be sent with an appropriate +ProtocolCode as detailed below. + +The following table describes the Secure Channel Status Report Protocol Specific codes. Each entry +in the list details the appropriate General Code to be utilized with the message and whether it may +be sent unencrypted. Secure Channel Status Report messages which are marked as encrypted below +SHALL only be sent encrypted in a session established with CASE or PASE. + +_Table 19. Secure Channel Protocol Codes_ + +``` +Protocol +Code +``` +``` +Error General +Code +``` +``` +Encrypted Additional +Data +``` +``` +Description +``` +``` +0x0000 SESSION_ESTABLISH­ +MENT_SUCCESS +``` +``` +SUCCESS N N Indication that the last session +establishment message was +successfully processed. +0x0001 NO_SHARED_TRUST_­ +ROOTS +``` +``` +FAILURE N N Failure to find a common set of +shared roots. +0x0002 INVALID_PARAMETER FAILURE N N Generic failure during session +establishment. +0x0003 CLOSE_SESSION SUCCESS Y N Indication that the sender will +close the current session. See +Section 4.11.1.4, “CloseSession” +for more details. +0x0004 BUSY BUSY N Y Indication that the sender can­ +not currently fulfill the request. +See Section 4.11.1.5, “Busy” for +more details. +``` +**4.11.1.4. CloseSession** + +A node may choose to close a session for a variety of reasons including, but not limited to, the fol­ +lowing: + +1. The interaction between nodes is complete +2. The node needs to free up resources for a new session +3. Fabric configuration associated with the CASE session was removed with the RemoveFabric + command invoked by an Administrator while the session was open + +The CloseSession StatusReport SHALL only be sent encrypted within an exchange associated with a +PASE or CASE session. The CloseSession StatusReport SHALL be sent within a new exchange and +SHALL NOT set the R Flag. + +If a Node has either sent or received a CloseSession StatusReport, that Node SHALL remove all state +associated with the session (see Section 4.13.3.1, “Secure Session Context”). The Node MAY save +state necessary to perform Session Resumption, see Section 4.14.2.2.1, “Session Resumption State” +for more details. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 147 +``` + +**4.11.1.5. Busy** + +When a receiver receives a request to start a new secure session via a Sigma1 or PBKDFParamRe­ +quest message, the receiver MAY respond with the BUSY StatusReport when it is unable to fulfill the +request. The BUSY StatusReport SHALL: + +1. Set the R Flag to 0 +2. Set the S Flag to 0 +3. Set the StatusReport ProtocolData to a 16-bit (two byte) little-endian value indicating the mini­ + mum time in milliseconds to wait before retrying the original request. +4. Set the Exchange ID to the _Exchange ID_ present in the Sigma1 or PBKDFParamRequest message + which triggered this response. + +For example, a responder wishing to indicate they are unable to fulfill the request and that the ini­ +tiator should wait 500 milliseconds before trying again would send StatusReport(GeneralCode: +BUSY, ProtocolId: SECURE_CHANNEL, ProtocolCode: BUSY, ProtocolData: [0xF4, 0x01]). + +The BUSY StatusReport SHALL NOT be sent in response to any message except for Sigma1 or +PBKDFParamRequest. + +An initiator receiving a BUSY StatusReport from a responder SHALL wait for at least a period of t +milliseconds before retrying the request where t is the value obtained from the Busy StatusReport +ProtocolData field. + +If the initiator sends a new session establishment request after receiving a BUSY StatusReport, the +request SHALL contain new values for all randomized parameters. + +**4.11.2. Parameters and Constants** + +Table 20, “Glossary of constants” is a glossary of constants used in the secure channel protocol, +along with a brief description and the default for each constant. + +_Table 20. Glossary of constants_ + +``` +Constant Name Description Value +MSG_COUNTER_WINDOW_SIZE Maximum number of previously processed mes­ +sage counters to accept from a given Node and +key. +``` +### 32 + +### MSG_COUNTER_SYNC_REQ_JIT­ + +### TER + +``` +Maximum amount of random delay before send­ +ing a MsgCounterSyncReq when the synchroniza­ +tion request is triggered by receipt of a multicast +message. +``` +``` +500 millisec­ +onds +``` +``` +MSG_COUNTER_SYNC_TIMEOUT The maximum amount of time (in milliseconds) +which a Node SHALL wait for a MsgCounterSyn­ +cRsp after sending a MsgCounterSyncReq. +``` +``` +400 millisec­ +onds +``` +``` +Page 148 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.12. Message Reliability Protocol (MRP)** + +The Message Reliability Protocol (MRP) provides confirmation of delivery for messages that require +reliability. The protocol is optimized for constrained devices that may not be able to receive a mes­ +sage at the point it is due to be delivered to them. Reliable messaging MAY be enabled on an indi­ +vidual message basis as required by the protocol design of the higher layer application. Reliability +is achieved through time-bounded delivery confirmation, ensuring best effort delivery of critical +messages over what may be an inherently lossy and unreliable communication medium. + +Flow control mechanisms are not incorporated in MRP because it is intended to be used for short +interactions with small numbers of messages in them. + +**4.12.1. Reliable Messaging Header Fields** + +The following fields are defined in the Exchange Flags for use exclusively by MRP: + +- R Flag + +``` +Indicates a reliable message. This flag SHALL be set by the sender when a message being sent +requires the receiver to send back an acknowledgment. To support unreliable messages, this +flag bit MAY be clear, so that no acknowledgements are requested from the receiver. +``` +- A Flag + +``` +Indicates the message is acting as an acknowledgement. This flag MAY be set on any message. +When set, the Acknowledged Message Counter field SHALL be present and valid. This flag SHALL +always be set for MRP Standalone Acknowledgement messages. +``` +- Acknowledged Message Counter + +``` +This field SHALL be set to the Message Counter of the message that is being acknowledged. +``` +**4.12.2. Reliable transfer** + +When the reliability bit is set, the _reliable message_ is transmitted at most _MRP_MAX_TRANSMIS­ +SIONS_ times until an acknowledgement of receipt is received from the peer or a timeout. + +**4.12.2.1. Retransmissions** + +Senders provide an automatic retransmission mechanism for reliable messages. In order for the +receiver to receive a message reliably, the sender SHALL trigger the automatic retry mechanism +after a period of _mrpBackoffTime_ milliseconds without receiving an acknowledgement, where _mrp­ +BackoffTime_ is calculated according to the formula below. The sender SHALL retry up to a config­ +ured maximum number of times ( _MRP_MAX_TRANSMISSIONS_ - 1) before giving up and notifying +the application. + +Messages sent to a Node can be lost for various reasons such as lossy network or insufficient buffer +space at the receiver. In the case of Intermittently Connected Devices, which are active infrequently +to receive messages destined for them, a sender must be aware of the characteristics of the recipi­ +ent to ensure it does not attempt to send at a rate beyond the recipient’s capability. Therefore, the + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 149 +``` + +sender SHALL choose retransmission timeouts based on the session characteristics of the destina­ +tion Node exposed via Section 4.3.2, “Operational Discovery”. + +At each sender, a retransmission timer is started each time a reliable message is transmitted. The +duration of the retransmission timer SHALL be calculated as follows: + +``` +"mrpBackoffTime" = i * "MRP_BACKOFF_BASE"^(max(0,n-"MRP_BACKOFF_THRESHOLD")) * (1.0 + +"random"(0,1) * "MRP_BACKOFF_JITTER") +``` +Where: + +``` +{:("mrpBackoffTime", =, "the resultant retransmission timeout for this +transmission"),(n, =, "the number of send attempts before the current one for this +message (0 if this is the initial transmission)"),(i, =, "the base retry interval for +the Exchange (either IDLE or ACTIVE)"):} +``` +For each unique Exchange, the sender SHALL wait for the acknowledgement message until the +retransmission timer, _mrpBackoffTime_ , expires. + +When waiting for an acknowledgement, an Intermittently Connected Device will always be in +Active Mode since it will have at least one active exchange. An Intermittently Connected Device +sender SHOULD increase the _mrpBackoffTime_ by its fast polling interval to take into account the +delay that might happen in receiving the acknowledgment while in Active Mode. + +For the first message of a new exchange, the base interval, i, SHALL be set according to the active +state of the peer node as stored in the Session Context of the session (either the Secure Session Con­ +text or the Unsecured Session Context depending on the Session Type). For all subsequent messages +of the exchange, the base interval, i, SHOULD be set according to the active state of the peer node as +stored in the Session Context of the session (either the Secure Session Context or the Unsecured Ses­ +sion Context depending on the Session Type), unless the sender has other means to determine +whether the device is active or idle. The backoff base interval SHALL be set to a value at least 10% +greater than the idle interval of the destination: + +- If PeerActiveMode in the Session Context is true: + ◦ i = SESSION_ACTIVE_INTERVAL of the peer +- Else the peer is in idle mode: + ◦ i = SESSION_IDLE_INTERVAL of the peer +- i = MRP_BACKOFF_MARGIN * i + +The _MRP_BACKOFF_THRESHOLD_ parameter creates a two-phase scheme which begins with linear +backoff to improve initial latency when congestion is not the cause of packet drops, and then transi­ +tions to exponential backoff to provide convergence when the network is congested. If a positive +acknowledgment is received before the retransmission timer expires, the retransmission timer is +stopped. Otherwise, if the retransmission timer expires, the message is retransmitted and the timer +started again. + +``` +Page 150 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The following table illustrates minimum, maximum, and cumulative retransmission times using +default parameters. + +_Table 21. Example MRP Retransmission Times_ + +``` +Metric Transmission Time [ms] +Min Jitter 330 330 528 845 1352 +Max Jitter 413 413 660 1056 1690 +Min Total 330 660 1188 2033 3385 +Max Total 413 825 1485 2541 4231 +Transmission # 0 1 2 3 4 +``` +The sender SHOULD initiate Section 4.3.2, “Operational Discovery” in parallel with the first retry to +re-resolve the address of the destination Node if the initial transmission fails after one expected +round trip. The sender SHOULD use the latest MRP parameters for the destination that result from +subsequent Operational Discovery. + +When a client is communicating with an ICD (i.e. the ICD Management cluster is present), the +sender SHALL initiate Section 4.3.2, “Operational Discovery” in parallel with the first retry to re- +resolve the address of the destination Node if the initial transmission fails after one expected round +trip. The sender SHALL use the latest MRP parameters for the destination that result from subse­ +quent Operational Discovery. + +**4.12.2.2. Acknowledgements** + +A receiver SHALL acknowledge a reliable message by either using a "piggybacked" acknowledg­ +ment in the next message destined to the peer, or a standalone acknowledgment, or both. + +The acknowledgement message SHALL set the _Acknowledged Message Counter_ field to the value of +the _Message Counter_ of the reliable message to be acknowledged. + +**Piggybacking Acknowledgments on Responses** + +Acknowledgements MAY be conveyed at the same time (i.e. piggybacked) as data in a response mes­ +sage. The receiver tries to optimize message transmission by deferring acknowledgments when a +reliable message is received (see Section 4.12.5.2.2, “Standalone acknowledgement processing”) and +piggybacking outstanding acknowledgments on messages that it needs to send back (see Section +4.12.5.1.1, “Piggyback acknowledgment processing” for more details). + +**Duplicate Message Detection** + +Since the reliable messaging protocol has a provision for the sender to retransmit messages, there +is a significant chance that a duplicate message may arrive at the receiver. The receiver SHALL +detect and mark duplicate messages that it receives using the standard authentication and replay +protection mechanisms of the secure message layer (see Section 4.6.5, “Replay Prevention and +Duplicate Message Detection”). The receiver SHALL send an acknowledgment message to the +sender for each instance of an authenticated, reliable message, including duplicates. The reliability +layer SHALL only propagate the first instance of a message to the next higher layer. Any message + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 151 +``` + +marked as a duplicate SHALL be dropped by the reliability layer. + +**4.12.3. Peer Exchange Management** + +The Reliable Messaging Protocol operates within the scope of an Exchange between two Nodes. +MRP SHALL support one pending acknowledgement and one pending retransmission per +Exchange. + +MRP control parameters, detailed in Table 22, “Glossary of MRP parameters”, are computed outside +of the Exchange communication itself; instead, they are valid for the duration of a secure session. +The SESSION_ACTIVE_INTERVAL and SESSION_IDLE_INTERVAL, used in computation of MRP control para­ +meters, are determined during Operational Discovery or Section 4.3.1, “Commissionable Node Dis­ +covery”. Additionally, the initiator of a secure session MAY provide these parameters in the initial +CASE Sigma1 or PASE PBKDFParamRequest messages, and the responder MAY provide its parame­ +ters in the corresponding protocol messages CASE Sigma2 or PBKDFParamResponse. + +**4.12.4. Transport Considerations** + +When the upper layer requests a reliable message over a UDP transport, the R Flag SHALL be set on +that message indicating that MRP SHALL be used. Reliable messages sent over TCP or BTP SHALL +utilize the underlying reliability mechanisms of those transports and SHOULD NOT set the R Flag. + +**4.12.5. Reliable Message Processing** + +**4.12.5.1. Reliable Message Processing of Outgoing Messages** + +To prepare a given Protocol Message for transmission, the message SHALL be processed as follows: + +1. Proceed to Section 4.12.5.1.1, “Piggyback acknowledgment processing”. + +**Piggyback acknowledgment processing** + +1. Determine if there is a matching pending acknowledgement in the _acknowledgement table_ for + the given message by checking all of the following conditions: + a.If the Destination Node Id and Exchange Id of the given message and pending acknowledge­ + ment are the same +b. AND either +i. the Session Id and underlying Session Credentials of the given message and pending +acknowledgement are the same +ii.OR both the given message and pending acknowledgement are of Unsecured Session +Type. +2. If there is a matching pending acknowledgement, the A Flag SHALL be set on the outbound mes­ + sage so it will serve as a piggybacked acknowledgement. + a.For such a piggybacked acknowledgement, the _Acknowledgment Message Counter_ field + SHALL be set to the message counter of the received message for which an acknowledge­ + ment was pending. + +``` +Page 152 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +b. If the message being prepared is not a standalone acknowledgement, remove the matching +entry from the acknowledgement table. +c. If the message being prepared is a standalone acknowledgement, set the StandaloneAckSent +field of the matching entry in the acknowledgement table to true. +``` +**Message retransmission processing** + +1. If the outbound message is marked to be delivered reliably over a UDP transport, the R Flag + SHALL be set on the given message to request an acknowledgement from the peer upon receipt. + a. Any message flagged for reliable delivery (R Flag set) SHALL be stored in the _retransmission_ + _table_ to track the message until it has been successfully acknowledged by the peer. +2. Perform Section 4.7.1, “Message Transmission” processing step on the message to send the mes­ + sage to the peer: + a. The same Session ID, Destination Node ID, Security Flags, and transport as were used for the + initial message transmission SHALL be used. +3. If the transport interface returns an error on the send attempt, the error is assessed to deter­ + mine whether the message can be retried. + a. If the error is fatal, the application is notified and the message removed from the _retrans­_ + _mission table_. + b. If there is no error, or a non-fatal error such as no memory, the message is resent + i. Update the _retransmission table_ to reflect the send count. +ii. Start a retransmission timer to track the maximum time to wait before attempting +another retransmission. +iii. For each retry, the _retransmission table_ is updated to track the number of retries until +the maximum number is attempted, at which point the message is evicted from the +_retransmission table_. + +**Send flow state diagram** + +The MRP send flow described above is depicted in the control flow diagram Figure 12, “MRP send +flow”. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 153 +``` + +_Figure 12. MRP send flow_ + +``` +Page 154 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.12.5.2. Reliable Message Processing of Incoming Messages** + +A message received from Section 4.7.2, “Message Reception” for reliability processing SHALL be +processed as follows: + +1. Verify the message has a legal combination of reliability flags: + a. If the R Flag is set: + i. If Group Session Type AND C Flag = 0 , drop the message. + b. If the A Flag is set: + i. If Group Session Type AND C Flag = 0 , drop the message. +2. Proceed to Section 4.10.5.1, “Exchange Message Matching”. +3. Proceed to Section 4.12.5.2.1, “Received acknowledgement processing”. + +**Received acknowledgement processing** + +1. If the A Flag is set: + a. Query the _retransmission table_ for the _Acknowledgement Message Counter_ contained in the + received message. + i. If there is a match: + A. Remove the entry from the _retransmission table_. + B. Stop the retransmission timer for that entry. +ii. If there is no match, it indicates that this is either a duplicate acknowledgment or the +Exchange context does not exist. +2. Proceed to Section 4.12.5.2.2, “Standalone acknowledgement processing”. + +**Standalone acknowledgement processing** + +1. If the R Flag is set, the received message is requesting an acknowledgement be sent back: + a. If the message is marked as a duplicate: + i. Immediately send a standalone acknowledgment. +ii. If the Exchange is marked as an _ephemeral exchange_ the Exchange SHALL be closed. +iii. Drop the message. + b. Otherwise, instead of sending an acknowledgement immediately upon the receipt of a reli­ + able message from a peer, the receiver SHOULD wait for a time no longer than _MRP_STAND­_ + _ALONE_ACK_TIMEOUT_ before sending a standalone acknowledgment: + i. Add the message counter of the received message to the _acknowledgement table_ to signal + that an outbound acknowledgement is pending. There can be only one outstanding + acknowledgement at a time on a single Exchange. If a pending acknowledgement + already exists for the Exchange, and it has StandaloneAckSent set to false, a standalone + acknowledgment SHALL be sent immediately for that pending message counter, and the + _acknowledgement table_ entry SHALL be replaced for the new message. +ii. Start the acknowledgement timer for the Exchange. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 155 +``` + +``` +A. If the timer triggers before being cancelled, a standalone acknowledgment SHALL be +sent to the source of the message. Sending this standalone acknowledgment SHALL +NOT remove the acknowledgement table entry and SHALL set the StandaloneAckSent +field of the entry to true. +``` +2. The received message is then delivered to the next processing step of Section 4.7.2, “Message + Reception”. + +**Receive flow state diagram** + +The MRP receive flow described above is depicted in Figure Figure 13, “MRP receive flow”. + +_Figure 13. MRP receive flow_ + +``` +Page 156 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.12.6. Reliable Message State** + +**4.12.6.1. Retransmission Table** + +For retransmissions, the sender maintains a _retransmission table_ of context records containing +information on all reliable messages sent that have acknowledgments still pending. Each such reli­ +able message context record includes the following fields: + +- Reference to Exchange Context +- Message Counter +- Reference to fully formed, encoded and encrypted message buffer +- Send count +- Retransmission timeout counter + +Each time a message that requires acknowledgment is sent, a new retransmission context record is +inserted into the _retransmission table_ or an existing record is updated to increment its send count. +The message is sent a configurable maximum number of times ( _MRP_MAX_TRANSMISSIONS_ ) and, +if still undelivered, the application is notified of the failure. + +**4.12.6.2. Acknowledgement Table** + +The receiver maintains an _acknowledgement table_ of context records containing information on +each reliable message for which an acknowledgment SHALL be sent. Each such reliable message +context record includes the following fields: + +- Reference to Exchange Context +- Message Counter +- A boolean, StandaloneAckSent, indicating whether a standalone acknowledgement has been sent + for this message counter. Initially false. + +An entry SHALL remain in the table until one of the following things happens: + +1. The exchange associated with the entry is closed. See Section 4.10.5.3, “Closing an Exchange”. +2. The exchange associated with the entry has switched to track a pending acknowledgement for a + new message counter value. See Section 4.12.5.2.2, “Standalone acknowledgement processing”. +3. A message that is not a standalone acknowledgement is sent which serves as an acknowledge­ + ment for the entry. See Section 4.12.5.1.1, “Piggyback acknowledgment processing”. + +**4.12.7. MRP Messages** + +**4.12.7.1. MRP Standalone Acknowledgement** + +The _MRP Standalone Acknowledgement_ message SHALL be formed as follows: + +- The application payload SHALL be empty. +- The A Flag SHALL be set to 1. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 157 +``` + +- The Acknowledged Message Counter SHALL be included in the header. +- The Protocol ID SHALL be set to PROTOCOL_ID_SECURE_CHANNEL. +- The Protocol Opcode SHALL be set to _MRP Standalone Acknowledgement_. + +The rules for when to send this message are detailed in Section 4.12.5.2.2, “Standalone acknowl­ +edgement processing”. + +**4.12.8. Parameters and Constants** + +This is a glossary of the MRP parameters used in this chapter with a brief description for each para­ +meter. A Node SHALL use the provided default value for each parameter unless the message recipi­ +ent Node advertises an alternate value for the parameter via Operational Discovery. + +_Table 22. Glossary of MRP parameters_ + +``` +Parameter Name Description Default Value +MRP_MAX_TRANSMISSIONS The maximum number of transmission +attempts for a given reliable message. The +sender MAY choose this value as it sees fit. +``` +### 5 + +``` +MRP_BACKOFF_BASE The base number for the exponential back­ +off equation. +``` +### 1.6 + +``` +MRP_BACKOFF_JITTER The scaler for random jitter in the backoff +equation. +``` +### 0.25 + +``` +MRP_BACKOFF_MARGIN The scaler margin increase to backoff over +the peer idle interval. +``` +### 1.1 + +``` +MRP_BACKOFF_THRESHOLD The number of retransmissions before +transitioning from linear to exponential +backoff. +``` +### 1 + +``` +MRP_STANDALONE_ACK_TIMEOUT Amount of time to wait for an opportunity +to piggyback an acknowledgement on an +outbound message before falling back to +sending a standalone acknowledgement. +``` +``` +200 millisec­ +onds +``` +**4.13. Unicast Communication** + +This section specifies the semantics of establishing a unicast session and the lifecycle of a unicast +session. + +Unicast sessions exist in one of two phases: + +1. Session Establishment Phase: A series of well-defined unencrypted messages that aim to estab­ + lish a shared key. +2. Application Data Phase: A series of ad-hoc encrypted messages exchanging interaction model + protocol actions, application data, etc. + +``` +Page 158 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.13.1. Session Parameters** + +This is a glossary of the session parameters used during session establishment with a brief descrip­ +tion for each parameter. A Node SHALL use the provided default value for each parameter unless +the message recipient Node advertises an alternate value for the parameter via Operational Discov­ +ery. + +_Table 23. Glossary of Session parameters_ + +``` +Parameter Name Description Default Value +SESSION_IDLE_INTERVAL Minimum amount of time between sender +retries when the destination node is Idle. +This SHALL be greater than or equal to the +maximum amount of time a node may be +non-responsive to incoming messages +when Idle. +``` +``` +500 millisec­ +onds +``` +``` +SESSION_ACTIVE_INTERVAL Minimum amount of time between sender +retries when the destination node is Active. +This SHALL be greater than or equal to the +maximum amount of time a node may be +non-responsive to incoming messages +when Active. +``` +``` +300 millisec­ +onds +``` +``` +SESSION_ACTIVE_THRESHOLD Minimum amount of time the node +SHOULD stay active after network activity. +``` +``` +4000 millisec­ +onds +DATA_MODEL_REVISION Version of Data Model for the Session para­ +meters side where it appears. +``` +``` +See DataModel­ +Revision +attribute. +INTERACTION_MODEL_REVISION Version of Interaction Model for the Ses­ +sion parameters side where it appears. +``` +``` +See Section +8.1.1, “Revision +History”. +SPECIFICATION_VERSION Version of Specification for the Session +parameters side where it appears. +``` +``` +See Specifica­ +tionVersion +attribute. +MAX_PATHS_PER_INVOKE The maximum number of elements in the +InvokeRequests list that the Node is able to +process +``` +``` +See Max­ +PathsPerIn­ +voke attribute. +SUPPORTED_TRANSPORTS A bitmap of the supported transport proto­ +cols in addition to MRP. +``` +``` +See Table 7, +“Supported +Transport +Mode Values”. +MAX_TCP_MESSAGE_SIZE Maximum size of the message carried over +TCP, excluding the framing message length +field, that the node is capable of receiving +from its peer. +``` +``` +64000 bytes. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 159 +``` + +These parameters are encoded in the following TLV format when included in CASE / PASE session +establishment: + +``` +session-parameter-struct => STRUCTURE [ tag-order ] +{ +SESSION_IDLE_INTERVAL [1, optional] : UNSIGNED INTEGER [ range 32-bits ], +SESSION_ACTIVE_INTERVAL [2, optional] : UNSIGNED INTEGER [ range 32-bits ], +SESSION_ACTIVE_THRESHOLD [3, optional] : UNSIGNED INTEGER [ range 16-bits ], +DATA_MODEL_REVISION [4] : UNSIGNED INTEGER [ range 16-bits ], +INTERACTION_MODEL_REVISION [5] : UNSIGNED INTEGER [ range 16-bits ], +SPECIFICATION_VERSION [6] : UNSIGNED INTEGER [ range 32-bits ], +MAX_PATHS_PER_INVOKE [7] : UNSIGNED INTEGER [ range 16-bits ], +SUPPORTED_TRANSPORTS [8] : UNSIGNED INTEGER [ range 16-bits ], +MAX_TCP_MESSAGE_SIZE [9, optional] : UNSIGNED INTEGER [ range 32-bits ], +} +``` +For backwards compatibility, if any tag after tag 2 ( _SESSION_ACTIVE_INTERVAL_ ) is present, then the +_SESSION_ACTIVE_INTERVAL_ SHALL also be present. + +### NOTE + +``` +That means that SESSION_ACTIVE_INTERVAL is always present if the sender of the +CASE/PASE session establishment message supports DATA_MODEL_REVISION , +INTERACTION_MODEL_REVISION , and SPECIFICATION_VERSION , but recipients +SHALL NOT assume that it is present. +``` +For backwards compatibility, if the _DATA_MODEL_REVISION_ field is missing, it implies a DataMod­ +elRevision value of either 16 or 17. + +For backwards compatibility, if the _INTERACTION_MODEL_REVISION_ field is missing, it implies a +value of either 10 or 11. + +For backwards compatibility, if the _SPECIFICATION_VERSION_ field is missing, it implies a Specifica­ +tionVersion value strictly smaller than 0x01030000. + +For backwards compatibility, if the _MAX_PATHS_PER_INVOKE_ field is missing, it implies a Max­ +PathsPerInvoke set to 1. + +For backwards compatibility, if the _SUPPORTED_TRANSPORTS_ field is missing, it implies that the +node only supports MRP. When present with a value of 0, it indicates that the node only supports +MRP. + +The _MAX_TCP_MESSAGE_SIZE_ field SHALL only be present if the _SUPPORTED_TRANSPORTS_ field +indicates that TCP is supported. + +**4.13.2. Session Establishment Phase** + +Session establishment uses either the CASE or PASE protocol. + +``` +Page 160 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +CASE SHALL be used as a session establishment mechanism for **all** sessions except: + +1. Communication for the purpose of commissioning when NOC has not yet been installed + +PASE SHALL only be used for session establishment mechanism during device commissioning. +PASE SHALL NOT be used as a session establishment mechanism for any other session. BTP MAY be +used as the transport for device commissioning. BTP SHALL NOT be used as a transport for opera­ +tional purposes. + +Unless otherwise specified, the CASE, PASE, User-Directed Commissioning protocol, and Secure +Channel Status Report messages SHALL be the only allowed **unencrypted** messages. + +This phase aims to: + +1. Authenticate peers (CASE-based sessions only). +2. Derive shared secrets to encrypt subsequent session data. +3. Choose session identifiers to identify the subsequent session. + +**4.13.2.1. Unsecured Session Context** + +The following session context data SHALL be utilized to associate messages to a particular peer and +recover context during unencrypted sessions: + +1. Session Role: Records whether the node is the session initiator or responder. +2. Ephemeral Initiator Node ID: Randomly selected for each session by the initiator from the Oper­ + ational Node ID range and enclosed by initiator as Source Node ID and responder as Destination + Node ID. + ◦ Initiators SHALL select a new random ephemeral node ID for each unsecured session, and + SHALL select an ID that does not conflict with any ephemeral node IDs for any other ongo­ + ing unsecured sessions opened by the initiator. +3. Message Reception State: Provides tracking for the Unencrypted Message Counter of the remote + peer. + +Matching and responder creation of Unsecured Session Contexts SHALL be as follows: + +1. Given an incoming unencrypted message + a. Locate any Unsecured Session Context with matching Ephemeral Initiator Node ID + i. If any is located, the incoming message SHALL be assumed to be associated with this + Unsecured Session Context + b. Else if the message carries a Source Node ID + i. Create a new Unsecured Session Context +ii. Set Session Role to responder +iii. Record the incoming message’s Source Node ID as Ephemeral Initiator Node ID +c. Else discard the message + +Initiator creation of Unsecured Session Contexts SHALL be as follows: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 161 +``` + +1. Given the first outgoing message of an unencrypted exchange + a.Create a new Unsecured Session Context +b. Set Session Role to initiator +c.Randomly select a node ID from the Operational Node ID range that does not collide with +any ephemeral node IDs for any other ongoing unsecured sessions opened by the initiator +and record this as Ephemeral Initiator Node ID + +**4.13.2.2. Session Establishment over IP** + +When establishing a session over IP, the initiator MAY use TCP when both of the following are true: + +1. The initiator supports TCP Client as defined in the Supported Transport Mode Values table in the + T record. +2. The responder supports TCP Server as defined in the Supported Transport Mode Values table in + the T record. + +Otherwise, the initiator SHALL use MRP to establish the session. + +The transport used during the session establishment phase SHALL also be used for the subsequent +transport of messages over the established session. + +**4.13.2.3. Shared Secrets** + +Both CASE and PASE produce two shared keys: I2RKey and R2IKey. These keys will be saved to the +session’s context and used to encrypt and decrypt messages during the Session Data Phase. + +Nodes that support the CASE session resumption SHALL also save to the session’s context the +SharedSecret computed during the CASE protocol execution. + +**4.13.2.4. Choosing Secure Unicast Session Identifiers** + +Both CASE and PASE allow each participant the ability to choose a unicast session identifier for the +subsequent encrypted session. The session identifier SHALL be used to look up the relevant encryp­ +tion keys and any other metadata for a particular session. + +Messages using a unicast session identifier SHALL set the Session Type field to 0. Each peer SHALL +specify a Session Identifier unique in reference to **their own** active sessions. There SHALL NOT be +overlap between the Session ID values allocated for PASE and CASE sessions, as the Session Identi­ +fier space is shared across both session establishment methods. + +For example, if the initiator has two active sessions with session identifiers 0x0001 and 0x0002, it +could choose any non-zero session identifier besides 0x0001 and 0x0002. + +If there are no available session identifiers (i.e. the participant has 65,535 open sessions), the Node +SHALL terminate an existing session to free a session identifier. + +**4.13.3. Application Data Phase** + +When the last CASE or PASE protocol message is sent or received and successfully processed, ses­ + +``` +Page 162 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +sion establishment has completed. +``` +``` +4.13.3.1. Secure Session Context +``` +``` +During the Application Data Phase, the following conceptual session context data SHALL be utilized +to securely process subsequent messages: +``` +1. Session Type: Records whether the session was established using CASE or PASE. +2. Session Role: Records whether the node is the session initiator or responder. +3. Local Session Identifier: Individually selected by each participant in secure unicast communi­ + cation during session establishment and used as a unique identifier to recover encryption keys, + authenticate incoming messages and associate them to existing sessions. + ◦ On a given Node, this is the identifier that SHALL be used to map from an incoming mes­ + sage’s Session ID field to the session context data. +4. Peer Session Identifier: Assigned by the peer during session establishment. + ◦ On a given Node, this is the identifier that SHALL be used in the Session ID field of every out­ + going message associated with the session, so that it can be interpreted as the Local Session + Identifier by the remote peer. +5. I2RKey: Encrypts data in messages sent from the initiator of session establishment to the respon­ + der. +6. R2IKey: Encrypts data in messages sent from the session establishment responder to the initia­ + tor. +7. SharedSecret: Computed during the CASE protocol execution and re-used when CASE session + resumption is implemented. +8. Local Message Counter: Secure Session Message Counter for outbound messages. + ◦ At successful session establishment, the Local Message Counter SHALL be initialized per Sec­ + tion 4.6.1.1, “Message Counter Initialization”. +9. Message Reception State: Provides tracking for the Secure Session Message Counter of the + remote peer. +10. Local Fabric Index: Records the local Index for the session’s Fabric, which MAY be used to look +up Fabric metadata related to the Fabric for which this session context applies. +◦ This field SHALL contain the "no Fabric" value of 0 when the SessionType is PASE and success­ +ful invocation of the AddNOC command has not yet occurred during commissioning. +11. Peer Node ID: Records the authenticated node ID of the remote peer, when available. + +``` +◦ This field SHALL contain the "Unspecified Node ID" value of 0 when the SessionType is PASE. +``` +12. Resumption ID: The ID used when resuming a session between the local and remote peer. +13. SessionTimestamp: A timestamp indicating the time at which the last message was sent or + received. This timestamp SHALL be initialized with the time the session was created. See Sec­ + tion 4.11.1.1, “Session Establishment - Out of Resources” for more information. +14. ActiveTimestamp: A timestamp indicating the time at which the last message was received. This + timestamp SHALL be initialized with the time the session was created. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 163 +``` + +15.The following Session parameters (see Table 23, “Glossary of Session parameters”): + +``` +a. SESSION_IDLE_INTERVAL +b. SESSION_ACTIVE_INTERVAL +c. SESSION_ACTIVE_THRESHOLD +d. PeerActiveMode: A boolean that tracks whether the peer node is in Active or Idle mode. Peer­ +ActiveMode is set as follows: +``` +``` +"PeerActiveMode" = ("now()" - "ActiveTimestamp") < "SESSION_ACTIVE_THRESHOLD" +``` +Note that the Local Fabric Index and Peer Fabric Index reported in the NOC Response MAY differ in +value, while still referring to the same Fabric, since for a given complete Fabric Reference, the short +Fabric Index allocated during commissioning of the respective Nodes on the same Fabric MAY be +different. This possible difference is due to the order in which the Fabric in question was joined in +the lifecycle of the respective Nodes. See the section on AddNOC command behavior for details on +Fabric Index allocation behavior over time. + +There SHALL also be reservation of storage to support CASE Authenticated Tag (CAT) fields. The CAT +fields are 32-bit values that MAY have been present in RDN case-authenticated-tag of the remote +peer’s operational certificate, during CASE. + +The CAT fields are used to cache Operational Certificate data so that it can be used by the ACL pro­ +cessing logic to support CASE Authenticated Tags. + +Since these fields MAY be omitted from NOCs, they MAY be marked as absent in the context, such +that they are not taken into account when missing. When present, they SHALL be stored. Maximum +up to 3 CAT fields SHALL be supported. + +Their value is unused in PASE session contexts. + +**4.14. Session Establishment** + +**4.14.1. Passcode-Authenticated Session Establishment (PASE)** + +This section describes session establishment using a shared passcode together with an augmented +Password-Authenticated Key Exchange (PAKE), in which only one party knows the passcode before­ +hand, to generate shared keys. This protocol is only used when commissioning a Node (i.e. the Com­ +missionee). + +**4.14.1.1. Protocol Overview** + +The Passcode-Authenticated Session Establishment (PASE) protocol aims to establish the first ses­ +sion between a Commissioner and a Commissionee using a known passcode provided out-of-band. +The pairing is performed using Section 3.10, “Password-Authenticated Key Exchange (PAKE)” and +relies on a Password-Based Key Derivation Function (PBKDF) where the passcode is used as pass­ +word. + +``` +Page 164 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +This session establishment protocol provides a means to: + +1. Communicate PBKDF parameters. +2. Derive PAKE bidirectional secrets. + +_Figure 14. Overview of the PASE Protocol_ + +The Commissioner is the Initiator and the Commissionee is the Responder. + +It is assumed that the initiator has somehow obtained the passcode and that the responder has the +relevant Crypto_PAKEValues_Responder corresponding to the passcode before starting a PASE session +establishment protocol. + +**4.14.1.2. Protocol Details** + +**Message format** + +All PASE messages SHALL be structured as specified in Section 4.4, “Message Frame Format”. + +All PASE messages are sent using an Unsecured Session: + +- The Session ID field SHALL be set to 0. +- The Session Type bits of the Security Flags SHALL be set to 0. +- In the PASE messages from the initiator, S Flag SHALL be set to 1 and DSIZ SHALL be set to 0. +- In the PASE messages from the responder, S Flag SHALL be set to 0 and DSIZ SHALL be set to 1. + +For each PASE message, the application payload is the TLV encoding of the message structure as +defined below: + +_Table 24. PASE Messages_ + +``` +Message Name Payload TLV Encoding +PBKDFParamRequest pbkdfparamreq-struct +PBKDFParamResponse pbkdfparamresp-struct +Pake1 pake-1-struct +Pake2 pake-2-struct +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 165 +``` + +``` +Message Name Payload TLV Encoding +Pake3 pake-3-struct +PakeFinished N/A (encoded via StatusReport) +``` +The other fields of the Message format are not specific to the PASE messages. + +For all TLV-encoded PASE messages, any context-specific tags not listed in the associated TLV +schemas SHALL be reserved for future use, and SHALL be silently ignored if seen by a recipient +which cannot understand them. + +**Message Exchange** + +The PBKDFParamRequest, PBKDFParamResponse, Pake1, Pake2, Pake3, and PakeFinished of a distinct session +establishment are part of the same message exchange. The initiator and responder SHALL NOT +send encrypted application data in the newly established session until PakeFinished is received by +the initiator within the unencrypted session used for establishment. + +Each message SHALL use PROTOCOL_ID_SECURE_CHANNEL as Protocol ID and the corresponding Protocol +Opcode as defined in Table 18, “Secure Channel Protocol Opcodes”. + +The flags of the Exchange Flags of the Protocol Header are defined as follows per PASE message: + +``` +Message I Flag +PBKDFParamRequest 1 +PBKDFParamResponse 0 +Pake1 1 +Pake2 0 +Pake3 1 +``` +All PASE messages SHALL be sent reliably. This may be implicit (e.g. TCP) or explicit (e.g. MRP reli­ +able messaging) in the underlying transport. + +The other fields of the Protocol Header are not specific to the PASE messages. + +**PBKDFParamRequest** + +This message serves to request the PBKDF parameters, with a payload that follows this TLV schema: + +``` +pbkdfparamreq-struct => STRUCTURE [ tag-order ] +{ +initiatorRandom [1] : OCTET STRING [ length 32 ], +initiatorSessionId [2] : UNSIGNED INTEGER [ range 16-bits ], +passcodeId [3] : UNSIGNED INTEGER [ length 16-bits ], +hasPBKDFParameters [4] : BOOLEAN, +initiatorSessionParams [5, optional] : session-parameter-struct +``` +``` +Page 166 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### } + +1. The initiator SHALL generate a random number InitiatorRandom = Crypto_DRBG(len = 32 * 8). +2. The initiator SHALL generate a session identifier (InitiatorSessionId) for subsequent identifica­ + tion of this session. The InitiatorSessionId field SHALL NOT overlap with any other existing + PASE or CASE session identifier in use by the initiator. See Section 4.13.2.4, “Choosing Secure + Unicast Session Identifiers” for more details. The initiator SHALL set the Local Session Identi­ + fier in the Session Context to the value InitiatorSessionId. +3. The initiator SHALL choose a passcode identifier (PasscodeId) corresponding to a particular + PAKE passcode verifier installed on the responder. A value of 0 for the passcodeID SHALL corre­ + spond to the PAKE passcode verifier for the currently-open commissioning window, if any. Non- + zero values are reserved for future use. For example, for initial commissioning, the verifier + would be the built-in verifier matching the Onboarding Payload's passcode or, equivalently, the + multi-fabric Basic Commissioning Method passcode if that method is supported. For the multi- + fabric Enhanced Commissioning Method, the verifier would match the verifier provided + through the OpenCommissioningWindow command. +4. The initiator SHALL indicate whether the PBKDF parameters (salt and iterations) are known for + the particular passcodeId (for example from the QR code) by setting HasPBKDFParameters. If HasP­ + BKDFParameters is set to True, the responder SHALL NOT return the PBKDF parameters. If HasP­ + BKDFParameters is set to False, the responder SHALL return the PBKDF parameters. +5. The initiator SHALL send a message with the appropriate Protocol Id and Protocol Opcode from + Table 18, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded pbkdf­ + paramreq-struct PBKDFParamRequest with an anonymous tag for the outermost struct. + +``` +PBKDFParamRequest = +{ +initiatorRandom (1) = InitiatorRandom, +initiatorSessionId (2) = InitiatorSessionId, +passcodeID (3) = PasscodeId, +hasPBKDFParameters (4) = HasPBKDFParameters, +} +``` +**PBKDFParamResponse** + +``` +pbkdfparamresp-struct => STRUCTURE [ tag-order ] +{ +initiatorRandom [1] : OCTET STRING [ length 32 ], +responderRandom [2] : OCTET STRING [ length 32 ], +responderSessionId [3] : UNSIGNED INTEGER [ range 16-bits ], +pbkdf_parameters [4] : Crypto_PBKDFParameterSet, +responderSessionParams [5, optional] : session-parameter-struct +} +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 167 +``` + +On receipt of PBKDFParamRequest, the responder SHALL: + +1. Verify passcodeID is set to 0. If verification fails, the responder SHALL send a status report: Sta­ + tusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAME­ + TER) and perform no further processing. +2. Generate a random number ResponderRandom = Crypto_DRBG(len = 32 * 8). +3. Generate a session identifier (ResponderSessionId) for subsequent identification of this session. + The ResponderSessionId field SHALL NOT overlap with any other existing PASE or CASE session + identifier in use by the responder. See Section 4.13.2.4, “Choosing Secure Unicast Session Identi­ + fiers” for more details. The responder SHALL set the Local Session Identifier in the Session + Context to the value ResponderSessionId. +4. Set the Peer Session Identifier in the Session Context to the value PBKDFParamRequest.initia­ + torSessionId. +5. Construct the appropriate Crypto_PBKDFParameterSet (PBKDFParameters). If PBKDFParamRe­ + quest.hasPBKDFParameters is True the responder SHALL NOT include the PBKDF parameters (i.e. + salt and iteration count) in the Crypto_PBKDFParameterSet. If Msg1.hasPBKDFParameters is False the + responder SHALL include the PBKDF parameters (i.e. salt and iteration count) in the Crypto_P­ + BKDFParameterSet. +6. Send a message with the appropriate Protocol Id and Protocol Opcode from Table 18, “Secure + Channel Protocol Opcodes” whose payload is the TLV-encoded pbkdfparamresp-struct PBKDF­ + ParamResponse with an anonymous tag for the outermost struct. + +``` +PBKDFParamResponse = +{ +initiatorRandom (1) = PBKDFParamRequest.initiatorRandom, +responderRandom (2) = ResponderRandom, +responderSessionId (3) = ResponderSessionId, +pbkdf_parameters (4) = PBKDFParameters +} +``` +**Pake1** + +``` +pake-1-struct => STRUCTURE [ tag-order ] +{ +pA [1] : OCTET STRING [ length CRYPTO_PUBLIC_KEY_SIZE_BYTES ], +} +``` +On receipt of PBKDFParamResponse, the initiator SHALL: + +1. Set the Peer Session Identifier in the Session Context to the value PBKDFParamResponse.respon­ + derSessionId. +2. Generate the Crypto_PAKEValues_Initiator according to the PBKDFParamResponse.pbkdf_parameters +3. Using Crypto_PAKEValues_Initiator, generate pA := Crypto_pA(Crypto_PAKEValues_Initiator) + +``` +Page 168 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +4. Send a message with the appropriate Protocol Id and Protocol Opcode from Table 18, “Secure + Channel Protocol Opcodes” whose payload is the TLV-encoded pake-1-struct Pake1 with an + anonymous tag for the outermost struct. + +``` +Pake1 = +{ +pA (1) = pA, +} +``` +**Pake2** + +``` +pake-2-struct => STRUCTURE [ tag-order ] +{ +pB [1] : OCTET STRING [ length CRYPTO_PUBLIC_KEY_SIZE_BYTES ], +cB [2] : OCTET STRING [ length CRYPTO_HASH_LEN_BYTES], +} +``` +On receipt of Pake1, the responder SHALL: + +1. Compute pB := Crypto_pB(Crypto_PAKEValues_Responder) using the passcode verifier indicated in + PBKDFParamRequest +2. Compute TT := Crypto_Transcript(PBKDFParamRequest, PBKDFParamResponse, Pake1.pA, pB) +3. Compute (cA, cB, Ke) := Crypto_P2(TT, Pake1.pA, pB) +4. Send a message with the appropriate Protocol Id and Protocol Opcode from Table 18, “Secure + Channel Protocol Opcodes” whose payload is the TLV-encoded pake-2-struct Pake2 with an + anonymous tag for the outermost struct. + +``` +Pake2 = +{ +pB (1) = pB, +cB (2) = cB, +} +``` +**Pake3** + +``` +pake-3-struct => STRUCTURE [ tag-order ] +{ +cA [1] : OCTET STRING [length CRYPTO_HASH_LEN_BYTES], +} +``` +On receipt of Pake2, the initiator SHALL: + +1. Compute TT := Crypto_Transcript(PBKDFParamRequest, PBKDFParamResponse, Pake1.pA, Pake2.pB) + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 169 +``` + +2. Compute (cA, cB, Ke) := Crypto_P2(TT, Pake1.pA, Pake2.pB) +3. Verify Pake2.cB against cB. If verification fails, the initiator SHALL send a status report: Status­ + Report(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) + and perform no further processing. +4. Send a message with the appropriate Protocol Id and Protocol Opcode from Table 18, “Secure + Channel Protocol Opcodes” whose payload is the TLV-encoded pake-3-struct Pake3 with an + anonymous tag for the outermost struct. + +``` +Pake3 = +{ +cA (1) = cA, +} +``` +5. The initiator SHALL NOT send any encrypted application data until it receives PakeFinished + from the responder. + +On reception of Pake3, the responder SHALL: + +1. Verify Pake3.cA against cA. If verification fails, the responder SHALL send a status report: Sta­ + tusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAME­ + TER) and perform no further processing. +2. The responder SHALL set SessionTimestamp to a timestamp from a clock which would allow for + the eventual determination of the last session use relative to other sessions. +3. The responder SHALL encode and send PakeFinished. + +**PakeFinished** + +To indicate the successful completion of the protocol, the responder SHALL send a status report: +StatusReport(GeneralCode: SUCCESS, ProtocolId: SECURE_CHANNEL, ProtocolCode: SESSION_ESTABLISH­ +MENT_SUCCESS). + +The initiator SHALL set SessionTimestamp to a timestamp from a clock which would allow for the +eventual determination of the last session use relative to other sessions. + +**Session Encryption Keys** + +After verification of Pake3, each party can compute their sending and receiving session keys as +described below: + +``` +byte SEKeys_Info[] = /* "SessionKeys" */ +{0x53, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x4b, +0x65, 0x79, 0x73} +``` +``` +I2RKey || R2IKey || AttestationChallenge = +Crypto_KDF +``` +``` +Page 170 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### ( + +``` +inputKey = Ke, +salt = [], +info = SEKeys_Info, +len = 3 * CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +1. Each key is exactly CRYPTO_SYMMETRIC_KEY_LENGTH_BITS bits. +2. The initiator SHALL use I2RKey to encrypt and integrity protect messages and the `R2IKey' to + decrypt and verify messages. +3. The responder SHALL use R2IKey to encrypt and integrity protect messages and the `I2RKey' to + decrypt and verify messages. +4. The AttestationChallenge SHALL only be used as a challenge during device attestation. See Sec­ + tion 6.2.3, “Device Attestation Procedure” for more details. + +Upon initial installation of the new PASE Session Keys: + +1. The Node SHALL initialize its Local Message Counter in the Session Context per Section 4.6.1.1, + “Message Counter Initialization”. +2. The Node SHALL initialize the Message Reception State in the Session Context` and set the syn­ + chronized max_message_counter of the peer to 0. + +where || indicates message concatenation and [] a zero-length array. + +**4.14.2. Certificate Authenticated Session Establishment (CASE)** + +This section describes a certificate-authenticated session establishment (CASE) protocol using Node +Operational credentials. This session establishment mechanism provides an authenticated key +exchange between exactly two peers while maintaining privacy of each peer. A resumption mecha­ +nism allows bootstrapping a new session from a previous one, dramatically reducing the computa­ +tion required as well as reducing the number of messages exchanged. + +**4.14.2.1. Protocol Overview** + +This session establishment protocol provides a means to: + +1. Mutually authenticate both peer Nodes +2. Generate cryptographic keys to secure subsequent communication within a session +3. Exchange operational parameters for the session, such as Session Identifier and MRP parame­ + ters + +The cryptographic protocol mirrors the [SIGMA] protocol and uses the Identity Protection Key (IPK) +to provide better identity protection. Briefly, the protocol will: + +1. Exchange ephemeral elliptic curve public keys (Sigma1.initiatorEphPubKey and Sigma2.respon­ + derEphPubKey) to generate a shared secret + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 171 +``` + +2. Exchange certificates to prove identities (Sigma2.encrypted2.responderNOC and Sigma3.encrypt­ + ed3.initiatorNOC) +3. Prove possession of the NOC private key by signing the ephemeral keys and NOC (sigma-2-tbs­ + data and sigma-3-tbsdata) + +The basic protocol can be achieved within 2 round trips as shown below: + +_Figure 15. Basic Session Establishment_ + +**4.14.2.2. Session Resumption** + +The protocol also provides a means to quickly resume a session using a previously established ses­ +sion. Resumption does **not** require expensive signature creation and verification which signifi­ +cantly reduces the computation time. Because of this, resumption is favoured for low-powered +devices when applicable. Session resumption SHOULD be used by initiators when the necessary +state is known to the initiator. + +The nomenclature Sigma1 with Resumption in the following subsections implies a Sigma1 message +with both the optional resumptionID and initiatorResumeMIC fields populated in sigma-1-struct. + +_Figure 16. Session Resumption_ + +In the case where a Responder is not able to resume a session as requested by a Sigma1 with Resump­ +tion, the information included in the Sigma1 with Resumption message SHALL be processed as a Sig­ +ma1 message without any resumption fields to construct a Sigma2 message and continue the stan­ +dard session establishment protocol without resumption. + +To make the resumption succeed, both the Initiator and the Responder SHALL have remembered +the SharedSecret they have computed during the previous execution of the CASE session establish­ +ment. It SHALL be that SharedSecret that is used to compute the resumption ID. + +``` +Page 172 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Session Resumption State** + +To perform session resumption, the following state from the previous session context must be +known to the initiator and responder: + +1. SharedSecret +2. Local Fabric Index +3. Peer Node ID +4. Peer CASE Authenticated Tags +5. ResumptionID + +**4.14.2.3. Protocol Details** + +**Message format** + +All CASE messages SHALL be structured as specified in Section 4.4, “Message Frame Format”. + +All CASE messages are sent using an Unsecured Session: + +- The Session ID field SHALL be set to 0. +- The Session Type bits of the Security Flags SHALL be set to 0. +- In the CASE messages from the initiator, S Flag SHALL be set to 1 and DSIZ SHALL be set to 0. +- In the CASE messages from the responder, S Flag SHALL be set to 0 and DSIZ SHALL be set to 1. + +For each CASE message, the application payload is the TLV encoding of the message structure as +defined below: + +_Table 25. CASE Messages_ + +``` +Message Name Payload TLV Encoding +Sigma1 sigma-1-struct +Sigma2 sigma-2-struct, +Sigma3 sigma-3-struct, +Sigma2_Resume sigma-2-resume-struct, +SigmaFinished N/A (encoded via StatusReport) +``` +The other fields of the Message format are not specific to the CASE messages. + +**Message Exchange** + +The Sigma1, Sigma2, Sigma3, and SigmaFinished of a distinct session establishment are part of the same +message exchange. The Sigma1 with resumption, Sigma2_Resume and SigmaFinished of a distinct ses­ +sion resumption are part of the same message exchange. The Sigma1 with resumption, Sigma2, Sigma3 +and SigmaFinished of a distinct session resumption that failed to perform the resumption are part of +the same message exchange. + +Each message SHALL use PROTOCOL_ID_SECURE_CHANNEL as Protocol ID and the corresponding Protocol + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 173 +``` + +Opcode as defined in Table 18, “Secure Channel Protocol Opcodes”. + +The Exchange Flags of the Protocol Header are defined as follows per CASE message: + +``` +Message I Flag +CASE Sigma1 1 +CASE Sigma2 0 +CASE Sigma3 1 +CASE Sigma2_Resume 0 +``` +For the SigmaFinished message the value of the I Flag is set depending on whether the status mes­ +sage is sent by the Initiator or the Responder. + +All CASE messages SHALL be sent reliably. This may be implicit (e.g. TCP) or explicit (e.g. MRP reli­ +able messaging) in the underlying transport. + +The other fields of the Exchange format are not specific to the CASE messages. + +**Generate and Send Sigma1** + +The initiator encodes and sends a Sigma1 message, with a payload that follows this TLV schema: + +``` +sigma-1-struct => STRUCTURE [ tag-order ] +{ +initiatorRandom [1] : OCTET STRING [ length 32 ], +initiatorSessionId [2] : UNSIGNED INTEGER [ range 16-bits ], +destinationId [3] : destination-identifier, +initiatorEphPubKey [4] : ec-pub-key, +initiatorSessionParams [5, optional] : session-parameter-struct, +resumptionID [6, optional] : OCTET STRING [ length 16 ], +initiatorResumeMIC [7, optional] : OCTET STRING [ length +CRYPTO_AEAD_MIC_LENGTH_BYTES ] +} +``` +1. The initiator SHALL generate a random number InitiatorRandom = Crypto_DRBG(len = 32 * 8). +2. The initiator SHALL generate a session identifier (InitiatorSessionId) for subsequent identifica­ + tion of this session. The InitiatorSessionId field SHALL NOT overlap with any other existing + PASE or CASE session identifier in use by the initiator. See Section 4.13.2.4, “Choosing Secure + Unicast Session Identifiers” for more details. +3. The initiator SHALL generate a destination identifier (DestinationId) according to Destination + Identifier to enable the responder to properly select a mutual Fabric and trusted root for the + secure session. +4. The initiator SHALL generate an ephemeral key pair InitiatorEphKeyPair = Crypto_GenerateKey­ + pair(). + +``` +Page 174 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +5. The initiator MAY encode any relevant MRP parameters. +6. Any context-specific tags not listed in the above TLV schemas SHALL be reserved for future use, + and SHALL be silently ignored if seen by a responder which cannot understand them. +7. If the initiator is resuming a session from a previous execution of the CASE with the same peer, + the initiator SHALL: + a. Note the ResumptionID of the previous session. + b. Generate the S1RK key. + c. Generate the initiatorResumeMIC using the SharedSecret from the previous session: + +``` +byte Resume1MIC_P[] = {} +byte Resume1MIC_A[] = {} +byte Resume1MIC_Nonce[13] = /* "NCASE_SigmaS1" */ +{0x4e, 0x43, 0x41, 0x53, 0x45, 0x5f, 0x53, 0x69, +0x67, 0x6d, 0x61, 0x53, 0x31} +``` +``` +InitiatorResume1MIC = Crypto_AEAD_GenerateEncrypt( +K = S1RK, +P = Resume1MIC_P, +A = Resume1MIC_A, +N = Resume1MIC_Nonce +) +``` +8. The initiator SHALL send a message with Secure Channel Protocol ID and Sigma1 Protocol Opcode + from Table 18, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded Sigma1 + Msg1 with an anonymous tag for the outermost struct. + +``` +Msg1 = +{ +initiatorRandom (1) = InitiatorRandom, +initiatorSessionId (2) = InitiatorSessionId, +destinationId (3) = DestinationId, +initiatorEphPubKey (4) = InitiatorEphKeyPair.publicKey +initiatorSessionParams (5) = session-parameter-struct (optional), +resumptionID (6) = ResumptionID (optional, only present if performing +resumption), +initiatorResumeMIC (7) = InitiatorResume1MIC (optional, only present if +performing resumption) +} +``` +**Validate Sigma1** + +On receipt of Msg1, the responder SHALL perform the following: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 175 +``` + +1. If Msg1 contains either a resumptionID **or** an initiatorResumeMIC field **but not both** , the responder + SHALL send a status report: StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, + ProtocolCode: INVALID_PARAMETER) and perform no further processing. +2. Set the Peer Session Identifier in the Session Context to the value Msg1.initiatorSessionId. +3. If Msg1 contains both the resumptionID **and** initiatorResumeMIC fields, the responder SHALL + search for an existing session that has a Resumption ID equal to the incoming resumptionID. If a + single such session exists, the responder SHALL follow the steps in Section 4.14.2.3.10, “Validate + Sigma1 with Resumption” rather than continue the steps outlined in Section 4.14.2.3.5, “Validate + Sigma1 Destination ID”. +4. If Msg1 does not contain a resumptionID and initiatorResumeMIC field, the responder SHALL con­ + tinue the steps in Section 4.14.2.3.5, “Validate Sigma1 Destination ID”. + +**Validate Sigma1 Destination ID** + +1. The responder SHALL validate the incoming destinationId: + a.The responder SHALL traverse all its installed Node Operational Certificates (NOC), gather­ + ing the associated trusted roots' public keys from the associated chains and SHALL generate + a candidateDestinationId based on the procedure in Section 4.14.2.4.1, “Destination Identi­ + fier” for that tuple of . +b. The responder SHALL verify that the incoming destinationId matches one of the candidat­ +eDestinationId generated above. Upon such a match, the associated trusted root, Fabric ID, +Node ID and IPK SHALL be recorded for subsequent use. +c.Note that at the initiator, only the current Epoch Key for the IPK will have been used. At the +receiver, several IPK Epoch Keys may be installed, requiring several candidateDestinationId +to be computed, one per available IPK Operational Key, per NOC. +2. If there is no candidateDestinationId matching the incoming destinationId, the responder + SHALL send a status report: StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, + ProtocolCode: NO_SHARED_TRUST_ROOTS) and perform no further processing. +3. Otherwise, if a match was found for the destinationId, the matched NOC, ICAC (if present), and + associated trusted root SHALL be used for selection of the responderNOC and responderICAC in the + steps for Sigma2. + +**Generate and Send Sigma2** + +If validation is successful, the responder encodes and sends a Sigma2 message. + +``` +sigma-2-tbsdata => STRUCTURE [ tag-order ] +{ +responderNOC [1] : OCTET STRING, +responderICAC [2, optional] : OCTET STRING, +responderEphPubKey [3] : ec-pub-key, +initiatorEphPubKey [4] : ec-pub-key, +} +``` +``` +Page 176 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +sigma-2-tbedata => STRUCTURE [ tag-order ] +{ +responderNOC [1] : OCTET STRING, +responderICAC [2, optional] : OCTET STRING, +signature [3] : ec-signature, +resumptionID [4] : OCTET STRING [ length 16 ], +} +``` +``` +sigma-2-struct => STRUCTURE [ tag-order ] +{ +responderRandom [1] : OCTET STRING [ length 32 ], +responderSessionId [2] : UNSIGNED INTEGER [ range 16-bits ], +responderEphPubKey [3] : ec-pub-key, +encrypted2 [4] : OCTET STRING, +responderSessionParams [5, optional] : session-parameter-struct +} +``` +``` +NOTE sigma-2-tbsdata is NOT transmitted but is instead signed; the signature will be +encrypted and transmitted. +``` +1. The responder SHALL generate a random resumption ID ResumptionID = Crypto_DRBG(len = 16 * + 8). + a. The responder SHALL set the Resumption ID in the Session Context to the value ResumptionID. +2. The responder SHALL use the Node Operational Key Pair ResponderNOKeyPair, responderNOC, and + responderICAC (if present) corresponding to the NOC obtained in Section 4.14.2.3.4, “Validate Sig­ + ma1”. +3. The responder SHALL generate an ephemeral key pair ResponderEphKeyPair = Crypto_Gener­ + ateKeypair(). +4. The responder SHALL generate a shared secret: + +``` +SharedSecret = Crypto_ECDH( +privateKey = ResponderEphKeyPair.privateKey, +publicKey = Msg1.initiatorEphPubKey, +) +``` +5. The responder SHALL encode the following items as a sigma-2-tbsdata with an anonymous tag: + +``` +a. responderNOC as a matter-certificate +b. responderICAC (if present) as a matter-certificate +c. ResponderEphKeyPair.publicKey +d. Msg1.initiatorEphPubKey +``` +6. The responder SHALL generate a signature: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 177 +``` + +``` +TBSData2Signature = Crypto_Sign( +message = sigma-2-tbsdata, +privateKey = ResponderNOKeyPair.privateKey +) +``` +7. The responder SHALL encode the following items as a sigma-2-tbedata, where the encoding of + responderNOC and responderICAC items SHALL be byte-for-byte identical to the encoding in sigma- + 2-tbsdata: + a.responderNOC as a matter-certificate. This encoding SHALL be byte-for-byte identical to the + encoding in sigma-2-tbsdata. +b. responderICAC (if present) as a matter-certificate. This encoding SHALL be byte-for-byte iden­ +tical to the encoding in sigma-2-tbsdata. +c.TBSData2Signature +d. ResumptionID +8. The responder SHALL generate a random number Random = Crypto_DRBG(len = 32 * 8). +9. The responder SHALL generate the S2K key using Random as Responder Random and Respon­ + derEphKeyPair.publicKey as Responder Ephemeral Public Key. + +10.The responder SHALL generate the encrypted and integrity protected data: + +``` +byte TBEData2_A[] = {} +byte TBEData2_Nonce[13] = /* "NCASE_Sigma2N" */ +{0x4e, 0x43, 0x41, 0x53, 0x45, 0x5f, 0x53, 0x69, +0x67, 0x6d, 0x61, 0x32, 0x4e} +``` +``` +TBEData2Encrypted = Crypto_AEAD_GenerateEncrypt( +K = S2K, +P = TBEData2, +A = TBEData2_A, +N = TBEData2_Nonce +) +``` +11.The responder SHALL generate a session identifier (ResponderSessionId) for subsequent identifi­ +cation of this secured session. The ResponderSessionId field SHALL NOT overlap with any other +existing PASE or CASE session identifier in use by the responder. See Section 4.13.2.4, “Choosing +Secure Unicast Session Identifiers” for more details. The responder SHALL set the Local Session +Identifier in the Session Context to the value ResponderSessionId. + +12.The responder SHALL use the Fabric IPK configured as described in Section 4.14.2.6.1, “Identity +Protection Key (IPK)”. + +13.Any context-specific tags not listed in the above TLV schemas SHALL be reserved for future use, +and SHALL be silently ignored if seen by an initiator which cannot understand them. + +14.The responder SHALL send a message with Secure Channel Protocol ID and Sigma2 Protocol + +``` +Page 178 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Opcode from Table 18, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded +Sigma2 Msg2 with an anonymous tag for the outermost struct. +``` +``` +Msg2 = +{ +responderRandom (1) = Random, +responderSessionId (2) = ResponderSessionId, +responderEphPubKey (3) = ResponderEphKeyPair.publicKey, +encrypted2 (4) = TBEData2Encrypted, +responderSessionParams (5) = session-parameter-struct (optional) +} +``` +**Validate Sigma2** + +On receipt of Msg2, the initiator SHALL perform the following: + +1. The initiator SHALL generate a shared secret: + +``` +SharedSecret = Crypto_ECDH( +privateKey = InitiatorEphKeyPair.privateKey, +publicKey = Msg2.responderEphPubKey, +) +``` +2. The initiator SHALL generate the S2K key using Msg2.responderRandom as Responder Random and + Msg2.responderEphPubKey as Responder Ephemeral Public Key. +3. The initiator SHALL generate the decrypted data: + +``` +byte TBEData2_A[] = {} +byte TBEData2_Nonce[13] = /* "NCASE_Sigma2N" */ +{0x4e, 0x43, 0x41, 0x53, 0x45, 0x5f, 0x53, 0x69, +0x67, 0x6d, 0x61, 0x32, 0x4e} +``` +``` +Success, TBEData2 = Crypto_AEAD_DecryptVerify( +K = S2K, +C = Msg2.encrypted2, +A = TBEData2_A, +N = TBEData2_Nonce +) +``` +4. If the value of Success is FALSE, the initiator SHALL send a status report: StatusReport(General­ + Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no + further processing. +5. The initiator SHALL verify that the NOC in TBEData2.responderNOC and ICAC in TBEData2.respon­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 179 +``` + +``` +derICAC (if present) fulfills the following constraints: +a.The Fabric ID and Node ID SHALL match the intended identity of the receiver Node, as +included in the computation of the Destination Identifier when generating Sigma1. +b. If an ICAC is present, and it contains a Fabric ID in its subject, then it SHALL match the Fab­ +ricID in the NOC leaf certificate. +c.The certificate chain SHALL chain back to the Trusted Root CA Certificate TrustedRCAC whose +public key was used in the computation of the Destination Identifier when generating Sig­ +ma1. +d. All the elements in the certificate chain SHALL respect the Matter Certificate DN Encoding +Rules, including range checks for identifiers such as Fabric ID and Node ID. +``` +6. If any of the validations from the previous step fail, the initiator SHALL send a status report: + StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARA­ + METER) and perform no further processing. +7. The initiator SHALL verify TBEData2.responderNOC using: + a.Success = Crypto_VerifyChain(certificates = [TBEData2.responderNOC, TBEData2.responderI­ + CAC, TrustedRCAC]), when TBEData2.responderICAC is present, or +b. Success = Crypto_VerifyChain(certificates = [TBEData2.responderNOC, TrustedRCAC]), when +TBEData2.responderICAC is not present. +8. If the value of Success is FALSE, the initiator SHALL send a status report: StatusReport(General­ + Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no + further processing. +9. The initiator SHALL encode the following items as a sigma-2-tbsdata with an anonymous tag: + a.responderNOC as copied from TBEData2 +b. responderICAC (if present) as copied from TBEData2 +c.Msg2.responderEphPubKey +d. InitiatorEphKeyPair.publicKey + +10.The initiator SHALL verify TBEData2.signature (see RFC 5280): + +``` +Success = Crypto_Verify( +publicKey = Public key obtained from responderNOC, +message = sigma-2-tbsdata, +signature = TBEData2.signature +) +``` +11.If the value of Success is FALSE, the initiator SHALL send a status report: StatusReport(General­ +Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no +further processing. + +12.Set the Resumption ID in the Session Context to the value TBEData2.resumptionID. + +13.Set the Peer Session Identifier in the Session Context to the value Msg2.responderSessionId. + +``` +Page 180 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Generate and Send Sigma3** + +If validation is successful, the initiator encodes and sends a Sigma3 message. + +``` +sigma-3-tbsdata => STRUCTURE [ tag-order ] +{ +initiatorNOC [1] : OCTET STRING, +initiatorICAC [2, optional] : OCTET STRING, +initiatorEphPubKey [3] : ec-pub-key, +responderEphPubKey [4] : ec-pub-key, +} +``` +``` +sigma-3-tbedata => STRUCTURE [ tag-order ] +{ +initiatorNOC [1] : OCTET STRING, +initiatorICAC [2, optional] : OCTET STRING, +signature [3] : ec-signature, +} +``` +``` +sigma-3-struct => STRUCTURE [ tag-order ] +{ +encrypted3 [1] : OCTET STRING, +} +``` +``` +NOTE sigma-3-tbsdata is NOT transmitted but is instead signed; the signature will be +encrypted and transmitted. +``` +1. The initiator SHALL select its Node Operational Key Pair InitiatorNOKeyPair, Node Operational + Certificates initiatorNOC and initiatorICAC (if present), and Trusted Root CA Certificate Truste­ + dRCAC corresponding to the chosen Fabric as determined by the Destination Identifier from Sig­ + ma1. +2. The initiator SHALL encode the following items as a sigma-3-tbsdata with an anonymous tag: + a. initiatorNOC as a matter-certificate + b. initiatorICAC (if present) as a matter-certificate + c. InitiatorEphKeyPair.publicKey + d. Msg2.responderEphPubKey +3. The initiator SHALL generate a signature: + +``` +TBSData3Signature = Crypto_Sign( +message = sigma-3-tbsdata, +privateKey = InitiatorNOKeyPair.privateKey +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 181 +``` + +### ) + +4. The initiator SHALL encode the following items as a sigma-3-tbedata: + a.initiatorNOC as a matter-certificate. This encoding SHALL be byte-for-byte identical to the + encoding in sigma-3-tbsdata. +b. initiatorICAC (if present) as a matter-certificate. This encoding SHALL be byte-for-byte iden­ +tical to the encoding in sigma-3-tbsdata. +c.TBSData3Signature +5. The initiator SHALL generate the S3K key. +6. The initiator SHALL generate the encrypted and integrity protected data: + +``` +byte TBEData3_A[] = {} +byte TBEData3_Nonce[13] = /* "NCASE_Sigma3N" */ +{0x4e, 0x43, 0x41, 0x53, 0x45, 0x5f, 0x53, 0x69, +0x67, 0x6d, 0x61, 0x33, 0x4e} +``` +``` +TBEData3Encrypted = Crypto_AEAD_GenerateEncrypt( +K = S3K, +P = TBEData3, +A = TBEData3_A, +N = TBEData3_Nonce +) +``` +7. Any context-specific tags not listed in the above TLV schemas SHALL be reserved for future use, + and SHALL be silently ignored if seen by a responder which cannot understand them. +8. The initiator SHALL send a message with Secure Channel Protocol ID and Sigma3 Protocol Opcode + from Table 18, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded Sigma3 + Msg3 = { encrypted3 (1) = TBEData3Encrypted } with an anonymous tag for the outermost + struct. +9. The initiator SHALL generate the session encryption keys using the method described in Section + 4.14.2.6.6, “Session Encryption Keys”. + +**Validate Sigma3** + +On receipt of Msg3, the responder SHALL perform the following: + +1. The responder SHALL generate the S3K key. +2. The responder SHALL generate the decrypted data: + +``` +byte TBEData3_A[] = {} +byte TBEData3_Nonce[13] = /* "NCASE_Sigma3N" */ +{0x4e, 0x43, 0x41, 0x53, 0x45, 0x5f, 0x53, 0x69, +``` +``` +Page 182 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +0x67, 0x6d, 0x61, 0x33, 0x4e} +``` +``` +Success, TBEData3 = Crypto_AEAD_DecryptVerify( +K = S3K, +C = Msg3.encrypted3, +A = TBEData3_A, +N = TBEData3_Nonce +) +``` +3. If the value of Success is FALSE, the responder SHALL send a status report: StatusReport(Gener­ + alCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform + no further processing. +4. The responder SHALL verify that the NOC in TBEData3.initiatorNOC and the ICAC in TBE­ + Data3.initiatorICAC fulfill the following constraints: + a. The Fabric ID SHALL match the Fabric ID matched during processing of the Destination + Identifier after receiving Sigma1. + b. If an ICAC is present, and it contains a Fabric ID in its subject, then it SHALL match the Fab­ + ricID in the NOC leaf certificate. +c. The certificate chain SHALL chain back to the Trusted Root CA Certificate TrustedRCAC whose +public key was matched during processing of the Destination Identifier after receiving Sig­ +ma1. + d. All the elements in the certificate chain SHALL respect the Matter Certificate DN Encoding + Rules, including range checks for identifiers such as Fabric ID and Node ID. +5. If any of the validations from the previous step fail, the responder SHALL send a status report: + StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARA­ + METER) and perform no further processing. +6. The responder SHALL verify TBEData3.initiatorNOC using: + +``` +a. Success = Crypto_VerifyChain(certificates = [TBEData3.initiatorNOC, TBEData3.initiatorI­ +CAC, TrustedRCAC]), when TBEData3.initiatorICAC is present, or +b. Success = Crypto_VerifyChain(certificates = [TBEData3.initiatorNOC, TrustedRCAC]), when +TBEData3.initiatorICAC is not present. +``` +7. If the value of Success is FALSE, the responder SHALL send a status report: StatusReport(General­ + Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER_) and perform + no further processing. +8. The responder SHALL encode the following items as a sigma-3-tbsdata with an anonymous tag: + +``` +a. initiatorNOC as copied from TBEData3 +b. initiatorICAC (if present) as copied from TBEData3 +c. Msg1.initiatorEphPubKey +d. ResponderEphKeyPair.publicKey +``` +9. The responder SHALL verify TBEData3.signature (see RFC 5280): + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 183 +``` + +``` +Success = Crypto_Verify( +publicKey= public key obtained from initiatorNOC, +message = sigma-3-tbsdata, +signature = TBEData3.signature +) +``` +10.If the value of Success is FALSE, the responder SHALL send a status report: StatusReport(General­ +Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no +further processing. + +11.The responder SHALL generate the session keys as described in Section 4.14.2.6.6, “Session +Encryption Keys”. + +12.The responder SHALL initialize its Local Message Counter in the Session Context per Section +4.6.1.1, “Message Counter Initialization”. + +13.The responder SHALL initialize the Message Reception State in the Session Context` and set the +synchronized max_message_counter of the peer to 0. + +14.The responder SHALL set SessionTimestamp to a timestamp from a clock which would allow for +the eventual determination of the last session use relative to other sessions. + +15.The responder SHALL encode and send SigmaFinished. + +**Validate Sigma1 with Resumption** + +The responder SHALL continue validating the Sigma1 message Msg1 as follows: + +1. Obtain the SharedSecret from the Section 4.13.3.1, “Secure Session Context” of the resumed ses­ + sion. +2. Generate the S1RK key. +3. Verify the Resume1MIC by decrypting the following values: + +``` +byte Resume1MIC_A[] = {} +byte Resume1MIC_Nonce[13] = /* "NCASE_SigmaR1" */ +{0x4e, 0x43, 0x41, 0x53, 0x45, 0x5f, 0x53, 0x69, +0x67, 0x6d, 0x61, 0x53, 0x31} +``` +``` +Success, Resume1MICPayload = Crypto_AEAD_DecryptVerify( +K = S1RK, +C = Msg1.sigma1ResumeMIC, +A = Resume1MIC_A, +N = Resume1MIC_Nonce +) +``` +4. If the value of Success is FALSE, the responder SHALL continue processing Sigma1 as if it didn’t + include any resumption information by continuing the steps in Section 4.14.2.3.5, “Validate Sig­ + +``` +Page 184 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ma1 Destination ID”. +``` +5. If the value of Success is TRUE, the responder SHALL: + a. Set the Peer Session Identifier in the in the Session Context to the value Msg1.initiatorSes­ + sionId. + b. Send a Sigma2_Resume message. + +**Generate and Send Sigma2_Resume** + +The responder SHALL encode and send a Sigma2_Resume message in response to a valid Sigma1 with +response. + +``` +sigma-2-resume-struct => STRUCTURE [ tag-order ] +{ +resumptionID [1] : OCTET STRING [ length 16 ], +sigma2ResumeMIC [2] : OCTET STRING [ length 16 ], +responderSessionID [3] : UNSIGNED INTEGER [ range 16-bits ], +responderSessionParams [4, optional] : session-parameter-struct +} +``` +1. The responder SHALL generate a new resumption ID ResumptionID = Crypto_DRBG(len = 128). +2. The responder SHALL generate a session identifier (ResponderSessionId) for subsequent identifi­ + cation of this session. The ResponderSessionId field SHALL NOT overlap with any other existing + PASE or CASE session identifier in use by the responder. See Section 4.13.2.4, “Choosing Secure + Unicast Session Identifiers” for more details. The responder SHALL set the Local Session Iden­ + tifier in the Session Context to the value ResponderSessionId. +3. The responder SHALL generate the S2RK key. +4. The responder SHALL generate a resumption MIC: + +``` +byte Resume2MIC_P[] = {} +byte Resume2MIC_A[] = {} +byte Resume2MIC_Nonce[13] = /* "NCASE_SigmaS2" */ +{0x4e, 0x43, 0x41, 0x53, 0x45, 0x5f, 0x53, 0x69, +0x67, 0x6d, 0x61, 0x53, 0x32} +``` +``` +Resume2MIC = Crypto_AEAD_GenerateEncrypt( +K = S2RK, +P = Resume2MIC_P, +A = Resume2MIC_A, +N = Resume2MIC_Nonce +) +``` +5. Any context-specific tags not listed in the above TLV schemas SHALL be reserved for future use, + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 185 +``` + +``` +and SHALL be silently ignored if seen by an initiator which cannot understand them. +``` +6. The responder SHALL send a message with the Secure Channel Protocol ID and Sigma2Resume Pro­ + tocol Opcode from Table 18, “Secure Channel Protocol Opcodes” whose payload is the TLV- + encoded Sigma2_Resume ResumeMsg2 with an anonymous tag for the outermost struct. + +``` +ResumeMsg2 = +{ +resumptionID (1) = ResumptionID, +sigma2ResumeMIC (2) = ResumeMIC2, +responderSessionID (3) = ResponderSessionId, +responderSessionParams (4) = session-parameter-struct (optional) +} +``` +7. The responder SHALL generate the session keys as described in Section 4.14.2.6.7, “Resumption + Session Encryption Keys”. + +**Validate Sigma2_Resume** + +On receipt of ResumeMsg2, the initiator SHALL perform the following: + +1. The initiator SHALL generate the S2RK key. +2. The initiator SHALL verify the Resume2MIC by decrypting the following values: + +``` +byte Resume2MIC_A[] = {} +byte Resume2MIC_Nonce[13] = /* "NCASE_SigmaR2" */ +{0x4e, 0x43, 0x41, 0x53, 0x45, 0x5f, 0x53, 0x69, +0x67, 0x6d, 0x61, 0x53, 0x32} +``` +``` +Success, Resume2MICPayload = Crypto_AEAD_DecryptVerify( +K = S2RK, +C = ResumeMsg2.sigma2ResumeMIC, +A = Resume2MIC_A, +N = Resume2MIC_Nonce +) +``` +3. If Success is FALSE, the initiator SHALL send a status report: StatusReport(GeneralCode: FAILURE, + ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER_) and perform no further pro­ + cessing. +4. The initiator SHALL set the Resumption ID in the Session Context to the value Resume2Msg.resump­ + tionID. +5. The initiator SHALL generate the session keys as described in Section 4.14.2.6.7, “Resumption + Session Encryption Keys”. +6. The initiator SHALL reset its Local Message Counter in the Session Context per Section 4.6.1.1, + +``` +Page 186 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +“Message Counter Initialization”. +``` +7. The initiator SHALL reset the Message Reception State of the Session Context` and set the syn­ + chronized max_message_counter of the peer to 0. +8. The initiator SHALL set SessionTimestamp to a timestamp from a clock which would allow for the + eventual determination of the last session use relative to other sessions. +9. The initiator SHALL set the Peer Session Identifier in the in the Session Context to the value + ResumeMsg2.responderSessionId. +10. The initiator SHALL send Section 4.14.2.3.13, “SigmaFinished”. + +``` +SigmaFinished +``` +``` +To indicate the successful completion of the protocol, the Node receiving Sigma3 (if a new session is +being established) or Sigma2_Resume (if a session is being resumed) SHALL send a status report: +StatusReport(GeneralCode: SUCCESS, ProtocolId: SECURE_CHANNEL, ProtocolCode: SESSION_ESTABLISH­ +MENT_SUCCESS). +``` +``` +On successful receipt of SigmaFinished: +``` +1. The receiving node SHALL initialize the Local Message Counter according to Section 4.6.1.1, + “Message Counter Initialization” for the newly established secure session whose success is + acknowledged by this message. +2. The receiving node SHALL set SessionTimestamp to a timestamp from a clock which would allow + for the eventual determination of the last session usage relative to other sessions. + +``` +If this message is received out-of-order or unexpectedly, then it SHALL be ignored. +``` +``` +4.14.2.4. Field Descriptions +``` +``` +Destination Identifier +``` +``` +destination-identifier => OCTET STRING [length CRYPTO_HASH_LEN_BYTES] +``` +``` +The Destination Identifier field enables the initiator of the Sigma1 message to unambiguously +express the following, in a privacy-preserving manner: +``` +- Which shared Trusted Root to select +- Which Fabric ID to use for validation of initiator and responder operational certificates +- Which Node ID is targeted in the given Fabric + +``` +This serves several purposes: +``` +1. It requires an initiator to have knowledge of both the IPK and one of the full identities of the + responder Node before it forces the responder node to generate a costly Sigma2 message + a. Note that the replay of previously recorded initiator messages is possible, and therefore a + Node MAY choose to keep memory of some prior destination identifiers that were success­ + fully processed which it would later reject if seen again, for additional replay protection + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 187 +``` + +2. It ensures that there is no ambiguity on the responder as to which Fabric was selected for com­ + munication +3. It hides which Fabric was chosen by the initiator + +A destination identifier is generated by: + +1. Concatenating the following octet strings for subsequent usage as a destinationMessage: + ◦ initiatorRandom: The value of initiatorRandom that will be used in the same message as the + Destination Identifier + ◦ rootPublicKey: The public key of the root of trust of the desired fabric, from the ec-pub-key + field of the Matter Certificate of that root, as an uncompressed elliptic curve point as defined + in section 2.3.3 of SEC 1 + ◦ fabricId: The Fabric ID of the destination, matching the matter-fabric-id field of the Matter + Certificate of the desired destination’s NOC, and encoding the 64-bit scalar as a little-endian + byte order octet string + ◦ nodeId: The Node ID of the destination, matching the matter-node-id field of the Matter Cer­ + tificate of the desired destination’s NOC, and encoding the 64-bit scalar as a little-endian byte + order octet string +2. Obtaining the appropriate Identity Protection Key (IPK) Operational Group Key for the associ­ + ated Fabric under Group Key Set index 0 within the Group Key Management Cluster. +3. Computing an identifier destinationIdentifier of length CRYPTO_HASH_LEN_BYTES using Crypto_H­ + MAC() with the IPK as the key and destinationMessage as the message + +The above steps can be summarized as: + +``` +destinationMessage = initiatorRandom || rootPublicKey || fabricId || nodeId +destinationIdentifier = Crypto_HMAC(key=IPK, message=destinationMessage) +``` +For example, given the following: + +- Root public key for the common Fabric, in uncompressed elliptical curve point form: + +``` +RootPublicKey := // Raw uncompressed point form +04:4a:9f:42:b1:ca:48:40:d3:72:92:bb:c7:f6:a7:e1: +1e:22:20:0c:97:6f:c9:00:db:c9:8a:7a:38:3a:64:1c: +b8:25:4a:2e:56:d4:e2:95:a8:47:94:3b:4e:38:97:c4: +a7:73:e9:30:27:7b:4d:9f:be:de:8a:05:26:86:bf:ac: +fa +``` +- Common Fabric ID of 0x2906_C908_D115_D362 scalar (octets "62:d3:15:d1:08:c9:06:29" in little- + endian) +- Desired Destination Node ID of 0xCD55_44AA_7B13_EF14 (octets "14:ef:13:7b:aa:44:55:cd" in lit­ + tle-endian) + +``` +Page 188 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Identity Protection Key Epoch Key value of: + +``` +IPKEpochKey := 4a:71:cd:d7:b2:a3:ca:90:24:f9:6f:3c:96:a1:9d:ee +``` +``` +◦ Note that this is the octet string of a group Epoch Key as would be provided in the IPKValue +field of the AddNOC command in the Node Operational Credentials Cluster, or in one of the +EpochKey fields of the KeySetWrite command in the Group Key Management Cluster. +◦ The derived Operational Group Key to be used for computation of a destination identifier, +given the above values of root public key, Fabric ID and Identity Protection Key Epoch Key, +would be: +``` +``` +IPK := 9b:c6:1c:d9:c6:2a:2d:f6:d6:4d:fc:aa:9d:c4:72:d4 +``` +- Initiator Random value of: + +``` +7e:17:12:31:56:8d:fa:17:20:6b:3a:cc:f8:fa:ec:2f: +4d:21:b5:80:11:31:96:f4:7c:7c:4d:eb:81:0a:73:dc +``` +Then, using the above procedure would yield the following: + +- DestinationMessage octets: + +``` +7e:17:12:31:56:8d:fa:17:20:6b:3a:cc:f8:fa:ec:2f: +4d:21:b5:80:11:31:96:f4:7c:7c:4d:eb:81:0a:73:dc: +04:4a:9f:42:b1:ca:48:40:d3:72:92:bb:c7:f6:a7:e1: +1e:22:20:0c:97:6f:c9:00:db:c9:8a:7a:38:3a:64:1c: +b8:25:4a:2e:56:d4:e2:95:a8:47:94:3b:4e:38:97:c4: +a7:73:e9:30:27:7b:4d:9f:be:de:8a:05:26:86:bf:ac: +fa:62:d3:15:d1:08:c9:06:29:14:ef:13:7b:aa:44:55: +cd +``` +- DestinationIdentifier octets: + +``` +dc:35:dd:5f:c9:13:4c:c5:54:45:38:c9:c3:fc:42:97: +c1:ec:33:70:c8:39:13:6a:80:e1:07:96:45:1d:4c:53 +``` +**Public Key** + +``` +ec-pub-key => OCTET STRING [ length CRYPTO_PUBLIC_KEY_SIZE_BYTES ] +``` +A public key ec-pub-key is the byte string representation of an uncompressed elliptic curve point as +defined in section 2.3.3 of SEC 1. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 189 +``` + +**4.14.2.5. Signature** + +An ec-signature is the encoding of the signature as defined in Section 3.5.3, “Signature and verifica­ +tion”. + +``` +ec-signature => OCTET STRING [ length (CRYPTO_GROUP_SIZE_BYTES * 2) ] +``` +**4.14.2.6. Cryptographic Keys** + +**Identity Protection Key (IPK)** + +The Identity Protection Key (IPK) SHALL be the operational group key under GroupKeySetID of 0 +for the fabric associated with the originator’s chosen destination. + +The IPK SHALL be exclusively used for Certificate Authenticated Session Establishment. The IPK +SHALL NOT be used for operational group communication. + +For the generation of the Destination Identifier, the originator SHALL use the operational group key +with the second newest EpochStartTime, if one exists, otherwise it SHALL use the single operational +group key available. + +The operational group key index to use to follow the "second newest EpochStartTime" rule is illus­ +trated below: + +``` +Number of keys in Group Key +Set +``` +``` +Operational key index Epoch Key +``` +``` +1 0 EpochKey0 +2 0 EpochKey0 +3 1 EpochKey1 +``` +**Sigma2 Key (S2K)** + +1. A transcript hash SHALL be generated: + +``` +TranscriptHash = Crypto_Hash(message = Msg1) +``` +2. The Sigma2 key SHALL be generated: + +``` +byte S2K_Info[] = /* "Sigma2" */ +{0x53, 0x69, 0x67, 0x6d, 0x61, 0x32} +``` +``` +S2K = Crypto_KDF( +inputKey = SharedSecret, +salt = IPK || Responder Random || Responder Ephemeral Public Key || +TranscriptHash, +info = S2K_Info, +``` +``` +Page 190 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +len = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +where || indicates message concatenation and IPK is generated according to Section 4.14.2.6.1, +“Identity Protection Key (IPK)”. + +**Sigma3 Key (S3K)** + +1. A transcript hash SHALL be generated: + +``` +TranscriptHash = Crypto_Hash(message = Msg1 || Msg2) +``` +2. The Sigma3 key SHALL be generated: + +``` +byte S3K_Info[] = /* "Sigma3" */ +{0x53, 0x69, 0x67, 0x6d, 0x61, 0x33} +``` +``` +S3K = Crypto_KDF( +inputKey = SharedSecret, +salt = IPK || TranscriptHash, +info = S3K_Info, +len = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +where || indicates message concatenation and IPK is generated according to Section 4.14.2.6.1, +“Identity Protection Key (IPK)”. + +**Sigma1 Resumption Key** + +The Sigma1 resumption key SHALL be generated: + +``` +byte S1RK_Info[] = /* "Sigma1_Resume" */ +{0x53, 0x69, 0x67, 0x6d, 0x61, 0x31, 0x5f, +0x52, 0x65, 0x73, 0x75, 0x6d, 0x65} +``` +``` +S3K_Info +S1RK = Crypto_KDF( +inputKey = SharedSecret, +salt = Sigma1.initiatorRandom || ResumptionID, +info = S1RK_Info, +len = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +where || indicates message concatenation and ResumptionID is the identifier for the previous ses­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 191 +``` + +sion. + +**Sigma2 Resumption Key** + +The Sigma2 resumption key SHALL be generated: + +``` +byte S2RK_Info[] = /* "Sigma2_Resume" */ +{0x53, 0x69, 0x67, 0x6d, 0x61, 0x32, 0x5f, +0x52, 0x65, 0x73, 0x75, 0x6d, 0x65} +``` +``` +S2RK = Crypto_KDF( +inputKey = SharedSecret, +salt = Sigma1.initiatorRandom || ResumptionID, +info = S2RK_Info, +len = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +where || indicates message concatenation and ResumptionID is the new identifier for the this ses­ +sion. + +**Session Encryption Keys** + +1. A transcript hash SHALL be generated: + +``` +TranscriptHash = Crypto_Hash(message = Msg1 || Msg2 || Msg3) +``` +2. The session encryption keys SHALL be generated: + +``` +byte SEKeys_Info[] = /* "SessionKeys" */ +{0x53, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x4b, +0x65, 0x79, 0x73} +``` +``` +I2RKey || R2IKey || AttestationChallenge = Crypto_KDF( +inputKey = SharedSecret, +salt = IPK || TranscriptHash, +info = SEKeys_Info, +len = 3 * CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +3. Each key is exactly CRYPTO_SYMMETRIC_KEY_LENGTH_BITS bits. +4. The initiator SHALL use I2RKey to encrypt and integrity protect messages and the `R2IKey' to + decrypt and verify messages. +5. The responder SHALL use R2IKey to encrypt and integrity protect messages and the `I2RKey' to + +``` +Page 192 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +decrypt and verify messages. +``` +6. The AttestationChallenge SHALL only be used as a challenge during device attestation. See Sec­ + tion 6.2.3, “Device Attestation Procedure” for more details. + +where || indicates message concatenation. + +**Resumption Session Encryption Keys** + +1. The resumption session encryption keys SHALL be generated: + +``` +byte RSEKeys_Info[] = /* "SessionResumptionKeys" */ +{0x53, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x52, +0x65, 0x73, 0x75, 0x6d, 0x70, 0x74, 0x69, 0x6f, +0x6e, 0x4b, 0x65, 0x79, 0x73} +``` +``` +I2RKey || R2IKey || AttestationChallenge = Crypto_KDF( +inputKey = SharedSecret, +salt = Sigma1.initiatorRandom || ResumptionID, +info = RSEKeys_Info, +len = 3 * CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +2. Each key is exactly CRYPTO_SYMMETRIC_KEY_LENGTH_BITS bits. +3. The initiator SHALL use I2RKey to encrypt and integrity protect messages and the `R2IKey' to + decrypt and verify messages. +4. The responder SHALL use R2IKey to encrypt and integrity protect messages and the `I2RKey' to + decrypt and verify messages. +5. The AttestationChallenge SHALL only be used as a challenge during device attestation. See Sec­ + tion 6.2.3, “Device Attestation Procedure” for more details. + +where || indicates message concatenation and ResumptionID is the new identifier for the this ses­ +sion. + +**4.14.2.7. Session Context Storage** + +After the session is established successfully at both peers, some fields SHALL be recorded in the +secure session context for later use (see Section 4.13.3, “Application Data Phase”), in addition to the +Session Encryption Keys: + +- The peer NOC's matter-node-id (1.3.6.1.4.1.37244.1.1) from the subject field +- The Section 2.5.1, “Fabric References and Fabric Identifier” for the Fabric within which this + secure session is being established +- All peer NOC's case-authenticated-tag (1.3.6.1.4.1.37244.1.6) from the subject field, if present + +These fields MAY be recorded at any opportune point during the protocol, but SHALL only be com­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 193 +``` + +mitted to the secure session context once the session is established successfully at both peers. + +**4.14.2.8. Minimal Number of CASE Sessions** + +A node SHALL support at least 3 CASE session contexts per fabric. Device type specifications MAY +require a larger minimum. Unless the device type specification says otherwise, a minimum number +it defines is a per-fabric minimum. + +The minimal supported capabilities, subject to the minimal constraints above, are reported in the +CapabilityMinima of the Basic Information cluster. + +- Example: If a device type requires at least 4 CASE session contexts, and a node supports 7 fab­ + rics, the node would support at least 28 CASE session contexts, and ensure that each fabric could + use at least 4 of them. + +**4.15. Secure Communications over TCP** + +Matter messages over MRP need to be sized so that each UDP datagram fits within an IPv6 MTU +limit of 1280 bytes, to avoid IPv6 fragmentation and reassembly. Thus, larger messages cannot be +transferred over MRP unless the application explicitly performs fragmentation and reassembly. +Therefore, nodes that need to send large command messages must use an alternative transport pro­ +tocol, such as TCP. TCP support is communicated by nodes through the TXT record key T in their +DNS-SD operational service records. + +Since TCP already provides message transmission reliability, a node that is using TCP as the under­ +lying transport protocol SHALL NOT use MRP reliability semantics on its message exchanges. + +**4.15.1. Secure Session Establishment** + +When a pair of nodes that both support TCP intend to establish a secure session between them­ +selves, they MAY choose TCP as the underlying transport protocol. With a given peer, a node +SHOULD, typically, either have a secure session over MRP or one over TCP, but MAY also have both. +For example, a node might be using MRP for all its interactions with a controller, but might set up a +session over TCP with the same for specific data-heavy operations such as OTA. + +The underlying TCP connection MAY be long-lived or short-lived depending on the use case. Unlike +MRP, which does not rely on an underlying connection, a secure session over TCP is unusable when +its connection is broken or is closed. Nodes MAY choose to remove the secure session when the con­ +nection goes down. If the session is retained after the connection goes away, then the session +SHALL be marked appropriately so that the underlying connection is re-established before the ses­ +sion can be used again. Moreover, the session resumption state MAY be retained to expedite session +establishment when the connection is re-established with the corresponding peer. + +**4.15.2. TCP Connection Management** + +A TCP connection between a pair of nodes requires appropriate configurations and active manage­ +ment in order to meet the responsiveness demands of the application. + +``` +Page 194 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.15.2.1. TCP Connection Configuration** + +The TCP connection configuration parameters MAY include the following: + +1. Connection Establishment Timeout: A node MAY use this option to configure the amount of time + that it waits for an initiated connection establishment attempt to succeed, before giving up and + notifying the application. +2. TCP Keep Alive Messages For Connection Liveness: TCP Keep Alive messages MAY be used to + maintain liveness for long-lived connections. They MAY be used at both the client and server to + configure the liveness for each half of the connection. The configurable parameters SHALL be: + a. _TCP_KEEP_ALIVE_TIME_ : The interval between the last data packet sent and the first keep- + alive probe. + b. _TCP_KEEP_ALIVE_INTERVAL_ : The interval between subsequent keep-alive probes. + c. _TCP_KEEP_ALIVE_PROBES_ : The number of unacknowledged probes to send before consid­ + ering the connection dead and notifying the application. +3. TCP User Timeout: The TCP User Timeout option specifies the amount of time that transmitted + data may remain unacknowledged before the TCP connection is forcibly closed. This option + MAY be used by a node to limit the time the connection stays open when the data flow is not + progressing. + +The total TCP Keep Alive Timeout is given by: + +``` +TCP Keep Alive Timeout = TCP_KEEP_ALIVE_TIME + TCP_KEEP_ALIVE_INTERVAL * +TCP_KEEP_ALIVE_PROBES +``` +**4.15.2.2. TCP Connection Closures And Re-establishment** + +The TCP connection MAY be closed by either side of the connection. A node MAY proactively close +its connection when instructed by the upper layer. It MAY also close the connection based on its +current state. + +For example, it MAY close its connection under the following circumstances: + +1. The TCP Keep Alive Timeout expires on an idle connection. +2. Sent data on the connection is not acknowledged at the TCP layer, and the configured TCP User + Timeout expires. + +When the TCP layer of a node gets notified that the peer has closed the connection, it SHALL close +its end of the connection as well, and notify the application. Subsequently, all active Exchanges over +that connection SHOULD also be closed as they would be unusable over a closed connection. + +Either side MAY choose to re-establish the connection when it is closed or determined to be broken. +A node SHOULD back-off (typically, based on a Fibonacci back-off sequence) a random amount of +time after the connection closure, before attempting to establish the connection again. + +A node, upon receipt of a connection request from a peer, SHOULD discard its own backed-off con­ +nection retry timer to the same peer, if one is active. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 195 +``` + +This random back-off mechanism SHOULD prevent connection races between peers for most, if not +all scenarios. In addition, nodes SHOULD try to reap old unused connections as much as possible to +conserve resources. + +**4.15.2.3. Memory Requirements for Large messages** + +Since the TCP transport is designed for large messages, the system platform is expected to have +memory available for storing the received messages. The system platform MAY configure a Maximum +Message Size for the payload that it is capable of receiving over the TCP connection. If a node +receives a message header that indicates that the message is larger than the Maximum Message Size +that it supports, then it SHALL close the connection, and SHOULD send a Status Report error mes­ +sage with a status code set to MESSAGE_TOO_LARGE back to the sender, before closing the connection. + +Given that a node MAY be using both MRP and TCP for sending/receiving messages with different +peers, and these transports have different Maximum Message Size configurations, the system SHOULD +be able to dynamically change this configuration based on what transport the current Exchange is +using. + +**4.16. Group Communication** + +This section specifies the semantics of sending and receiving multicast group messages and the life­ +cycle of such groupcast sessions. Multicast addressing is accomplished using the 16-bit Group ID +field as the destination address. A multicast group is a collection of Nodes, all registered under the +same multicast Group ID. A multicast message is sent to a particular destination group and is +received by all members of that group. + +**4.16.1. Groupcast Session Context** + +Groupcast sessions are conceptually long-running, lasting the duration of a node’s membership in a +group. Group membership is tracked in the Group Key Management Cluster. However, on ingress of +each groupcast message, the following ephemeral context SHALL be constructed to inform upper +layers of groupcast message provenance: + +1. Fabric Index: Records the local Fabric Index for the Fabric to which an incoming message’s + group is scoped. +2. Group ID: Captures the Group ID to which a groupcast message was sent. +3. Source Node ID: The Source Node ID enclosed by the sender of a groupcast message. + ◦ Together, Fabric Index, Group ID and Source Node ID comprise a unique identifier that + upper layers may use to understand the source and destination of groupcast messages. +4. Source IP Address: The unicast source IP address for the originator of the message. +5. Source Port: The source port for the originator of the message. + ◦ The source IP address and port MAY be used for unicast responses to group communication + peers, as are required for the Message Counter Synchronization Protocol. +6. Operational Group Key: The Operational Group Key that was used to encrypt the incoming group + message. + +``` +Page 196 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +7. Group Session ID: Records the Group Session ID derived from the Operational Group Key used to + encrypt the message. + +Once a Groupcast Session Context with trust-first policy is created to track authenticated messages +from a given Source Node ID, that record SHALL NOT be deleted or recycled until the node reboots. +This is to prevent replay attacks that first exhaust the memory allocated to group session counter +tracking and then inject older messages as valid, and enforces that trust-first authentication works +as intended within the full duration of a boot cycle. Any message from a source that cannot be +tracked SHALL be dropped. + +**4.16.2. Sending a group message** + +To prepare a multicast message to a Group ID with a given GroupKeySetID and IPv6 hop count +parameter, the Node SHALL: + +1. Obtain, for the given GroupKeySetID, the current Operational Group Key as the Encryption Key, + and the associated Group Session ID. + a. If no key is found for the given GroupKeySetID, security processing SHALL fail and no fur­ + ther security processing SHALL be done on this message. +2. Perform Section 4.7.1, “Message Transmission” processing steps on the message with the follow­ + ing arguments: + a. The Destination Node Id argument SHALL be the Group Node Id corresponding to the given + Group ID. + b. The Session Id argument SHALL be the Group Session ID from step 1. + c. The Security Flags SHALL have only the P Flag set. + d. The transport SHALL be a site-local routable IPv6 interface. + +Next, prepare the message as an IPv6 packet: + +1. Set the private, secured message from step 2 above as the IPv6 payload. +2. Set the IPv6 hop count to the value given. +3. Set the IPv6 destination to the Section 2.5.6.2, “IPv6 Multicast Address” based on the provided + destination Group ID, Fabric ID, and GroupKeyMulticastPolicy of the group key. +4. Set the IPv6 source to an operational IPv6 Unicast Address of the sending Node. +5. Set the IPv6 UDP port number to the Matter IPv6 multicast port. + +**4.16.3. Receiving a group message** + +All Nodes supporting groups SHALL register to receive on the associated IPv6 multicast address, at +the Matter IPv6 multicast port, for each group of which they are a member. + +Upon receiving an IPv6 message addressed to one of these Multicast Addresses the Node is regis­ +tered for, the Node SHALL: + +1. Extract the message from the IPv6 payload. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 197 +``` + +2. Perform Section 4.7.2, “Message Reception” processing steps on the message. + +**4.17. Group Key Management** + +This section describes operational group keys, a mechanism for generating, disseminating and +managing shared symmetric keys across a group of Nodes in a Fabric. Operational group keys are +made available to applications for the purpose of authenticating peers, securing group communica­ +tions, and encrypting data. These keys allow Nodes to: + +- Prove to each other that they are members of the associated group +- Exchange messages confidentially, and without fear of manipulation by non-members of the + group +- Encrypt data in such a way that it can only be decrypted by other members of the group + +A central feature of operational group keys is the ability to limit access to keys to a trusted set of +Nodes. In particular, credentials required to generate operational group keys SHALL only be acces­ +sible to Nodes with a certain level of privilege — those deemed a member of the group. Barring soft­ +ware error or compromise of a privileged Node, access to shared keys SHALL be computationally +infeasible for non-trusted parties. + +Operational group keys are shareable across all types and combinations of Nodes as determined by +the Administrator managing the group. Given all Nodes in possession of the current epoch keys for +the group can communicate with other Nodes in the group, it is the responsibility of the Adminis­ +trator managing the group to only compose groups of Nodes where communication is appropriate +for the given application and security requirements. + +**4.17.1. Operational Groups** + +An operational group is a logical collection of Nodes that are running one or more common applica­ +tion clusters and share a common security domain in the form of a shared, symmetric group key. +For example, a set of Nodes running a lighting application can form an operational group by shar­ +ing a common operational group key derived from the mechanisms described here. Subgroups can +be formed within the operational group by defining distinct Group Identifiers for each set of Nodes, +while sharing a common operational group key. + +Membership in the security domain of an operational group is determined by a Node’s possession +of all the epoch keys required to generate the current, valid _operational group key_ for the group. +Individual Nodes can be members of multiple operational groups simultaneously. The set of groups +to which a Node belongs can change over time as dictated by application requirements and policies. +Groups MAY be introduced or withdrawn over time as need arises. + +**4.17.1.1. Operational Group Ids** + +Operational groups are identified uniquely within a Fabric by a Group Identifier. Administrators +SHALL assign Group Ids such that no two operational groups within a Fabric have the same Group +ID. It is assumed a given Administrator has sufficient access to centralized knowledge, so as to allo­ +cate unique Group Ids under a given Fabric such that there are no collisions. + +``` +Page 198 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Multiple operational groups MAY share the same operational group key, and thus be used to create +logical subgroups over a shared security domain. Operational groups which do not share related +functionality, such as a lighting group and a sprinkler group, SHOULD NOT share the same opera­ +tional key. As an example policy, a lighting application could have all lighting Nodes share a single +group key, while organizing lighting subgroups for various rooms or spaces within the structure by +assigning a different Group ID to each such subgroup. + +**4.17.2. Operational Group Key Derivation** + +An _operational group key_ is a symmetric key used as the Encryption Key during Message Processing +for group communication. An _operational group key_ is produced by applying a key derivation func­ +tion with an _epoch key_ and salt value as inputs as follows: + +``` +OperationalGroupKey = +Crypto_KDF +( +InputKey = Epoch Key, +Salt = CompressedFabricIdentifier, +Info = "GroupKey v1.0", +Length = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS +) +``` +where [] denotes a zero-length array. + +The Info portion of the key derivation is specified in Section 4.17.2.1, “Group Security Info”. The +Salt portion of the key derivation is specified in Section 4.3.2.2, “Compressed Fabric Identifier”. + +For example, given: + +- An Epoch Key value of: 23:5b:f7:e6:28:23:d3:58:dc:a4:ba:50:b1:53:5f:4b +- A CompressedFabricIdentifier value of: 87:e1:b0:04:e2:35:a1:30 + +After the above derivation following the definition of Crypto_KDF in Section 3.8, “Key Derivation +Function (KDF)”, the resulting operational group key would be: +a6:f5:30:6b:af:6d:05:0a:f2:3b:a4:bd:6b:9d:d9:60. + +Group membership is enforced by limiting access to the epoch keys. Only Nodes that possess the +input epoch key can derive a given operational key. Lack of possession of a particular epoch key +restricts access, based on the distribution policy of the epoch keys. + +The following diagram shows the process by which operational keys are derived from the epoch +key material: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 199 +``` + +_Figure 17. Group Key Derivation_ + +**4.17.2.1. Group Security Info** + +A hard-coded _group security info_ is used to diversify the set of operational group keys. This value is +hard-coded into the standard’s implementation, and thus is distributed with the associated code. +Should the standard’s security mechanisms need to evolve (e.g. to upgrade encryption from AES- +128 to AES-256), the _group security info_ can be changed to ensure that new keys will be derived for +use in the new algorithm. The _group security info_ SHALL be the byte stream "GroupKey v1.0", i.e. +0x47 0x72 0x6f 0x75 0x70 0x4b 0x65 0x79 0x20 0x76 0x31 0x2e 0x30. + +With the exception of the _group security info_ , all input key material SHALL be maintained on a per- +Fabric basis. + +**4.17.2.2. Group Key Set** + +A _group key set_ limits the key derivation process to Nodes within the respective operational groups. +Access to a _group key set_ is limited based on the functionality provided by a Node and/or the privi­ +lege afforded to it. For example, certain home security devices, such as a security system or door +lock, may have access to a "Physical Access" _group key set_ , while devices such as light bulbs or win­ +dow coverings would not. + +Operational group key lifetime is limited by assigning an expiration time to each _epoch key_ in a +given _group key set_. By constraining the validity of a given epoch key to an epoch, the ability for +members to derive and operate with an operational group key can be constrained to particular +periods of time. Epoch keys may be rotated on a periodic basis, and denying access to updated ver­ +sions of these keys serves as a means to eject group members. + +**4.17.3. Epoch Keys** + +Epoch keys provide a means for limiting the lifetime of derived operational group keys. They also +provide a way for an Administrator to revoke access to Nodes that have been explicitly excluded +from an operational group (albeit after a period of time). + +Epoch keys are generated, managed, and stored by an Administrator on a per-Fabric basis. Each key +SHALL be a random value of length CRYPTO_SYMMETRIC_KEY_LENGTH_BITS bits. + +``` +EpochKey = Crypto_DRBG(len = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS) +``` +``` +Page 200 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Each epoch key has associated with it a start time that denotes the time at which the key becomes +active for use by transmitting Nodes. Epoch key start times are absolute UTC time in microseconds +encoded using the epoch-us representation. + +**4.17.3.1. Using Epoch Keys** + +Nodes sending group messages SHALL use operational group keys that are derived from the _current +epoch key_ (specifically, the epoch key with the _latest_ start time that is not in the future). Nodes that +cannot reliably keep track of time calculate the _current epoch key_ as described in Section 4.17.3.4, +“Epoch Key Rotation without Time Synchronization”. + +Nodes receiving group messages SHALL accept the use of any key derived from one of the currently +installed epoch keys. This requirement holds regardless of whether the start time for the key is in +the future or the past. This means Nodes continue to accept communication secured under an +epoch key until that key is withdrawn by explicitly deleting the key from a Node’s group state by +the key distribution Administrator. + +Note that there is no end time associated with an epoch key. An epoch key marked with the maxi­ +mum start time SHALL be disabled and render the corresponding epoch key slot unused. + +**4.17.3.2. Managing Epoch Keys** + +The epoch keys are managed using the Group Key Management Cluster. For every group key set +published by the key distribution Administrator, there SHALL be at least 1 and at most 3 epoch keys +in rotation. Key additions or updates are done using the KeySetWrite command. + +Key updates are idempotent operations to ensure the Administrator is always the source of truth. +An epoch key update SHALL order the keys from oldest to newest. + +Any epoch key update MAY deliver a partial key set but SHALL include EpochKey0 and MAY include +EpochKey1 and EpochKey2. Any update of the key set, including a partial update, SHALL remove all +previous keys in the set, however many were defined. + +An Administrator MAY completely remove a group key set from a Node using the KeySetRemove +command. + +**4.17.3.3. Epoch Key Rotation** + +The key distribution Administrator generates new epoch keys on a regular basis, giving each a +unique id and adding them to the list of existing epoch keys within a group. The start time for each +new epoch key is scheduled to occur after a configurable _key propagation interval_. The propagation +interval is set sufficiently large such that the Administrator can synchronize all Nodes in the opera­ +tional group with the new epoch key list within that time. + +The rotation rate for epoch keys is expected to be on the order of days to weeks for typical applica­ +tions, but the rate is configurable as required by the key distribution Administrator. Because of the +relatively long rotation interval, and the overlap of active epoch keys, local clock drift within Nodes +is generally not a concern. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 201 +``` + +**4.17.3.4. Epoch Key Rotation without Time Synchronization** + +Although epoch keys are distributed with an associated start time, it is nonetheless possible for +Nodes that do not maintain a synchronized clock to participate in key rotation. Specifically, upon +receiving a new epoch key list from the key distribution Administrator, such a Node can note which +of the keys is the current epoch key by comparing their relative start times and using the current +epoch key which has the second newest time. It can then use the current key for all locally initiated +security interactions until such time as it makes contact with the distribution Administrator again. + +This scheme requires the Node to receive epoch keys from the key distribution Administrator at a +rate that is at least as fast as the configured _key propagation interval_. The Administrator SHOULD +provide a sufficient set of epoch keys to Nodes that do not maintain synchronized time so that they +can maintain communication with other group members while a key update is in progress. The key +distribution Administrator SHOULD update all Nodes without time, such as ICDs, before the _new +epoch key_ is activated, and then let Nodes with time all roll to the _new epoch key_ at the synchronized +start time. + +**4.17.3.5. Epoch Key Rotation logic** + +The full life-cycle of Epoch Key rotation is shown in Figure 18, “Epoch Key Rotation”. For each epoch +key slot, the start time of the key is shown as one of the following values: + +- **New** - a key with a start time in the future. +- **Current** - the active key with the newest start time. +- **Previous** - the active key with the second newest start time. +- **Old** - an active key with the third newest start time. + +The diagram shows two types of state transitions: + +1. **Admin** - an update of an old key by the Administrator. Changes made during this state transi­ + tion are indicated in green. +2. **Epoch Activate** - activation of an epoch key due to system time becoming greater than the start + time. Changes during this state transition are indicated in yellow. + +``` +Page 202 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 18. Epoch Key Rotation_ + +The Admin Refresh state begins when an entire _group key set_ is freshly written to a Node during +commissioning or administration, such as when a new group is added. The Epoch Activate state is +entered when time progresses to activate a fresh _current epoch key_ , aging out the other epoch key +slots. The Admin Update state is entered when an Administrator updates an _old epoch key_ with a _new +epoch key_. When in steady state, the Admin Refresh state MAY be entered in place of an Admin Update +state transition to update additional keys to the required ones or to completely reset the group secu­ +rity. + +Note that in the above diagram, only an example key distribution scheme is illustrated. It is also +possible to devise key distribution algorithms that to not rely on time synchronization, or group +configurations that never rotate keys in favor or configuring new groups and removing groups and +group key sets with expired keys. + +**Group Key Set ID** + +The Group Key Set ID is a 16-bit field that uniquely identifies the set of epoch keys used for deriva­ +tion of an operational group key. Each Group Key Set ID is scoped to a particular Fabric and +assigned by an Administrator so as to be unique within a Fabric. + +The Group Key Set ID of 0 SHALL be reserved for managing the Identity Protection Key (IPK) on a +given Fabric. It SHALL NOT be possible to remove the IPK Key Set if it exists. + +**4.17.3.6. Group Session ID** + +A _Group Session ID_ is a special case of a 16-bit Session ID that is specifically used for group commu­ +nication. When Session Type is 1, denoting a group session, the Session ID SHALL be a _Group Ses­ +sion ID_ as defined here. The _Group Session ID_ identifies probable operational group keys across a +Fabric. The _Group Session ID_ for a given _operational group key_ is derived by treating the output of a +Crypto_KDF against the associated Operational Group Key as a big-endian representation of a 16-bit + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 203 +``` + +integer, as follows: + +``` +GroupKeyHash = +Crypto_KDF +( +InputKey = OperationalGroupKey, +Salt = [], +Info = "GroupKeyHash", +Length = 16 // Bits +) +``` +``` +// GroupKeyHash is an array of 2 bytes (16 bits) per Crypto_KDF +``` +``` +// GroupSessionId is computed by considering the GroupKeyHash as a Big-Endian +// value. GroupSessionId is a scalar. Its use in fields within messages may cause a +// re-serialization into a different byte order than the one used for initial +generation. +GroupSessionId = (GroupKeyHash[0] << 8) | (GroupKeyHash[1] << 0) +``` +where [] denotes a zero-length array. + +For example, given: + +- An Operational Group Key value of: a6:f5:30:6b:af:6d:05:0a:f2:3b:a4:bd:6b:9d:d9:60 + +After the above derivation following the definition of Crypto_KDF in Section 3.8, “Key Derivation +Function (KDF)”, the resulting Group Session ID data would be: + +- Raw output of GroupKeyHash: b9:f7 +- Group Session ID scalar value to be used for further processing: 0xB9F7 (47607 decimal) + +The _Group Session ID_ MAY help receiving nodes efficiently locate the _Operational Group Key_ used to +encrypt an incoming groupcast message. It SHALL NOT be used as the sole means to locate the asso­ +ciated _Operational Group Key_ , since it MAY collide within the fabric. Instead, the _Group Session ID_ +provides receiving nodes a means to identify _Operational Group Key_ candidates without the need to +first attempt to decrypt groupcast messages using all available keys. + +On receipt of a message of Group Session Type, all valid, installed, operational group key candidates +referenced by the given Group Session ID SHALL be attempted until authentication is passed or +there are no more operational group keys to try. This is done because the same Group Session ID +might arise from different keys. The chance of a Group Session ID collision is 2-16 but the chance of +both a Group Session ID collision and the message MIC matching two different operational group +keys is 2-80. + +Group Session Ids are sized to fit within the context of the Session Identifier field of a message. +When used in this context, the Group Session ID value allows a receiving Node to identify the +appropriate message encryption key to use from the set of active operational keys it has currently + +``` +Page 204 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +installed. + +**4.17.4. Distribution of Key Material** + +The operational group keys mechanism relies on a key distribution Administrator to reliably dis­ +tribute select epoch key material to appropriate participants. It is assumed the key distribution +Administrator is in possession of all epoch keys, has knowledge of the set of group security domain +members which require access to those keys, and is responsible for pushing updates of these cre­ +dentials to all authorized Nodes in those groups it manages. + +Key material is distributed to key holders using the Group Key Management Cluster. In general, the +key material of a Node is exposed via Attributes with ACL entries that only allow access by the key +distribution Administrator. The information exposed in the Section 11.2, “Group Key Management +Cluster” includes the group epoch keys and associated group session identifiers. + +_Figure 19. Group Key Distribution_ + +**4.17.4.1. Installing a Group onto a Newly Commissioned Node** + +This section provides an example of the operations required to install a group onto a newly com­ +missioned node. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 205 +``` + +_Figure 20. Installing a group onto a new node_ + +Sequence: + +- _Admin_ : + ◦ Generate fabric-unique group ID GID and random key key0 for group key set ID K. + ◦ Write the group key set K to the remote node, GroupMember, using KeySetWrite command. + ◦ Associate group ID GID with key set K by writing an entry to the GroupKeyMap list attribute. +- _GroupMember_ : + ◦ Node subscribes to the IPv6 multicast address generated from the fabric ID and group ID. +- _Admin_ : + ◦ Associate endpoint with group ID GID by sending the Groups cluster’s AddGroup command to + endpoint. + +**4.18. Message Counter Synchronization Protocol** + +**(MCSP)** + +This section describes the protocol used to securely synchronize the message counter used by a + +``` +Page 206 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +sender of messages encrypted with a symmetric group key. + +Message counter synchronization is an essential part of enabling secure messaging between mem­ +bers of an operational group. Specifically, it protects against replay attacks, where an attacker +replays older messages, which may result in unexpected behavior if accepted and processed by the +receiver. + +The recipient of a message encrypted with a group key can trust and process that message only if it +has kept the last message counter received from a given sender using that key. + +Underlying MCSP is a simple request / response protocol. When a multicast message with unknown +counter is received, synchronization via MCSP begins by sending a synchronization request via uni­ +cast UDP to the multicast message originator’s unicast IPv6 address. That originator then sends a +synchronization response to the unsynchronized node via unicast UDP. After cryptographic verifi­ +cation, the formerly unsynchronized node is now synchronized with the originator’s message +counter and can trust the original and subsequent messages from the originator node. + +**4.18.1. Message Counter Synchronization Methods** + +There are two methods for synchronizing the message counter of a peer node, which are config­ +urable per-group-key based on the GroupKeySecurityPolicy field of a given group key set (see +GroupKeySetStruct). + +**4.18.1.1. Trust-first policy** + +The first authenticated message counter from an unsynchronized peer is trusted, and its message +counter is used to configure message-counter-based replay protection on future messages from that +node. All control messages (any message with C Flag set) use the control message counter and +SHALL use Trust-first for synchronization. Note that MCSP is not used for Trust-first synchroniza­ +tion. + +This policy provides lower latency for less security-sensitive applications such as lighting. + +### WARNING + +``` +Trust-first synchronization is susceptible to accepting a replayed message after +a Node has been rebooted. +``` +**4.18.1.2. Cache-and-sync policy** + +The message that triggers message counter synchronization is stored, a message counter synchro­ +nization exchange is initiated, and only when the synchronization is completed is the original mes­ +sage processed. Cache-and-sync provides replay protection even in the case where a Node has been +rebooted, at the expense of higher latency. + +Support for the cache-and-sync policy and MCSP is optional. A node indicates its ability to support +this feature via the Group Key Management cluster FeatureMap. + +### WARNING + +``` +Large groups may cause significant message synchronization burden on the +sender and message queueing pressure or latency on the receiver when mes­ +sage counter synchronization state is out of sync, such as after a brown-out, on +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 207 +``` + +``` +first message to a new large group, or similar large scale sets of synchroniza­ +tions being required at a single point in time. +``` +**4.18.2. Group Peer State** + +The _Group Peer State Table_ stores information about every peer with which the node had a group +message exchange. For every peer node id the following information is available in the table: + +- Peer’s Encrypted Group Data Message Counter Status: + ◦ _Synchronized Data Message Counter_ - the largest encrypted data message counter received + from the peer, if available. + ◦ Flag to indicate whether this counter value is valid and synchronized. + ◦ The _message reception state_ bitmap tracking the recent window of data message counters + received from the peer. +- Peer’s Encrypted Group Control Message Counter Status: + ◦ _Synchronized Control Message Counter_ - the largest encrypted control message counter + received from the peer, if available. + ◦ Flag to indicate whether this counter value is valid and synchronized. + ◦ The _message reception state_ bitmap tracking the recent window of control message counters + received from the peer. + +There are three scenarios where the receiver of an encrypted message does not know the sender’s +last message counter: + +- The encrypted message is the first received from a peer. +- The device rebooted without persisting the _Group Peer State Table_ content. + +``` +NOTE It is not required to persist the Peer State Table. +``` +- The entry for the Peer in the _Group Peer State Table_ was expunged due to the table being full. + +There SHALL be at least 10 entries per supported fabric for Peer Encrypted Group data Message +Status in the Group Peer State table. This number SHOULD NOT be less than 5 entries per fabric per +instance of Groups cluster on an endpoint. The number of entries is a compromise between the +number of peers that can send a group message to a receiver while the table is maintained, and the +associated memory usage. + +There SHALL be at least 2 entries per supported fabric for Peer Encrypted Group Control Message +Status in the Group Peer State table. + +The next sections describe the functional protocol used to request message counter synchronization +with a peer and form responses to such message counter synchronization requests. + +**4.18.3. MCSP Messages** + +``` +Page 208 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**4.18.3.1. MsgCounterSyncReq - Message Counter Synchronization Request** + +The Message Counter Synchronization Request ( _MsgCounterSyncReq_ ) message is sent when a mes­ +sage was received from a peer whose current message counter is unknown. + +A _MsgCounterSyncReq_ message SHALL set the C Flag in the message header. The control message +counter SHALL be used for message protection. + +A _MsgCounterSyncReq_ message SHALL be secured with the group key for which counter synchro­ +nization is requested and SHALL set the Session Type to 1 , indicating a group session as per the +rules outline in Section 4.18.5, “Message Counter Synchronization Exchange”. + +The payload of the _MsgCounterSyncReq_ message takes the format defined in Table 26, “Message +Counter Sync Request”: + +_Table 26. Message Counter Sync Request_ + +``` +Field +Size +``` +``` +Message Field Description +``` +``` +8 bytes Challenge The Challenge is a 64-bit random number generated using +the DRBG by the initiator of a MsgCounterSyncReq to +uniquely identify the synchronization request crypto­ +graphically. +``` +**4.18.3.2. MsgCounterSyncRsp - Message Counter Synchronization Response** + +The Message Counter Synchronization Response ( _MsgCounterSyncRsp_ ) message is sent in response +to a _MsgCounterSyncReq_. + +A _MsgCounterSyncRsp_ message SHALL set the C Flag in the message header. The control message +counter SHALL be used for message protection. + +The _MsgCounterSyncRsp_ message has the format defined in Table 27, “Message Counter Sync +Response”: + +_Table 27. Message Counter Sync Response_ + +``` +Field +Size +``` +``` +Message Field Description +``` +``` +4 bytes Synchronized Counter The current data message counter for the node sending +the MsgCounterSyncRsp message. +8 bytes Response The Response SHALL be the same as the 64-bit value sent +in the Challenge field of the corresponding MsgCounter­ +SyncReq. +``` +**4.18.4. Unsynchronized Message Processing** + +An unsynchronized message is one that is cryptographically verified from a node whose message +counter is unknown. Upon receipt of an unsynchronized message process the message as follows: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 209 +``` + +1. The message SHALL be of Group Session Type, otherwise discard the message. +2. If C Flag is set to 1 : + a.Create a Message Reception State and set its max_message_counter to the message counter of + the given message, i.e. trust-first. +b. Accept the message for further processing. +3. If C Flag is set to 0 : + a.Determine the GroupKeySecurityPolicy (as set by the Section 11.2, “Group Key Management + Cluster”) of the operational group key used to authenticate the message. +b. If the key has a _trust-first_ security policy, the receiver SHALL: +i. Set the peer’s group key data message counter to _Message Counter_ of the message. +A. Clear the Message Reception State bitmap for the group session from the peer. +B. Mark the peer 's group key data message counter as synchronized. +ii.Process the message. +c.If the key has a _cache-and-sync_ security policy, the receiver SHALL: +i. If MCSP is not in progress for the given peer Node ID and group key: +A. Store the message for later processing. +B. Proceed to Section 4.18.5, “Message Counter Synchronization Exchange”. +ii.Otherwise, do not process the message. +A. An implementation MAY queue the message for later processing after MCSP com­ +pletes if resources allow. + +For each peer Node ID and group key pair there SHALL be at most one synchronization exchange +outstanding at a time. + +**4.18.5. Message Counter Synchronization Exchange** + +A message synchronization exchange starts by sending the MsgCounterSyncReq message to the +peer Node that sent the message with unknown message counter. When a synchronization request +is triggered by an incoming multicast message, the Node SHALL first wait for a uniformly random +amount of time between 0 and MSG_COUNTER_SYNC_REQ_JITTER. + +The sender of the _MsgCounterSyncReq_ message SHALL: + +1. Set the Message Header fields as follows: + a.The S Flag SHALL be set to 1. +b. The DSIZ field SHALL be set to 1. +c.The P Flag SHALL be set to 1. +d. The C Flag SHALL be set to 1. +e. The Session Type field SHALL be set to 1. +f. The Session ID field SHALL be set to the Group Session Id for the operational group key + +``` +Page 210 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +being synchronized. +g. The Source Node ID field SHALL be set to the Node ID of the sender Node. +h. The Destination Node ID field SHALL be set to the Source Node ID of the message that trig­ +gered the synchronization attempt. +``` +2. Create a new synchronization Exchange. + a. The Exchange ID of the message SHALL be set to match the new Exchange. + b. The I Flag SHALL be set to 1. + c. The A Flag SHALL be set to 0. + d. The R Flag SHALL be set to 1. +3. Set the _Challenge_ field to the value returned by Crypto_DRBG(len = 8 * 8) and store that value to + resolve synchronization responses from the destination peer. +4. Arm a timer to enforce that a synchronization response is received before MSG_COUNTER_­ + SYNC_TIMEOUT. + a. Upon firing of the timer: + i. The synchronization exchange SHALL be closed. +ii. Any message waiting on synchronization associated with the exchange SHALL be dis­ +carded. + b. The timer SHALL be stopped upon receipt of an authenticated _MsgCounterSyncRsp_ message + that matches: + i. The Source Node ID field matches the Destination Node ID field of the most recent _Msg­_ + _CounterSyncReq_ message generated for that Node. +ii. The _Response_ field corresponds to the _Challenge_ field of the _MsgCounterSyncReq_ mes­ +sage. +5. Invoke Section 4.7.1, “Message Transmission” using parameters from step 1 to encrypt and then + send the request message over UDP to the IPv6 unicast address of the destination. + a. The request message SHALL use the same operational group key as the message which trig­ + gered synchronization. + b. The group key SHALL be known/derivable by both parties (sender and receiver). + +The receiver of _MsgCounterSyncReq_ SHALL: + +1. Verify the Destination Node ID field SHALL match the Node ID of the receiver, otherwise discard + the message. +2. Respond with _MsgCounterSyncRsp_. + +The sender of the _MsgCounterSyncRsp_ response message SHALL: + +1. Set the Message Header fields as follows: + a. The S Flag SHALL be set to 1. + b. The DSIZ field SHALL be set to 1. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 211 +``` + +``` +c.The P Flag SHALL be set to 1. +d. The C Flag SHALL be set to 1. +e. The Session Type field SHALL be set to 1. +f. The Session ID field SHALL be set to the Group Session Id for the operational group key +being synchronized. +g. The Source Node ID field SHALL be set to the Node ID of the sender Node. +h. The Destination Node ID field SHALL be set to the Source Node ID of the MsgCounterSyn­ +cReq. +``` +2. Set the MsgCounterSyncRsp payload fields as follows: + a.The _Response_ field SHALL be set to the value of the _Challenge_ field from the _MsgCounterSyn­_ + _cReq_. +b. The _Synchronized Counter_ field SHALL be set to the current Global Group Encrypted Data +Message Counter of the sender. +3. Use the same exchange context as the _MsgCounterSyncReq_ being responded to. + a.The Exchange ID of the message SHALL be set to the _Exchange ID_ of the _MsgCounterSyncReq_. +b. The I Flag SHALL be set to 0. +c.The A Flag SHALL be set to 1. +d. The R Flag SHALL be set to 1. +4. Invoke Section 4.7.1, “Message Transmission” using parameters from step 1 to encrypt and then + send the response message over UDP to the IPv6 unicast address of the destination. + +The receiver of the _MsgCounterSyncRsp_ message SHALL: + +1. Verify the _MsgCounterSyncRsp_ matches a previously sent _MsgCounterSyncReq_ : + a.An active synchronization exchange SHALL exist with the source node. +b. The _Exchange ID_ field SHALL match the _Exchange ID_ used for the original _MsgCounterSyn­ +cReq_ message. +c.The _Response_ field SHALL match the _Challenge_ field used for the original _MsgCounterSyn­ +cReq_ message. +d. The Destination Node ID field SHALL match the Source Node ID of the original _MsgCounter­ +SyncReq_ message. + e. The Source Node ID field SHALL match the Destination Node ID of the original _MsgCounter­_ + _SyncReq_ message. +2. On verification failure: + a.Silently ignore the _MsgCounterSyncRsp_ message. +3. On verification success: + a.Set the peer’s group key data message counter to _Synchronized Counter_. +b. Clear the Section 4.6.5.1, “Message Reception State” bitmap for the peer. +c.Mark the peer 's group key data message counter as synchronized. + +``` +Page 212 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +d. Resume processing of any queued message that triggered synchronization according to Sec­ +tion 4.6.7, “Counter Processing of Incoming Messages”. +i. If more than one message is queued from the synchronized peer, using the same opera­ +tional group key, the messages SHALL be processed in the order received. +e. Close the synchronization exchange created for the original MsgCounterSyncReq message. +``` +**4.18.6. Message Counter Synchronization Session Context** + +While conducting Message Counter Synchronization with a peer, nodes SHALL maintain the follow­ +ing session context. For nodes initiating message counter synchronization, this context SHALL be +maintained throughout the full exchange of _MsgCounterSyncReq_ and _MsgCounterSyncRsp_ messages. +For nodes responding to _MsgCounterSyncReq_ messages, the context SHALL only be maintained long +enough to generate and successfully transmit the _MsgCounterSyncRsp_ message. + +1. Fabric Index: Records the Index for the Fabric within which nodes are conducting message + counter synchronization. + ◦ Fabric Index is derived by identification of an Operational Group Key associated with the + fabric through successful decryption with that key and verification of the Message Integrity + Check. For nodes initiating counter synchronization, this occurs at decryption of an inbound + groupcast message. For nodes in the responder role, this occurs at decryption of an inbound + _MsgCounterSyncReq_ message. +2. Peer Node ID: Records the node ID of the peer with which message counter synchronization is + being conducted. + ◦ For nodes initiating message counter synchronization, this is the node ID of the responder. + For nodes responding to message counter synchronization, this is the node ID of the initia­ + tor. +3. Role: Records whether the node is the initiator of or responder to message counter synchroniza­ + tion. + ◦ Together, _Fabric Index_ , _Peer Node ID_ and _Role_ comprise a unique key that can be used to + match incoming messages to ongoing MCSP exchanges. +4. Message Reception State: Provides tracking for the Control Message Counter of the remote peer. +5. Peer IP Address: The unicast IP address of the peer. +6. Peer Port: The receiving port of the peer. +7. Operational Group Key: The Operational Group Key that is being used to encrypt messages + within the counter synchronization exchange. +8. Group Session ID: Records the Group Session ID derived from the Operational Group Key that is + being used to encrypt messages within the counter synchronization exchange. + +**4.18.7. Sequence Diagram** + +The following sequence diagram shows an example of how message counter synchronization +behaves in the most common scenario. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 213 +``` + +**4.18.7.1. Scenario 1 — Multicast Receiver Initiated** + +Assumptions: + +- _Sender_ transmits a multicast message. +- _Receiver_ does not know _Sender_ 's message counter. + +_Figure 21. Multicast Receiver Initiated Message Counter Synchronization_ + +Sequence: + +- _Sender_ : + ◦ Generates, encrypts and sends _Msg1_ as a multicast message. _Msg1_ could be: + ▪ Regular message that starts encrypted group communication with receivers _Receiver1_ + and _Receiver2_. +- Receivers _Receiver1_ and _Receiver2_ each: + ◦ Receive, decrypt, authenticate, and cache _Msg1_ message for later processing. + ▪ Generate, encrypt, and send _MsgCounterSyncReq_ message. + +``` +Page 214 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- _Sender_ : + ◦ Receives _MsgCounterSyncReq_ message. + ◦ Generates, encrypts and sends _MsgCounterSyncRsp_ message. +- R1 and R2 each: + ◦ Receive, decrypt, process, and verify _MsgCounterSyncRsp_ message from _Sender_. + ◦ On verification success: marks _Sender_ 's group key message counter as synchronized. + ▪ Processes cached _Msg1_ message. + +**4.19. Bluetooth Transport Protocol (BTP)** + +The Bluetooth Transport Protocol (BTP) provides a TCP-like layer of reliable, connection-oriented +data transfer on top of GATT. BTP splits individual Service Data Unit (SDU) messages into multiple +BTP segments, which are each transmitted via a single GATT write or indication (as shown in Figure +22, “MATTERoBLE: Matter Message / BTP layering”). + +While BTP is a generic protocol, Matter specifically uses BTP to define a Matter-over-Bluetooth Low +Energy (MATTERoBLE) Interface. A MATTERoBLE Interface MUST implement BTP as a universally +compatible transport mode. A MATTERoBLE Interface SHALL only be used to transport Matter mes­ +sages as the BTP SDU. + +_Figure 22. MATTERoBLE: Matter Message / BTP layering_ + +The BTP session handshake allows devices to check BTP protocol version compatibility and +exchange other data before a BTP session is established. Once established, this session is used to +send and receive BTP SDUs (such as Matter messages) as BTP Message Segments. A BTP session MAY +open and close with no effect on the state of the underlying Bluetooth LE connection, except in the +case where a BTP session is closed by the Peripheral Device. Either the Peripheral or the Central +MAY signal the end of a BTP session by closing the underlying BLE connection. + +Due chiefly to constraints put on design by resource-limited BLE chipsets, BTP defines a receive +window for each side of a session in units of GATT PDUs. Each GATT Write Characteristic Value +(ATT_WRITE_REQ) PDU or Indication (ATT_HANDLE_VALUE_IND) PDU is sent with a sequence num­ +ber which the receiver uses to acknowledge receipt of each packet at the BTP layer and open its + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 215 +``` + +receive window from the sender’s perspective. + +**4.19.1. BTP Session Interface** + +Conceptually, an open BTP session is exposed to the next-higher session layer as a full-duplex mes­ +sage stream. + +**4.19.2. BTP Frame Format** + +A BTP Frame consists of an 8-bit header followed by one or more optional fields, as detailed below. +BTP uses little endian encoding for any header fields larger than one byte in length. + +Table 28, “BTP Packet PDU format” defines the BTP Packet PDU format. + +Unused fields SHALL be set to '0'. + +_Table 28. BTP Packet PDU format_ + +``` +bit^0123456789101112131415 +Control Flags [Management Opcode] +[Ack Number] [Sequence Number] +[Message Length] +[Segment Payload]... +... +``` +**4.19.2.1. Control Flags** + +_Table 29. BTP Control Flags_ + +``` +bit^76543210 +``` +- H M - A E C B + +**H (Handshake) bit (position 6)** + +Set to '0' for normal BTP packets. When set, this bit indicates a BTP handshake packet for session +establishment and has a different packet format described below. + +**M (Management Message) bit (position 5)** + +Indicates the presence ('1') or absence ('0') of the Management Opcode field. All segments of a mes­ +sage MUST set this bit to the same value. + +**A (Acknowledgement) bit (position 3)** + +Indicates the presence of the Ack Number field. + +**E (Ending Segment) bit (position 2)** + +Set to '1' on the last segment of a BTP SDU and set to '0' for all other segments of the same BTP SDU. + +``` +Page 216 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +A segment MAY have both the Beginning and Ending bits set indicating that a full BTP SDU is +included in the message. When set, the segment payload length is equal to the total remaining unre­ +ceived message data. When not set, the segment payload length is equal to the maximum allowable +BTP session packet size minus header overhead. + +**C (Continuing Segment) bit (position 1)** + +Set to '0' on the first segment of a BTP SDU and set to '1' for all remaining segments of the same BTP +SDU. + +**B (Beginning Segment) bit (position 0)** + +Set to '1' on the first segment of a BTP SDU and set to '0' for all remaining segments of the same BTP +SDU. It indicates the presence of the Message Length field. + +**4.19.2.2. Ack Number** + +Optional field specified in Section 4.19.4.8, “Packet Acknowledgements”. + +**4.19.2.3. Sequence Number** + +Mandatory field for regular data messages specified in Section 4.19.4.6, “Sequence Numbers”. + +**4.19.2.4. Message Length** + +Optional field present in Beginning Segment only. Value indicates the length in bytes of the full mes­ +sage buffer to be transmitted. None of the BTP Packet PDU fields is included in the Message Length. + +**4.19.2.5. Segment Payload** + +Optional field containing a segment of the Service Data Unit (SDU) message in transmission to the +receiver. + +**4.19.3. BTP Control Frames** + +BTP defines different control frame formats depending on the Management Opcode that is in the +BTP Packet PDU header. Valid Management Opcodes for BTP Control Frames are defined in Table +30, “BTP Control codes”. + +_Table 30. BTP Control codes_ + +``` +Management +Opcode +``` +``` +Name Description +``` +``` +0x6C Handshake Request and response for BTP session establishment +``` +**4.19.3.1. BTP Handshake Request** + +_Table 31. BTP Handshake Request format_ + +``` +bit^0123456789101112131415 +Control Flags = 0x65 Management Opcode = 0x6C +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 217 +``` + +``` +bit^0123456789101112131415 +Ver[0] Ver[1] Ver[2] Ver[3] +Ver[4] Ver[5] Ver[6] Ver[7] +Requested ATT_MTU +Client Window Size +``` +**H (Handshake) bit** + +Set to '1' for connection handshake messages. + +**M (Management) bit** + +Set to '1' for connection handshake messages. + +**Ver[i] (Version) nibbles** + +Used to negotiate the highest version capability between a Device pair. Supported versions are +listed once each, newest first, in descending order. Unused version fields are filled with ‘0’. + +The following values are defined: + +- 0 — Unused field +- 4 — BTP as defined by Matter v1.0 + +**Requested ATT_MTU** + +Requested ATT_MTU is a 16-bit unsigned integer field containing the size of the GATT PDU +(ATT_MTU) that can be received by the sender minus the size of the GATT header (3). This value is +obtained via the standard ATT MTU exchange procedure (see Bluetooth® Core Specification 4.2 Vol +3, Part F, Section 3.4.2 "MTU Exchange") and is used to validate that both sides of the BLE connec­ +tion are using the common minimum value. If BTP is not aware of the negotiated GATT MTU, the +value SHALL be set to '23', indicating the minimum ATT_MTU defined by GATT. If the client has no +preference, the value may be set to '0'. + +### NOTE + +``` +Each GATT PDU used by the BTP protocol introduces 3 byte header overhead mak­ +ing the maximum BTP Segment Size for the session equal to negotiated ATT_MTU-3. +``` +**Client Window Size** + +Value of the maximum receive window size supported by the server, specified in units of BTP pack­ +ets where each packet may be up to 244 bytes in length. This maximum was chosen so a single BTP +segment can fit into a single 255 byte BLE link layer PDU, including all headers from the link layer, +L2CAP, GATT, and BTP. + +**4.19.3.2. BTP Handshake Response** + +_Table 32. BTP Handshake Response format_ + +``` +Page 218 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +bit^0123456789101112131415 +Control Flags = 0x65 Management Opcode = 0x6C +Final Protocol Version Reserved Selected ATT_MTU (low byte)... +...Selected ATT_MTU (high byte) Selected Window Size +``` +**H (Handshake) bit** + +Set to '1' for session handshake messages. + +**M (Management) bit** + +Set to '1' for session handshake messages. + +**Final Protocol Version** + +Value of the BTP protocol version selected by the server. + +**Reserved** + +Must be set to '0'. + +**Selected ATT_MTU** + +Value of the maximum ATT_MTU for the connection selected by the server as a 16-bit unsigned inte­ +ger. + +**Selected Window Size** + +Value of the maximum receive window size supported by the server, specified in units of BTP pack­ +ets where each packet may be up to the selected segment size in length. + +**4.19.4. BTP GATT Service** + +**4.19.4.1. BTP Channelization** + +Bluetooth Transport Protocol provides a packetized stream interface over GATT but says nothing +about the actual contents of the data packets it transports. The BTP Service UUID is used to specify +the actual contents of the packets (see Table 33, “BTP Service UUID”). + +_Table 33. BTP Service UUID_ + +``` +BTP Datagram Contents BTP Service UUID +Matter Message frames MATTER_BLE_SERVICE_UUID +``` +``` +NOTE See Section 4.19.6, “Bluetooth SIG Considerations” for terms of use. +``` +While a single BTP connection may exist between a BTP Client and BTP Server, multiple BTP ses­ +sions may be established between various peers. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 219 +``` + +**4.19.4.2. BTP GATT Service** + +The BTP GATT service is composed of a service with three characteristics—C1, C2 and C3 (see Table +34, “BTP GATT service”). The client SHALL exclusively use C1 to initiate BTP sessions by sending BTP +handshake requests and send data to the server via GATT ATT_WRITE_REQ PDUs. While a client is +subscribed to allow indications over C2, the server SHALL exclusively use C2 to respond to BTP +handshake requests and send data to the client via GATT ATT_HANDLE_VALUE_IND PDUs. + +_Table 34. BTP GATT service_ + +``` +Attribute Description +BTP Service UUID = MATTER_BLE_SERVICE_UUID +C1 Characteristic +(Client TX Buffer) +``` +### UUID = 18EE2EF5-263D-4559-959F-4F9C429F9D11 + +``` +Characteristic Properties = Write +max length = 247 bytes +C2 Characteristic +(Client RX Buffer) +``` +### UUID = 18EE2EF5-263D-4559-959F-4F9C429F9D12 + +``` +Characteristic Properties = Indication +max length = 247 bytes +C3 Characteristic +(Additional commissioning- +related data) +``` +### UUID = 64630238-8772-45F2-B87D-748A83218F04 + +``` +Characteristic Properties = Read +max length = 512 bytes +``` +For all messages sent from the BTP Client to BTP Server, BTP SHALL use the GATT Write Character­ +istic Value sub-procedure. For all messages sent from the BTP Server to BTP Client, BTP SHALL use +the GATT Indications sub-procedure. + +The values of C1 and C2 SHALL both be limited to a maximum length of 247 bytes. This constraint is +imposed to align with maximum PDU size when LE Data Packet Length Extensions (DPLE) is +enabled on Bluetooth 4.2 hardware. Per Bluetooth® Core Specification 4.2 Vol 3, Part F, Section 3.2.9 +"Long Attribute Values", the maximum characteristic value length is 512 bytes. The maximum +lengths of C1 and C2 may increase in a future version of the BTP specification to allow higher +throughput on BLE connections whose ATT_MTU exceeds 247 bytes. + +C3 is an optional characteristic that the server MAY use to include additional data required during +the provisioning as defined in Section 5.4.2.5.7, “GATT-based Additional Data”. + +BTP Clients SHALL perform certain GATT operations synchronously, including GATT discovery, sub­ +scribe, and unsubscribe operations. GATT discovery, subscribe, or unsubscribe SHALL NOT be initi­ +ated while the result of a previous operation remains outstanding. This requirement is imposed by +GATT protocol. + +**4.19.4.3. Session Establishment** + +Before a BTP session can be initiated, a central SHALL first establish a BLE connection to a periph­ +eral. Once a BLE connection has been formed, centrals SHALL assume the GATT client role for BTP +session establishment and data transfer, and peripherals SHALL assume the GATT server role. If +peripheral supports LE Data Packet Length Extension (DPLE) feature it SHOULD perform data +length update procedure before establishing a GATT connection. + +``` +Page 220 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Before establishing a BTP session, the GATT client SHOULD perform a GATT Exchange MTU proce­ +dure. + +After that the BTP Client SHALL execute the GATT discovery procedure. The GATT discovery proce­ +dure starts with primary service discovery using either the GATT Discover All Primary Services sub- +procedure or the GATT Discover Primary Services by Service UUID sub-procedure. + +The BTP Client SHALL perform either the GATT Discover All Characteristics of a Service sub-proce­ +dure or the GATT Discover Characteristics by UUID sub-procedure in order to discover the C1 and +C2 characteristics. + +The BTP Client SHALL perform the GATT Discover All Characteristic Descriptors sub-procedure in +order to discover the Client Characteristic Configuration descriptor (CCCD) of C2 characteristic. + +To initiate a BTP session, a BTP Client SHALL send a BTP handshake request packet to the BTP +Server via a ATT_WRITE_REQ PDU on characteristic C1 of the BTP Service. The handshake request +packet SHALL include, a list of BTP protocol versions supported by the client, the client’s GATT +ATT_MTU, and the client’s maximum receive window size. The list of supported protocol versions +SHALL be sorted in descending numerical order. If the client cannot determine the BLE connec­ +tion’s ATT_MTU, it SHALL specify a value of '23' (the minimum ATT_MTU supported by GATT) for +this field in the handshake request. For a detailed specification of the handshake request binary +data format, see Section 4.19.3.1, “BTP Handshake Request”. + +After the BTP Client acknowledges delivery of the handshake request packet, upon receipt of a +GATT Write Response, the BTP Client SHALL enable indications over C2 characteristics by writing +value 0x01 to C2’s Client Characteristic Configuration descriptor as described in Bluetooth® Core +Specification 4.2 Vol 3, Part C, Section 10.3.1.1 "Handling GATT Indications and Notifications". + +Once the GATT server has received a client’s BTP handshake request and confirmed the client’s sub­ +scription to C2, it SHALL send a BTP handshake response to the client via a ATT_HANDLE_VAL­ +UE_IND PDU on C2. This response SHALL contain the window size, maximum BTP packet size, and +BTP protocol version selected by the server. For a detailed specification of the handshake response +binary data format, see Section 4.19.3.2, “BTP Handshake Response”. + +The server SHALL select a window size equal to the minimum of its and the client’s maximum win­ +dow sizes. Likewise, the server SHALL select a maximum BTP Segment Size for the BLE connection +by taking the minimum of 244 bytes (the maximum characteristic value length of C1 and C2), +server’s ATT_MTU-3 and ATT_MTU-3 as declared by the client. + +The server SHALL select a BTP protocol version that is the newest which it and the client both sup­ +port, where newer protocol version numbers are strictly larger than those of older versions. The +version number returned in the handshake response SHALL determine the version of the BTP pro­ +tocol used by client and server for the duration of the session. + +If the server determines that it and the client do not share a supported BTP protocol version, the +server SHALL close its BLE connection to the client. When a client sends a handshake request, it +SHALL start a timer with a globally-defined duration of BTP_CONN_RSP_TIMEOUT seconds. If this +timer expires before the client receives a handshake response from the server, the client SHALL +close the BTP session and report an error to the application. Likewise, a server SHALL start a timer +with the same duration when it receives a handshake request from a client. If this timer expires + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 221 +``` + +before the server receives a subscription request on C2, the server SHALL close the BTP session and +report an error to the application. The state machine in Figure 23, “BTP session handshake” illus­ +trates the function of these timers as part of the BTP session establishment procedure. + +_Figure 23. BTP session handshake_ + +**4.19.4.4. Data Transmission** + +Once a BTP session has been established, the next-higher-layer application on both peers may use +this BLE connection to send and receive data via GATT writes or indications, according to a peer’s +GATT role. Clients SHALL exclusively use GATT Write Characteristic Value sub-procedure to send +data to servers and servers SHALL exclusively use GATT Indication sub-procedure to send data to +clients. + +All BTP packets sent on an open BLE connection SHALL adhere to the BTP Packet PDU binary data +format specified in BTP Frame Formats. All BTP packets SHALL include a header flags byte and an +8-bit unsigned sequence number. All other packet fields are optional. These optional fields include +an 8-bit unsigned received packet acknowledgement number, 16-bit unsigned buffer length indica­ +tion, and variable-length buffer segment payload. + +This section is defined entirely within the scope of a single BTP session. Concurrent BTP sessions +between the same peer and multiple remote hosts SHALL maintain separate and independent +acknowledgement timers, sequence numbers, and receive windows. + +**4.19.4.5. Message Segmentation and Reassembly** + +When the session layer (that is, MATTERoBLE) sends a Matter Message as a BTP SDU over a BTP ses­ +sion, that BTP SDU SHALL be split into ordered, non-overlapping BTP segments so the set of all BTP +segments may be reassembled into the original BTP SDU (see Figure 22, “MATTERoBLE: Matter Mes­ + +``` +Page 222 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +sage / BTP layering”). Each BTP segment SHALL be prepended with a BTP packet header and sent as +the payload of a single GATT PDU. If a BTP SDU is split into more than one BTP segment, the BTP +segments SHALL be sent in order of their position in the original BTP SDU, starting with the BTP +segment at the buffer’s head. + +At any point in time, only one BTP SDU may be transmitted in each direction over a BTP session. +The transmission of BTP segments of any two BTP SDUs SHALL NOT overlap. If the application +attempts to send one BTP SDU while transmission of another BTP SDU is in progress, the new BTP +SDU SHALL be appended to a first-in, first-out queue. The next BTP SDU SHALL be dequeued from +this queue and transmitted once transmission of the current BTP SDU completes, that is, once all +BTP segments of the current BDP SDU have been transmitted and received by the peer via GATT. + +The first BTP segment of a BTP SDU sent over a BTP session SHALL have its Beginning Segment +header flag set to indicate the beginning of a new BTP SDU (see Table 28, “BTP Packet PDU format”). +The presence of this flag SHALL indicate the further presence of a 16-bit unsigned integer field, the +Message Length, that provides the receiver with the total length of the BTP SDU. The last BTP seg­ +ment for a given BTP SDU SHALL have its Ending Segment flag set to indicate the end of the trans­ +mitted BTP SDU. A BTP packet that bears an unsegmented BTP SDU—that is, a BTP SDU small +enough to fit into a single BTP segment—SHALL have both its Beginning Segment and Ending Seg­ +ment flags set. + +The size of a single BTP SDU sent via BTP is limited to 64KB, that is, the maximum size of the Mes­ +sage Length field in the BTP packet header. The number of segments used to send a buffer is unlim­ +ited and delimited by the Beginning Segment and Ending Segment bits in the BTP packet header. +The upper layer imposes more stringent requirements over the maximum SDU size, such as Section +4.4.4, “Message Size Requirements”. + +The length of the data payload in each BTP segment whose Ending Segment bit is not set SHALL be +equal to the session’s maximum BTP packet size minus the size of that packet’s header. If a packet’s +Ending Segment bit is set, the length of its BTP segment data payload SHALL equal the size of the +original BTP SDU minus the total size of all previously transmitted BTP segments of that BTP SDU. In +this way, the length of a SDU’s last BTP segment is implied by its size. + +Once a peer receives a complete set of BTP segments, it SHALL reassemble them in the order +received, and verify that the reassembled BTP SDU’s total length matches that specified by the +Beginning Segment’s Message Length value. If they match, the receiver SHALL pass the reassem­ +bled BTP SDU up to the next-higher-layer. If the reassembled buffer’s length does not match that +specified by the sender, or if received BTP segment payload size would exceed the maximum BTP +packet size, or receiver receives an Ending Segment without the presence of a previous Beginning +Segment, or a Beginning Segment when another BTP SDU’s transmission is already in progress, the +receiver BTP SHALL close the BTP session and report an error to the application. + +**4.19.4.6. Sequence Numbers** + +All BTP packets SHALL be sent with sequence numbers, regardless of whether they contain SDU +segments (for example, a packet acknowledgement with no attached segment payload). The pur­ +pose of sequence numbers is to facilitate the BTP receive window. A BTP sequence number SHALL +be defined as an unsigned 8-bit integer value that monotonically increments by 1 with each packet +sent by a given peer. A sequence number incremented past 255 SHALL wrap to zero. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 223 +``` + +Sequence numbers SHALL be separately defined for either direction of a BTP session. The sequence +number of the first packet sent by the client after completion of the BTP session handshake SHALL +be zero. The server’s BTP handshake response bears an implied sequence number of zero because +it occupies a slot in the client’s receive window. The client acknowledges the server’s BTP hand­ +shake response with an acknowledgement sequence of zero. For this reason, the sequence number +of the first data packet sent by the server after completion of the BTP session handshake SHALL be +1. + +Peers SHALL check to ensure that all received BTP packets properly increment the sender’s previ­ +ous sequence number by 1. If this check fails, the peer SHALL close the BTP session and report an +error to the application. + +**4.19.4.7. Receive Windows** + +The purpose of the receive window is to enable flow control at the GATT session layer between BTP +peers. + +Flow control is required at the GATT transport layer for embedded platforms that use "minimal" +BLE chipsets. These platforms may have limited space on the host processor to receive packets from +their BLE chipsets. In the case of some dual-chip architectures, writes and indications are received +and confirmed by the BLE chip with no input from the host processor. When the BLE chip sends the +result of a received GATT PDU to the host processor, that payload and the corresponding BTP packet +will be permanently lost if the host does not have enough space to receive it. For this reason, knowl­ +edge of a remote host’s ability to reliably receive GATT PDUs is presented at the transport layer in +the form of the BTP receive window. + +Both peers in a BTP session SHALL define a receive window, where the window’s size indicates the +number of GATT PDUs (that is, BTP segments) a peer can reliably receive and store without session- +layer acknowledgment. A maximum window size SHALL be established for both peers as part of +the BTP session handshake. To prevent sequence number wrap-around, the largest maximum win­ +dow size any peer may support is 255. + +Both peers SHALL maintain a counter to reflect the current size of the remote peer’s receive win­ +dow. Each peer SHALL decrement this counter when it sends a packet via GATT write or indication +and increment this counter when a sent packet is acknowledged. + +If a local peer’s counter for a remote peer’s receive window is zero, the window SHALL be consid­ +ered closed, and the local peer SHALL NOT send packets until the window reopens (is incremented +above zero). When a closed window reopens, a local peer SHALL immediately resume any pending +BTP packet transmission. + +A local peer SHALL also not send packets if the remote peer’s receive window has one slot open and +the local peer does not have a pending packet acknowledgement. This is to avoid the situation +where the receive windows of both peers are full and neither can send an acknowledgement to +reopen its window for the other. Because the server’s handshake response bears an implicit BTP +sequence number of zero, a server SHALL initialize its counter for the client’s receive window size +at (negotiated maximum window size - 1). A client SHALL initialize its counter for the server’s +receive window at the negotiated maximum window size. + +Both peers SHALL also keep a counter of their own receive window size based on the sequence + +``` +Page 224 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +number difference between the last packet they received and the last packet they acknowledged. +This counter is used to proactively send early packet acknowledgements when a peer’s own receive +window is about to close. See Section 4.19.4.8, “Packet Acknowledgements” for details. + +An example scenario involving BTP receive windows is depicted in Figure 24, “Example receive +window scenario”, complete with packet acknowledgements as specified in Section 4.19.4.8, “Packet +Acknowledgements”. In this scenario, the client transmits a three-segment buffer to the server once +it receives the server’s handshake request. The handshake request occupies one slot in the client’s +initial receive window. The server’s initial receive window is empty. Both client and server have a +maximum window size of 4. + +_Figure 24. Example receive window scenario_ + +**4.19.4.8. Packet Acknowledgements** + +The purpose of sequence numbers and packet receipt acknowledgements is to support the BTP +receive window and provide a keep-alive signal when a session is idle to affirm the health and con­ +tinued operation of a remote BTP stack. + +Per BTP Frame Formats, BTP packet receipt acknowledgements SHALL be received as unsigned 8- +bit integer values in the header of a BTP packet. The value of this field SHALL indicate the sequence +number of the acknowledged packet. + +Acknowledgement of a sequence number indicates acknowledgement of the previous sequence +number, if it too is unacknowledged. By induction, acknowledgement of a given packet implies +acknowledgement of all packets received on the same BTP session prior to the acknowledged +packet. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 225 +``` + +An acknowledgement is invalid if the acknowledged sequence number does not correspond to an +outstanding, unacknowledged BTP packet sequence number. In contrast to TCP, BTP acks are not +"free." A stand-alone ack—that is, a BTP packet that contains a packet receipt acknowledgement +value but no buffer segment payload—consumes a slot in a remote peer’s window just like any +other packet. Stand-alone acknowledgement packets SHALL be acknowledged by a remote peer. +The implications of this are examined in Section 4.19.4.9, “Idle Connection State”. + +Each peer SHALL maintain an acknowledgement-received timer. When a peer sends any BTP +packet, it SHALL start this timer if it is not already running. The timer’s duration SHALL be globally +defined as BTP_ACK_TIMEOUT seconds, referred to as the acknowledgement timeout interval. + +A peer SHALL restart its acknowledgement-received timer when a valid acknowledgement is +received for any but its most recently sent unacknowledged packet. A peer SHALL stop its acknowl­ +edgement-received timer if it receives an acknowledgement for its most recently sent unacknowl­ +edged packet. If a peer’s acknowledgement-received timer expires, or if a peer receives an invalid +acknowledgement, the peer SHALL close the BTP session and report an error to the application. + +Because the server’s handshake response bears an implicit BTP sequence number of zero, a server +SHALL start its acknowledgement-received timer when it sends a handshake response. + +Each peer SHALL also maintain a send-acknowledgement timer. When it receives any BTP packet, a +peer SHALL record the packet’s sequence number as the corresponding BTP session’s pending +acknowledgement value and start the send-acknowledgement timer if it is not already running. The +timer’s duration timer SHALL be defined as any value less than one-half the acknowledgement +timeout interval. This ensures that on a healthy BLE connection, a peer will always receive +acknowledgements for sent packets before its acknowledgement-received timer expires. + +A peer SHALL stop its send-acknowledgement timer when any pending acknowledgement is sent, +either as a stand-alone BTP packet or piggybacked onto an outgoing buffer segment. If this timer +expires and the peer has a pending acknowledgement, the peer SHALL immediately send that +acknowledgement. If the peer sends any packet before this timer expires, it SHALL piggyback any +pending acknowledgement on the transmitted packet and stop the send-acknowledgement timer. + +Because the server’s handshake response bears an implicit BTP sequence number of zero, a client +SHALL set its pending acknowledgement value to zero and start its send-acknowledgement timer +when it receives the server’s a handshake response. Operation of the send-acknowledgement and +acknowledgement-received timers is illustrated in Figure 26, “BTP session lifecycle for Central act­ +ing as GATT Client” in Section 4.19.4.11, “Protocol State Diagrams”. + +If a peer detects that its receive window has shrunk to two or fewer free slots, it SHALL immedi­ +ately send any pending acknowledgement as a stand-alone BTP packet. This prevents the session +from stalling in the interval between when a peer’s receive window becomes empty and when its +send-acknowledgement timer would normally fire. + +**4.19.4.9. Idle Connection State** + +When neither side of a BTP session has data to send, BTP packets will still be exchanged every send- +acknowledgement interval due to acknowledgements generated by the receipt of previous data or +stand-alone acknowledgement packets, as discussed in Section 4.19.4.8, “Packet Acknowledge­ +ments”. The behavior of the acknowledgement-received timer in this scenario doubles as a keep- + +``` +Page 226 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +alive mechanism, as it will cause a peer to close a BLE connection automatically if the remote BTP +stack crashes or becomes unresponsive. This scenario is illustrated in Figure 25, “Idle connection +scenario”. + +_Figure 25. Idle connection scenario_ + +**4.19.4.10. Connection Shutdown** + +To close a BTP session, a GATT client SHALL unsubscribe from characteristic C2. The GATT server +SHALL take this action to indicate closure of any BTP session open to the client. + +If a BTP Server needs to close the BTP session, it SHALL terminate its BLE connection to the client. + +**4.19.4.11. Protocol State Diagrams** + +Figure 26, “BTP session lifecycle for Central acting as GATT Client” shows the state machine for BTP +session management of a BTP Client Device. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 227 +``` + +_Figure 26. BTP session lifecycle for Central acting as GATT Client_ + +Figure 27, “BTP session lifecycle for Peripheral acting as GATT Server” shows the state machine for +BTP session management of a BTP Server Device. + +``` +Page 228 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 27. BTP session lifecycle for Peripheral acting as GATT Server_ + +Note that in Figure 27, “BTP session lifecycle for Peripheral acting as GATT Server”, the state +machine is identical for GATT clients and servers with the distinction that clients send data to +servers via confirmed writes, and servers send data to clients via indications. + +Figure 28, “State diagram for BTP session post-establishment” shows the state machine for BTP ses­ +sion maintenance at the protocol level, including liveliness enforcement through keep alive mes­ +sages and automatic teardown if acknowledgements are received before the timeout. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 229 +``` + +_Figure 28. State diagram for BTP session post-establishment_ + +**4.19.5. Parameters and Constants** + +Table 35, “Glossary of constants” is a glossary of constants used in this chapter, along with a brief +description and the default for each constant. + +_Table 35. Glossary of constants_ + +``` +Page 230 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Constant Name Description Default +BTP_CONN_RSP_TIMEOUT The maximum amount of time +after sending a BTP Session +Handshake request to wait for a +BTP Session Handshake +response before closing the con­ +nection. +``` +``` +5 seconds +``` +``` +BTP_ACK_TIMEOUT The maximum amount of time +after receipt of a segment +before a stand-alone ACK must +be sent. +``` +``` +15 seconds +``` +``` +BTP_CONN_IDLE_TIMEOUT The maximum amount of time +no unique data has been sent +over a BTP session before the +Central Device must close the +BTP session. +``` +``` +30 seconds +``` +**4.19.6. Bluetooth SIG Considerations** + +The UUID is provided by Bluetooth SIG, Inc. and may only be used by its members in compliance +with all terms and conditions of use issued by the Bluetooth SIG, Inc. For more information, visit +https://www.bluetooth.com/specifications/assigned-numbers/16-bit-uuids-for-sdos. + +Use of the Bluetooth extensions feature of this specification and specifically the MATTER_BLE_SER­ +VICE_UUID is strictly prohibited unless the product is certified by both the Bluetooth SIG and the +Connectivity Standards Alliance by a member of good standing of both organizations. + +_Table 36. SIG UUID assignment_ + +``` +Constant Name Description Value +MATTER_BLE_SERVICE_UUID The UUID for the Matter-over- +BLE service as assigned by the +Bluetooth SIG. +``` +``` +0xFFF6 +``` +**4.20. Check-In Protocol** + +The goal of the Check-In Protocol is to provide a way for a server to notify a client of an event or +state outside of a secure session in a private and secure fashion. + +Some of the events or states to be shared with a client are defined by different Check-in Protocol +Use Cases. The current list includes: + +- An ICD is available for communication. + +The Check-In Protocol is a set of requirements and processes that can be re-used by multiple Check- +In Protocol use cases. Multiple Check-In Protocol use cases can coexist on a single device. The +Check-In Protocol sends a sessionless message (Check-In message) that relies on a key that has been + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 231 +``` + +given to the server during the registration of the client. + +**4.20.1. Requirements** + +**4.20.1.1. Server Requirements** + +A Server use case of the Check-In Protocol SHALL implement these requirements. + +- A persistent data store for Keys. +- An implementation of the Check-In Counter. + +**Persistent Data Store** + +For the Check-In Protocol to be effective, the use case of the protocol SHALL provide a means to +store and persist client registration information. The minimum information that SHALL be stored +and persisted is the key to use during the encryption process of the Check-In message. + +**4.20.1.2. Client Requirements** + +The server does not store the starting value of the Check-In Counter for a given key. Therefore, it is +the client’s responsibility to do so when the client registers with the server. A Client use case of the +Check-In Protocol SHALL implement a means to store sets containing a key, the starting value of +Check-In Counter and the last known valid offset from the starting value of the Check-In Counter. A +Key that has been used to register for Check-In messages SHALL always be associated with a start­ +ing Check-In Counter value and the last known valid offset from the starting Check-In Counter +value. + +During the decryption process, the client uses the key, its associated starting Check-In Counter value +and offset to decrypt and authenticate a received Check-In message. + +**4.20.2. Message Content** + +_Table 37. Check-In Payload_ + +``` +Field Type Description +nonce byte[CRYPTO_AEAD_NON­ +CE_LENGTH_BYTES] +``` +``` +First plaintext field +``` +``` +Check-In Counter uint32 Encrypted field - Counter used +to generate the nonce +Application Data byte[] Encrypted field - Application +Data that can be added to the +Check-In message +MIC byte[CRYPTO_AEAD­ +_MIC_LENGTH_BYTES] +``` +``` +Message integrity Check +``` +**4.20.2.1. Nonce** + +The nonce used to encrypt the encrypted fields of the payload SHALL be the first CRYPTO_AEAD­ + +``` +Page 232 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_NONCE_LENGTH_BYTES bytes of the message payload. The nonce is included in plaintext. + +**4.20.2.2. Encrypted Section** + +The encrypted section SHALL be a concatenation of the following, in order: + +1. The Check-In Counter value used in the encryption process, represented as a 4-byte little-endian + value. +2. The Application Data, if used by the use case. + +**Check-In Counter** + +The Check-In Counter value SHALL be used to generate the nonce. This value SHALL be provided +by the Check-In Protocol use case. + +**Application Data** + +The application data is defined and provided by the Check-In Protocol use case. The Check-In Proto­ +col use case is not required to use application data. If application data is not used for a specific use- +case, creation of a Check-In message SHALL use a zero-length byte array for the application data. + +**4.20.2.3. MIC** + +Message integrity check generated by the AEAD is appended after the encrypted section. It SHALL +be the last CRYPTO_AEAD_MIC_LENGTH_BYTES bytes. + +**4.20.3. Algorithms** + +The Check-In message is a sessionless message, since one of the goals of the protocol is to provide a +means to recover a secure session that was lost. Since no session keys are available to encrypt the +entire message, the encryption of the Check-In message is limited to part of the payload. + +The inputs provided to the encryption process by the Check-In protocol use case are: + +1. The value of Check-In Counter represented as 4-byte little-endian value. In the following steps, + we assume the counter value is in the correct format. +2. The application data bytes represented as a byte array. In the following steps, we assume the + application data is in the correct format. +3. A symmetric encryption key represented as a CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES-byte + array. In the following steps, we assume the key is in the correct format. + +**4.20.3.1. Nonce Generation** + +To generate the nonce, the Check-In message SHALL use the Keyed-Hash Message Authentication +Code algorithm. The inputs of the algorithm SHALL be the key and the Check-In Counter value. Both +will be provided by the Check-In Protocol use case. From the generated hash, the nonce SHALL be +the first CRYPTO_AEAD_NONCE_LENGTH_BYTES bytes to match the AEAD requirements. + +``` +nonce = Crypto_HMAC(key = key, message = counter)[0..(CRYPTO_AEAD_NONCE_LENGTH_BYTES- +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 233 +``` + +### 1)] + +**4.20.3.2. Authenticated encryption** + +The payload of the Check-In message SHALL be encrypted using the AEAD function. The inputs of +the algorithm SHALL be the generated nonce, the key and the plaintext to encrypt. The additional +data field SHALL NOT be used. + +``` +Ciphertext = Crypto_AEAD_GenerateEncrypt( +K = key +P = plaintext, +A = "", +N = nonce) +``` +**4.20.3.3. Client Counter Validation** + +When receiving a Check-In message, the client SHALL verify the received counter by executing the +following steps. + +1. Subtract the stored starting value of the counter from the value provided in the Check-In mes­ + sage. The subtraction SHALL be done as unsigned integers mod 2^32. This ensures that even if the + subtraction rolls over, it will still produce the correct offset. +2. If the stored last known offset from the stored starting value of the counter is smaller than the + value from step 1, the verification SHALL return TRUE. +3. Otherwise the verification SHALL return FALSE. + +**4.20.3.4. Key Refreshing** + +A given key is only valid for one set of values of the Check-In Counter. A key becomes invalid once +all the Check-In Counter values for that key have been used. The tracking of the used Check-In +counter values is done as part of the decryption procedure. + +To avoid reuse of a nonce value with a given key, the key (shared secret) needs to be refreshed +before all the valid Check-In Counter values for that key have been used. If a Check-In Counter +value is reused with the same key, the Check-In messages reusing the counter will be discarded. To +avoid the situation where the relationship is broken because of a rollover, we are prescribing when +a client should refresh its entry. + +**Key Refresh Validation** + +When a client receives a Check-In message with a Check-In Counter value indicating that 2^31 +counter values have been used, the client SHALL refresh its entry with a new key. The client SHALL +determine if a key refresh is necessary by executing the following steps. + +1. Check whether the stored counter offset is greater than or equal to 2^31. +2. If the stored counter offset is greater than or equal to 2^31 , a key refresh is required. + +``` +Page 234 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +3. Otherwise, a key refresh is allowed, but not required. + +**4.20.4. Protocol Operation** + +**4.20.4.1. Encryption Procedure** + +When sending a Check-In message, the server SHALL encrypt the application payload (ie. Check-In +Counter and application data provided) following these steps. If the encryption procedure fails to +generate the Check-In message, the server SHALL NOT send the associated Check-In message. + +1. The server SHALL generate the nonce as described in Section 4.20.3.1, “Nonce Generation”. + a. If the generation failed, the encryption procedure SHALL return FAILURE. + b. If the generation succeeded, the server SHALL continue from step 2. +2. The server SHALL encrypt the plaintext as described in Section 4.20.3.2, “Authenticated encryp­ + tion”. + a. The plaintext SHALL be a concatenation of the following, in order : + i. The Check-In Counter value used in the encryption process and +ii. the Application Data, if used by the use case. + b. If the encryption fails, the encryption procedure SHALL return FAILURE. + c. If the encryption succeeds, the server SHALL continue from step 3. +3. The server SHALL create the payload string by concatenating the nonce and the output of the + AEAD function. + +``` +payload = nonce || Ciphertext +``` +**Check-In Protocol Encryption Diagram** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 235 +``` + +_Figure 29. Check-In Protocol Encryption Legend_ + +**4.20.4.2. Decryption Procedure** + +When a client receives a Check-In message, the client SHALL decrypt and process the message fol­ +lowing these steps: + +1. The client SHALL break down the message into the nonce and the ciphertext/MIC. + +``` +Page 236 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +nonce = payload[0:CRYPTO_AEAD_NONCE_LENGTH_BYTES] +ciphertext/MIC = payload[CRYPTO_AEAD_NONCE_LENGTH_BYTES:] +``` +2. The client SHALL try to decrypt the message with the key associated to the server being tested. + When a client has multiple associated servers, the client iterates through this process for the + keys associated to each potential server until the keys associated to all possible servers fail or a + successful key is found. + +``` +Success, Plaintext = Crypto_AEAD_DecryptVerify( +K = Key, +C = ciphertext/MIC, +A = "", +N = nonce) +``` +``` +a. If the decryption succeeds, the device associated with the key is identified as the server +checking in. The client SHALL continue from step 3. +b. If the decryption fails, the client SHALL move on to the next candidate server key per step 2, +or discard the message if there are no remaining registered server keys to try. +``` +3. From the plaintext, the client SHALL retrieve the Check-In Counter and the application data if + present. +4. The client SHALL verify that the received nonce is valid by calculating it as described in Section + 4.20.3.1, “Nonce Generation” from the received Check-In Counter and the key. The counter value + retrieved in the previous step is already in the correct encoding. + a. If the calculated nonce matches the received nonce, the client SHALL continue from step 5. + b. If the calculated nonce doesn’t match the received nonce, the client SHALL discard the mes­ + sage. +5. The client SHALL verify that the received Check-In Counter is valid as described in Section + 4.20.3.3, “Client Counter Validation”. The Check-In Counter is converted into a unsigned 32-bit + integer. + a. If the received counter value is valid, the client SHALL continue from step 6. + b. If the received counter value is invalid, the client SHALL discard the message. +6. The client SHALL store the offset between the received Check-In Counter value and the stored + starting value of the Check-In Counter. The subtraction SHALL be done as unsigned integers + mod 2^32. The client SHALL continue from step 7. +7. The client SHALL verify if a key refresh is necessary as described in Section 4.20.3.4.1, “Key + Refresh Validation”. + a. If a key refresh is necessary, the client SHALL trigger an attempt to refresh the key, unless + the client is already in the process of refreshing this specific key for this specific server. The + client SHALL continue from step 8 whether the key refresh succeeds or not. + b. If a key refresh is not necessary, the client SHALL continue from step 8. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 237 +``` + +8. The client SHALL notify the application that the server has checked-in. What this behavior + implies is application specific. + +Page 238 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 5. Commissioning** + +**5.1. Onboarding Payload** + +The purpose of this section is to define the contents of the Onboarding Payload needed to allow +onboarding a device into a Matter network. It also specifies the representation and encoding of said +payload as a QR Code, as a manually entered code, and as content in an NFC tag. + +**5.1.1. Onboarding Payload Contents** + +The Onboarding Payload is composed of required and optional information which will be used by +the Commissioner to ensure interoperability between commissioners and devices and provide a +consistent user experience. Some or all of this content will be encoded into different formats, some +human-readable (such as numeric string) and machine-readable (such as QR code and NFC) for­ +mats for printing or display on or integration into the device. The following are the elements that +may be used in an Onboarding Payload for a Matter device. + +**5.1.1.1. Version** + +A version indication provides versioning of the payload and SHALL be included. Version for +machine-readable formats is 3 bits with an initial version of 0b000. Version for Manual Pairing Code +is 1 bit with an initial version of 0b0. +_Rationale_ : This allows a way to introduce changes to the payload as needed going into the future. + +**5.1.1.2. Vendor ID and Product ID** + +Vendor ID and Product ID, each a 16-bit value, SHALL be included in machine-readable formats and +MAY be included in the Manual Pairing Code. +_Rationale_ : This allows a way to identify the make and model of the device, which is used further +during the commissioning flow, such as during the Device Attestation procedure. These unique +identifiers also help to retrieve device model metadata like product name, product description, and +firmware update URL from the Distributed Compliance Ledger, as well as information relevant to +the commissioning flow (see Section 5.7, “Device Commissioning Flows”). + +**5.1.1.3. Custom Flow** + +A 2-bit unsigned enumeration specifying the Device Commissioning Flow SHALL be included in +machine-readable formats. For the encoding of Custom Flow in the Manual Pairing Code, see Sec­ +tion 5.1.4.1.2, “Custom Flow for Manual Pairing Code”. +_Rationale_ : This guides the Commissioner as to whether steps are needed before commissioning can +take place. + +- A value of 0 indicates that no steps are needed (apart from powering the device). +- A value of 1 indicates that user interaction with the device (pressing a button, for example) is + required before commissioning can take place. The specific steps required can be found in the + CommissioningModeInitialStepsHint field of the Distributed Compliance Ledger for the given + Vendor ID and Product ID. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 239 +``` + +- A value of 2 indicates that additional interactions described in Section 5.7.3, “Custom Commis­ + sioning Flow” are required for initial device setup in order to be successfully commissioned by + any Commissioner. + +**5.1.1.4. Discovery Capabilities Bitmask** + +An 8-bit capabilities bitmask SHALL be included in machine-readable formats. +_Rationale_ : The Discovery Capabilities Bitmask contains information about the device’s available +technologies for device discovery (see Section 5.4, “Device Discovery”). + +**5.1.1.5. Discriminator value** + +A Discriminator SHALL be included as a 12-bit unsigned integer, which SHALL match the value +which a device advertises during commissioning. Manufacturers SHALL NOT use a common dis­ +criminator value for all devices, to allow a commissioner to distinguish between multiple advertis­ +ing devices. It is RECOMMENDED that manufacturers use sequential generation with rollover for +devices that might be sold or purchased in a multi-pack in order to reduce the chance of discrimi­ +nator collision between devices in the same pack. + +For machine-readable formats, the full 12-bit Discriminator is used. For the Manual Pairing Code, +only the upper 4 bits out of the 12-bit Discriminator are used. +_Rationale_ : The Discriminator value helps to further identify potential devices during the setup +process and helps to improve the speed and robustness of the setup experience for the user. + +**5.1.1.6. Passcode** + +A Passcode SHALL be included as a 27-bit unsigned integer, which serves as proof of possession dur­ +ing commissioning. The 27-bit unsigned integer encodes an 8-digit decimal numeric value, and +therefore SHALL be restricted to the values 0x0000001 to 0x5F5E0FE ( 00000001 to 99999998 in decimal), +excluding the invalid Passcode values. + +_Rationale_ : The Passcode establishes proof of possession and is also used as the shared secret in set­ +ting up the initial secure channel over which further onboarding steps take place. + +**5.1.1.7. TLV Data** + +Variable-length TLV data using the TLV format MAY be included in machine-readable formats pro­ +viding optional information. More details about the TLV can be found in Section 5.1.5, “TLV Con­ +tent”. + +**5.1.2. Onboarding Material Representation** + +In order for the users of Matter products to recognize the onboarding material, and be able to use it +easily, it is important to keep the representations of the onboarding material unified and of certain +minimum size. To support this the Matter Brand Guidelines specify the characteristics like composi­ +tion, colors, font, font size, QR Code size and digit-grouping of the Manual Pairing code. + +When the onboarding material is printed on product or packaging material it SHALL follow the +Matter Brand Guidelines. + +``` +Page 240 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Other representations (product display, app, etc) of the onboarding material SHOULD follow the +Matter Brand Guidelines. + +**5.1.3. QR Code** + +The Onboarding Payload MAY be included on (or with) a device in the form of a QR code. The fol­ +lowing sections detail the content, encoding, and formatting of the QR code. + +**5.1.3.1. Payload** + +The content of the QR code consists of the concatenation of a prefix string and a Base-38-encoded +string containing the required and optional TLV content: + +``` +QR code string := +``` +**Prefix String** + +The prefix string consists of the three-character string: + +### MT: + +**Base-38 Content** + +The required content of the QR code is composed of a Packed Binary Data Structure containing ele­ +ments of the Onboarding Payload as detailed below. The resulting data is Base-38 encoded (with a +specific alphabet) to form a string compatible with alphanumeric QR encoding. + +**Packed Binary Data Structure** + +Individual data elements SHALL be placed into the structure in the order detailed in the table +below. Elements being packed are not necessarily byte- or word-aligned. The resulting packed struc­ +ture is presented to the encoder as a multi-byte array (see Encoding section below), which SHALL +be padded with '0' bits at the end of the structure to the nearest byte boundary. + +The bits of each fixed-size value are placed in the packed binary data structure in order from least +significant to most significant. If TLV Data is included, it is appended to the end of the packed +binary data. + +For example, the first elements in the table below SHALL be packed into the first bytes of the data +array as pictured: + +_Table 38. Packing of the onboarding payload_ + +``` +lsb Byte 0 msb Byte 1 Byte 2 Byte 3 ... +0 7 0 7 0 7 0 7 0 +``` +``` +version Vendor ID Product ID +0 2 0 15 0 15 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 241 +``` + +_Table 39. Packed Binary Data Structure for Onboarding Payload_ + +``` +Onboarding +Payload Ele­ +ment +``` +``` +Size +(bits) +``` +``` +Require +d +``` +``` +Notes +``` +``` +Version 3 Yes 3-bit value specifying the QR code payload version. +SHALL be 000. +Vendor ID 16 Yes +Product ID 16 Yes +Custom Flow 2 Yes Device Commissioning Flow +0: Standard commissioning flow: such a device, when uncom­ +missioned, always enters commissioning mode upon power-up, +subject to the rules in Section 5.4.2.2, “Announcement Com­ +mencement”. +1: User-intent commissioning flow: user action required to +enter commissioning mode. +2: Custom commissioning flow: interaction with a vendor- +specified means is needed before commissioning. +3: Reserved +Discovery +Capabilities +Bitmask +``` +``` +8 Yes Defined in table below. +``` +``` +Discriminator 12 Yes 12-bit as defined in Discriminator +Passcode 27 Yes See Section 5.1.7, “Generation of the Passcode” +Padding 4 Yes Bit-padding of '0’s to expand to the nearest byte boundary, thus +byte-aligning any TLV Data that follows. +TLV Data Variable No Variable length TLV data. Zero length if TLV is not included. +This data is byte-aligned. +See TLV Data sections below for detail. +``` +_Table 40. Discovery Capabilities Bitmask_ + +``` +Bit Size +(bits) +``` +``` +Description +``` +### 0 + +``` +(lsb +) +``` +``` +1 Reserved (SHALL be 0) +``` +### 1 1 BLE: + +``` +0: Device does not support BLE for discovery or is currently commissioned into one +or more fabrics. +1: Device supports BLE for discovery when not commissioned. +2 1 On IP network: +1: Device is already on the IP network +``` +``` +Page 242 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Size +(bits) +``` +``` +Description +``` +``` +3 1 Wi-Fi Public Action Frame: +0: Device does not support Wi-Fi Public Action Frame for discovery or is currently +commissioned into one or more fabrics. +1: Device supports Wi-Fi Public Action Frame for discovery when not commissioned. +7..4 4 Reserved (SHALL be 0) +``` +**TLV Data** + +The TLV data is an optional, variable-length payload. The payload is composed of one or more TLV- +encoded elements as defined in detail below in the TLV Content section. + +**Encoding** + +The Packed Binary Data Structure is Base-38 encoded (with a specific alphabet) to produce an +alphanumeric string suitable for use as a QR code payload. + +**Alphabet** + +The Base-38 alphabet to be employed is composed of a subset of the 45 available characters (A-Z0- +9$%*+./ :-) in the QR code for alphanumeric encoding as defined by ISO/IEC 18004:2015, with char­ +acters $, %, *, +, /, , and : removed. + +_Table 41. Alphabet for Onboard Payload Encoding_ + +``` +Code Charac­ +ter +``` +``` +Code Charac­ +ter +``` +``` +Code Charac­ +ter +``` +``` +Code Charac­ +ter +``` +``` +Code Charac­ +ter +00 0 09 9 18 I 27 R 36 - +01 1 10 A 19 J 28 S 37. +02 2 11 B 20 K 29 T +03 3 12 C 21 L 30 U +04 4 13 D 22 M 31 V +05 5 14 E 23 N 32 W +06 6 15 F 24 O 33 X +07 7 16 G 25 P 34 Y +08 8 17 H 26 Q 35 Z +``` +**Method** + +Base-38 encoding is achieved by employing a simplified strategy where every 3 bytes (24 bits) of +binary source data are encoded to 5 characters of the Base-38 alphabet. + +Data from the Packed Binary Data Structure are encoded starting with the first byte of the struc­ +ture. Three-byte chunks are formed into a 24-bit unsigned integer for encoding as follows: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 243 +``` + +### UINT 24 = (BYTEN+2 << 16) | (BYTEN+1 << 8) | (BYTEN << 0) + +The 24-bit value is subsequently converted to Base-38 radix using the alphabet above to produce a +5-character substring, with the least-significant character appearing first (little-endian). + +If a single byte of binary source data remains, it SHALL be converted to Base-38 radix using the +alphabet above to produce a 2-character substring, with the least-significant character appearing +first. + +If two bytes of binary source data remains, they SHALL be formed into a 16-bit unsigned integer for +encoding as follows: + +### UINT 16 = (BYTEN+1 << 8) | (BYTEN << 0) + +This 16-bit value is subsequently converted to Base-38 radix using the alphabet above to produce a +4-character substring, with the least-significant character appearing first. + +The final encoded string is a result of concatenation of all substrings, with the first-encoded sub­ +string appearing at the beginning of the concatenated string. + +**5.1.3.2. QR Code Format** + +The format selection, which includes the QR code Version and ECC levels as well as size and color, +MAY be tailored to the requirements of the manufacturer and their respective product, provided it +meets the following requirements: + +**QR code Version and Encoding** + +The QR code generated, as defined in ISO/IEC 18004:2015, SHALL be of Version 1 or higher, using +alphanumeric encoding. The size of the payload implies a minimum Version, though a higher Ver­ +sion may be needed to allow a higher ECC level. For example, a minimum payload of 22 alphanu­ +meric characters (19 base-38-encoded characters from the packed binary structure plus 3 prefix +characters) can be fit into a Version 1 with ECC=L, but for ECC=M, Q or H, the same payload +requires a Version 2 QR code. This allows the Manufacturer to balance between ECC, pixel size and +overall size. + +**Example QR Code Sizes and Payloads** + +``` +QR Code +Version +``` +``` +Module +Size +``` +``` +ECC Level Alphanumeric +capacity (chars) +``` +``` +Total available +payload, exclud­ +ing prefix (bits) +``` +``` +Available pay­ +load for TLV data +(bits) +1 21x21 L 25 104 16 +2 25x25 L 47 208 120 +M 38 168 80 +Q 29 120 32 +``` +``` +Page 244 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +QR Code +Version +``` +``` +Module +Size +``` +``` +ECC Level Alphanumeric +capacity (chars) +``` +``` +Total available +payload, exclud­ +ing prefix (bits) +``` +``` +Available pay­ +load for TLV data +(bits) +3 29x29 L 77 352 264 +M 61 272 184 +Q 47 208 120 +H 35 152 64 +4 33x33 L 114 528 440 +M 90 416 328 +Q 67 304 216 +H 50 224 136 +5 37x37 L 154 720 632 +M 122 568 480 +Q 87 400 312 +H 64 288 200 +``` +### NOTE + +``` +Version 1 codes with ECC levels M, Q, and H and version 2 codes with ECC level H +have insufficient capacity +``` +### NOTE + +``` +Total available payload, excluding prefix = (trunc((N-3) / 5) * 24) where N is the +number of alphanumeric characters which fit in the QR code. This formula uses N-3 +to account for the prefix characters, and then determines how many groups of 5 +base-38-encoded characters can fit; each such group carrying 24 bits of payload. +This formula fills groups of 5 characters after the MT: prefix. If there are 2,3 or 4 +characters left after these groups, an additional 8 bits (for 2,3 characters) or 16 bits +(for 4 characters) of TLV data can be accommodated. So the entries in the table take +this into account. +Available payload for TLV data = (Total available payload, excluding prefix - 88) +since the minimum payload for the Packed Binary Data Structure is 84 bits before +padding, or 88 bits with padding. +``` +**Payload Limits** + +The number of alphanumeric characters in the QR code SHALL NOT exceed 255 characters. Using +this maximum size would yield a total available payload of 1208 bits, and hence 1120 bits of TLV +payload. + +**ECC Level** + +The QR code SHOULD employ level M or higher ECC. + +### NOTE + +``` +A higher level ECC does not help against typical 'reading' issues like shiny surfaces, +bad contrast or issues with camera resolution/focus, and lack of camera-app pro­ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 245 +``` + +``` +cessing dedicated for QR codes. Therefore, in certain situations ECC=L MAY be used +as well (e.g. to prevent having to move to a higher Version to fit the payload). +``` +**5.1.4. Manual Pairing Code** + +This section describes the content and format of the Manual Pairing Code, which can be used in cer­ +tain situations next to or instead of the QR code described above. + +**5.1.4.1. Content** + +**Payload** + +The payload of the Manual Pairing Code consists of the following required and optional data ele­ +ments. + +_Table 42. Manual Pairing Code Elements_ + +``` +Element Size +(bits) +``` +``` +Require +d +``` +``` +Notes +``` +``` +VERSION 1 Yes Shall be 0 +Version is encoded as part of first digit of the Manual Pair­ +ing Code. A value of 1 is reserved for future extension of +the specification. +VID_PID_PRESENT 1 Yes 0: no Vendor ID and Product ID present in Manual Pairing +Code +1: Vendor ID and Product ID data included +DISCRIMINATOR 4 Yes 4 Most-significant bits of the 12-bits Discriminator +described above +PASSCODE 27 Yes Same as 27-bit Passcode described above +VENDOR_ID 16 No Needed only to support devices that need a user-intent or +vendor specific flow before commissioning (i.e. a non-zero +Custom Flow value). +If an accompanying QR code is present on the device with +the Custom Flow field set to a non-zero value, or if the +device requires Custom commissioning flow, this element +SHALL be included. +PRODUCT_ID 16 No* * This element SHALL be included if and only if the VEN­ +DOR_ID element is present. +``` +The Vendor ID and Product ID elements are optional. Including these may provide additional infor­ +mation for the setup flow at the expense of a substantially longer Manual Pairing Code. + +**Custom Flow for Manual Pairing Code** + +The encoding for Manual Pairing Code does not have a dedicated field for Custom Flow, as exists in +the Packed Binary Data Structure. Instead, this information is encoded in the following way: + +``` +Page 246 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- For Standard commissioning flow, the variant of Manual Pairing Code _without_ Vendor ID and + Product ID SHALL be used. A commissioner encountering such Manual Pairing Code SHALL + assume it is a "standard flow" device. +- For User-intent commissioning flow and Custom Commissioning flow, the variant of Manual + Pairing Code _with_ Vendor ID and Product ID SHALL be used. For this case, a commissioner + SHOULD use Vendor ID and Product ID to lookup the CommissioningCustomFlow field in the + Distributed Compliance Ledger to determine which of these values applies for this Vendor ID + and Product ID combination. + +**Encoding** + +The required and optional elements, along with a check digit, are encoded into either an 11-digit or +21-digit decimal numeric string, depending on whether the optional Vendor and Product ID infor­ +mation is included. + +**Method** + +Each group of digits in the Pairing Code SHALL be encoded as described in the table below. The left- +most digit of the entire string SHALL be represented by _DIGIT[1]_. Groups of multiple digits SHALL +be encoded such that the most-significant digit appears first (left-most). + +_Table 43. Encoding Method without Vendor and Product ID’s (VID_PID_Present == 0)_ + +``` +Digit Contents Encoding Notes +1 +(left- +most) +``` +- Version 0 +- VID_PID present flag +- 2 ms-bits of discrimina­ +tor + +### DIGIT[1] := + +### (VID_PID_PRESENT << 2) | + +### (DISCRIMINATOR >> 10) + +``` +Allows first digit typed/spo­ +ken to determine version +and VID/PID present. +Yields a decimal number +from 0..7 (0..3 if VID,PID not +present). +First digit of '8' or '9' would +be invalid for v1 and would +indicate new format (e.g. +version 2) +2..6 - 3rd and 4th ms-bits of +Discriminator +``` +- 14 ls-bits of PASSCODE + +### DIGIT[2..6] := + +``` +((DISCRIMINATOR & 0x300) +<< 6) | +(PASSCODE & 0x3FFF) +``` +``` +Yields a 5-digit decimal num­ +ber from 00000 to 65535 +(0xFFFF/16 bits) +``` +``` +7..10 - 13 ms-bits of PASSCODE DIGIT[7..10] := +(PASSCODE >> 14) +``` +``` +Yields a 4-digit decimal num­ +ber from 0000 to 8191 +(0x1FFF/13 bits) +11 - Check Digit DIGIT[11] := +(CHECK_DIGIT) +``` +``` +See Check Digit section for +encoding +``` +_Table 44. Encoding Method with Vendor and Product ID’s included (VID_PID_Present == 1)_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 247 +``` + +``` +Digit Contents Encoding Notes +1 +(left- +most) +``` +- Version 0 +- VID_PID present flag +- 2 ms-bits of Discrimina­ +tor + +### DIGIT[1] := + +### (VID_PID_PRESENT << 2) | + +### (DISCRIMINATOR >> 10) + +``` +Allows first digit typed/spo­ +ken to determine version +and VID/PID present. +Yields a decimal number +from 0..7 (4..7 if VID,PID +present). +First digit of '8' or '9' would +be invalid for v1 and would +indicate new format (e.g. +version 2) +2..6 - 3rd and 4th ms-bits of +Discriminator +``` +- 14 ls-bits of PASSCODE + +### DIGIT[2..6] := + +``` +((DISCRIMINATOR & 0x300) +<< 6) | +(PASSCODE & 0x3FFF) +``` +``` +Yields a 5-digit decimal num­ +ber from 00000 to 65535 +(0xFFFF/16 bits) +``` +``` +7..10 - 13 ms-bits of PASSCODE DIGIT[7..10] := +(PASSCODE >> 14) +``` +``` +Yields a 4-digit decimal num­ +ber from 0000 to 8191 +(0x1FFF/13 bits) +11..15 - Vendor ID DIGIT[11..15] := +(VENDOR_ID) +``` +``` +Yields a 5-digit decimal num­ +ber from 00000 to 65535 +(0xFFFF/16 bits) +16..20 - Product ID DIGIT[16..20] := +(PRODUCT_ID) +``` +``` +Yields a 5-digit decimal num­ +ber from 00000 to 65535 +(0xFFFF/16 bits) +21 - Check Digit DIGIT[21] := +(CHECK_DIGIT) +``` +``` +See Check Digit section for +encoding +``` +**Check Digit** + +The _CHECK_DIGIT_ element is a single decimal digit computed across all of the preceding digits of +the Pairing Code using the Verhoeff algorithm. + +**5.1.4.2. Copying between applications** + +When the Manual Pairing Code is presented in an application within a multi-function device, such +as an application on a smartphone, it SHOULD provide a mechanism such as a copy button to allow +easy conveyance of the information to other commissioners on the same device. + +When a Commissioner is implemented as an application within a multi-function device, such as an +application on a smartphone, it SHOULD provide a mechanism such as a paste button to allow easy +conveyance of the information from an administrator on the same device. + +The receiving application SHALL be robust against characters like dashes and spaces that may be +included in the string, such as those added for readability by the user, when passed between the +applications. For example, a receiving application seeing the code "1234-567-8910" would need to +interpret it as "12345678910". + +``` +Page 248 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.1.5. TLV Content** + +A variable-length TLV Data section MAY be encoded into the Packed Binary Data Structure. The TLV +section MAY consist of manufacturer-specific information elements and/or elements common to +Matter, encoded using TLV. All elements SHALL be housed within an anonymous top-level structure +container. + +**5.1.5.1. Manufacturer-specific Elements** + +Manufacturer-specific elements SHALL be tagged with context-specific tags that have semantics +which are defined by the vendor for use in the products using their Vendor ID, and SHALL use tag +numbers 0x80 to 0xFF. +Tag numbers 0x00 to 0x7F are reserved to indicate Matter-common elements. + +Manufacturer-specific elements inherit the context of the Vendor ID and Product ID provided in the +Packed Binary Data Structure described above. All elements SHALL follow the constraints outlined +in Appendix A, _Tag-length-value (TLV) Encoding Format_. + +**5.1.5.2. Matter-common Elements** + +All elements common to Matter SHALL use tag numbers in the range 0x00 to 0x7F, as defined in the +following section. + +Vendors are encouraged to use Matter-common elements where applicable. + +_Table 45. Matter-common Reserved Tags_ + +``` +Tag Valu +e +``` +``` +Description Type(s) +``` +``` +kTag_Serial­ +Number +``` +``` +0x00 Device Serial # UTF-8 String (length = 1..32 bytes) +Unsigned Integer, up to 8-byte value (has +room to represent a 19-digit decimal num­ +ber) +PBKDFItera­ +tions * +``` +``` +0x01 PBKDFParameterSet Iterations Unsigned Integer (range = CRYPTO_PBKD­ +F_ITERATIONS_MIN.. CRYPTO_PBKDF_ITER­ +ATIONS_MAX) +PBKDFSalt * 0x02 PBKDFParameterSet Salt Octet String (length = 16..32 bytes) +kTag_Num­ +berOfDevices +``` +``` +0x03 Number of devices that are +expected to be onboarded +using this payload when using +the Enhanced Commissioning +Method +``` +``` +Unsigned Integer, range 1 to 255 +``` +``` +kTag_Commis­ +sioningTime­ +out +``` +``` +0x04 Time, in seconds, during which +the device(s) are expected to +be commissionable using the +Enhanced Commissioning +Method +``` +``` +Unsigned Integer, see Announcement Dura­ +tion +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 249 +``` + +``` +Tag Valu +e +``` +``` +Description Type(s) +``` +``` +reserved 0x05. +.0x7F +``` +``` +reserved for future use +``` +* If the PBKDF parameters are to be included in the TLV section, both the PBKDFSalt and PBKDFItera­ + +tions SHALL be encoded. + +**5.1.5.3. TLV Examples** + +**Manufacturer-specific and Matter-common elements** + +### { + +``` +vendorTag01 (0x81) = "Vendor", +kTag_SerialNumber(0) = "1234567890" +} +``` +The above notation encodes to the following bytes: + +``` +0x15 0x2C 0x81 0x06 0x56 0x65 0x6E 0x64 0x6F 0x72 0x2C 0x00 0x0A 0x31 0x32 0x33 +0x34 0x35 0x36 0x37 0x38 0x39 0x30 0x18 +``` +``` +Data Comments +=========== =================================================== +0x15 Control Byte for outermost container (structure) +``` +- Tag control 000xxxxxb: Anonymous tag +- Elem type xxx10101b: Structure + +``` +0x2C Control Byte for next TLV +``` +- Tag control 001xxxxxb: Context-specific tag +- Elem type xxx01100b: UTF-8 String, 1-byte length +0x81 Context-specific vendor tag +- Matter-common versus vendor tag 1xxxxxxxb: Vendor tag +- Tag number x0000001b: Vendor tag #1 +--------- +10000001b = 0x81 +0x06 Length of vendor string (e.g. 6 bytes) +0x56 0x65 0x6E 0x64 0x6F 0x72 +UTF-8 encoded vendor string "Vendor" + +``` +0x2C Control byte for next TLV +``` +- Tag control 001xxxxxb: Context-specific tag + +``` +Page 250 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Elem type xxx01100b: UTF-8 String, 1-byte length +--------- +00101100b = 0x2C +0x00 Context-specific Matter-common Serial Number tag +- Matter-common versus vendor tag 0xxxxxxxb: Matter-common tag +- Tag number x0000000b: kTag_SerialNumber +--------- +00000000b = 0x00 +0x0A Length of Serial Number string (10 bytes) +0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x30 +UTF-8 encoded Serial Number string "1234567890" + +``` +0x18 End of container +``` +**Matter-common elements only** + +### { + +``` +kTag_SerialNumber (0) = "1234567890" +} +``` +The above notation encodes to the following bytes: + +``` +0x15 0x2C 0x00 0x0A 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x30 0x18 +``` +``` +Data Comments +=========== =================================================== +0x15 Control Byte for outermost container (structure) +``` +- Tag control 000xxxxxb: Anonymous tag +- Elem type xxx10101b: Structure + +``` +0x2C Control Byte for next TLV +``` +- Tag control 001xxxxxb: Context-specific tag +- Elem type xxx01100b: UTF-8 String, 1-byte length +--------- +00101100b = 0x2C +0x00 Context-specific Matter-common Serial Number tag +- Matter-common versus vendor tag 0xxxxxxxb: Matter-common tag +- Tag number x0000000b: kTag_SerialNumber +--------- +00000000b = 0x00 +0x0A Length of Serial Number string (10 bytes) +0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x30 + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 251 +``` + +``` +UTF-8 encoded Serial Number string "1234567890" +``` +``` +0x18 End of container +``` +**5.1.6. Concatenation** + +The Onboarding Payload MAY be concatenated with additional Onboarding Payloads to be placed in +a single QR Code: + +``` +QR code string := MT:* +``` +Where * is used as the delimiter. + +Concatenation of multiple Matter Onboarding Payloads allows a single QR code to provide the +onboarding payload for a number of devices. Example use case for this concatenation: + +- Easy onboarding for multi-device packaging, e.g. for a package of light bulbs containing four + separate bulbs. Each bulb will have its own Onboarding Payload code(s) printed on the bulb + itself. The Manufacturer MAY include a leaflet in the box with a larger QR code containing the + concatenation of the four individual Onboarding Payloads. The user can then scan this com­ + bined QR code (one step for the user) which would give the Commissioner the Onboarding Pay­ + load for all four bulbs in one operation, and it can proceed to commission the four bulbs. + +All Commissioners SHALL recognize the * separator from the QR code as indication concatenation +is used. +A Commissioner which does not support such concatenated Matter Onboarding Payloads SHOULD +indicate to the user the need to commission devices one by one by scanning their individual QR +codes. +The Commissioner SHOULD commission the devices in the order as they are provided in the con­ +catenated code. (This ordering is particularly relevant in case of combi-packs where one of the +devices needs to be commissioned first, e.g. a Thread Router first, then one or more Thread-con­ +nected bulbs). + +Example of concatenated Onboarding Payloads: + +``` +MT:*** +``` +**5.1.7. Generation of the Passcode** + +A device can support either dynamic or static passcodes for purposes of establishing the shared +secret for the initial secure channel over which further onboarding steps take place. + +All devices SHALL conform to the following rules for passcodes: + +- Passcodes SHALL NOT be derived from public information, such as a serial number, manufac­ + turer date, MAC address, region of origin, etc. + +``` +Page 252 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- The Passcode generation process SHALL use a cryptographically secure random number gener­ + ator. + +If a device generates a dynamic Passcode, then it SHALL conform to the following additional rule: + +- Passcodes SHALL be accessible to commissioner only during the commissioning process. + +If a device cannot generate a dynamic Passcode, then the static Passcode SHALL conform to the fol­ +lowing additional rules: + +- A random passcode with 27 bits of entropy SHALL be generated and used for each individual + device. Because of the disallowed numbers, the entropy remaining in the actual setup code will + be somewhere between 26 bits and 27 bits but the initial value before rejecting disallowed num­ + bers SHALL have 27 bits of entropy. +- The device SHALL be supplied with the PAKE verifier in its internal storage. +- If the static passcode is also supplied to the device, the static passcode SHALL NOT be accessible + during operational mode using any data model attributes or commands. +- If the static passcode is supplied to the device, its storage location SHALL be physically isolated + from the location where the PAKE verifier is stored and SHALL only be accessible through local + interfaces and SHALL NOT be accessible to the executing unit handling the PAKE verifier. For + example, a device equipped with a NFC connected tag may contain the QR code containing the + static passcode in the NFC connected tag private memory and the NDEF record containing the + NFC tag onboarding payload is only presented to the commissioner during the commissioning + window through the NFC interface. + +**5.1.7.1. Invalid Passcodes** + +The following Passcodes SHALL NOT be used for the PASE protocol due to their trivial, insecure +nature: + +- 00000000 +- 11111111 +- 22222222 +- 33333333 +- 44444444 +- 55555555 +- 66666666 +- 77777777 +- 88888888 +- 99999999 +- 12345678 +- 87654321 + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 253 +``` + +**5.1.8. NFC Tag** + +A Commissioner MAY use, in addition to the QR Code Format and Manual Pairing Code as described +above, an NFC tag associated with a Commissionee to retrieve the Onboarding Payload. When an +NFC tag is used the following requirements are applicable. + +- The data contained in the NFC tag SHALL be the same as specified in QR Code Format. +- The NFC tag SHALL be one of the types as defined by _NFC Forum_. +- The NFC tag SHALL use the NFC Data Exchange Format (NDEF) as defined by NFC NDEF 1.0. +- The NFC tag SHALL use NDEF messages as defined by NFC RTD 1.0. +- The Onboarding Payload for the NFC tag SHALL use NDEF URI Record Type Definition as + defined by NFC RTD URI 1.0 and as specified in the following table. + +_Table 46. NFC NDEF Representation_ + +``` +Offset Content Description +0 0xD1 TNF=0x01, SR=1, MB=1, ME=1 +1 0x01 Length of Record Type +2 URI payload size in bytes Length of payload +3 0x55 Record Name ("U") +4 0x00 URI Identifier Code: No URI +abbreviation +5 URI data MT: +``` +**5.2. Initiating Commissioning** + +**5.2.1. Purpose and Scope** + +The process of Matter commissioning can be initiated by the User in a number of ways. This section +describes different user journeys supported by Matter. For each, a rationale is provided along with +a high-level flow description, up until the point where a commissioning secure session is estab­ +lished. References to sections describing dependent functionality in more detail are provided. + +The purpose of this section is to connect features provided in other sections to the user journeys for +which they are designed. + +### WARNING + +``` +The list of user journeys provided here is not meant to be exhaustive; there +may be other journeys not listed here which can be realized using Matter. +``` +This section provides rationales for Matter functionality and does NOT contain normative require­ +ments for Matter. + +The following User Journeys are described in this section: + +- Section 5.2.2.1, “Commissioner Setup Code Entry, Not Yet Commissioned Device”. "Launch Com­ + +``` +Page 254 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +missioner, Enter Code" +``` +- Section 5.2.2.2, “User-Initiated Beacon Detection, Not Yet Commissioned Device”. "Launch Com­ + missioner, Discover New Devices" +- Section 5.2.2.3, “User-Initiated Beacon Detection, Already Commissioned Device”. "Launch Com­ + missioner, Discover My devices" +- Section 5.2.2.4, “Commissioner Discovery, from an On-Network Device”. "Launch Device User + Interface, Discover Commissioners" + +**5.2.2. User Journey Details** + +**5.2.2.1. Commissioner Setup Code Entry, Not Yet Commissioned Device** + +"Launch Commissioner, Enter Code" + +In the Setup Code Entry for a Not Yet Commissioned Device use case, the User first initiates an inter­ +action with a Commissioner, and then provides the necessary setup code from the Commissionee, +by scanning an Onboarding Payload (e.g. QR Code) or otherwise inputting the manual setup code +through an input method supported by the commissioner. + +**5.2.2.1.1. Rationale** + +In this use case, the user will often have the device in-hand, have immediate access to the onboard­ +ing payload, and have immediate access to the desired Commissioner. + +**5.2.2.1.2. High Level Flow** + +1. User initiates an interaction with a Commissioner. +2. User inputs the onboarding payload from the Commissionee. +3. Commissioner determines which technologies to use for Device Discovery. When attempting to + locate the device on IP-bearing networks, the Commissionable Node Discovery method is used + and typically the DNS-SD service subtypes for long or short discriminator, and commissioning + mode (see Commissioning Subtypes) are specified to filter the results to Commissionees that + match the discriminator in the onboarding payload and that are in Commissioning Mode. When + attempting to locate the device via BLE advertisements, the discriminator will typically be used + to filter the results. +4. Commissioner begins the Commissioning process (see Section 5.5, “Commissioning Flows”). If + more than one Commissionee is discovered, the Commissioner may further refine the results + using any additional information such as a Vendor ID or Product ID that may be available in the + onboarding payload. If there is still more than one discovered Commissionee, the Commissioner + will typically attempt to establish a PASE secure commissioning session with each. + +**5.2.2.1.3. Misuse Considerations** + +When a device has a static onboarding payload, and the value is physically affixed to the product, it +is possible for an attacker with one-time physical access to the device to obtain the onboarding pay­ +load and use it to compromise the security of the device in the future. For example, if the device is +commissioned again using the same onboarding payload (for example, after a reset), then the + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 255 +``` + +attacker may be able to perform a person-in-the-middle attack which could result in a compromise +of sensitive user data such as network credentials if passed to the device. + +When a device includes device-specific information such as Vendor ID and Product ID in advertise­ +ments, then a malicious actor within advertisement range can detect this information and poten­ +tially associate it with the location of the device (and potentially, additional information about the +location, such as its residents) in ways that the user did not intend. + +**5.2.2.2. User-Initiated Beacon Detection, Not Yet Commissioned Device** + +"Launch Commissioner, Discover New Devices" + +In the User-Initiated Beacon Detection for a Not Yet Commissioned Device use case, the User first +initiates an interaction with a Commissioner, and then indicates an intention to commission +devices without providing additional information about them (no onboarding payload, etc). + +**5.2.2.2.1. Rationale** + +In this use case, the user has immediate access to a Commissioner. However, the user may not +know how to locate the onboarding payload (it may be hidden behind a panel, pin-protected in a +settings menu, or inaccessible on a device already physically installed). + +Example User interactions with the Commissioner include pushing a "Discover New Devices" but­ +ton, or speaking to a voice agent "Agent, discover new devices". + +**5.2.2.2.2. High Level Flow** + +1. User initiates an interaction with a Commissioner. +2. User indicates an intention to commission devices without providing additional information + about them. +3. Commissioner determines which technologies to use for Device Discovery. When attempting to + locate the device on IP-bearing networks, the Commissionable Node Discovery method is used + and typically the subtype for commissioning mode (see Commissioning Subtypes) is specified + with value 1 in order to filter the results to Commissionees that are in Commissioning Mode. +4. Commissioner constructs a list of Commissionees discovered, using as much information as pos­ + sible from the Commissionee advertisement. When a Vendor ID and Product ID is provided in + the advertisement, the Commissioner may obtain human readable descriptions of the Vendor + and Product in order to assist the user with selection by using fields such as ProductName and + ProductLabel from the Distributed Compliance Ledger or any other data set available to it. The + ledger entry may also include additional URLs which the Commissioner can offer to the user to + help in locating the Setup Code or otherwise assist in setting up the device such as the UserManu­ + alUrl, SupportUrl, and ProductUrl. The Commissioner may have additional data sets available for + assisting the user. +5. User selects Commissionee from list. +6. Commissioner instructs the user to locate and input the onboarding payload. +7. Commissioner begins the Commissioning process (see Section 5.5, “Commissioning Flows”). + +``` +Page 256 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.2.2.3. Variation - Filter by Device Type** + +The user may indicate the type of device to the Commissioner when initiating this flow. For exam­ +ple, the user might speak the following to a voice agent: "Agent, Discover TVs". + +When discovering TVs or any other specific device type on the IP network, this flow will be the +same except that a subtype which specifies the device type identifier (see Descriptor Cluster on root +node endpoint) is passed to the Commissionable Node Discovery method (see Commissioning Sub­ +types). + +**5.2.2.2.4. Misuse Considerations** + +In addition to the Misuse Considerations for the Section 5.2.2.2, “User-Initiated Beacon Detection, +Not Yet Commissioned Device”, a Commissioner which performs Device Discovery without knowl­ +edge of the Onboarding Payload may discover advertisements from devices that the user did not +intend to onboard with the given Commissioner. This additional information collected by the Com­ +missioner can be associated with the user in ways that the user did not intend. + +**5.2.2.3. User-Initiated Beacon Detection, Already Commissioned Device** + +"Launch Commissioner, Discover My Devices" + +In the User-Initiated Beacon Detection for an Already Commissioned Device use case, the User first +initiates an interaction with a Commissioner, and then indicates an intention to commission +devices already on the IP network without providing additional information about them. + +**5.2.2.3.1. Rationale** + +A Device may choose to be discoverable by entities on the local IP network, even when not in Com­ +missioning Mode, in order to satisfy specific user journeys. For example, a TV, Network Infrastruc­ +ture Manager, or Bridge device may choose to be discoverable in order to facilitate connectivity +with other Smart Home systems. One way for a device to be discoverable when not in Commission­ +ing Mode is to implement Extended Discovery. + +Example User interactions with the Commissioner include pushing a "Discover My Devices" button, +or speaking to a voice agent "Agent, discover my devices". + +**5.2.2.3.2. High Level Flow** + +1. User initiates an interaction with a Commissioner. +2. User indicates an intention to commission existing devices on the IP network. This may or may + not include additional information about them, such as a device type. +3. Commissioner performs Commissionable Node Discovery via DNS-SD. The subtype for device + type (see Commissioning Subtypes) can be specified in order to filter the results to Commis­ + sionees that have a specific primary function device type. +4. Commissioner constructs a list of Commissionees discovered, using as much information as pos­ + sible from the Commissionee advertisement. When a Vendor ID and Product ID is provided (see + Commissioning VID/PID), the Commissioner may obtain human readable descriptions of the + Vendor and Product in order to assist the user with selection by using fields such as ProductName + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 257 +``` + +``` +and ProductLabel from the Distributed Compliance Ledger or any other data set available to it. +The ledger entry may also include additional URLs which the Commissioner can offer to the +user to help in locating the Setup Code or otherwise assist in setting up the device such as the +UserManualUrl, SupportUrl, and ProductUrl. The Commissioner may have additional data sets +available for assisting the user. When the Device Type (see Commissioning Device Type) and/or +the Device Name (see Commissioning Device Name) values are provided, then the Commis­ +sioner may provide this information to the user in order to assist with Commissionee selection. +``` +5. User selects Commissionee from list. +6. The Commissionable Node Discovery DNS-SD TXT record for the selected Commissionee + includes key/value pairs that can help the Commissioner to guide the user through the next + steps of the commissioning process. +7. If the Commissioning Mode value (see Commissioning Mode) is set to 0, then the Commissionee + is not yet in Commissioning Mode and the Commissioner can guide the user through the steps + needed to put the Commissionee into Commissioning Mode. The Pairing Hint (see: Commission­ + ing Pairing Hint) and the Pairing Instruction (see: Commissioning Pairing Instruction) fields + would then indicate the steps that can be followed by the user to put the device into Commis­ + sioning Mode. When the Pairing Hint is present and its value has bit 1 set (Device Manufacturer + URL), then the Commissioner can utilize the URL specified in the CommissioningCustomFlowUrl of + the DeviceModel schema entry indexed by the Vendor ID and Product ID in the Distributed Com­ + pliance Ledger and utilize flows described in Custom Commissioning Flow to redirect the user + to a custom app or website specified by the device vendor, and receive the user back following + the callback flow which contains the onboarding payload. The Custom Commissioning Flow can + provide a deterministic user experience for putting the device into commissioning mode and + transferring the onboarding payload to the Commissioner. The Commissioner then verifies the + new Commissioning Mode state using Commissionable Node Discovery. +8. Commissioner instructs the user to locate and input the onboarding payload if needed. When a + Vendor ID and Product ID is available to the Commissioner, the Distributed Compliance Ledger + may also provide a URL for the Device User Guide which can contain additional information to + help in locating the onboarding payload. The Commissioner may have additional data sets avail­ + able for assisting the user. +9. Commissioner begins the Commissioning process (see Section 5.5, “Commissioning Flows”). + +**5.2.2.3.3. Variation - Filter by Device Type** + +A variation on this use case is when a user action causes the Commissioner to ask the user for per­ +mission to discover devices or to discover a specific type of device on the network, such as a TV for +remote controlling playback or a Home Router Access Point for managing network credentials. + +The user may indicate the type of device to the Commissioner when initiating this flow. For exam­ +ple, the user might speak the following to a voice agent: "Agent, Discover TVs". + +Example User interactions which are tied to discovery of specific device types include: + +1. When a user indicates their desire to use a specific Matter Admin/Commissioner, the Commis­ + sioner might attempt to discover devices of type Network Infrastructure Manager on the net­ + work, and prompt the user with instructions for connecting to it. + +``` +Page 258 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +2. When a user indicates their desire to use a specific Matter Video Remote Control, the Video + Remote Control might look for Video Players on the network, and prompt the user with instruc­ + tions for connecting to it. + +When discovering TVs or any other specific device type on the IP network, this flow will be the +same except that a subtype which specifies the device type identifier is passed to the Commission­ +able Node Discovery method (see Commissioning Subtypes). + +**5.2.2.3.4. Misuse Considerations** + +When a Device implements Commissionable Node Discovery while not in Commissioning Mode, the +time period during which it may unintentionally provide information to a malicious actor on the +network is longer than it otherwise would be. This additional information could potentially be asso­ +ciated with the user in ways that the user did not intend. See Commissionable Node Discovery Pri­ +vacy Considerations for device requirements relating to this risk. + +When a device includes device-specific information such as Vendor ID, Product ID and Device Type, +or user-generated data such as Device Name, in the DNS-SD TXT record, then a malicious actor on +the network can detect this information and potentially associate it with the user in ways that the +user did not intend. + +A Commissioner which performs Device Discovery without knowledge of the Onboarding Payload +may discover devices on the network that the user did not intend to onboard with the given Com­ +missioner. This additional information collected by the Commissioner can be associated with the +user in ways that the user did not intend. + +**5.2.2.4. Commissioner Discovery, from an On-Network Device** + +"Launch Device User Interface, Discover Commissioners" + +In the Commissioner Discovery use case for a Device already on the IP network, the User first initi­ +ates an interaction with the Device via a display or other user interface, and indicates the intention +to have this device commissioned by a Commissioner on the network. The Device might already +have been commissioned into one or many Fabrics or it might not yet have been commissioned. +Upon this user interaction, the Device discovers candidate Commissioners and allows the user to +select one. The Device then requests from that Commissioner to be commissioned. + +**5.2.2.4.1. Rationale** + +In this use case, a Device (Commissionee) with a user interface, such as a TV or Thermostat, initiates +the commissioning process. For example, this might be done from within a settings menu for Smart +Home control. The Device discovers Commissioners on the IP-bearing network, presents the result­ +ing list to the User for selection. Once selected, the Device indicates to the selected Commissioner +that it has been selected by the User, the Device enters Commissioning Mode and provides the +onboarding payload to the User. + +Another example for this use case is a Device or Node (Commissionee) with a user interface, such as +a Content Provider Device or Application, that initiates the commissioning process. This might be +done from a program guide or while watching a video when the user indicates a desire to play the +selected content on a nearby device. The Device discovers Commissioners on the IP-bearing net­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 259 +``` + +work, presents the resulting list to the User for selection. Once selected, the Commissionee indicates +to the selected Commissioner that it has been selected by the User (see User Directed Commission­ +ing), the Commissionee enters Commissioning Mode and provides the onboarding payload to the +User. + +**5.2.2.4.2. High Level Flow** + +1. User initiates an interaction with the Device. +2. User indicates a desire to connect this Device with a Commissioner on the network. +3. Device uses Commissioner Discovery over DNS-SD on the IP bearing network. +4. Device collects candidates from DNS-SD service records found. +5. Device displays list of Commissioners discovered, including as much information as possible + from the DNS-SD TXT record. When a Vendor ID and Product ID is provided (see Commissioning + VID/PID), the Device may obtain human readable descriptions of the Vendor and Product in + order to assist the user with selection by using fields such as ProductName and ProductLabel from + the Distributed Compliance Ledger or any other data set available to it. The Device may have + additional data sets available for assisting the user. When the Device Type (see Commissioning + Device Type) and/or the Device Name (see Commissioning Device Name) values are provided in + the DNS-SD TXT record, then the Device may provide this information to the user in order to + assist with Commissioner selection. +6. User selects an entry from the list. +7. Device enters Commissioning Mode. +8. Device displays onboarding payload to the user. +9. Device initiates a User Directed Commissioning session with the selected Commissioner, which + includes in the DNS-SD service name of the Device. + +10.Commissioner prompts user to confirm intention to commission this device and asks for +onboarding payload. + +11.User enters onboarding payload into Commissioner UX. + +12.Commissioner begins the commissioning process (see Section 5.5, “Commissioning Flows”). + +For additional variations relating to the display and input of the onboarding payload, see User +Directed Commissioning. + +**5.2.2.4.3. Misuse Considerations** + +In addition to the Misuse Considerations for the Section 5.2.2.3, “User-Initiated Beacon Detection, +Already Commissioned Device”, a Commissionee which performs Commissioner Discovery may dis­ +cover Commissioners on the network that the user did not intend to be discovered by the given +Commissionee. This additional information collected by the Commissionee can be associated with +the user in ways that the user did not intend. See Commissioner Discovery Privacy Considerations +for Commissioner requirements relating to this risk. + +Since there are no trust mechanisms employed for Commissioners advertising themselves, Commis­ +sionees may provide Commissioner selection choices to the User that are from malicious entities +masquerading as commissioners. + +``` +Page 260 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +When a Commissioner includes device-specific information such as Vendor ID, Product ID and +Device Type, or user-generated data such as Device Name, in the DNS-SD TXT record, then a mali­ +cious actor on the network can detect this information and potentially associate it with the user in +ways that the user did not intend. + +**5.3. User Directed Commissioning** + +**5.3.1. Overview** + +In User Directed Commissioning (UDC), the Commissionee sends a message to the Commissioner in +order to initiate the commissioning process (see Section 5.5, “Commissioning Flows”). In addition, +the Commissionee can specify its UX preferences for the commissioning session using optional +parameters in the message. Similarly, the Commissioner can send a message to the Commissionee +to indicate its pre-commissioning state in order to help the Commissionee simplify the experience +for the user. + +The availability of the UDC protocol is advertised through Commissioner Discovery service records +of DNS-SD service type _matterd._udp (see Section 4.3.3, “Commissioner Discovery”). + +Overall, the UDC protocol is a lightweight "door bell" message sent by a Commissionee. There is no +state or session associated with UDC protocol messages, allowing the recipient to choose to support +messages received from different sources at the same time, or choose to ignore messages received +while the processing of an earlier message has not completed. The UDC protocol consists of an Iden­ +tification Declaration which provides the Commissionee’s _matterc._udp DNS‑SD service instance +name. In addition, Identification Declaration MAY include optional information relating to the +requested commissioning session. + +Upon receiving this message, the Commissioner MAY query the DNS-SD service instance indicated +in the Identification Declaration, including TXT records, in order to obtain additional information +about the Commissionee, MAY obtain the corresponding Onboarding Payload or Passcode from the +user for this Commissionee, and MAY initiate the commissioning process with it. + +The Commissioner MAY send a CommissionerDeclaration to the Identification Declaration message +sender’s source IP and Port. The CommissionerDeclaration provides information to a Commissionee +indicating the Commissioner’s pre-commissioning state, which MAY be used by the Commissionee +to simplify the Passcode entry user experience. + +Upon receiving this message, the Commissionee MAY provide instructions to the user about how to +proceed to the next steps in the commissioning process, for example, by displaying a Passcode to +the user, and instructing them to provide it to the Commissioner. + +While a sequence of these messages between Commissionee and Commissioner can be used to +achieve a specific user experience, as the examples below illustrate, the processing of each message +is expected to stand alone and not be dependent upon other messages in the sequence. For this rea­ +son there is no use of session or exchange identifiers, and no encryption of the messages. Conse­ +quently, there are no guarantees of behavior or acknowledgements, information contained in mes­ +sages SHOULD be assumed to be visible to the network, and messages SHALL NOT contain private +or sensitive information. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 261 +``` + +The Commissionee and Commissioner SHALL enforce rate limiting of these messages and provide +the option for the user to disable handling of them (either temporarily or until manually re- +enabled). For example, a rate limiting algorithm of accepting no more than 20 messages (not includ­ +ing retries) in a 10 minute period is recommended. + +One possible user journey for this feature is described in Commissioner Discovery from an Existing +Device. + +_Figure 30. Overview of the UDC Protocol Identification Declaration message_ + +The Commissionee is the Initiator and the Commissioner is the Recipient of the IdentificationDecla­ +ration message. + +_Figure 31. Overview of the UDC Protocol Commissioner Declaration message_ + +The Commissioner is the Initiator and the Commissionee is the Recipient of the CommissionerDec­ +laration message. + +It is assumed that the user has directed the Initiator to send the IdentificationDeclaration message +to the Recipient. Upon receipt and before starting a PASE session with the Initiator, it is assumed +that the Recipient will obtain DNS-SD record information (including TXT records) for the Initiator, +which was either provided in the IdentificationDeclaration message or can be obtained by querying +the DNS-SD records, and then prompt the user for approval and to enter its Onboarding Payload or +Passcode. + +**5.3.2. UDC Protocol Messages** + +_Table 47. User Directed Commissioning Protocol_ + +``` +Protocol +Opcode +``` +``` +Protocol Command +Name +``` +``` +Description +``` +``` +Protocol ID = PROTOCOL_ID_USER_DIRECTED_COMMISSIONING +0x00 IdentificationDeclaration The Identification Declaration message provides the DNS- +SD Instance Name of the commissionee requesting com­ +missioning to the commissioner selected by the user. It can +also include information relating to the requested commis­ +sioning session. +``` +``` +Page 262 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Protocol +Opcode +``` +``` +Protocol Command +Name +``` +``` +Description +``` +``` +0x01 CommissionerDeclaration The Commissioner Declaration message provides informa­ +tion to a commissionee from the commissioner indicating +its pre-commissioning state. This information can be used +by the commissionee to simplify the Passcode entry flow +for the user. +``` +**5.3.3. Message format** + +All UDC messages SHALL be structured as specified in Section 4.4, “Message Frame Format”. + +All UDC messages are unsecured at the message layer: + +- The Session ID field SHALL be set to 0. +- The Session Type bits of the Security Flags SHALL be set to 0. +- The S Flag and DSIZ fields of the Message Flags SHALL be set to 0. + +The R Flag of the Exchange Flags for the UDC messages SHALL be set to 0. + +For each UDC message, the application payload is the TLV encoding of the message structure as +defined below: + +_Table 48. UDC Messages_ + +``` +Message Name Payload TLV Encoding +IdentificationDeclaration IdentificationDeclaration-struct +CommissionerDeclaration CommissionerDeclaration-struct +``` +The other fields of the Message format are not specific to the UDC messages. + +**5.3.4. Message Exchanges** + +The flags of the Exchange Flags of the Protocol Header are defined as follows per UDC message: + +``` +Message I Flag +IdentificationDeclaration 1 +CommissionerDeclaration 1 +``` +All UDC IdentificationDeclaration messages SHALL be sent without acknowledgement (e.g., unreli­ +ably) using UDP, to an IP address found in a A or AAAA record associated with the Commissioner +Discovery (_matterd._udp) service, using UDP with a destination port as found in the _matterd._udp +SRV record. + +All UDC CommissionerDeclaration messages SHALL be sent without acknowledgement (e.g., unreli­ +ably) using UDP, to the source IP address of the sender of IdentificationDeclaration message, and +the port specified in the IdentificationDeclaration message payload. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 263 +``` + +The Initiator MAY send up to 4 retries. Each retransmission SHALL be delayed by at least 100 ms +from the previous transmission. + +The other fields of the Protocol Header are not specific to the UDC messages. + +**5.3.5. IdentificationDeclaration Message** + +This message serves to identify the Commissionee. It can also specify information relating to the +requested commissioning session, such as whether to display a Passcode entry dialog. It is sent by +the Commissionee to the Commissioner. + +In addition to a mandatory instanceName field, which can be used by the Commissioner to perform +Commissionable Node Discovery in order to determine the service IP and Port used to establish a +PASE session with the Commissionee, there are a number of optional fields in the IdentificationDec­ +laration which can be used by the Commissionee to improve performance and usability of the user +experience. + +The payload for the IdentificationDeclaration message begins with 17 bytes which consist of the +DNS-SD instance name defined in Commissionable Node Discovery encoded as 16 characters of +ascii text, followed by a null termination character. + +Following the 17 bytes is the encoded IdentificationDeclaration-struct TLV. + +``` +instanceName : OCTET STRING [ length 17 ] +IdentificationDeclaration-struct => STRUCTURE [ tag-order ] +{ +VendorId [1, optional] : UNSIGNED INTEGER [ range 16-bits ], +ProductId [2, optional] : UNSIGNED INTEGER [ range 16-bits ], +DeviceName [3, optional] : STRING [ length 0..32 ], +DeviceType [4, optional] : UNSIGNED INTEGER [ range 32-bits ], +PairingInstruction [5, optional] : STRING [ length 0..32 ], +PairingHint [6, optional] : UNSIGNED INTEGER [ range 32-bits ], +RotatingDeviceId [7, optional] : STRING [ length 0..100 ]. +Port [8, optional] : UNSIGNED INTEGER [ range 16-bits ], +TargetAppList [9, optional] : ARRAY OF +{ +TargetApp [10, optional] : STRUCTURE [ tag-order ] +{ +AppVendorId [11, optional] : UNSIGNED INTEGER [ range 16-bits ], +AppProductId [12, optional] : UNSIGNED INTEGER [ range 16-bits ], +}, +}, +NoPasscode [13, optional] : BOOLEAN, +CdUponPasscodeDialog [14, optional] : BOOLEAN, +CommissionerPasscode [15, optional] : BOOLEAN, +``` +``` +Page 264 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +CommissionerPasscodeReady [16, optional] : BOOLEAN, +CancelPasscode [17, optional] : BOOLEAN +} +``` +**5.3.5.1. Features** + +**5.3.5.1.1. Bypass Commissionable Node Discovery** + +In practice, the Commissionable Node Discovery step performed by the Commissioner in response +to receiving an IdentificationDeclaration can incur 1 second or more of latency. A Commissionee +can provide the same information that a Commissioner would obtain through Commissionable +Node Discovery by providing this data in the IdentificationDeclaration message. + +The Commissioner MAY bypass the Commissionable Node Discovery step of the Commissioner Dis­ +covery from an Existing Device process when it receives the information it needs in the Identifica­ +tionDeclaration message, namely, the Port field. The Commissionee MAY also include VendorId, Pro­ +ductId, DeviceName, DeviceType, PairingInstruction, PairingHint, and RotatingDeviceId fields in the +IdentificationDeclaration message, similar to the existence of these fields in the DNS-SD Commis­ +sionable Node Discovery response. + +See UDC With Commissionable Node Discovery Bypass. + +**5.3.5.1.2. Target Content Application** + +In some cases, the Commissionee prefers to determine in advance of commissioning if their Content +Application is present on the Commissioner (see Device Library, section 10 _Media Device Types_ ). +This allows the Commissionee to warn the user when an experience with reduced functionality will +result from commissioning, and may cause the Commissionee or the user to choose not to proceed +with the user-directed-commissioning flow. + +Some Commissionees will choose not to proceed with the user-directed-commissioning flow if their +app is not present for cases where the user experience requires their app, such as when a casting +video client app is designed for communication with a specific content app on a casting video +player. + +The NoPasscode field allows the Commissionee to determine if their app is present but has a differ­ +ent account active in it. Some Commissionees do not support guest mode, or multiple simultaneous +accounts in their app. In this scenario, the Commissionee might ask the user to switch accounts on +the Commissioner in order to proceed. + +When the Commissionee provides the VidList, the Commissioner SHALL apply this list as a further +restriction upon the set of Content Application Vendor IDs that can be used for authentication (see +AccountLogin cluster). + +See UDC With Targeted App Selection. + +**5.3.5.1.3. Coordinate Passcode Dialogs** + +In some cases, the Passcode needed for commissioning is obtained from a Content App running on +the Commissioner by way of the AccountLogin cluster. When the Passcode is obtained in this fash­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 265 +``` + +ion, no Passcode display on the Commissionee is required, and displaying a Passcode can be confus­ +ing for the user. + +To address this, the Commissionee can request to be told by the Commissioner when it is requesting +a Passcode from the user (so that the Commissionee can display the Passcode) by using the CdUpon­ +PasscodeDialog field in the IdentificationDeclaration message. The Commissioner would then send a +CommissionerDeclaration message to indicate that a Passcode is needed. + +The Commissionee can also inform the Commissioner that the user has declined or exited the com­ +missioning process by using the CancelPasscode field in the IdentificationDeclaration message. + +See UDC With Coordinated Passcode. + +**5.3.5.1.4. Commissioner-Generated Passcode** + +In some scenarios, it is simpler for the user to enter a Passcode into the Commissionee UX than it is +to enter a Passcode into a Commissioner UX. For example, when the Commissionee is a mobile +phone app and the Commissioner is a TV, it can be easier to enter a Passcode on a mobile phone +than a TV remote control (which might not have number buttons). + +In this scenario, the Commissioner generates a Passcode and displays it for the user. The user +enters the Passcode into the Commissionee UX. The Commissionee UX generates a PASE verifier +based upon this Passcode and enters commissioning mode using this PASE verifier. The Commis­ +sionee then notifies the Commissioner that it is in commissioning mode (using the new PASE veri­ +fier) by sending a IdentificationDeclaration with the CommissionerPasscodeReady field set to true. + +If, in addition to dynamic passcodes, the Commissioner provides a fixed passcode option, it SHALL +be user-updatable and the Commissioner SHALL provide an option to the user to reset the fixed +passcode frequently, and SHALL provide an option to disable the fixed passcode feature. + +A Commissioner indicates that it supports this feature via the CP txt record in Commissionable Node +Discovery. + +A Commissionee can utilize this feature via the CommissionerPasscode and CommissionerPasscodeReady +fields. + +The Commissionee can also inform the Commissioner that the user has declined or exited the com­ +missioning process by using the CancelPasscode field in the IdentificationDeclaration message. + +See UDC With Commissioner Passcode. + +**5.3.5.2. Parameters** + +This following table lists the parameters used in IdentificationDeclaration with a brief description +for each parameter and the feature that uses it. + +_Table 49. List of IdentificationDeclaration parameters_ + +``` +Page 266 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Parameter +Name** + +``` +Feature Description +``` +instanceName Always Required The DNS-SD instance name defined in +Commissionable Node Discovery. + +VendorId Bypass Commissionable Node Discov­ +ery + +``` +The Vendor ID provided as input to the +mdns TXT records (see TXT key for Vendor +ID and Product ID). +``` +ProductId Bypass Commissionable Node Discov­ +ery + +``` +The Product ID provided as input to the +mdns TXT records (see TXT key for Vendor +ID and Product ID). +``` +DeviceName Bypass Commissionable Node Discov­ +ery + +``` +The device name as described in the mdns +TXT records (see TXT key for device name). +``` +DeviceType Bypass Commissionable Node Discov­ +ery + +``` +The device type as described in the mdns +TXT records (see TXT key for device type). +``` +PairingInstruc­ +tion + +``` +Bypass Commissionable Node Discov­ +ery +``` +``` +The pairing instruction as described in the +mdns TXT records (see TXT key for pairing +instruction). +``` +PairingHint Bypass Commissionable Node Discov­ +ery + +``` +The pairing hint as described in the mdns +TXT records (see TXT key for pairing hint). +``` +RotatingDevi­ +ceId + +``` +Bypass Commissionable Node Discov­ +ery +``` +``` +The Rotating Device Identifier as described +in the mdns txt records (see TXT key for +rotating device identifier). +``` +Port Bypass Commissionable Node Discov­ +ery + +``` +The service port for PASE as found in the +SRV record of the DNS-SD Commissionable +Node Discovery response. +``` +TargetAppList Target Content Application The set of content app Vendor IDs (and +optionally, Product IDs) that can be used +for authentication. + +TargetApp Target Content Application An entry in the TargetAppList which con­ +tains a TargetVendorId and an optional +TargetProductId. + +AppVendorId Target Content Application The content app Vendor IDs that can be +used for authentication. + +AppProductId Target Content Application The content app Product ID associated +with the specified Vendor ID that can be +used for authentication. + +NoPasscode Target Content Application Flag to instruct the Commissioner not to +display a Passcode input dialog, and +instead send a CommissionerDeclaration +message if a commissioning Passcode is +needed. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 267 +``` + +``` +Parameter +Name +``` +``` +Feature Description +``` +``` +CdUponPass­ +codeDialog +``` +``` +Coordinate Passcode Dialogs Flag to instruct the Commissioner to send a +CommissionerDeclaration message when +the Passcode input dialog on the Commis­ +sioner has been shown to the user. +Commissioner­ +Passcode +``` +``` +Commissioner-Generated Passcode Flag to instruct the Commissioner to use +the Commissioner-generated Passcode for +commissioning. +Commissioner­ +PasscodeReady +``` +``` +Commissioner-Generated Passcode Flag to indicate whether or not the Com­ +missionee has obtained the Commissioner +Passcode from the user and is therefore +ready for commissioning. +CancelPass­ +code +``` +``` +Coordinate Passcode Dialogs Flag to indicate when the Commissionee +user has decided to exit the commissioning +process. +``` +To send a IdentificationDeclaration message, the Commissionee SHALL: + +1. Construct the instanceName based upon the DNS-SD instance name defined in Commissionable + Node Discovery. +2. To optionally allow the Commissioner to bypass the Commissionable Node Discovery request: + a.Construct the Port from the service port for PASE as found in the SRV record of the DNS-SD + Commissionable Node Discovery response. +b. Optionally, construct the VendorId value as described as input to the TXT key for Vendor ID +and Product ID. +c.Optionally, construct the ProductId value as described as input to the TXT key for Vendor ID +and Product ID. +d. Optionally, construct the DeviceName value as described in TXT key for device name. +e. Optionally, construct the DeviceType value as described in TXT key for device type. +f. Optionally, construct the PairingInstruction value as described in TXT key for pairing +instruction. +g. Optionally, construct the PairingHint value as described in TXT key for pairing hint. +h. Optionally, construct the RotatingDeviceId value as described in TXT key for rotating device +identifier. +3. Optionally, construct the TargetAppList based upon the set of content app vid/pids that can be + used for authentication. This is a subset of vid/pid selected by the Commissioner based upon the + vid/pid of the client. +4. To optionally prevent the Commissioner from automatically showing a Passcode dialog: + a.Construct NoPasscode and set to true to indicate that this message SHOULD only trigger a + commissioning session if it can be done without asking the user to input a Passcode (eg. the + Passcode was provided by external means). When this field is set to true in the Identifica­ + +``` +Page 268 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +tionDeclaration message, the Commissioner SHALL NOT show a Passcode dialog to the user. +Instead, the Commissioner SHOULD send a CommissionerDeclaration message with the +NeedsPasscodeDialog field set to true (and potentially NoAppsFound to indicate the reason). +The Commissionee can then choose whether to prompt a Passcode dialog (by re-sending the +IdentificationDeclaration message without this field) or to abandon this commissioning +attempt. +``` +5. To optionally request that the Commissioner send a CommissionerDeclaration message to serve + as an indication that the Commissioner has presented a Passcode dialog to the user: + a. Construct the CdUponPasscodeDialog and set to true. When this field is set to true in the Identi­ + ficationDeclaration message, the Commissioner SHOULD send a CommissionerDeclaration + message with the PasscodeDialogDisplayed set to true upon showing the Passcode input dia­ + log to the user. This field SHALL NOT be set when the CommissionerPasscode field is set + since these two functionalities are mutually exclusive. +6. To optionally request a Commissioner-generated Passcode from a Commissioner which indi­ + cates support for this feature via the CP TXT record in Commissionable Node Discovery: + a. Construct the CommissionerPasscode and set to true. When this field is set to true in the Identi­ + ficationDeclaration message, the Commissioner SHOULD display the commissioning Pass­ + code to the user, and wait to initiate commissioning until an IdentificationDeclaration mes­ + sage is received with the CommissionerPasscodeReady field set to true. + b. Construct the CommissionerPasscodeReady and set to true to indicate the Commissionee has + obtained the Commissioner Passcode from the user and is ready for commissioning, or false + to indicate that the user has not entered the Passcode yet, and therefore, the Commissioner + SHOULD NOT commence commissioning. +7. To optionally indicate that the Commissionee user has cancelled the commissioning process: + a. Construct the CancelPasscode and set to true. This indicates that the Commissioner can dis­ + miss any dialogs corresponding to commissioning, such as a Passcode input dialog or a Pass­ + code display dialog. +8. Construct and send IdentificationDeclaration. + +**5.3.6. CommissionerDeclaration Message** + +This message is sent by a Commissioner to a Commissionee in response to a IdentificationDeclara­ +tion message. The CommissionerDeclaration provides information indicating the Commissioner’s +pre-commissioning state. + +``` +CommissionerDeclaration-struct => STRUCTURE [ tag-order ] +{ +ErrorCode [1, optional] : UNSIGNED INTEGER [ range 16-bits ], +NeedsPasscode [2, optional] : BOOLEAN, +NoAppsFound [3, optional] : BOOLEAN, +PasscodeDialogDisplayed [4, optional] : BOOLEAN, +CommissionerPasscode [5, optional] : BOOLEAN, +QRCodeDisplayed [6, optional] : BOOLEAN +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 269 +``` + +``` +CancelPasscode [7, optional] : BOOLEAN +} +``` +**5.3.6.1. Parameters** + +This following table lists the parameters used in IdentificationDeclaration with a brief description +for each parameter and the feature that uses it. + +_Table 50. List of IdentificationDeclaration parameters_ + +``` +Parameter +Name +``` +``` +Feature Description +``` +``` +ErrorCode All Indicates errors incurred during commis­ +sioning. +NeedsPasscode Coordinate PIN Dialogs When NoPasscode field set to true, and the +Commissioner determines that a Passcode +code will be needed for commissioning. +NoAppsFound Target Content Application No apps with AccountLogin cluster imple­ +mentation were found for the last Identifi­ +cationDeclaration request. Only apps +which provide access to the vendor id of +the Commissionee will be considered. +PasscodeDi­ +alogDisplayed +``` +``` +Coordinate PIN Dialogs A Passcode input dialog is now displayed +for the user on the Commissioner. +Commissioner­ +Passcode +``` +``` +Commissioner-Generated Passcode A Passcode is now displayed for the user +by the Commissioner. +QRCodeDis­ +played +``` +``` +Commissioner-Generated Passcode The user experience conveying a Passcode +to the user also displays a QR code. +CancelPass­ +code +``` +``` +Coordinate Passcode Dialogs Flag to indicate whether the Commissioner +user has decided to exit the commissioning +process. +``` +The allowed values for the ErrorCode field are the following + +``` +Code Description +0 No error +1 Commissionable Node discovery failed +2 PASE connection failed +3 PASE authentication failed (bad Passcode) +4 DAC validation failed +5 Already on fabric +6 Operational Node discovery failed +``` +``` +Page 270 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Code Description +7 CASE connection failed +8 CASE authentication failed +9 Configuration failed +10 Binding Configuration failed +11 Commissioner Passcode not supported +12 Invalid UDC parameters +13 App Install Consent Pending +14 App Installing +15 App Install Failed +16 App Installed Retry Needed +``` +To send a CommissionerDeclaration message, the Commissioner SHALL: + +1. Construct the ErrorCode field if an error condition has been encountered during commissioning + by the Commissioner. +2. When the IdentificationDeclaration message includes the NoPasscode field set to true, and the + Commissioner determines that a Passcode code will be needed for commissioning: + a. Construct the NeedsPasscode and set to true. +3. Optionally, construct the NoAppsFound and set to true to indicate that no apps with AccountLogin + cluster implementation were found for the last IdentificationDeclaration request. Only apps + which provide access to the vendor id of the Commissionee will be considered. +4. When the IdentificationDeclaration message includes the CdcForPasscode field set to true: + a. Construct the PasscodeDialogDisplayed and set to true to indicates that a Passcode input dia­ + log is now displayed for the user on the Commissioner. Upon receipt, the Commissionee + SHOULD display its Passcode to the user. This field SHALL NOT be set when the Commission­ + erPasscode field is set because these fields are mutually exclusive. +5. When the IdentificationDeclaration message includes the CommissionerPasscode field set to + true: + a. Construct the CommissionerPasscode and set to true to indicates that a Passcode is now dis­ + played for the user by the Commissioner. Upon receipt, the Commissionee SHOULD ask the + user to input this Passcode into the Commissionee, the Commissionee SHOULD then update + its PAKE Verifier so that it uses this Passcode, and then SHOULD send an IdentificationDecla­ + ration message with the CommissionerPasscodeReady field set to true. + b. Optionally, construct QRCodeDisplayed and set to true to indicates that the Passcode displayed + on the Commissioner includes a QR code option. Clients have the option of letting the user + scan via the phone camera. +6. Construct and send CommissionerDeclaration. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 271 +``` + +**5.3.7. Example Message Exchanges** + +**5.3.7.1. Regular UDC** + +For reference. + +1. UDC with IdentificationDeclaration sent to Commissioner +2. Commissioner reads instanceName, performs Commissionable Node Discovery to determine + vid, pid, rotating ID, Device name, PASE IP, PASE Port +3. Commissioner prompts user for permission to commission Device name +4. User approves +5. Commissioner checks for apps granting access to the vid of the Commissionee, applies a filter on + this list if the VidList in the IdentificationDeclaration is populated, and attempts to use Account + Login on any resulting apps in order to obtain Passcode using rotatingID +6. If no Passcode is obtained, Commissioner prompts user to input Passcode from Commissionee +7. Commissioner attempts to commission Commissionee + +**5.3.7.2. UDC with Commissionable Node Discovery bypass** + +This saves about 1 second of latency in practice due to skipping second step (Commissionable Node +Discovery) in Regular UDC. + +1. UDC with IdentificationDeclaration containing VendorId, ProductId, RotatingDeviceId and Port + sent to Commissioner +2. Commissioner prompts user for permission to commission Device name +3. User approves +4. Commissioner checks for apps granting access to the vid of the Commissionee, applies a filter on + this list if the VidList in the IdentificationDeclaration is populated, and attempts to use Account + Login on any resulting apps in order to obtain Passcode using rotatingID +5. If no Passcode is obtained, Commissioner prompts user to input Passcode from Commissionee +6. Commissioner attempts to commission Commissionee + +**5.3.7.3. UDC with coordinated Passcode prompt** + +This allows the Commissionee to wait to display the Passcode until it receives a signal from the +Commissioner that a Passcode is needed. When the same user account is active on both the Com­ +missionee (often, in a phone app) and the Commissioner (often, in a TV app), then the commission­ +ing process can often complete without requiring the Commissionee to display a Passcode. When no +Passcode is required, it can be confusing for the user if the Commissionee shows a Passcode. To +address this, the Commissionee can request to be told by the Commissioner when it’s Passcode +input dialog is displayed to the user by sending the IdentificationDeclaration message with the +CdUponPasscodeDialog set to true. Then, when a Passcode is needed, the Commissioner sends a +CommissionerDeclaration with the NeedsPasscode set to true. + +``` +Page 272 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +5.3.7.3.1. UDC with coordinated Passcode prompt, no Passcode needed +``` +1. UDC with IdentificationDeclaration sent to Commissioner containing CdUponPasscodeDialog set + to true +2. If Port not provided, then Commissioner reads instanceName, performs Commissionable Node + Discovery to determine vid, pid, rotating ID, Device name, PASE IP, PASE Port +3. Commissioner prompts user for permission to commission Device name +4. User approves +5. Commissioner checks for apps granting access to the vid of the Commissionee, applies a filter on + this list if the VidList in the IdentificationDeclaration is populated, and attempts to use Account + Login on any resulting apps in order to obtain Passcode using rotatingID +6. Passcode is obtained, no need for Commissioner to prompt user to input Passcode from Com­ + missionee +7. Commissioner attempts to commission Commissionee + +``` +5.3.7.3.2. UDC with coordinated Passcode prompt, Passcode is needed +``` +1. UDC with IdentificationDeclaration sent to Commissioner containing CdUponPasscodeDialog set + to true +2. If Port not provided, then Commissioner reads instanceName, performs Commissionable Node + Discovery to determine vid, pid, rotating ID, Device name, PASE IP, PASE Port +3. Commissioner prompts user for permission to commission Device name +4. User approves +5. Commissioner checks for apps granting access to the vid of the Commissionee, applies a filter on + this list if the VidList in the IdentificationDeclaration is populated, and attempts to use Account + Login on any resulting apps in order to obtain Passcode using rotatingID +6. No Passcode is obtained, Commissioner prompts user to input Passcode from Commissionee +7. Commissioner sends CommissionerDeclaration with the PasscodeDialogDisplayed set to true +8. Commissionee displays Passcode code for user +9. User enters Passcode code into Commissioner +10. Commissioner attempts to commission Commissionee + +``` +5.3.7.4. UDC with no Passcode prompt (targeted app selection) +``` +``` +This allows the Commissionee to determine if their app is present on the Commissioner. Some Com­ +missionees will choose not to proceed with commissioning if their app is not present for cases +where the user experience requires their app. +``` +``` +This also allows the Commissionee to determine if their app is present but has a different account +active in it. Some Commissionees do not support guest mode, or multiple simultaneous accounts in +their app. In this scenario, the Commissionee might ask the user to switch accounts on the Commis­ +sioner in order to proceed. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 273 +``` + +**5.3.7.4.1. UDC with no app present** + +1. UDC with IdentificationDeclaration sent to Commissioner containing NoPasscode set to true +2. If Port not provided, then Commissioner reads instanceName, performs Commissionable Node + Discovery to determine vid, pid, rotating ID, Device name, PASE IP, PASE Port +3. Commissioner prompts user for permission to commission Device name +4. User approves +5. Commissioner checks for apps granting access to the vid of the Commissionee, applies a filter on + this list if the VidList in the IdentificationDeclaration is populated, and attempts to use Account + Login on any resulting apps in order to obtain Passcode using rotatingID +6. No app is found +7. Commissioner sends CommissionerDeclaration with the NoAppsFound and NeedsPasscode + fields set to true +8. Commissionee informs user that given Commissioner does not support its app. Provides addi­ + tional instructions as needed. + +**5.3.7.4.2. UDC with mismatched account** + +1. UDC with IdentificationDeclaration sent to Commissioner containing NoPasscode set to true +2. If Port not provided, then Commissioner reads instanceName, performs Commissionable Node + Discovery to determine vid, pid, rotating ID, Device name, PASE IP, PASE Port +3. Commissioner prompts user for permission to commission Device name +4. User approves +5. Commissioner checks for apps granting access to the vid of the Commissionee, applies a filter on + this list if the VidList in the IdentificationDeclaration is populated, and attempts to use Account + Login on any resulting apps in order to obtain Passcode using rotatingID +6. App is found but does not return Passcode +7. Commissioner sends CommissionerDeclaration with the NeedsPasscode field set to true +8. Commissionee informs user that its app has a different active account. Provides additional + instructions as needed. + +**5.3.7.5. UDC with Commissioner-generated Passcode** + +This allows the Commissionee to utilize a Passcode code generated and displayed on the Commis­ +sioner, and input by the user into the Commissionee, rather than the Regular UDC flow where the +Passcode code is generated and displayed on the Commissionee, and input by the user into the Com­ +missioner. This flow can simplify the user experience when the Commissionee is a mobile phone +app and the Commissioner is a TV since it can be easier to enter a Passcode on a mobile phone than +a TV. + +1. Commissionee performs Commissioner Discovery, prompts user to select a Commissioner. +2. Selected Commissioner indicates support for Commissioner Passcode feature (CP=1) in its DNS- + SD TXT record. + +``` +Page 274 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +3. UDC with IdentificationDeclaration sent to Commissioner containing CommissionerPasscode set + to true +4. If Port not provided, then Commissioner reads instanceName, performs Commissionable Node + Discovery to determine vid, pid, rotating ID, Device name, PASE IP, PASE Port +5. Commissioner prompts user for permission to commission Device name +6. User approves +7. Commissioner checks for apps granting access to the vid of the client, applies a filter on this list + if the VidList in the IdentificationDeclaration is populated, and attempts to use Account Login + on any resulting apps in order to obtain Passcode using rotatingID +8. If no Passcode is obtained, Commissioner displays a Passcode +9. Commissioner sends CommissionerDeclaration with PasscodeDialogDisplayed and Commission­ + erPasscode set to true. If a QR code is also displayed, then QRCodeDisplayed is also set to true. +10. Commissionee prompts user to input Passcode from Commissioner +11. Commissionee generates a PAKE verifier using input Passcode, enters commissioning mode +using this PAKE verifier +12. Commissionee sends IdentificationDeclaration to Commissioner containing CommissionerPass­ +code and CommissionerPasscodeReady set to true +13. Commissioner attempts to commission Commissionee using Passcode + +**5.4. Device Discovery** + +**5.4.1. Purpose and Scope** + +``` +The purpose of this section is to describe the process by which a device is discovered in order to +commission it onto an operational Fabric. +``` +``` +Depending on the networking technologies supported by a device, discovery and commissioning +are possible using Bluetooth Low Energy (BLE), Wi-Fi (IEEE 802.11-2020) technologies, or over IP if +a device is already on an IP network. +``` +``` +Devices that utilize Thread networking technology SHALL support BLE for the purpose of discovery +and commissioning. Thread network commissioning procedures as defined in Thread are not used +to perform Matter discovery and commissioning. +``` +``` +BLE commissioning utilizes the Generic Access Profile (GAP) for discovery and for connection +establishment, and the Generic Attribute Profile (GATT) for credential conveyance. +``` +``` +Wi-Fi Public Action Frame commissioning utilizes Wi-Fi Alliance Unsynchronized Service Discovery +(WFA-USD) for discovery, peer-to-peer communication, and credential conveyance. +``` +``` +WFA-USD is a mechanism for link layer discovery and direct communication between the Commis­ +sioner and the device without an 802.11 association between them. It uses the publish and sub­ +scribe public action frames for discovery between the Commissioner and the device. After discov­ +ery, the Commissioner and the device use follow-up public action frames for credential conveyance +and commissioning messages exchange. The publish, subscribe, and follow-up public action frames +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 275 +``` + +are defined by the Wi-Fi Alliance. Devices that support commissioning over Wi-Fi Public Action +Frame SHALL support such commissioning on all Wi-Fi bands they support. + +### NOTE + +``` +Since support for commissioning via Wi-Fi Public Action Frame is a new feature, it +might not be supported by the user’s choice of Commissioner. Therefore, devices +whose only Matter-defined commissioning method uses Wi-Fi Public Action Frame, +and which are being certified in the first 2 years following the release of the Matter +1.4 Specification, SHALL support the Commissioning Fallback Mechanism. +``` +If a device already has IP-bearing network connectivity (over Wi-Fi, Ethernet, or otherwise), a Com­ +missioner SHALL discover such a device using DNS-based Service Discovery (DNS-SD), conveying +credentials to the device over IP. + +**5.4.2. Announcement by Device** + +This section describes how devices announce their commissionable status to allow a Commissioner +to discover the device to be commissioned. + +**5.4.2.1. Announcement and Discovery Using Multiple Technologies** + +A device SHALL announce on all of the networking technologies it supports as indicated in the Dis­ +covery Capability Bitmask (see Table 40, “Discovery Capabilities Bitmask”). A Commissioner that is +aware of the device’s Discovery Capability Bitmask SHALL initiate Device Discovery on all of the +networking technologies that are supported by both the Commissioner and the device. A Commis­ +sioner that is unaware of the device’s Discovery Capability Bitmask SHALL initiate Device Discov­ +ery on all of the networking technologies it supports out of Wi-Fi Public Action Frame, BLE, and on +IP network discovery. + +Commissioners SHALL always support discovering a device using DNS-based Service Discovery +(DNS-SD) for commissioning, irrespective of the Discovery Capabilities Bitmask specified in the Sec­ +tion 5.1.1, “Onboarding Payload Contents”. + +**5.4.2.2. Announcement Commencement** + +A device which is not yet commissioned into a Matter fabric SHALL commence announcing its abil­ +ity to be commissioned depending on its primary device function and manufacturer-chosen Device +Commissioning Flow, per the following table. Nodes already commissioned into one or more Matter +fabrics or already connected to an IP-bearing network that wish to announce SHALL ONLY do so +using DNS-SD over their operational network (see Section 5.4.2.7, “Using Existing IP-bearing Net­ +work” and Section 4.3, “Discovery”). In the interest of privacy, an already-commissioned Node +SHALL NOT commence announcement using Bluetooth LE or Wi-Fi Public Action Frame. + +``` +Primary Device Function Announcement +Most control originates from a Fabric +(excluding Locks and Barrier Access +Devices) +``` +``` +SHALL start announcing automatically upon application +of power when using Standard commissioning flow. When +using User-intent commissioning flow or Custom Commis­ +sioning flow, it SHALL NOT start announcing automati­ +cally upon application of power. +``` +``` +Page 276 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Primary Device Function Announcement +Most control does not originate from a +Fabric ( e.g. , dishwasher, coffee maker, +refrigerator) +``` +``` +SHALL NOT start announcing automatically upon applica­ +tion of power. User-intent commissioning flow or Custom +Commissioning flow is required. +Locks and Barrier Access Devices SHALL NOT start announcing automatically upon applica­ +tion of power. User-intent commissioning flow or Custom +Commissioning flow is required. +``` +Note that the above guidelines are in place to avoid unnecessary pollution of the 2.4 GHz spectrum +and as a mitigation of the privacy threat created due to unnecessary transmissions by a commis­ +sionable device. + +If announcement has ceased (see Section 5.4.2.3, “Announcement Duration”), it may be re-initiated +via a device-specific user interaction such as a button press or other action defined by the manufac­ +turer and indicated by the methods specified in Section 5.7, “Device Commissioning Flows”. + +**5.4.2.3. Announcement Duration** + +In order to minimize unnecessary pollution of the 2.4 GHz and 5 GHz shared wireless spectrum, +especially with device discovery, a commissionable device SHALL NOT announce with a rapid inter­ +val for a duration longer than 15 minutes after announcement commences. This duration was cho­ +sen to capture the primary case of a user setting up immediately after powering on for a range of +devices, including time to download, install and launch applications, transit rooms within a home, +etc. + +Note that devices MAY choose to announce for less time in order to conserve battery life or for +other device-specific reasons. Note that an announcement duration that is too short may result in a +poor setup experience for users. Shorter announcement intervals SHOULD only be employed to +meet otherwise unattainable device functionality/requirements. To help strike a balance between a +good setup experience and conserving battery life, a device SHALL NOT announce for a duration of +less than 3 minutes after announcement commences. + +A failed attempt to commission does not restart or delay the timeout. Moreover, this timeout applies +only to cessation of announcements and not to abortion of connections, _i.e._ , a connection SHOULD +NOT abort prematurely upon expiration of the announcement duration. + +**5.4.2.3.1. Extended Announcement** + +An uncommissioned device MAY announce for a longer period, up to 48 hours in total, known as +Extended Announcement. This enhances setup success likelihood for cases where a user needs +more than 15 minutes after first powering an uncommissioned device (e.g. physical setup takes >15 +minutes, user must leave and return later). + +If a device opts to use Extended Announcement, it SHALL set both the PID and VID to 0 in the +announcement and SHALL elide any Extended Data. This is to preserve user privacy for scenarios +where a device may remain uncommissioned for extended periods. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 277 +``` + +**5.4.2.4. Discovery Information** + +This section details the information advertised by a commissionable Node. + +``` +Field Length Is Required? +Discriminator 12-bit Yes +Vendor ID 16-bit No +Product ID 16-bit No +Extended Data Variable No +``` +**5.4.2.4.1. Discriminator** + +A 12-bit value matching the field of the same name in the Setup Code. + +**5.4.2.4.2. Vendor ID** + +A 16-bit value identifying the device manufacturer (see Section 2.5.2, “Vendor Identifier (Vendor ID, +VID)”). + +**5.4.2.4.3. Product ID** + +A 16-bit value identifying the product (see Product ID). + +**5.4.2.4.4. Extended Data** + +Extended Data MAY be made available by commissionable Nodes. This data SHALL be encoded +using a standard TLV encoding defined in this section. The location of this data varies based on the +Node’s commissioning networking technology. + +This extended data SHALL be encoded as a TLV structure tagged with an anonymous tag. + +The members of this structure SHALL use context-specific tags with the values and meanings +shown in the table below. + +``` +Tag Value Member type Member Description +RotatingIdTag 0x00 octet string Rotating Device Identifier +``` +**5.4.2.4.5. Rotating Device Identifier** + +Some device makers need a way to uniquely identify a device before it has been commissioned for +vendor-specific customer support purposes. For example, the device maker may need this to iden­ +tify factory software version and related features, manufacturing date, or to assist in recovery +when a setup code has been lost or damaged. In order to avoid privacy issues associated with +exposing a fixed unique identifier, devices MAY utilize a Rotating Device Identifier for identifica­ +tion purposes. A Rotating Device Identifier is similar to a serial number but rotates at pre-defined +moments. + +The Rotating Device Identifier provides a non-trackable identifier which is unique per-device and +that can be used in one or more of the following ways: + +``` +Page 278 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Provided to the vendor’s customer support for help in pairing or establishing Node provenance; +- Used programmatically to obtain a Node’s Passcode or other information in order to provide a + simplified setup flow. Note that the mechanism(s) by which the Passcode may be obtained is + outside of this specification. If the Rotating Device Identifier is to be used for this purpose, the + system implementing this feature SHALL require proof of possession by the user at least once + before providing the Passcode. The mechanism for this proof of possession, and validation of it, + is outside of this specification. + +The Rotating Device Identifier is an optional feature for a Node to implement and an optional fea­ +ture for a Commissioner to utilize. The algorithm used for generating a Rotating Device Identifier +SHALL meet the following security and privacy requirements: + +1. It SHALL be irreversible in such a way that: + a. It SHALL prevent recovery of a unique identifier for the device by entities that do not + already have access to the set of possible unique identifiers. + b. Leaking of a common key or equivalent could not be used to recover a unique identifier for + all devices sharing the common key. +2. It SHALL protect against long-term tracking by rotating upon each commencement of advertis­ + ing. +3. It SHALL have a total of at least 64 bits of entropy and SHOULD preferably have more, up to 256 + bits. +4. It SHALL NOT contain a fixed identifier such as a serial number. + +The Rotating Device Identifier Algorithm below meets these requirements. A Node that implements +the Rotating Device Identifier SHALL use either the Rotating Device Identifier Algorithm or a differ­ +ent algorithm which has been approved and verified by the Connectivity Standards Alliance for this +purpose and which meets the same set of security and privacy requirements listed above. + +The Rotating Device Identifier Algorithm employs a key derivation algorithm that combines a +monotonically increasing lifetime counter with a persistent unique per-device identifier. + +This persistent unique identifier SHALL consist of a randomly-generated 128-bit or longer octet +string which SHALL be programmed during factory provisioning or delivered to the device by the +vendor using secure means after a software update. + +This persistent unique identifier SHALL be protected against reading or writing over the air after +initial introduction into the device, and stay fixed during the lifetime of the device. + +### NOTE + +``` +This persistent unique identifier SHALL NOT be the same as the UniqueID attribute +exposed in the Basic Information cluster. +``` +The lifetime counter SHALL be an integer at least 16 bits in size, incremented upon each com­ +mencement of advertising, and wrapping when the maximum value is reached. + +The Rotating Device Identifier Algorithm is defined as follows: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 279 +``` + +``` +Rotating Device ID = Rotation Counter || Crypto_KDF( +inputKey := Persistent Unique ID, +salt:= Rotation Counter, +info := "RotatingDeviceID", +len := 128) +``` +(where || is the concatenation operation) + +The rotation counter is encoded as 2 bytes using little-endian encoding in the above algorithm, +everywhere it appears. + +The Rotating Device ID is the concatenation of the current rotation counter and the 16 bytes of the +Crypto_KDF result. + +**5.4.2.4.6. TLV Example** + +Extended data containing just a Rotating Device Identifier would be encoded as the following bytes: + +``` +Offset Data Comments +0x00 0x15 Control byte for structure with anonymous tag +0x01 0x30 Control byte for octet string with 1-byte length and a context-specific tag +0x02 0x00 Context-specific tag for Rotating Device Identifier +0x03 0x12 Length of Rotating Device Identifier (e.g. 18 bytes) +0x04 0xXX..0x +XX +``` +``` +Rotating Device Identifier +``` +``` +0x16 0x18 End of container +``` +**5.4.2.5. Using BLE** + +This section provides details of how a device announces its commissionable status using BLE tech­ +nology. As required in Section 5.4.2.2, “Announcement Commencement”, Nodes currently commis­ +sioned into one or more fabrics or already connected to an IP-bearing network SHALL NOT employ +this method. + +``` +NOTE Need to add link(s) to BLE specification. +``` +**5.4.2.5.1. Device Role** + +Commissionable devices SHALL implement the role of a Generic Access Profile (GAP) Peripheral. + +**5.4.2.5.2. Channels** + +There are three advertising channels used by BLE. All three channels SHOULD be used by commis­ +sionable devices for BLE advertising. + +``` +Page 280 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.4.2.5.3. Interval** + +Commissionable devices SHOULD use an Advertising Interval between 20 ms and 60 ms for the first +30 seconds and a value between 150 ms to 1285 ms for the rest of the Announcement duration. +Shorter intervals typically result in shorter discovery times. + +If a device opts to use Extended Announcement, it SHALL switch to using an Advertising Interval +larger or equal to 1200 ms and SHOULD use a nominal Advertising Interval of 1285 ms. When using +Extended Announcement, the device SHALL set the Extended Announcement Flag in the Matter +Service Data in the BLE Advertisement (see Table 51, “Matter BLE Service Data payload format”). + +**5.4.2.5.4. Advertising Mode** + +Commissionable devices SHALL use the GAP General Discoverable mode, sending connectable +undirected advertising events. + +**5.4.2.5.5. Advertising Address** + +To ensure privacy, commissionable devices SHALL use LE Random Device Address (see Bluetooth® +Core Specification 4.2 Vol 6, Part B, Section 1.3.2.1 "Static device address") for BLE Advertising and +SHALL change it at least on every boot. + +**5.4.2.5.6. Advertising Data** + +In order to reduce 2.4 GHz spectrum congestion due to active BLE scanning, and to extend battery +life in battery-powered devices, all critical data used for device discovery is contained in the Adver­ +tising Data rather than the Scan Response Data. This allows a BLE Commissioner to passively scan +(i.e., not issue Scan Requests upon receiving scannable advertisements) and still be able to receive +all information needed to commission a device. + +Note that if additional vendor-specific information is to be conveyed and does not fit within the +Advertising Data, it may be included in the Scan Response Data. See Section 5.4.2.8, “Manufacturer- +specific data” for details on including vendor-specific information. + +Advertising data for Matter discovery uses "Service Data - 16 bit UUID" advertisement data type (see +Bluetooth® Core Specification Supplement 11 Section 1.11 "Service Data"), with 16-bit UUID value of +0xFFF6 (see Table 36, “SIG UUID assignment”). + +The following fields are defined within the Matter service data: + +_Table 51. Matter BLE Service Data payload format_ + +``` +Bytes Type Description +0 uint8 Matter BLE OpCode. +Value == 0x00 (Commissionable) +Values 0x01 - 0xFF are reserved +1-2 uint16 Bits[15:12] == 0x0 (Advertisement version) +Bits[11:0] == 12-bit Discriminator (see Section 5.4.2.4.1, “Discriminator”) +3-4 uint16 16-bit Vendor ID (see Section 5.4.2.4.2, “Vendor ID”) +Set to 0, if elided +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 281 +``` + +``` +Bytes Type Description +5-6 uint16 16-bit Product ID (see Section 5.4.2.4.3, “Product ID”) +Set to 0, if elided +7 uint8 Bit[0] == Additional Data Flag (see Section 5.4.2.5.7, “GATT-based Additional +Data”) +Bit[1] == Using Extended Announcement Flag (see Section 5.4.2.3.1, “Extended +Announcement”) +Bits[7:2] are reserved for future use and SHALL be clear (set to 0) +``` +All multi-byte values are encoded in little-endian byte order within the service data payload. + +Devices MAY choose not to advertise either the VID and PID, or only the PID due to privacy or other +considerations. When choosing not to advertise both VID and PID, the device SHALL set both VID +and PID fields to 0. When choosing not to advertise only the PID, the device SHALL set the PID field +to 0. A device SHALL NOT set the VID to 0 when providing a non-zero PID. + +The Using Extended Announcement flag SHALL be set while the device is in the Extended +Announcement period and SHALL NOT be set during the initial Announcement Duration. + +The following table details the contents of an exemplary Advertising PDU payload for Vendor ID +0xFFF1, Product ID 0x8000, Discriminator 0x3AB and with GATT-based Additional Data marked as +present: + +_Table 52. Exemplary Matter BLE commissionable advertisement_ + +``` +Byte Value Description +0 0x02 AD[0] Length == 2 bytes +1 0x01 AD[0] Type == 1 (Flags) +2 0x06 Bit 0 (LE Limited Discoverable Mode) set to 0 +Bit 1 (LE General Discoverable Mode) set to 1 +Bit 2 (BR/EDR Not supported) set to 1 +3 0x0B AD[1] Length == 11 bytes +4 0x16 AD[1] Type == 0x16 (Service Data - 16-bit UUID) +5-6 0xF6, 0xFF 16-bit Matter UUID assigned by Bluetooth SIG = 0xFFF6 +7 0x00 Matter BLE OpCode == 0x00 (Commissionable) +8-9 0xAB, 0x03 Bits[15:12] == 0x0 (Advertisement version) +Bits[11:0] == 12-bit Discriminator == 0x3AB +10-11 0xF1, 0xFF 16-bit Vendor ID == 0xFFF1 +12-13 0x00, 0x80 16-bit Product ID == 0x8000 +14 0x01 Bit[0] == 1: (GATT-based Additional Data present) +Bits[7:1] clear (reserved for future use) +``` +Note that the position of the fields within the Advertising PDU (e.g. Flags, 16-bit UUID Service Data, +etc.) within a conformant advertisement MAY differ from the example above, since there are no + +``` +Page 282 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +ordering constraints for advertisement fields in the Length-Type-Value format used in BLE adver­ +tisements. + +**5.4.2.5.7. GATT-based Additional Data** + +When the Additional Data Flag is set in the Matter Service Data in the BLE Advertisement, the com­ +missioner MAY access additional commissioning-related data via an unencrypted read-only GATT +characteristic C3 (see Table 34, “BTP GATT service”). + +The value of the C3 characteristic SHALL be set to the Extended Data payload of the Discovery +Information (see Section 5.4.2.4.4, “Extended Data”). + +**5.4.2.6. Using Wi-Fi Public Action Frame** + +This section provides details of how a device announces its commissionable status using Wi-Fi Pub­ +lic Action Frame. As required in Section 5.4.2.2, “Announcement Commencement”, Nodes currently +commissioned into one or more fabrics or already connected to an IP-bearing network SHALL NOT +employ this method. + +**5.4.2.6.1. Device Role** + +Commissionable devices SHALL implement the role of a publisher in Wi-Fi Alliance Unsynchro­ +nized Service Discovery (WFA-USD). + +**5.4.2.6.2. Channels** + +The Commissionable device advertises itself on channel 6 in the 2.4 GHz frequency band, which is +the Default Publish Channel in WFA-USD. Additionally, the Commissionable device also advertises +itself on channels in the Publish Channel List. This Publish Channel List includes all 20 MHz chan­ +nels in the 2.4 GHz frequency band and 5 GHz band (if supported) that are allowed per regulation +in the geographical location. + +The Commissionable device iterates between advertising itself on the Default Publish Channel and +on channels in the Publish Channel List per behavior described in WFA-USD. For Commissionable +devices to advertise on Dynamic Frequency Selection channels within the 5 GHz band, full compli­ +ance with the regulatory requirements of the specific geographical location is mandatory. + +The Commissionable device can prioritize advertising on channels in the Publish Channel List in +which it determines the presence of an IEEE 802.11 Basic Service Set. The Commissionable device +can determine presence of an IEEE 802.11 Basic Service Set on a channel by scanning that channel +passively (i.e., SHOULD NOT send Probe Requests) in order to reduce unnecessary transmissions in +the shared spectrum. + +The detection of an IEEE 802.11 beacon on a particular channel serves as a strong indication of the +presence of an IEEE 802.11 Basic Service Set operating on that same channel. Moreover, within the +IEEE 802.11 beacon, a Commissionable device can find information about the regulatory domain it +is currently located in, specifically in the Country Information Element. + +**5.4.2.6.3. Publisher Operating Parameters** + +Commissionable devices SHALL create a Publish instance by invoking the Publish Method, using + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 283 +``` + +argument values specified in Table 53, “Publish method arguments values for discovery”. Little- +endian encoding is used for all argument values. + +_Table 53. Publish method arguments values for discovery_ + +``` +Argument Description Value for discovery +service_­ +name +``` +``` +UTF-8 name string which identifies the +service +``` +``` +_matterc._udp +``` +``` +matching_fil­ +ter_tx +``` +``` +Ordered sequence of pairs +to be included in the Publish message +``` +### NULL + +``` +matching_fil­ +ter_rx +``` +``` +Ordered sequence of +pairs that specify further the response +conditions beyond the service name used +to filter the Subscribe message +``` +### NULL + +``` +ser­ +vice_speci­ +fic_info +``` +``` +Sequence of values that are conveyed in +the Publish message +``` +``` +Ordered sequence: +<8-bits, Device OpCode>, +<16-bits, Device Information>, +<16-bits, Vendor ID>, +<16-bits, Product ID>, + +configura­ +tion_para­ +meters +``` +``` +Miscellaneous configuration parameters Publish Type = unso­ +licited and solicited transmissions +Discovery range = 0 +Solicited transmission type = unicast +Announcement period = (see text below) +Time to live = (see text below) +Event conditions = always +Matching filter flag = 1 +NAN Ranging Flag = 0 +Data Path Flag = 0 +Awake DW Interval = Not Applicable +Further Service Discovery flag = 1 +Further Service Discovery function = 0 +NAN Discovery flag = 1 +Default Publish Channel = 6 +Publish Channel List = [all 20 MHz chan­ +nels in 2.4 GHz band and 5 GHz band (if +supported), per regulation in the geo­ +graphical region] +Nmin = 5 +Nmax = 10 +Mmin = 5 +Mmax = 10 +``` +_Table 54. Wi-Fi Public Action Frame Device OpCode_ + +``` +Page 284 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Device OpCode +Value +``` +``` +Description +``` +``` +0x00 Commissionable +0x01 - 0xFF Reserved +``` +_Table 55. Wi-Fi Public Action Frame Device Information_ + +``` +Bits Description +b15:b12 Advertisement version, set to 0x0 +b11:b0 12-bit discriminator (see Section 5.4.2.4.1, “Discriminator”) +``` +Some devices MAY choose not to advertise the Vendor ID and/or Product ID due to privacy or other +considerations. These devices SHALL set the Vendor ID and Product ID to value 0 in the ser­ +vice_specific_info. Extended Data is optionally present in service_specific_info. The Time to live +value is set according to Section 5.4.2.3, “Announcement Duration”. The recommended value of +Announcement period is 100 TUs. 1 TU is equal to 1024 microseconds. + +Single-channel Publish State and Multiple-channels Publish State defined in WFA-USD govern the +advertisement behavior. + +1. Single-channel Publish State: The Commissionable device operates in the Default Publish Chan­ + nel during this state. The dwell period (the time spent on a channel) is randomly determined as + N x 100 TU, where N is an integer randomly selected within the range [Nmin, Nmax]. +2. Multiple-channels Publish State: In this state, the publisher can operate in one or more channels + from the Publish Channel List. The dwell period is randomly determined as M x 100 TU, where + M is an integer randomly selected within the range [Mmin, Mmax]. The implementation of WFA- + USD has flexibility to divide the dwell period across the channels in the Publish Channel List. + The Commissionable device MAY publish on a subset of channels within each multiple-channels + Publish State, and the minimum time spent on any one channel is 100 ms in WFA-USD. + +If a device opts to use Extended Announcement, it SHALL switch to using Nmin, Nmax, Mmin, and Mmax +greater than or equal to 10, 15, 10, 15, respectively, and SHOULD use an Announcement period of 1000 +TUs. + +``` +NOTE These recommended values may be updated in a future version of the specification. +``` +**5.4.2.7. Using Existing IP-bearing Network** + +This section details how a device that is already connected to an IP-bearing network advertises its +commissionable state. The discovery protocols leverage IETF Standard DNS-based Service Discov­ +ery [RFC 6763]. A device SHALL use multicast DNS [RFC 6762] on Wi-Fi and Ethernet networks to +make itself discoverable. On Thread networks, a device SHALL use the Service Registration Protocol +[SRP] and an Advertising Proxy [AdProx] running on a Thread Border Router to make itself discov­ +erable. Additional details on application of the above protocols in Matter is found in Section 4.3, +“Discovery”. The encoding of the information required for discovery during the commissioning +process is covered in Section 4.3.1, “Commissionable Node Discovery”. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 285 +``` + +**5.4.2.8. Manufacturer-specific data** + +If needed, manufacturer-specific data MAY be advertised by a commissionable device using one of +the following mechanisms, based on the supported commissioning technology. Commissioners +receiving this data SHOULD treat it as opaque unless they have the need to and possess the ability +to correctly interpret the information conveyed. + +**5.4.2.8.1. Using BLE** + +Any manufacturer-specific data may be included as a Manufacturer Specific Data AD type in the +Advertising Data or in the Scan Response data. + +Note that to receive Scan Response data information the Commissioner has to perform BLE active +scanning that, in addition to creating additional traffic in the shared 2.4 GHz unlicensed band, can +delay device discovery and connection, increasing the overall time required to commission a +device. + +**5.4.2.8.2. Using Wi-Fi Public Action Frame** + +Any manufacturer-specific data SHOULD be conveyed using the Vendor-specific attributes in WFA- +USD. + +**5.4.3. Discovery by Commissioner** + +How a Commissioner discovers a commissionable device depends on the networking technologies +that device and the Commissioner supports (see Section 5.4.2.1, “Announcement and Discovery +Using Multiple Technologies”). Though not all networking technologies must be supported by every +device (see Table 40, “Discovery Capabilities Bitmask”), a Commissioner SHALL support Commis­ +sioning (see Section 5.5, “Commissioning Flows”) using existing IP network and over BLE (if having +such interface) and SHOULD support commissioning over Wi-Fi Public Action Frame (if having Wi- +Fi interface). + +The following sections detail Commissioner behavior for each of these networking technologies. +Though a QR or Manual Pairing code may be scanned or entered prior to discovery, it is not +required to do so. However, after scan/entry of the code, the Discriminator, VID and PID elements +are available to ensure that the intended device is discovered before proceeding to the connection +phase of commissioning. + +**5.4.3.1. Using BLE** + +Commissioners SHALL implement the role of a GAP Central. To discover a commissionable device +advertising over BLE, a Commissioner SHALL perform a BLE scan across all three advertising chan­ +nels with a sufficient dwell time, interval, and overall duration of scan. In order to promote quick +discovery it is recommended that a Commissioner scan as aggressively as possible within the Com­ +missioner device functionality/UX constraints. In addition, if manufacturer-specific data is not +needed, a passive scan ( _i.e._ , one that only listens for Advertisement PDUs and does not issue Scan +Request PDUs). + +If discovery procedure is user initiated the scan interval SHOULD be set between 30 ms and 60 ms, +and the scan window SHOULD be set to 30 ms. If discovery procedure is not user initiated (i.e., the + +``` +Page 286 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Commissioner is scanning in the background), the device may use more relaxed scan, for example, +the scan interval set to 1.28 seconds and scan window set to 11.25 ms. + +### NOTE + +``` +Recommended values are defined in Appendix A: Timers and Constants of Blue­ +tooth® Core Specification 4.2, Vol 3, Part C. +``` +**5.4.3.2. Using Wi-Fi Public Action Frame** + +``` +NOTE Discovery and commissioning using Wi-Fi Public Action Frames is provisional. +``` +To discover a commissionable device advertising using Wi-Fi Public Action Frame (see Section +5.4.2.6, “Using Wi-Fi Public Action Frame”), a Commissioner that supports commissioning using Wi- +Fi Public Action Frame SHALL implement the role of a Subscriber in Wi-Fi Alliance Unsynchronized +Service Discovery (WFA-USD). The Commissioner SHALL create an active or a passive subscribe +instance by invoking the Subscribe Method using the argument values specified in Table 56, “Sub­ +scribe method arguments values for discovery” (WFA-USD). + +_Table 56. Subscribe method arguments values for discovery_ + +``` +Argument Description Value for discovery +service_­ +name +``` +``` +UTF-8 name string which identifies the +service +``` +``` +_matterc._udp +``` +``` +matching_fil­ +ter_rx +``` +``` +Ordered sequence of +pairs used to filter out received publish +discovery messages containing the ser­ +vice name +``` +### NULL + +``` +matching_fil­ +ter_tx +``` +``` +Ordered sequence of pairs +to be included in the Subscribe message +``` +### NULL + +``` +ser­ +vice_speci­ +fic_info +``` +``` +Sequence of values that are conveyed in +the Subscribe message +``` +### NULL + +``` +configura­ +tion_para­ +meters +``` +``` +Miscellaneous configuration parameters Subscribe Type = Passive or Active +Discovery range = 0 +Query period = (see text below) +Time to live = (see text below) +Matching filter flag = 1 +NAN Ranging Flag = 0 +Awake DW Interval = 1 +NAN Discovery flag = 1 or 0 +Default Publish Channel = 6 +Publish Channel List = [44, 149] +``` +The recommended value of Query period is between 100 TUs and 600 TUs when Subscribe Type = +Active. The Query period is not applicable when Subscribe Type = Passive. The Time to live value is +set according to Section 5.4.2.3, “Announcement Duration”. + +The Commissioner can create the subscribe instance on Default Publish Channel (channel 6 in the + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 287 +``` + +2.4 GHz band) or any of the 20 MHz channels in the 2.4 GHz frequency band or any of the 20 MHz +channels in the 5 GHz frequency band, if supported (see Section 5.4.2.6.2, “Channels”). The fre­ +quency and duration of the Commissioner’s presence on the channel where the subscribe instance +is created are based on implementation. For swiftest device discovery in WFA-USD, the Commis­ +sioner SHOULD follow these guidelines: + +1. Whenever possible, the Commissioner SHOULD create a subscribe instance on the Default Pub­ + lish Channel. +2. If the Commissioner is already associated with an operational network on the 5 GHz band, it + can still create a subscribe instance on the same operating channel. However, if Commissioner + is not an Access Point and if the operating channel is a Dynamic Frequency Selection channel, + then to ensure compliance with the local regulatory requirements, the Commissioner SHOULD + choose either channel 44 or channel 149 in the 5 GHz band for the subscribe instance, + whichever is permitted with a higher transmission power based on the regulatory domain. + Access Points as Commissioners can choose to create subscribe instance on any operating chan­ + nel, including Dynamic Frequency Selection channels. + +When the Commissioner discovers the _matterc._udp service name published by a Commissionable +device, and the Commissioner uniquely identifies the Commissionable device through 12-bit dis­ +criminator or Extended Data, then the Commissioner MAY proceed with the commissioning flow +(see Section 5.5, “Commissioning Flows”). When commissioning over Wi-Fi Public Action Frame, the +Commissioner SHALL use concurrent connection commissioning flow. Any Commissionable device +supporting Wi-Fi Public Action Frame commissioning SHALL support concurrent connection com­ +missioning flow, indicating this capability in the SupportsConcurrentConnection attribute of the +General Commissioning Cluster. + +During commissioning flow, the Commissioner and the Commissionable device SHALL use WFA- +USD Service Discovery Frame (SDF) Follow-up messages to transport Matter messages until the +Commissionable device joins the operational network. When a WFA-USD SDF Follow-up message is +used to transport a Matter message, the Service Info field of the Service Descriptor Extension +Attribute included in the Wi-Fi USD Follow-up message SHALL be used to encapsulate the Matter +message. The value of its Service Protocol Type field SHALL be set to '3' to indicate Matter, and its +Service Specific Info field SHALL carry the Matter message sent by the Commissionable device or +the Commissioner. + +**5.4.3.3. Using Existing IP-bearing Network** + +To discover a commissionable device over an existing IP-bearing network connection, the Commis­ +sioner SHALL perform service discovery using DNS-SD as detailed in Section 4.3, “Discovery”, and +more specifically in Section 4.3.1, “Commissionable Node Discovery”. + +**5.5. Commissioning Flows** + +There are two commissioning flows depending upon the networking capability of the Commis­ +sioner and Commissionee, namely concurrent connection commissioning flow and non-concurrent +connection commissioning flow. + +For additional security requirements related to commissioning flows, refer to Section 13.6, “Secu­ + +``` +Page 288 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +rity Best Practices”. + +A Commissioner and Commissionee with concurrent connection have the ability to maintain two +network connections simultaneously. One connection is between the Commissioner (or Commis­ +sionee) and the operational network (e.g., home Wi-Fi network or Thread network) that the Com­ +missionee is being programmed to join. The second connection is between the Commissioner and +Commissionee for commissioning as is referred to as commissioning channel. A Commissioner and +Commissionee with non-concurrent connection capability cannot be simultaneously connected to +both the operational network that the Commissionee is being configured to join, and the commis­ +sioning channel. + +The two connections MAY either be on the same or on different networking interfaces. For exam­ +ple, a Commissioner uses its Wi-Fi interface to connect to the operational network, but use its Blue­ +tooth Low Energy interface for commissioning. + +To determine whether a Commissionee has concurrent or non-concurrent connection capability, +the Commissioner can use the SupportsConcurrentConnection attribute of the General Commission­ +ing Cluster. + +Commissioning SHALL be a time-bound process that completes before expiration of a fail-safe +timer. The fail-safe timer SHALL be set at the beginning of commissioning. If the fail-safe timer +expires prior to commissioning completion, the Commissioner and Commissionee SHALL terminate +commissioning. Successful completion of commissioning SHALL disarm the fail-safe timer. + +A Commissionee that is ready to be commissioned SHALL accept the request to establish a PASE ses­ +sion with the first Commissioner that initiates the request. When a Commissioner is either in the +process of establishing a PASE session with the Commissionee or has successfully established a ses­ +sion, the Commissionee SHALL NOT accept any more requests for new PASE sessions until session +establishment fails or the successfully established PASE session is terminated on the commissioning +channel (see CloseSession in Secure Channel Status Report Messages). In the event a CloseSession +status message is sent or received: + +1. If the fail-safe timer is armed, the fail-safe timer SHALL be considered expired and the cleanup + steps detailed in ArmFailSafe SHALL be executed. +2. If the commissioning window is still open, the Commissionee SHALL continue listening for com­ + missioning requests. + +In order to avoid locking out the Commissionee from accepting new PASE session requests indefi­ +nitely, a Commissionee SHALL expect a PASE session to be established within 60 seconds of receiv­ +ing the initial request. This means the Commissionee SHALL expect to receive the PAKE3 message +within 60 seconds after sending a PBKDFParamResponse in response to a PBKDFParamRequest +message from the Commissioner to establish a PASE session. If the PASE session is not established +within the expected time window the Commissionee SHALL terminate the current session estab­ +lishment using the INVALID_PARAMETER status code as described in Section 4.11.1.3, “Secure Channel +Status Report Messages”. + +The commissioning commands and attributes are defined in Clusters (see Section 11.9, “Network +Commissioning Cluster”, Section 11.10, “General Commissioning Cluster”, Section 11.14, “Thread +Network Diagnostics Cluster”, and Section 11.15, “Wi-Fi Network Diagnostics Cluster”) and are sent, + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 289 +``` + +written, or read using the Interaction Model (see Interaction Model). + +Figure 32, “Concurrent connection commissioning flow” and Figure 33, “Non-concurrent connec­ +tion commissioning flow” depict the commissioning flow between the Commissioner and Commis­ +sionee with concurrent connection ability and non-concurrent connection ability, respectively. The +specific steps are described below. Unless indicated otherwise, a commissioner SHALL complete a +step, including waiting for any responses to commands it sends in that step, before moving on to +the next step. + +1. The Commissioner initiating the commissioning SHALL have regulatory and fabric information + available, and SHOULD have accurate date, time and timezone. +2. Commissioner and Commissionee SHALL find each other over networking interfaces such as + Bluetooth, Wi-Fi, or Ethernet using the process of discovery and establish a commissioning + channel between each other (see Section 5.4, “Device Discovery”). +3. If the Commissioner and device support Terms and Conditions (TC) Acknowledgement, then the + Commissioner SHALL obtain the Terms and Conditions to present to the user from Section + 11.23.6.22, “EnhancedSetupFlowTCUrl”. +4. If the Commissioner and device support Terms and Conditions (TC) Acknowledgement, the Com­ + missioner SHALL present the Terms and Conditions to the user following Terms and Conditions + (TC) Acknowledgement, unless the Commissioner already has user provided responses that can + be used. +5. If the Commissioner and device support Terms and Conditions (TC) Acknowledgement, and + Terms and Conditions were presented in step 4 , then the Commissioner SHALL receive the user + responses to the provided terms for use in step 9. +6. Commissioner and Commissionee SHALL establish encryption keys with PASE (see Section + 4.14.1, “Passcode-Authenticated Session Establishment (PASE)”) on the commissioning channel. + All subsequent messages on the commissioning channel are encrypted using PASE-derived + encryption keys. Upon completion of PASE session establishment, the Commissionee SHALL + autonomously arm the Fail-safe timer for a timeout of 60 seconds. This is to guard against the + Commissioner aborting the Commissioning process without arming the fail-safe, which may + leave the device unable to accept additional connections. +7. Commissioner SHALL re-arm the Fail-safe timer on the Commissionee to the desired commis­ + sioning timeout within 60 seconds of the completion of PASE session establishment, using the + ArmFailSafe command (see ArmFailSafe). A Commissioner MAY obtain device information + including guidance on the fail-safe value from the Commissionee by reading BasicCommis­ + sioningInfo attribute (see BasicCommissioningInfo) prior to invoking the ArmFailSafe com­ + mand. +8. The commissioner configures the regulatory information and time cluster as described below. + The order of the operations in this commissioning step is not critical. + ◦ If the Commissionee has at least one instance of the Network Commissioning cluster on any + endpoint with either the WI (i.e. Wi-Fi) or TH (i.e. Thread) feature flags set in its FeatureMap, + Commissioner SHALL configure regulatory information in the Commissionee using the + SetRegulatoryConfig command. + ◦ If the Commissionee supports the Time Synchronization Cluster server: + +``` +Page 290 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +▪ The Commissioner SHOULD configure UTC time using the SetUTCTime command. +▪ The Commissioner SHOULD set the time zone using the SetTimeZone command, if the +TimeZone feature is supported. +▪ The Commissioner SHOULD set the DST offsets using the SetDSTOffset command if the +TimeZone feature is supported, and the SetTimeZoneResponse from the Commissionee +had the DSTOffsetsRequired field set to True. +▪ The Commissioner SHOULD set a Default NTP server using the SetDefaultNTP command +if the NTPClient feature is supported and the DefaultNTP attribute is null. If the current +value is non-null, Commissioners MAY opt to overwrite the current value. +``` +9. If the Terms & Conditions Enhanced Setup Flow feature is supported by both the device and by + the commissioner, and TCAcknowledgementsRequired is True, the Commissioner SHALL + present them as documented in Terms and Conditions Acknowledgement. The user’s responses + SHALL be propagated back to the node with SetTCAcknowledgements. +10. Commissioner SHALL establish the authenticity of the Commissionee as a certified Matter +device (see Section 6.2.3, “Device Attestation Procedure”). +◦ If the Commissionee fails the Device Attestation Procedure, for any reason, the Commis­ +sioner MAY choose to either continue to the Commissioning, or terminate it, depending on +implementation-dependent policies. +◦ Upon failure of the procedure, the Commissioner SHOULD warn the user that the Commis­ +sionee is not a fully trusted device, and MAY give the user the choice to authorize or deny +the commissioning. Such a warning enables user choice in Commissionee trust on their Fab­ +ric, for development workflows, as well as homebrew device development. Such a warning +SHOULD contain as much information as the commissioner can provide about the Commis­ +sionee, and SHOULD be adapted to the reason of the failure, for example by being different +between the case of an expired certificate versus a revoked PAI certificate. +◦ Reasons for failing the Device Attestation procedure MAY include, but are not limited to, the +following: +▪ The Commissionee being of a device type currently in development or not yet certified +(see certification_type in the Certification Declaration). +▪ The Commissionee’s PAA not being in the Commissioner’s trusted set. +▪ The Commissioner having obtained knowledge that a PAA or PAI certificate presented +has been revoked, or that the particular Device Attestation Certificate has been revoked +(see Section 6.2.4, “Device attestation revocation”). +▪ The Commissioner cannot obtain a revocation set or cannot obtain updated revocation +information from the CA (see Section 6.2.4.2, “Determining Revocation Status of an +Entity”). +▪ The Commissionee failing to prove possession of the Device Attestation private key, +either by programming error, malicious intent or other reasons. +▪ One of the elements of the Commissionee’s Device Attestation Certificate chain not meet­ +ing the policy validation steps of the Device Attestation Procedure, including errors on +validity period. +◦ If a Commissioner denies commissioning for any reason, it SHOULD notify the user of the + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 291 +``` + +``` +reason with sufficient details for the user to understand the reason, so that they could deter­ +mine if it would be possible to commission the device using a different Commissioner. +``` +11.Following the Device Attestation Procedure yielding a decision to proceed with commissioning, +the Commissioner SHALL request operational CSR from Commissionee using the CSRRequest +command (see CSRRequest). The CSRRequest command will cause the generation of a new oper­ +ational key pair at the Commissionee. + +12.Commissioner SHALL generate or otherwise obtain an Operational Certificate containing Oper­ +ational ID after receiving the CSRResponse command from the Commissionee (see CSRRequest), +using implementation-specific means. + +13.Commissioner SHALL install operational credentials (see Figure 43, “Node Operational Creden­ +tials flow”) on the Commissionee using the AddTrustedRootCertificate and AddNOC commands, +and SHALL use the UpdateFabricLabel command to set a string that the user can recognize and +relate to this Commissioner/Administrator. +The AdminVendorId field of the AddNOC command SHALL be set to a value for which the Ven­ +dor Schema in DCL contains the name and other information of the Commissioner’s manufac­ +turer. + +14.If the Commissionee supports the Time Synchronization Cluster server, the Commissioner +SHOULD set a trusted time source using the SetTrustedTimeSource command if the TimeSync­ +Client feature is supported, the TrustedTimeSource attribute is null and there is an available +trusted time source on the fabric. The Commissioner SHOULD ensure the ACL on the Trusted­ +TimeSource is set to grant the Commissionee View privilege to the Time Synchronization clus­ +ter. If the TrustedTimeSource is non-null, the Commissioner MAY opt to overwrite the current +value with a node from its own fabric by sending the SetTrustedTimeSource command. This +step MAY be performed at any point after installing operational credentials, including after +sending the CommissioningComplete command. + +15.Commissioner MAY configure the Access Control List (see Section 9.10, “Access Control Cluster”) +on the Commissionee in any way it sees fit, if the singular entry added by the AddNOC command +in the previous step granting Administer privilege over CASE authentication type for the Node +ID provided with the command is not sufficient to express its desired access control policies. +a.The Commissioner MAY read the Commissioning Access Restriction List (see Section 9.10, +“Access Control Cluster”) on the Commissionee in order to identify fabric restrictions. When +restrictions exist, the Administrator MAY invoke the ReviewFabricRestrictions command on +the same cluster in order to initiate the review process (see Managed Device), however, the +Administrator SHALL wait until after commissioning completes before sending this com­ +mand. + +16.If the Commissionee both supports it and requires it, the Commissioner SHALL configure the +operational network at the Commissionee using commands such as AddOrUpdateWiFiNetwork +(see AddOrUpdateWiFiNetwork) and AddOrUpdateThreadNetwork (see AddOrUpdateThread­ +Network). A Commissionee requires network commissioning if it is not already on the desired +operational network. A Commissionee supports network commissioning if it has any Network­ +Commissioning cluster instances. A Commissioner MAY learn about the networks visible to the +Commissionee using ScanNetworks command (see ScanNetworks). + +17.The Commissioner SHALL trigger the Commissionee to connect to the operational network +using ConnectNetwork command (see ConnectNetwork) unless the Commissionee is already on +the desired operational network. + +``` +Page 292 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +18. Finalization of the Commissioning process begins. An Administrator configured in the ACL of + the Commissionee by the Commissioner SHALL use Operational Discovery to discover the Com­ + missionee. This Administrator MAY be the Commissioner itself, or another Node to which the + Commissioner has delegated the task. +19. The Administrator SHALL open a CASE (see Section 4.14.2, “Certificate Authenticated Session + Establishment (CASE)”) session with the Commissionee over the operational network. +20. The Administrator having established a CASE session with the Commissionee over the opera­ + tional network in the previous steps SHALL invoke the CommissioningComplete command (see + CommissioningComplete). A success response after invocation of the CommissioningComplete + command ends the commissioning process. + +``` +While the Administrator of steps 18 - 20 will, in many situations, be the Commissioner Node itself, it +MAY be a different Node that was configured by the Commissioner to have Administer privilege +against the Commissionee’s General Commissioning Cluster. This is to support flexibility in finaliz­ +ing the Commissioning. From a Commissionee’s perspective, all Nodes with Administer privilege in +the Commissionee’s ACL are equivalent once the Node has a Node Operational Certificate and asso­ +ciated Node Operational Identifier on the Fabric into which it was just commissioned. +``` +``` +A Commissioner MAY configure UTC time, Operational ID, and Operational certificates, etc., infor­ +mation over an arbitrary number of interactions at the Commissionee, over the operational net­ +work after the commissioning is complete, or over the commissioning channel after PASE-derived +encryption keys are established during commissioning. +``` +``` +In concurrent connection commissioning flow the commissioning channel SHALL terminate after +successful step 20 (CommissioningComplete command invocation). In non-concurrent connection +commissioning flow the commissioning channel SHALL terminate after successful step 17 (trigger +joining of operational network at Commissionee). The PASE-derived encryption keys SHALL be +deleted when commissioning channel terminates. The PASE session SHALL be terminated by both +Commissioner and Commissionee once the CommissioningComplete command is received by the +Commissionee. +``` +``` +In both concurrent connection commissioning flow and non-concurrent connection commissioning +flow, the Commissioner MAY choose to continue commissioning and override the failure in step 10 +(Commissionee attestation). +``` +**5.5.1. Commissioning Flows Error Handling** + +``` +Overall, all Commissioning operations employ actions using cluster attributes and commands that +are also, in certain cases, available during normal steady-state operation once commissioned. +``` +``` +If a Commissionee requires network commissioning, the Commissioner SHOULD attempt to config­ +ure the primary network interface on the Root Node endpoint initially. +``` +``` +If the initial attempt fails for networking-related reasons, then the Commissioner SHOULD attempt +to configure secondary network interfaces via additional endpoints that have a server instance of +the Network Commissioning cluster, if such endpoints exist. +``` +``` +Before attempting to configure any such alternative interface, the commissioner SHALL revert net­ +work configuration changes made as part of the preceding unsuccessful configuration attempt, +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 293 +``` + +specifically the RemoveNetwork command SHALL be used to remove any Thread or Wi-Fi network +configurations added by such an unsuccessful attempt. This ensures that when commissioning ulti­ +mately succeeds, only the configuration changes relating to the network interface that was success­ +fully configured will be committed by the CommissioningComplete command. + +The Commissioner MAY leverage out-of-band information to prioritize network interfaces, consid­ +ering factors like the availability of Thread Border Routers, Wi-Fi Access Point status, and user pref­ +erences. + +Whenever the Fail-Safe timer is armed, Commissioners and Administrators SHALL NOT consider +any cluster operation to have timed-out before waiting at least 30 seconds for a valid response from +the cluster server. Some commands and attributes with complex side-effects MAY require longer +and have specific timing requirements stated in their respective cluster specification. + +Some request commands used for Commissioning and administration have a 'Breadcrumb' argu­ +ment. When set, this argument SHALL be used to update the value of the Breadcrumb Attribute as a +side-effect of successful execution of those commands. On command failures, the Breadcrumb +Attribute SHALL remain unchanged. + +In concurrent connection commissioning flow, the failure of any of the steps 2 through 15 SHALL +result in the Commissioner and Commissionee returning to step 2 (device discovery and commis­ +sioning channel establishment) and repeating each step. The failure of any of the steps 16 through +20 in concurrent connection commissioning flow SHALL result in the Commissioner and Commis­ +sionee returning to step 16 (configuration of operational network information), and MAY result in +an attempt to configure secondary network interfaces. In the case of failure of any of the steps 16 +through 20 in concurrent connection commissioning flow, the Commissioner and Commissionee +SHALL reuse the existing PASE-derived encryption keys over the commissioning channel and all +steps up to and including step 15 are considered to have been successfully completed. + +In non-concurrent connection commissioning flow, the failure of any of the steps 2 through 20 +SHALL result in the Commissioner and Commissionee returning to step 2 (device discovery and +commissioning channel establishment) and repeating each step. + +Commissioners that need to restart from step 2 MAY immediately expire the fail-safe by invoking +the ArmFailSafe command with an ExpiryLengthSeconds field set to 0. Otherwise, Commissioners +will need to wait until the current fail-safe timer has expired for the Commissionee to begin accept­ +ing PASE again. + +In both concurrent connection commissioning flow and non-concurrent connection commissioning +flow, the Commissionee SHALL exit Commissioning Mode after 20 failed attempts. + +Once a Commissionee has been successfully commissioned by a Commissioner into its fabric, the +commissioned Node SHALL NOT accept any more PASE requests until any one of the following con­ +ditions is met: + +- Device is factory-reset. +- Device enters commissioning mode. + +Ongoing administration of Nodes by Administrators employs many of the same clusters and con­ +straints related to Fail-Safe timer and cluster operation time-outs used for initial or subsequent + +``` +Page 294 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Commissioning into new Fabrics. The respective cluster specifications for the Node Operational +Credentials Cluster and the Network Commissioning Cluster reflect the necessary usage of the Arm­ +FailSafe and CommissioningComplete commands of the General Commissioning Cluster to achieve +consistent state during administrative operations. + +**5.5.2. Commissioning Flow Diagrams** + +_Figure 32. Concurrent connection commissioning flow_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 295 +``` + +_Figure 33. Non-concurrent connection commissioning flow_ + +**5.6. Administrator Assisted Commissioning Flows** + +**5.6.1. Introduction** + +In this method, a current Administrator of a Node first sends the OpenCommissioningWindow com­ +mand to the Node over a CASE session. The new Administrator SHALL already have network con­ +nectivity and complete commissioning based on the two flows described below. + +The commands for these flows are defined in Section 11.19, “Administrator Commissioning Clus­ + +``` +Page 296 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +ter”. + +**5.6.2. Basic Commissioning Method (BCM)** + +This method is OPTIONAL for Nodes and Administrators/Commissioners to implement. In this +method, the current Administrator SHALL send the OpenBasicCommissioningWindow command to +the Node over a CASE session. The Node SHALL advertise its presence over DNS-SD (see Section +5.4.2.7, “Using Existing IP-bearing Network” and Commissionable Node Discovery) after receiving +the OpenBasicCommissioningWindow command. + +The new Administrator’s Commissioner then completes commissioning with the Node using similar +Commissioning flow as it would do for a factory-new device (although note that IP channel is used +for discovery). It can either scan the QR code format or use the Manual Pairing Code format of the +Section 5.1, “Onboarding Payload” of the Node. + +The following steps describe a possible sequence of events for BCM commissioning: + +1. Current Administrator puts the Node in OpenBasicCommissioningWindow for a specified time + window, and receives success response from the Node on the OpenBasicCommissioningWindow + command. + a. When the targeted Node is a ICD, the current Administrator can guide the user to perform + some action to 'wake' the device from its sleep cycle. +2. New Administrator completes commissioning within the prescribed window using steps out­ + lined in Figure 32, “Concurrent connection commissioning flow”. + +**5.6.3. Enhanced Commissioning Method (ECM)** + +This method SHALL be implemented for Nodes and Commissioners/Administrators. When using +ECM, the Node’s current Administrator instructs the Node over a CASE session, to go into OpenCom­ +missioningWindow. It SHALL choose a new RANDOM passcode and SHALL compute and send the cor­ +responding PAKE passcode verifier to the Node. Actual value of the passcode SHALL NOT be sent to +the Node. The current Administrator then presents the new passcode and discriminator as +described below. The Node SHALL advertise its presence over DNS-SD (see Section 5.4.2.7, “Using +Existing IP-bearing Network” and Commissionable Node Discovery) after receiving the OpenCom­ +missioningWindow command. + +**5.6.3.1. Presentation of Onboarding Payload for ECM** + +Presentation of the passcode and other relevant information SHALL be done at least with one or +more of the methods below, depending on the capabilities of the first Administrator opening the +OCW: + +1. If a user interface display is supported, the temporary Onboarding Payload SHALL be displayed + using a textual representation of the Manual Pairing Code, using the 11-digit variant: it SHALL + NOT contain the VENDOR_ID or PRODUCT_ID as the onboarding of the node(s) using the ECM cannot + be subject to User-Intent or Custom Flows. +2. If a user interface display is supported, the temporary Onboarding Payload SHOULD also be dis­ + played using the definitions included in Section 5.1.3, “QR Code” subject to the following con­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 297 +``` + +``` +straints: +a.If only a single Node is being subjected to the ECM, the Vendor ID and Product ID in the +onboarding payload SHALL be the same as those of that Node. +b. If multiple Nodes are being subjected to the ECM using the same onboarding payload, the +Vendor ID SHALL be set to 0x0000 (Matter Standard) and the Product ID SHALL be set to +0x0000 (consistent with the value used for not advertising a Product ID in Device Announce­ +ment). +c.The Custom Flow element SHALL be set to 0 to indicate standard flow. +d. The Discovery Capabilities Mask SHALL have ONLY bit 2 set to indicate the Node is only dis­ +coverable on the IP network. +e. The Passcode element SHALL be set by the existing Administrator to the same value as the +passcode chosen for this ECM operation. +f. The Discriminator element SHALL be set by the existing Administrator to the same value as +the Discriminator parameter in Section 11.19.8.1, “OpenCommissioningWindow Command”. +g. If multiple Nodes are subjected to ECM, the Section 5.1.5, “TLV Content” SHALL contain an +entry with kTag_NumberOfDevices containing the number of devices that are expected to par­ +ticipate in the onboarding with this ECM operation. +h. When the Commissioning Timeout parameter of the OCW command is set to less than the +allowed maximum (15 minutes), the Section 5.1.5, “TLV Content” SHALL contain an entry +with kTag_CommissioningTimeout containing the value of the Commissioning Timeout parame­ +ter used for this ECM operation. +``` +3. If only audio output is supported, the temporary Onboarding Payload SHALL be delivered using + a voice prompt of the Manual Pairing Code format. A method SHOULD be available for the user + to have the pairing code repeated. + +Remote UIs, both visual and audio — such as a manufacturer-specific mobile app or a web UI — are +expressly permitted in the set of acceptable mechanisms for conveyance of the onboarding infor­ +mation. + +This method allows a current Administrator to set multiple Nodes for commissioning with a new +administrator with an appropriate Commissioning Window, by opening a commissioning window +using the OpenCommissioningWindow command and sending the PAKE passcode verifier to a +series of Nodes. The new Administrator uses the information in Manual Pairing Code to discover +the Nodes that are in Commissioning mode and commission them using the new passcode. + +The following steps describe a possible sequence of events for ECM commissioning: + +1. Current Administrator puts the Node(s) in commissioning mode for a specified time window + with a new setup passcode, and receives success responses from the involved Node(s) on the + OpenCommissioningWindow command. + a.When one or more ICD are among the targeted Nodes, the current Administrator can guide + the user to perform some action to 'wake' these devices from their sleep cycle. +2. Current Administrator presents Onboarding Payload as described above. +3. New Administrator completes commissioning within the prescribed window using steps out­ + +``` +Page 298 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +lined in Figure 32, “Concurrent connection commissioning flow”. +``` +**5.6.4. Open Commissioning Window** + +The following sequence diagram shows steps current Administrator takes to enable Open Commis­ +sioning Window. + +_Figure 34. Open Commissioning Window (Administrator A)_ + +**5.7. Device Commissioning Flows** + +This section describes the three different flows for out-of-box commissioning that a Matter device +manufacturer may select for a given product. For each flow, a description is provided which +includes actions required to place the device into commissioning mode, fields in the Onboarding +Payload which identify the flow selected by the device manufacturer, fields in the Distributed Com­ +pliance Ledger that provide information used for commissioning and help the Commissioner pro­ +vide the user with appropriate instructions, and requirements for device packaging relating to the +Onboarding Payload. The three flows are the following: + +- Standard Commissioning Flow +- User-Intent Commissioning Flow +- Custom Commissioning Flow + +Matter device manufacturers SHALL use the Distributed Compliance Ledger to provide commis­ +sioners with information and instructions for both initial and secondary commissioning, and +SHOULD use this Ledger to provide links to the user guide, a link to a manufacturer app, and other +pre-setup information, to enable an optimal commissioning flow without requiring bilateral +arrangements between each commissioner manufacturer and each device manufacturer. +Some fields in the Ledger SHALL or SHOULD be populated, depending on the type of commission­ +ing flow, as detailed in the text below and in the Distributed Compliance Ledger section. + +**5.7.1. Standard Commissioning Flow** + +- A Standard Commissioning Flow device SHALL be available for initial commissioning by any + Matter commissioner. +- A Standard Commissioning Flow device, when in factory-new state, SHALL start advertising + automatically upon power on (see Commencement). +- A Standard Commissioning Flow device SHALL set Custom Flow bits in the Onboarding Payload + to indicate '0 - Standard Flow'. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 299 +``` + +- A Standard Commissioning Flow device SHALL follow the rules for Manual Pairing Code and QR + Code Inclusion. +- For the case where the device has stopped advertising (e.g. user has powered on the device + longer ago than the advertisement period), the manufacturer SHOULD provide guidance about + how to bring the device back into advertising mode using the CommissioningModeInitial­ + StepsHint field from the Distributed Compliance Ledger. Commissioners SHOULD use this infor­ + mation to guide the user for this case. +- When commissioning fails, the commissioner MAY also reference Distributed Compliance + Ledger fields such as CommissioningFallbackUrl (see Section 5.7.5, “Commissioning Fallback + Mechanism”), UserManualUrl, SupportUrl and ProductUrl to assist the user in further steps to + resolve the issue(s). +- The Distributed Compliance Ledger entries for Standard Commissioning Flow devices SHALL + include the CommissioningCustomFlow field set to '0 - Standard' and the CommissioningMod­ + eInitialStepsHint field set to a non-zero integer value, with bit 0 (Power Cycle) being set to 1. The + CommissioningModeInitialStepsInstruction field SHALL be set when CommissioningModeIni­ + tialStepsHint has a Pairing Instruction dependency. + +_Table 57. Values of Ledger fields to represent Standard Commissioning Flow_ + +``` +Field Name Value(s) +CommissioningCustomFlow 0 - Standard (Mandatory) +CommissioningModeInitialStepsHint This field SHALL be set to a non-zero integer +value. See Pairing Hint Table for a complete list +of pairing instructions. +``` +``` +Example value: 33 - The following bits are set: 0 +(Power Cycle - Mandatory), 5 (Device Manual - +Optional). Bit 1 (Device Manufacturer URL) MAY +be set. +CommissioningModeInitialStepsInstruction The field SHALL be set when Commissioning­ +ModeInitialStepsHint has a Pairing Instruction +dependency. See PI Dependency column of Pair­ +ing Hint Table to determine which pairing hints +have Pairing Instruction dependency and there­ +fore require this field to be populated. +``` +**5.7.2. User-Intent Commissioning Flow** + +- A User-Intent Commissioning Flow device SHALL be available for initial commissioning by any + Matter commissioner. +- A User-Intent Commissioning Flow device, when in factory-new state, SHALL NOT start adver­ + tising automatically upon application of power (see Commencement). +- To place a User-Intent Commissioning Flow device into advertising mode, some form of user + interaction with the device beyond application of power is required (see Pairing Hint Table). If a + Device Manufacturer setup artifact is required for this, beyond documentation, then the device + +``` +Page 300 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +is a Custom Commissioning Flow device and not a User-Intent Commissioning Flow device. The +documentation MAY be printed or in the form of online documentation (e.g. Section 11.23.6.15, +“UserManualUrl”). +``` +- A User-Intent Commissioning Flow device SHALL follow the rules for Manual Pairing Code and + QR Code Inclusion. +- The Distributed Compliance Ledger entries for User-Intent Commissioning Flow devices SHALL + include the CommissioningCustomFlow field set to '1 - User Intent' and the CommissioningMod­ + eInitialStepsHint field set to a non-zero integer value. Bit 0 (Power Cycle) in the Commissioning­ + ModeInitialStepsHint field SHALL be set to 0. The CommissioningModeInitialStepsInstruction + field SHALL be set when CommissioningModeInitialStepsHint has a Pairing Instruction depen­ + dency. +- A User-Intent Commissioning Flow device SHALL set Custom Flow bits in the Onboarding Pay­ + load to indicate '1 - User Intent'. +- The commissioner SHOULD reference Distributed Compliance Ledger fields such as Commis­ + sioningModeInitialStepsHint, CommissioningModeInitialStepsInstruction, UserManualUrl, and + SupportUrl to assist the user during commissioning, e.g. to explain how to bring the device into + commissioning mode. + +_Table 58. Values of Ledger fields to represent User-Intent Commissioning Flow_ + +``` +Field Name Value(s) +CommissioningCustomFlow 1 - User Intent (Mandatory) +CommissioningModeInitialStepsHint This field SHALL be set to a non-zero integer +value. See Pairing Hint Table for a complete list +of pairing instructions. +``` +``` +Example value: 96 - The following bits are set: 6 +(Press Reset Button - Optional), 5 (Device Man­ +ual - Optional). Bit 1 (Device Manufacturer URL) +MAY be set. +CommissioningModeInitialStepsInstruction The field SHALL be set when Commissioning­ +ModeInitialStepsHint has a Pairing Instruction +dependency. See PI Dependency column of Pair­ +ing Hint Table to determine which pairing hints +have Pairing Instruction dependency and there­ +fore require this field to be populated. +``` +**5.7.3. Custom Commissioning Flow** + +- A Custom Commissioning Flow device SHALL require interaction with custom steps, guided by a + service provided by the manufacturer for initial device setup, before it can be commissioned by + any Matter commissioner. +- A Custom Commissioning Flow device that supports the Enhanced Setup Flow SHALL include a + usable Onboarding Payload on-device or in packaging, so that a Commissioner which supports + the Enhanced Setup Flow can commission the device using the information provided in the + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 301 +``` + +``` +Onboarding Payload. +``` +- A Custom Commissioning Flow device which does not support Enhanced Setup Flow MAY + include the Onboarding Payload on-device or in packaging. + ◦ If the Onboarding Payload is not included, then it SHALL be provided to the user through + other means provided by the manufacturer. +- A Custom Commissioning Flow device SHALL set Custom Flow bits in the Onboarding Payload + to indicate '2 - Custom'. +- The Distributed Compliance Ledger entries for Custom Commissioning Flow devices SHALL + include: + ◦ the CommissioningCustomFlow field set to '2 - Custom' + ◦ the CommissioningModeInitialStepsHint with bit 0 (Power Cycle) set to 0 and bit 1 (Device + Manufacturer URL) set to 1 + ◦ the CommissioningCustomFlowUrl field populated in order to indicate to commissioners + that initial commissioning can only be completed by the user visiting the URL contained + therein. + This URL will typically lead to a web page with relevant instructions and/or to a server + which (e.g. by looking at the User-Agent) redirects the user to allow viewing, downloading, + installing or using a manufacturer-provided means for guiding the user through the process + and bring the device into a state that it is available for commissioning by any commissioner. + Since the URL is retrieved from a DCL entry corresponding to a specific VID and PID combi­ + nation, the device manufacturer MAY choose to use any constructed URL valid in a HTTP + GET request (i.e. dedicated for the product the user wants to commission) such as, for exam­ + ple, https://domain.example/download-install-app?vid=FFF1&pid=1234. +- When a Commissioner encounters a device with Custom Flow field (in Onboarding Payload) or + its CommissioningCustomFlow field (in Distributed Compliance Ledger) set to '2 - Custom', it + SHOULD use the CommissioningCustomFlowUrl to guide the user on how to proceed, unless it + has alternative means to guide the user to successful commissioning (for example, if the com­ + missioner supports the set of EnhancedSetupFlowOptions required by the device). + ◦ If a Commissioner follows or launches the CommissioningCustomFlowUrl after a User + request, it SHALL expand it as described in Section 5.7.3.1, “CommissioningCustomFlowUrl + format”. +- If EnhancedSetupFlowOptions indicates to use the Enhanced Setup Flow and the flags indicated + are supported by the Commissioner, then the commissioner SHOULD perform the required + steps described in Enhanced Setup Flow rather than following the CommissioningCustom­ + FlowUrl. +- A manufacturer contemplating using this flow should realize that + ◦ This flow typically requires internet access to access the URL, so initial commissioning of the + device may fail if there is no internet connection at that time/location. + ◦ If the flow requires an app, it needs to be made available for popular platforms amongst the + user population; some of their platforms running a commissioner (e.g. a smart speaker not + running a popular mobile OS) may thus not be able to be used for the initial commissioning + of such devices. + +Page 302 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +_Table 59. Values of Ledger fields to represent Custom Commissioning Flow_ + +``` +Field Name Value(s) +CommissioningCustomFlow 2 - Custom (Mandatory) +CommissioningCustomFlowUrl 'URL' - Device Manufacturer URL (Mandatory) +CommissioningModeInitialStepsHint This field SHALL be set to a non-zero integer +value with at least bit 1 set (Device Manufac­ +turer URL). See Pairing Hint Table for a com­ +plete list of pairing instructions. +``` +``` +Example value: 2 - The following bits are set: 1 +(Device Manufacturer URL) (Mandatory). +CommissioningModeInitialStepsInstruction The field SHALL be set when Commissioning­ +ModeInitialStepsHint has a Pairing Instruction +dependency. See PI Dependency column of Pair­ +ing Hint Table to determine which pairing hints +have Pairing Instruction dependency and there­ +fore require this field to be populated. +``` +**5.7.3.1. CommissioningCustomFlowUrl format** + +The CommissioningCustomFlowUrl MAY contain a query component (see RFC 3986 section 3.4). If a +query is present, it SHALL be composed of one or more key-value pairs: + +- The query SHALL use the & delimiter between key/value pairs. +- The key-value pairs SHALL in the format name= where name is the key name, and + is the contents of the value encoded with proper URL-encoded escaping. +- If key MTcu is present, it SHALL have a value of "_" (i.e. MTcu=_). This is the "callback URL (Call­ + backUrl) placeholder". +- If key MTop is present, it SHALL have a value of "_" (i.e. MTop=_). This is the "onboarding payload + placeholder". +- Any key whose name begins with MT not mentioned in the previous bullets SHALL be reserved + for future use by this specification. Manufacturers SHALL NOT include query keys starting with + MT in either the CommissioningCustomFlowUrl or CallbackUrl unless they are referenced by a ver­ + sion of this specification. + +When the CommissioningCustomFlowUrl for a Custom Commissioning Flow device includes the MTop +key, the Passcode embedded in any Onboarding Payload placed on-device or in packaging SHALL +NOT be one that can be used for secure channel establishment with the device. This requirement is +intended to ensure a shared secret used for proof of possession will not be transferred to a server +without user consent. A Custom Commissioning Flow device MAY utilize Onboarding Payload fields +such as the Serial Number (see kTag_SerialNumber) to pass device identification to the server speci­ +fied in CommissioningCustomFlowUrl, as these fields by themselves could not be used to gain access to +the device on their own like the Passcode could. + +When the CommissioningCustomFlowUrl for a Custom Commissioning Flow device includes the MTop + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 303 +``` + +key, the Passcode embedded in any Onboarding Payload placed on-device or in packaging MAY be +set to 0 in order to provide a hint to the Commissioner that it is not one that can be used for secure +channel establishment with the device. This would allow the Commissioner to avoid attempting to +commission the device if an advertisement from it is detected. + +Any other element in the CommissioningCustomFlowUrl query field not covered by the above rules, as +well as the fragment field (if present), SHALL remain as obtained from the Distributed Compliance +Ledger's CommissioningCustomFlowUrl field, including the order of query key/value pairs present. + +**5.7.3.1.1. Expansion of CommissioningCustomFlowUrl by Commissioner** + +Once the URL is obtained, it SHALL be expanded to form a final URL (ExpandedCommissioningCustom­ +FlowUrl) by proceeding with the following substitution algorithm on the original CommissioningCus­ +tomFlowUrl: + +1. If key MTcu is present, compute the CallbackUrl desired (see Section 5.7.3.2, “CallbackUrl format + for Custom Commissioning Flow response”), and substitute the placeholder value "_" (i.e. in + MTcu=_) in the CommissioningCustomFlowUrl with the desired contents, encoded with proper URL- + encoded escaping (see RFC 3986 section 2). +2. If key MTop is present, substitute the placeholder value "_" (i.e. in MTop=_) in the CommissioningCus­ + tomFlowUrl with either numeric manual code, or QR code body including the MT: prefix and TLV + data (if present), encoded with proper URL-encoded escaping (see RFC 3986 section 2). Note that + both methods SHOULD be supported by the Manufacturer’s custom flow. + +A Commissioner SHALL NOT append the MTop= query key/value pair unless the key/value pair was +already present as MTop=_ in the CommissioningCustomFlowUrl previously obtained. This constraint +enables the determination of which products make use of the payload in their Custom Commission­ +ing Flow infrastructure by inspection of the Distributed Compliance Ledger records. + +The final URL after expansion (ExpandedCommissioningCustomFlowUrl) SHALL be the one to follow per +Section 5.7.3, “Custom Commissioning Flow”, rather than the original value obtained from the Dis­ +tributed Compliance Ledger. + +**5.7.3.2. CallbackUrl format for Custom Commissioning Flow response** + +If a CallbackUrl field (i.e. MTcu=) query field placeholder is present in the CommissioningCustom­ +FlowUrl, the Commissioner MAY replace the placeholder value "_" in the ExpandedCommissioningCus­ +tomFlowUrl with a URL that the manufacturer custom flow can use to make a smooth return to the +Commissioner when the device is in a state that it can be commissioned. + +This URL field MAY contain a query component (see RFC 3986 section 3.4). + +If a query is present, it SHALL be composed of one or more key-value pairs: + +- The query SHALL use the & delimiter between key/value pairs. +- The key-value pairs SHALL follow the format name= where name is the key name, and + is the contents of the value encoded with proper URL-encoded escaping. +- If key MTrop is present, it SHALL have a value of "_" (i.e. MTrop=_). This is the placeholder for a + "returned onboarding payload" provided by the manufacturer flow to the Commissioner. + +``` +Page 304 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Any key whose name begins with MT not mentioned in the previous bullets SHALL be reserved + for future use by this specification. + +Any other element in the CallbackUrl query field not covered by the above rules, as well as the frag­ +ment field (if present), SHALL remain as provided by the Commissioner through embedding within +the ExpandedCommissioningCustomFlowUrl, including the order of query key/value pairs present. + +**5.7.3.2.1. Expansion of CallbackUrl by the manufacturer custom flow** + +Once the CallbackUrl is obtained by the manufacturer flow, it MAY be expanded to form a final +ExpandedCallbackUrl URL to be used by proceeding with the following substitution algorithm on the +provided CallbackUrl: + +- If key MTrop is present, the manufacturer custom flow having received the initial query contain­ + ing the CallbackUrl MAY compute an Onboarding Payload in QR code format including MT: pre­ + fix, and substitute the placeholder value "_" (i.e. in MTrop=_) in the CallbackUrl with the desired + contents, encoded with proper URL-encoded escaping (see RFC 3986 section 2). + ◦ The contents of the MTrop=_ key/value pair in the ExpandedCallbackUrl SHALL only be + expanded if the manufacturer custom flow, having received the initial query containing the + CallbackUrl, supports opening a commissioning window on the target device and supports + conveying the corresponding onboarding payload to the Commissioner. + ◦ The return onboarding payload, if provided, SHALL contain an ephemeral Passcode and not + a permanent code that can be used in a subsequent commissioning window. If the manufac­ + turer wants the Passcode embedded in the Onboarding Payload placed on-device or in pack­ + aging to be the one used for session establishment with the Commissioner, then the manu­ + facturer SHALL NOT include the MTop key in its CommissioningCustomFlowUrl and SHALL NOT + populate the MTrop value in the CallbackUrl expansion. + ◦ The contents of the return onboarding payload, if provided, SHALL be constructed to match + the state of the device at the moment the ExpandedCallbackUrl is opened. At least one ingredi­ + ent which needs to be adapted relative to the received Onboarding Payload is the Custom + Flow field which needs to be 0 for the return onboarding payload. + ◦ The presence of this field is to assist automatically resuming commissioning without addi­ + tional data entry (QR code or numeric manual code) by the user at the Commissioner that + initially triggered the custom flow. The manufacturer custom flow SHOULD provide an alter­ + nate means of conveying the onboarding payload, such as a manual pairing code. + ◦ Note that if the information in the initial onboarding payload that caused triggering of a + Custom Commissioning Flow was directly usable, it may be used by the Commissioner, + either upon being triggered through the ExpandedCallbackUrl having been opened, or + autonomously as a fallback. + ◦ Commissioners providing a CallbackUrl to the manufacturer custom flow through the + ExpandedCommissioningCustomFlowUrl SHOULD support using the ExpandedCallbackUrl to trig­ + ger resumption of Commissioning flow if the ExpandedCallbackUrl is followed, otherwise the + Commissioner SHOULD NOT substitute the MTcu query field when expanding the Commission­ + ingCustomFlowUrl into the ExpandedCommissioningCustomFlowUrl. + ◦ If the manufacturer custom flow failed to make the device commissionable, it SHALL NOT + replace the placeholder value "_" of an included MTrop=_ key/value pair, to avoid a Commis­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 305 +``` + +``` +sioner attempting to discover or commission a device not made ready by the custom flow. +``` +A manufacturer custom flow having received an ExpandedCommissioningCustomFlowUrl SHOULD +attempt to open the ExpandedCallbackUrl, on completion of the steps, if an ExpandedCallbackUrl was +computed from the CallbackUrl and opening such a URL is supported. + +**5.7.3.3. Examples of CommissioningCustomFlow URLs** + +Below are some examples of valid ExpandedCommissioningCustomFlowUrl for several valid values of +CommissioningCustomFlowUrl, as well as some examples of invalid values of CommissioningCustom­ +FlowUrl: + +- Valid URL with no query string: + ◦ Before expansion: https://company.domain.example/matter/custom/flows/vFFF1p1234 + ◦ After expansion: https://company.domain.example/matter/custom/flows/vFFF1p1234 (no + change) +- Invalid URL with no query string: http scheme is not allowed: + ◦ [http://company.domain.example/matter/custom/flows/vFFF1p1234](http://company.domain.example/matter/custom/flows/vFFF1p1234) +- Valid URL with basic manufacturer-specific scheme for query: + ◦ Before expansion: https://company.domain.example/matter/custom/flows?vid=FFF1& + pid=1234 + ◦ After expansion: https://company.domain.example/matter/custom/flows?vid=FFF1&pid=1234 + (no change) +- Valid URL with MTop=_ placeholder using QR format onboarding payload embedding: + ◦ Before expansion: https://company.domain.example/matter/custom/flows?vid=FFF1& + pid=1234&MTop=_ + ◦ After expansion: https://company.domain.example/matter/custom/flows?vid=FFF1& + pid=1234&MTop=MT%3A-MOA57ZU02IT2L2BJ00 + ▪ Onboarding payload QR content MT:-MOA57ZU02IT2L2BJ00 was embedded within MTop key +- Valid URL with MTop=_ placeholder using numeric manual code onboarding payload embedding: + ◦ Before expansion: https://company.domain.example/matter/custom/flows?vid=FFF1& + pid=1234&MTop=_ + ◦ After expansion: https://company.domain.example/matter/custom/flows?vid=FFF1& + pid=1234&MTop=610403146665521046600 + ▪ Onboarding numeric manual code 610403146665521046600 was embedded within MTop key +- Valid URL with MTop=_ placeholder using numeric manual code onboarding payload embedding, + using a different order of keys/value pairs than the previous example: + ◦ Before expansion: https://company.domain.example/matter/custom/flows?pid=1234& + MTop=_&vid=FFF1 + ◦ After expansion: https://company.domain.example/matter/custom/flows?pid=1234& + MTop=610403146665521046600&vid=FFF1 + +``` +Page 306 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +▪ Onboarding numeric manual code 610403146665521046600 was embedded within MTop key +``` +- Valid URL with onboarding payload elided (because commissioner could not provide it): + ◦ Before expansion: https://company.domain.example/matter/custom/flows?vid=FFF1& + pid=1234&MTop=_ + ◦ After expansion: https://company.domain.example/matter/custom/flows?vid=FFF1& + pid=1234&MTop=_ (no change) +- Valid URL, return onboarding payload and CallbackUrl requested: + ◦ Before expansion: + +``` +https://company.domain.example/matter/custom/flows?vid=FFF1&pid=1234&MTop=_&MTcu +=_ +``` +``` +◦ After expansion: +``` +``` +https://company.domain.example/matter/custom/flows?vid=FFF1&pid=1234&MTop=MT%3A- +MOA57ZU02IT2L2BJ00&MTcu=https%3A%2F%2Fcommissioner.domain.example%2Fcb%3Ftoken%3 +DmAsJ6_vqbr-vjDiG_w%253D%253D%26MTrop%3D_ +``` +``` +◦ The ExpandedCommissioningCustomFlow URL contains: +▪ An embedded onboarding payload QR content value of MT:-MOA57ZU02IT2L2BJ00 +▪ A CallbackUrl with a Commissioner-provided arbitrary token= key/value pair and the +MTrop= key/value pair place-holder to indicate support for a return onboarding payload: +https://commissioner.domain.example/cb?token=mAsJ6_vqbr-vjDiG_w%3D%3D& +MTrop=_ +▪ After expansion of the CallbackUrl (MTcu key) into an ExpandedCallbackUrl, with an exam­ +ple return onboarding payload of MT:-MOA5.GB00V68T62O10, the ExpandedCallbackUrl would +be: +``` +``` +https://commissioner.domain.example/cb?token=mAsJ6_vqbr- +vjDiG_w%3D%3D&MTrop=MT%3A-MOA5.GB00V68T62O10 +``` +``` +Note that the MTcu key/value pair was initially provided URL-encoded within the Expand­ +edCommissioningCustomFlow URL and the MTrop=_ key/value pair placeholder now contains +a substituted returned onboarding payload. +``` +- Invalid URL, due to MTza=79 key/value pair in reserved MT-prefixed keys reserved for future use: + ◦ https://company.domain.example/matter/custom/flows?vid=FFF1&pid=1234&MTop=_& + MTza=79 + +**5.7.3.4. Example Custom Commissioning Flow** + +An example of this flow is illustrated below. The "DCL info" concept denotes that the Commissioner +SHALL collect the information from the DCL via some mechanism, such as a network resource + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 307 +``` + +accessible to the Commissioner containing a replicated set of the DCL’s content. + +_Figure 35. Custom Commissioning Flow sequence diagram_ + +In the flow above: + +- In the final steps, the User might have to perform the trigger to the first Commissioner, so that it + can start or continue the commissioning process. +- If possible, a Commissioner MAY continue to scan for announcements from the device in the + background while any manufacturer-specific app is configuring the device to be available for + commissioning. The Commissioner might need a new OnboardingPayload provided to the User + by the Manufacturer Website or App. +- In order to simplify the flow, the Commissioner MAY: + ◦ Include the onboarding payload obtained from the user (see MTop key in Section 5.7.3.1, + “CommissioningCustomFlowUrl format”) within the CommissioningCustomFlowUrl. + ◦ Include a callback URL (see MTcu key in Section 5.7.3.1, “CommissioningCustomFlowUrl for­ + mat”) within the ExpandedCommissioningCustomFlowUrl. +- The Manufacturer Website or App MAY utilize the CallbackUrl field, if provided in the query + string, in order to simplify the process for signaling the completion of the manufacturer-specific + part of the flow back to the Commissioner. When doing so, the Manufacturer Website or App + SHOULD put the device into Commissioning mode and SHOULD provide the corresponding + onboarding payload to the Commissioner using the MTrop key/value pair within the Expanded­ + CallbackUrl. + +**5.7.4. Enhanced Setup Flow (ESF)** + +The Enhanced Setup Flow feature provides an optional way for a Custom Commissioning Flow + +``` +Page 308 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +device to specify in a standardized way a set of additional commissioning steps that a device +requires which are not included in the Standard Commissioning Flow performed by commission­ +ers. For example, some devices require the user to read and accept a set of terms and conditions +provided by the manufacturer before the device setup can complete. Since Standard Commission­ +ing Flow does not include this functionality, a device with this requirement is compelled to use Cus­ +tom Commissioning Flow. The Enhanced Setup Flow feature allows a commissioner which under­ +stands how to perform the additional commissioning steps required by a device to replace the Cus­ +tom Commissioning Flow by performing the additional commissioning steps as part of an enhanced +Standard Commissioning Flow. + +For the Enhanced Setup Flow feature, additional commissioning steps are defined such as the need +for a Terms and Conditions acknowledgement. A Custom Commissioning Flow device can indicate +via Enhanced Setup Flow Options whether it supports the Enhanced Setup Flow feature and if so, +which of the defined common additional commissioning steps it requires. + +- A manufacturer contemplating using this flow has to consider that: + ◦ Enhanced Setup Flow needs to be supported by the Commissioner in order to be used during + commissioning. + ◦ If Enhanced Setup Flow is not supported by the commissioner, then the commissioner and + device both need to support Custom Commissioning Flow in order for the device to be suc­ + cessfully commissioned. + +``` +NOTE Support for the Enhanced Setup Flow is provisional. +``` +_Table 60. Enhanced Setup Flow Options Values_ + +``` +Bit index Name Description +0 TC on initial Commission A commissioner is required to +show Terms and Conditions +content if this is the initial com­ +missioning for the device out of +a factory-reset state. +1 Disallow user TC responses +reuse for required TC +``` +``` +The commissioner SHALL NOT +reuse user’s responses to the +required Terms and Conditions +from commissioning a previous +product (same VID) with the +same T&C. +2 Disallow user TC responses +reuse for non-required TC +``` +``` +The commissioner SHALL NOT +reuse user’s responses to the +non-required Terms and Condi­ +tions from commissioning a +previous product (same VID) +with the same T&C. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 309 +``` + +``` +Bit index Name Description +3 Disallow user TC responses +reuse between PIDs +``` +``` +The commissioner SHALL NOT +reuse user’s responses to the +Terms and Conditions from +commissioning a previous prod­ +uct (same VID, other PID) with +the same T&C. +``` +**5.7.4.1. Terms and Conditions (TC) Acknowledgement** + +One additional step defined in the Enhanced Setup Flow feature involves the display and collection +of user acknowledgement of a set of Terms and Conditions defined by the device manufacturer. +Commissioners that support this feature SHALL obtain the set of Terms and Conditions texts from +the URL defined in Enhanced Setup Flow Url. This file SHALL only be used when successfully vali­ +dated using Section 11.23.6.24, “EnhancedSetupFlowTCDigest”, Section 11.23.6.25, “EnhancedSe­ +tupFlowTCFileSize”, and the TC File Format. When the ESF file is not found, or validation fails, the +Commissioner SHALL proceed using the Custom Commissioning Flow. + +The Commissioner SHALL present the terms in a such a way that the user is given primary focus on +the text and the text is not hidden, obscured, or omitted, unless allowed by exceptions indicated in +this section. The user SHALL be given an option to either accept or decline each of the provided +texts. If the user declines any text that are marked as required, then the commissioner SHALL end +commissioning and notify the user that the device cannot be commissioned due to their refusal of +the terms. + +**5.7.4.2. Reuse of Cached Acknowledgements** + +In certain cases, such as commissioning multiple instances of the same or similar product, the +device manufacturer might not require repeated acknowledgements for each instance. + +Examples (the corresponding setting of the bits is indicated in the table below) + +1. A manufacturer of motion sensors (same PID) requires acknowledgement of the T&C only when + commissioning the first motion sensor - but not for a Smoke/CO sensor (other PID) from same + manufacturer - not allowing reuse of acceptance between PIDs. +2. A manufacturer of luminaires of different sizes (various PIDs) requires acknowledgement of the + T&C only when commissioning the first luminaire - allowing reuse of acceptance between PIDs + with same T&C. +3. A manufacturer of a range of cameras has both required and non-required T&C. The non- + required T&C concern uploading video stills to a manufacturer’s server for e.g. storage and + delayed replay. The user’s consent to the non-required T&C (for remote data storage) can be dif­ + ferent on how/where the camera is used. For example, they might want to allow this for a cam­ + era overlooking the front yard, but not for a camera in a bedroom. In this case, the "Disallow + user TC responses reuse for non-required TC" bit is set to 1, which would make the commis­ + sioner present the required T&C only once, but present the non-required T&C for every camera + device being commissioned, so the user can make a decision on remote data storage for each + camera separately. + +``` +Page 310 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The table below defines when caching MAY be used, based on the bits "Disallow user TC responses +reuse for required TC", "Disallow user TC responses reuse for non-required TC" and "Disallow user +TC responses reuse between PIDs" of EnhancedSetupFlowOptions. In conditions marked with yes in +the table, a commissioner MAY cache a user’s acknowledgements and use them for future commis­ +sioning of products with the same T&C. In conditions marked with no, the commissioner SHALL +NOT use a cached user’s acknowledgements. + +_Table 61. Enhanced Setup Flow - Use of Cached Acknowledgements_ + +``` +Bit 1 Bit 2 Bit 3 same PID, +required +T&C +``` +``` +same PID, +non- +required +T&C +``` +``` +other PID, +required +T&C +``` +``` +other PID, +non- +required +T&C +``` +``` +example +``` +``` +0 0 0 yes yes yes yes 2 +0 1 0 yes no yes no 3 +0 0 1 yes yes no no 1 +0 1 1 yes no no no +1 x x no no no no +``` +Reuse of cached acknowledgements SHALL NOT be used when the VID for the product currently +being commissioned is different from the product for which the user has reviewed and acknowl­ +edged the T&C. + +If a Commissioner caches Terms and Conditions acknowledgement responses, then it SHOULD also +provide the user a way to remove or update the cached responses. For example, an option could be +provided to the user for removing all saved responses, ensuring they would be prompted with +Terms and Conditions the next time they commissioned a device which previously had cached +responses. + +**5.7.4.2.1. Definition of "same T&C"** + +The above text uses the phrase "same T&C". Caching SHALL NOT be done when the ESF file pre­ +sented to the user has changed between when they reviewed and acknowledged it and the current +commissioning, i.e. if values of one or both of EnhancedSetupFlowTCDigest and EnhancedSe­ +tupFlowTCRevision have changed. + +**5.7.4.3. Use of T&C Acknowledgment during the Custom Commissioning Flow** + +When Custom Commissioning Flow is used for displaying Terms and Conditions, the manufacturer- +provided means for obtaining user consent SHALL ensure that commissioning can be completed by +the original commissioner without performing Terms and Conditions steps by setting TCAcknowl­ +edgementsRequired to False, TCAcceptedVersion to the accepted version of the Terms and Condi­ +tions, and TCAcknowledgements with the responses provided by the user. + +A manufacturer contemplating using Terms and Conditions should realize that extending or adding +them to a product using software updates needs to be considered with great care and SHOULD be +avoided to prevent consumer frustration. For example: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 311 +``` + +- Extending the list of required terms (more requirements that the user MUST agree to) has the + risk that the user will not accept the new terms and be confronted with a device which will + longer function as before. +- Adding Terms and Conditions to a product which previously did not have them will likely result + in confusion with the user who could be confronted with a Terms and Conditions dialog after + the update. + +**5.7.4.4. Example of Enhanced Setup Flow for Terms and Conditions** + +_Figure 36. Enhanced Setup Flow TC commissioning sequence diagram_ + +**5.7.4.5. Presenting Updated Terms and Conditions** + +When required by the manufacturer, a device MAY update TCMinRequiredVersion and set TCAc­ +knowledgementsRequired to True, indicating to an Administrator that updated Terms and Condi­ +tions are available for presentation to the user. The Administrator SHOULD subscribe to the TCAc­ +knowledgementsRequired attribute in order to detect this situation. The Administrator SHOULD +present the updated Terms and Conditions in a similar manner to how they would be presented +during the commissioning flow, as documented in Terms and Conditions Acknowledgement. The +user’s responses SHALL be propagated back to the node with SetTCAcknowledgements. + +Until new acknowledgements have been received, the device MAY operate with limited functional­ +ity related to such functionality for which the updated Terms & Conditions are more restrictive +than the agreed ones - until new acknowledgements have been received. Since Administrators are +recommended but not required to present updated Terms and Conditions to the user, any such limi­ +tation in functionality could lead to a potentially confusing and frustrating experience for the user. +As a result, this condition SHOULD be avoided by the manufacturer if possible. If a device opts to +enforce updated Terms and Conditions in this way, then it SHOULD inform the user of this require­ +ment in the provided Terms and Conditions and use TCUpdateDeadline to indicate the deadline +before any action takes place. If TCUpdateDeadline is non-null, then the Administrator SHOULD +inform the user by when they must accept the updated Terms and Conditions to avoid any impact + +``` +Page 312 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +to device functionality. Any interactions which cannot succeed due to this functionality limitation +SHALL return the TERMS_AND_CONDITIONS_CHANGED failure status code. An administrator +encountering this status code SHOULD direct the user to the URL located at EnhancedSetupFlow­ +MaintenanceUrl, where the user can be directed on required actions for resolution. Upon satisfac­ +tory acceptance of the updated Terms and Conditions, the device SHALL operate with the function­ +ality of the related features, taking into account the user response. + +Where re-use of T&C acceptance between products is allowed (see Section 5.7.4.2, “Reuse of Cached +Acknowledgements”, upon acceptance of acknowledgements for a new EnhancedSetupFlowTCRevi­ +sion by the user, the Administrator MAY set the latest acknowledgements to all applicable devices +using SetTCAcknowledgements. + +_Figure 37. Presenting updated Enhanced Setup Flow features diagram_ + +**5.7.4.6. Terms and Conditions File Format** + +The file contained at EnhancedSetupFlowTCUrl is a JSON file containing the localized version of the +texts to be displayed to the user for the Enhanced Setup Flow Terms & Conditions. Encoding of the +file SHALL be UTF-8. + +**5.7.4.6.1. schemaVersion Field** + +This field SHALL indicate the version of the JSON schema format. This helps in managing changes +to the structure of the schema over time. Whenever there is a change to the schema (such as +adding, removing, or modifying fields), the schemaVersion SHALL be incremented. This ensures that +the software processing these configuration files can recognize which version of the schema it is +dealing with and handle it appropriately. + +This field SHALL be present in the ESF file. + +**5.7.4.6.2. esfRevision Field** + +This field is a 16-bit integer version number of the file that SHALL match the Version at Enhanced­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 313 +``` + +SetupFlowTCRevision. + +This field SHALL be present in the ESF file. + +**5.7.4.6.3. defaultCountry Field** + +This field is an ISO 3166-1 alpha-2 country code string that indicates the default country to be used +if the user’s country is not defined in the file. + +This field SHALL be present in the ESF file. + +**5.7.4.6.4. countryEntries Field** + +This field contains a list of terms and condition entries using the associated county as the key. + +This field SHALL be present in the ESF file and contain at least one entry. + +**5.7.4.6.5. defaultLanguage Field** + +This field is an ISO 639-1 language code string that indicates the default language to be used if the +user’s language is not defined for a given country. + +This field SHALL be present in the ESF file for each entry in countryEntries. + +**5.7.4.6.6. languageEntries Field** + +This field contains a list of the different texts to be displayed using the associated language as the +key. + +This field SHALL be present in the ESF file for each entry in countryEntries and contain at least one +entry. + +**5.7.4.6.7. ordinal Field** + +This field SHALL specify which bit number this text maps to in TCAcknowledgements. Each bit in +the map SHALL keep the same purpose through the life of the product to ensure a correct interpre­ +tation of a user’s response across device firmware versions. + +This field SHALL be present in the ESF file for each entry in countryEntries. + +**5.7.4.6.8. required Field** + +This field is a boolean that indicates whether the corresponding text is required for the device’s +functionality. If set to true, the user must accept this condition to commission the device. + +This field SHALL be present in the ESF file for each entry in the list of terms under the language key +in languageEntries. + +**5.7.4.6.9. title Field** + +This field is a string that represents the title to use for the terms and conditions subsection when +presenting the text. It MAY contain the following subset of HTML tags and their corresponding clos­ +ing tags to allow for basic formatting of the presented title. Other HTML tags SHALL NOT be used. + +``` +Page 314 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The permitted HTML tags are: , , , , , and . + +This field SHALL be present in the ESF file for each entry in the list of terms under the language key +in languageEntries. + +**5.7.4.6.10. text Field** + +This field is a string that contains the text to be presented to the user. It MAY contain the following +subset of HTML tags and their corresponding closing tags to allow for formatting of the presented +terms. Other HTML tags SHALL NOT be used. The permitted HTML tags are: ,
, ,

, +

,

,

,

,
,
, ,
  • ,
      ,

      , , , , and

        . + +This field SHALL be present in the ESF file for each entry in the list of terms under the language key +in languageEntries. + +**5.7.4.7. Terms and Conditions File Localization** + +The locale selected for the TC texts SHALL be a BCP47 language tag. It SHALL be selected with the +user’s preferred language and an ISO 3166-1 alpha-2 country code. The country code SHALL repre­ +sent the country, dependent territory, or special area of geographic interest in which the Node is +located at the time. If the requested locale is not found then the default SHALL be used in its place. + +**5.7.4.8. Enhanced Setup Flow File Example (Terms and Conditions)** + +### { + +``` +"schemaVersion": 1, +"esfRevision": 1, +"defaultCountry": "US", +"countryEntries": { +"US": { +"defaultLanguage": "en", +"languageEntries": { +"en": [ +{ +"ordinal": 0, +"required": true, +"title": "Terms and Conditions", +"text": "

        Feature 1 Text

        Please accept +these.

        " +}, +{ +"ordinal": 1, +"required": false, +"title": "Privacy Policy", +"text": "

        Feature 2 Text

        " +} +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 315 +``` + +### ], + +``` +"es": [ +{ +"ordinal": 0, +"required": true, +"title": "Términos y condiciones", +"text": "

        Característica 1 Texto

        Por favor +acéptelos.

        " +}, +{ +"ordinal": 1, +"required": false, +"title": "Política de privacidad", +"text": "

        Característica 2 Texto

        " +} +] +} +}, +"MX": { +"defaultLanguage": "es", +"languageEntries": { +"es": [ +{ +"ordinal": 0, +"required": true, +"title": "Términos y condiciones", +"text": "

        Característica 1 Texto

        Por favor +acéptelos.

        " +} +] +} +}, +"CN": { +"defaultLanguage": "zh", +"languageEntries": { +"zh": [ +{ +"ordinal": 0, +"required": true, +"title": "条款和条件", +"text": "

        产品 1 文字

        " +}, +{ +``` +Page 316 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +"ordinal": 1, +"required": false, +"title": "隐私条款", +"text": "

        产品 2 文字

        " +} +] +} +}, +"RU": { +"defaultLanguage": "ru", +"languageEntries": { +"ru": [ +{ +"ordinal": 0, +"required": true, +"title": "Условия и положения", +"text": "

        Текст функции 1

        Пожалуйста, +примите эти условия пользования.

        " +}, +{ +"ordinal": 1, +"required": false, +"title": "Положение о конфиденциальности", +"text": "

        Текст функции 2

        " +} ] } } } } +``` +**5.7.5. Commissioning Fallback Mechanism** + +Commissioning using any of the methods described above can potentially fail for a number of rea­ +sons. In some cases this will be a transient failure (e.g., due to wireless interference), while in other +cases failure will be systematic (e.g., a mismatch in capabilities of the Commissioner and the Com­ +missionee). + +Especially for the latter cases, a fallback mechanism is defined which allows the Commissioner to +direct the user to a manufacturer-provided mechanism where the user can be guided towards reso­ +lution of the issues since the manufacturer typically has more knowledge about the specific device +than the commissioner. + +Examples of means that could be employed to attempt to resolve the issues: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 317 +``` + +- The CommissioningFallbackUrl can lead to a web page listing suggestions to resolve the failure + (e.g., "restart the device to start another commissioning attempt" which helps in case the 15 + minute announcement interval since power-on had expired before commissioning was + attempted) +- The CommissioningFallbackUrl can lead to a manufacturer-provided mechanism to get the + device on the IP-bearing network (which can then be followed by "commissioning while already + on IP-network"). + +**5.7.5.1. Commissioning Fallback flow for Device Manufacturers** + +For cases where commissioning failure can be anticipated (such as devices which rely on commis­ +sioning via a technology which is not mandatory for Commissioners e.g. supporting only commis­ +sioning via Wi-Fi Public Action Frame), the CommissioningFallbackUrl and DiscoveryCapabilities­ +Bitmask fields in the DeviceModel schema in the DCL SHALL be populated. For the Manual Pairing +Code for such a product, the Encoding Method with Vendor and Product ID’s included SHALL be +used so the Commissioner has access to the VendorID and ProductID for DCL-lookup of the URL. + +For other cases, this field MAY be populated to provide a manufacturer-provided mechanism in +case commissioning fails for any (other) reason. + +**5.7.5.2. Commissioning Fallback flow for Commissioners** + +When a Commissioner encounters a situation where the commissioning fails systematically (e.g., +due to a mismatch in capabilities of the Commissioner and the Commissionee), and it has no other +means to guide the user to resolution of the issues, it SHALL use the CommissioningFallbackUrl +(when provided) in the DeviceModel schema in the DCL to guide the user to the manufacturer-pro­ +vided means towards resolution of the commissioning issues. + +- In cases where using this URL is technically impossible (e.g. a headless commissioner, or the + lack of internet access) or when the Commissioner is performing offline mode commissioning, + the Commissioner SHOULD inform the user of the assumed reason for commissioning failure, + and MAY provide additional advice on how this could potentially be resolved. + +When a Commissioner encounters a situation where the commissioning failure is transient, the +Commissioner MAY try again; it also MAY use the CommissioningFallbackUrl (when provided) to +guide the user to the manufacturer-provided means towards resolution of the commissioning +issues. + +**5.7.5.3. URL used in Commissioning Fallback Mechanism** + +The CommissioningFallbackUrl MAY be constructed in the same way as the CommissioningCustom­ +FlowUrl field, including making it specific for a particular VendorID and/or ProductID (as described +in Section 5.7.3, “Custom Commissioning Flow”, 5th bullet). Also, the query components as described +in Section 5.7.3.1, “CommissioningCustomFlowUrl format” can be added to the URL to improve the +overall flow. For example, usage of MTop, MTcu and MTrop parameters would be useful to smooth the +flow in case the manufacturer-provided mechanism uses a manufacturer-defined mechanism to get +the device on the IP network, after which the original commissioner can take care of the Matter +commissioning ("device already on IP-network"). + +``` +Page 318 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +An example of this flow is illustrated below. The "DCL info" concept denotes that the Commissioner +SHALL collect the information from the DCL via some mechanism, such as a network resource +accessible to the Commissioner containing a replicated set of the DCL’s content. + +_Figure 38. Commissioning Fallback Mechanism sequence diagram_ + +In the flow above: + +- In the final steps, the User might have to perform the trigger to the Commissioner, so that it can + start or continue the commissioning process. +- If possible, a Commissioner MAY continue to scan for announcements from the device in the + background while any manufacturer-specific app is configuring the device to be available for + commissioning. The Commissioner might need a new OnboardingPayload provided to the User + by the Manufacturer Website or App. +- In order to simplify the flow, the Commissioner MAY: + ◦ Include the onboarding payload obtained from the user (see MTop key) within the Commission­ + ingFallbackUrl. + ◦ Include a callback URL (see MTcu key) within the ExpandedFallbackUrl. +- The Manufacturer Website or App MAY utilize the CallbackUrl field, if provided in the query + string, in order to simplify the process for signaling the completion of the manufacturer-specific + part of the flow back to the Commissioner. When doing so, the Manufacturer Website or App + SHOULD put the device into Commissioning mode and SHOULD provide the corresponding + onboarding payload to the Commissioner using the MTrop key/value pair within the Expanded­ + CallbackUrl. + +**5.7.6. Manual Pairing Code and QR Code Inclusion** + +Manual Pairing Code and QR setup codes enable secure commissioning and provide a consistent +experience that many users are familiar with. However, because they contain a symmetric security + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 319 +``` + +code it is not appropriate in all circumstances to have them be in a readily accessible location on +the device, such as printed on the back. + +The following are the requirements and recommendations regarding the QR Code and Manual Pair­ +ing code for Standard and User Intent Commissioning Flow Devices. Custom Commissioning Flow +Device rules are described in the Custom Commissioning Flow. + +The term 'on-device' allows for a physical label affixed to the device or printed directly on the +device, as well as one that can be displayed on demand through some physical interface properties +of the device (e.g. visual or audio). + +1. Devices SHALL include the Manual Pairing code on-device or in packaging. +2. Devices SHALL NOT have the QR nor the manual pairing code in an unprotected format on the + outer packaging. +3. Devices SHOULD include the QR Code, and SHOULD include it alongside the Manual Pairing + Code on-device or in packaging. +4. Manual Pairing Code and QR Code on-device MAY be removable or obscured to allow the owner + to prevent commissioning without their consent. +5. Devices MAY include the QR Code and Manual Pairing Code in multiple forms (see below). + +Presentation of the QR Code and Manual Pairing code on-device can occur in many forms to allow +for adherence to device security requirements and manufacturing considerations. For example +security devices could limit the access to the QR code or Manual Pairing Code to avoid an unautho­ +rized user obtaining the information by simple inspection, or make the QR code and/or Manual +Pairing Code removable. + +The following is a list of possible ways that are acceptable to satisfy the requirements of inclusion +of the QR code and Manual Pairing Code. An entry in the list should not be interpreted as being +mutually exclusive with another entry. A device SHOULD include as many of these ways as possible. + +- QR and Manual Pairing Code shown via an on-device display (when available) +- QR and Manual Pairing Code printed on-device, with removal/obscuring considerations noted + above. +- Manual Pairing Code presented on-device via audio output (when available) +- QR and Manual Pairing Code printed on in-packaging materials. + +The following are examples of QR code and Manual Pairing Code inclusion. + +- QR Code and Manual Pairing Code printed on a Matter wireless shade inside the battery com­ + partment cover, and provided in the packaging. +- QR Code and Manual Pairing code on a Matter Smart Thermostat that can be activated via an + on-device User Interface and displayed only on screen. +- QR Code and Manual Pairing code for a security sensor that is provided in the packaging, and + on-device hidden behind a tamper-monitored cover. +- QR code provided on an E12 light bulb, with manual pairing code on a removable label (the + area of QR code likely fits better on small form factor bulb than the area for a 13 character + +``` +Page 320 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +string). +``` +- A wearable device with only a Manual Pairing Code printed on the fabric. No QR code is present + because of the difficulty in scanning a QR code on an irregular surface. +- A Smart speaker, without printed QR or manual pairing code on the device (but possibly in- + packaging), that can be triggered to read out a Manual Pairing Code. + +**5.8. In-field Upgrade to Matter** + +This (informative) section discusses the case of a pre-Matter device currently in the user’s home +which gets software updated to support Matter, and which steps (either Matter-specified or manu­ +facturer specific) would typically be applied to accomplish this goal. + +- The initial situation is a device which is connected to the local network, and some manufacturer + specific means (e.g. a manufacturer-provided app) is used to provide new firmware (including + Matter functionality) to the device, along with the associated Certification Declaration. Also, a + unique Device Attestation Certificate is provided into the device using secure, manufacturer- + specific means. +- The device restarts to enable the new firmware, and is now an uncommissioned Matter device. +- The device can be commissioned by any Commissioner; the Onboarding Payload needs to be + provided to that Commissioner (since this information is not provided on or with the device out + of the factory). + ◦ For this, similar mechanisms as discussed as in Section 5.6.3, “Enhanced Commissioning + Method (ECM)” can be employed: + ▪ information equivalent to the parameters of the Open Commissioning Window com­ + mand is sent to the device using some secure manufacturer-defined means + ▪ presentation of the passcode and other relevant information can be performed using the + mechanisms described in Section 5.6.3.1, “Presentation of Onboarding Payload for ECM”. + ◦ For devices with a means to output the Onboarding Payload themselves (e.g. device with a + display or audio output), alternatively, similar mechanisms as discussed as in Section 5.6.2, + “Basic Commissioning Method (BCM)” can be employed: + ▪ information equivalent to the parameters of the Open Basic Commissioning Window + command is sent to the device using some secure manufacturer-defined means + ▪ the device itself presents Onboarding Payload. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 321 +``` + +Page 322 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 6. Device Attestation and** + +**Operational Credentials** + +This chapter describes the procedures and cryptographic credentials involved in establishing trust +between entities. + +The Device Attestation section provides mechanisms for Commissioners and Administrators to +determine whether a Node is a genuine certified product before sharing sensitive information such +as keys and other credentials. The Device Attestation feature relies on a Device Attestation Certifi­ +cate (DAC) chain and on a Certification Declaration (CD). + +The Node Operational Credentials section describes the credentials used by all Nodes to mutually +authenticate each other during Certificate-Authenticated Session Establishment, including the Node +Operational Certificate (NOC) chain. These credentials form the basis of how Nodes are identified +and take part in securing operational unicast communication. + +**6.1. Certificate Common Conventions** + +This chapter makes use of digital certificates in several subsections. All certificates within this spec­ +ification are based on X.509v3-compliant certificates as defined in RFC 5280. The storage format of +the certificates depends on application (e.g., DAC or NOC chain), but all certificates are directly com­ +patible with X.509v3 DER representation after suitable loading or decompression. + +In order to simplify further exposition, this subsection contains some common normative conven­ +tions that SHALL apply to all digital certificates described in this specification. + +The following certificate formats are defined within this specification: + +- Compressed Node Operational credentials certificate chain elements in Matter Operational Cer­ + tificate Encoding or "Matter Certificate" format: + ◦ Node Operational Certificate (NOC) + ◦ Intermediate CA Certificate (ICAC) + ◦ Root CA Certificate (RCAC) +- Device Attestation certificate chain elements in Standard X.509 DER format: + ◦ Device Attestation Certificate (DAC): see Section 6.2.2.3, “Device Attestation Certificate (DAC)” + ◦ Product Attestation Intermediate (PAI): see Section 6.2.2.4, “Product Attestation Intermediate + (PAI) Certificate” + ◦ Product Attestation Authority (PAA): see Section 6.2.2.5, “Product Attestation Authority (PAA) + Certificate” + +**6.1.1. Encoding of Matter-specific RDNs** + +In addition to the standard DN (Distinguished Names) attribute types that appear in certificate Sub­ +ject and Issuer fields, there are Matter-specific DN attribute types under the 1.3.6.1.4.1.1.37244 pri­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 323 +``` + +vate arc. These are listed in Table 62, “Matter-specific DN Object Identifiers”. These OID values are +assigned by the Connectivity Standards Alliance for use with Matter. All of these Matter-specific +RDNs encode values normatively defined as scalars. + +When used in Matter Operational Certificate (TLV) format (see Section 6.5, “Operational Certificate +Encoding”), Matter-specific DN attribute types SHALL be encoded in Matter TLV as unsigned inte­ +gers with the specified length. + +When used in X.509 ASN.1 DER format certificate encoding, Matter-specific DN attribute types +SHALL have their value encoded as either a UTF8String or PrintableString according to the table +below. The values SHALL be encoded in network byte order as exactly twice their specified maxi­ +mum octet length, encoded as uppercase hexadecimal number format without any separators or +prefix, and without omitting any leading zeroes. + +For example: + +- A scalar value 0x0123_4567_89AB_CDEF for matter-node-id: + ◦ Scalar maximal length: 8 octets (64 bits) + ◦ Resulting string: "0123456789ABCDEF" (without quotes) + ◦ Resulting length: 16 characters +- A scalar value 0xAA_33CC for matter-noc-cat: + ◦ Scalar maximal length: 4 octets (32 bits) + ◦ Resulting string: "00AA33CC" (without quotes) + ◦ Resulting length: 8 characters + +_Table 62. Matter-specific DN Object Identifiers_ + +``` +TLV Tag Matter name Length +(octets) +``` +``` +String length ASN.1 OID Types Allowed +in X.509 +17 matter-node-id 8 16 1.3.6.1.4.1.3724 +4.1.1 +``` +``` +UTF8String +``` +``` +18 matter- +firmware-sign­ +ing-id +``` +### 8 16 1.3.6.1.4.1.3724 + +### 4.1.2 + +``` +UTF8String +``` +``` +19 matter-icac-id 8 16 1.3.6.1.4.1.3724 +4.1.3 +``` +``` +UTF8String +``` +``` +20 matter-rcac-id 8 16 1.3.6.1.4.1.3724 +4.1.4 +``` +``` +UTF8String +``` +``` +21 matter-fabric- +id +``` +### 8 16 1.3.6.1.4.1.3724 + +### 4.1.5 + +``` +UTF8String +``` +``` +22 matter-noc-cat 4 8 1.3.6.1.4.1.3724 +4.1.6 +``` +``` +UTF8String +``` +``` +N/A matter-oid-vid 2 4 1.3.6.1.4.1.3724 +4.2.1 +``` +``` +UTF8String, +PrintableString +``` +``` +Page 324 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +TLV Tag Matter name Length +(octets) +``` +``` +String length ASN.1 OID Types Allowed +in X.509 +N/A matter-oid-pid 2 4 1.3.6.1.4.1.3724 +4.2.2 +``` +``` +UTF8String, +PrintableString +``` +**6.1.2. Key Identifier Extension Constraints** + +Whenever an X.509 certificate contains Authority Key Identifier or Subject Key Identifier exten­ +sions, the associated Key Identifier SHALL be of a length of 20 octets, consistent with the length of +derivation method (1) described in section 4.2.1.2 of [RFC 5280]. + +Further constraints related to the exact derivation appear in the following subsections: + +- Matter Certificates (NOC, ICAC, RCAC) Subject Key Identifier extension: see Section 6.5.11.4, + “Subject Key Identifier Extension” +- Matter Certificates Authority Key Identifier extension: see Section 6.5.11.5, “Authority Key Iden­ + tifier Extension” +- Device Attestation Certificate (DAC) extensions: see Section 6.2.2.3, “Device Attestation Certifi­ + cate (DAC)” +- Product Attestation Intermediate (PAI) Certificate extensions: see Section 6.2.2.4, “Product Attes­ + tation Intermediate (PAI) Certificate” +- Product Attestation Authority (PAA) Certificate extensions: see Section 6.2.2.5, “Product Attesta­ + tion Authority (PAA) Certificate” + +**6.1.3. Certificate Sizes** + +All certificates SHALL NOT be longer than 600 bytes in their uncompressed DER format. This con­ +straint SHALL apply to the entire DAC chain (DAC, PAI, PAA) and NOC chain (NOC, ICAC, RCAC). + +Wherever Matter Operational Certificate Encoding representation is used, all certificates SHALL +NOT be longer than 400 bytes in their TLV form. This constraint only applies to the NOC chain (NOC, +ICAC, RCAC) since the DAC chain (DAC, PAI, PAA) only appears in DER format. + +All certificates used within Matter SHOULD be as short as possible. + +**6.1.4. Presentation of example certificates** + +Certificate bodies are presented for exemplary purposes in multiple formats within this chapter. +Since the translation of an X.509 certificate from ASN.1 DER format to human-readable text format +may lose fidelity, especially with regards to equivalent types (e.g., PrintableString versus IA5String +versus UTF8String) or serialization when non-standard OIDs are seen, textual examples SHALL +NOT be considered to be normative. Only direct encoding of DER encoding, such as PEM blocks, +should be used to further study the examples. In case of unforeseen divergence between an exam­ +ple certificate illustration and the normative rules expressed in prose, the normative prose SHALL +take precedence over an ambiguous interpretation of an example. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 325 +``` + +**6.2. Device Attestation** + +**6.2.1. Introduction** + +Certification of a Device includes configuring the Device with immutable credentials that can be +cryptographically verified. Device Attestation is the step of the Commissioning process whereby a +Commissioner cryptographically verifies a Commissionee is in fact a certified Device. This chapter +describes the Device Attestation Certificate (DAC) and the systems involved in the verification of a +DAC. + +The processes used to convey the DAC from a Commissionee to a Commissioner, how to verify that +a Commissionee holds the private key corresponding to its DAC, and specifically how the DAC is ver­ +ified are described in Section 6.2.3, “Device Attestation Procedure”. + +This chapter refers to the signature algorithm ECDSA with SHA256 and to the elliptic curve secp256r1 +(a.k.a. prime256v1 and NIST P-256) in compliance with the mapping for version 1.0 of the Matter Mes­ +sage Format of the cryptographic primitives as specified in Chapter 3, _Cryptographic Primitives_. +Future versions of this specification might adapt these references accordingly. + +**6.2.2. Device Attestation Certificate (DAC)** + +All commissionable Matter Nodes SHALL include a Device Attestation Certificate (DAC) and corre­ +sponding private key, unique to that Device. The DAC is used in the Device Attestation process, as +part of Commissioning a Commissionee into a Fabric. The DAC SHALL be a DER-encoded X.509v3- +compliant certificate as defined in RFC 5280 and SHALL be issued by a Product Attestation Interme­ +diate (PAI) that chains directly to an approved Product Attestation Authority (PAA), and therefore +SHALL have a certification path length of 2. + +The DAC also SHALL contain specific values of Vendor ID and Product ID (see Section 6.2.2.2, +“Encoding of Vendor ID and Product ID in subject and issuer fields”) in its subject field to indicate +the Vendor ID and Product ID provenance of the attestation certificate. See Section 6.2.3.1, “Attesta­ +tion Information Validation” for how these are used. + +The validity period of a DAC is determined by the vendor and MAY be set to the maximum allowed +value of 99991231235959Z GeneralizedTime to indicate that the DAC has no well-defined expiration +date. + +The notation used in this section to describe the specifics of the DAC uses the ASN.1 basic notation +as defined in X.680. The notation below also leverages types defined in RFC 5280 such as Algorith­ +mIdentifier, RelativeDistinguishedName, Validity, Time, UTCTime, GeneralizedTime, or permitted exten­ +sion types. Additionally, the notation below uses the ASN.1 definitions captured in the figure below: + +``` +-- Matter signatures are ECDSA with SHA256 +``` +``` +MatterSignatureIdentifier ::= SEQUENCE { +algorithm OBJECT IDENTIFIER(id-x962-ecdsa-with-sha256) } +``` +``` +Page 326 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +-- Matter Names + +-- The second to last RelativeDistinguishedName object in MatterDACName SEQUENCE SHALL +contain an +-- attribute with type equal to matter-oid-vid and the last RelativeDistinguishedName + +object in the + +-- SEQUENCE SHALL contain an attribute with type field set to matter-oid-pid + +MatterDACName ::= SEQUENCE OF RelativeDistinguishedName + +-- There are two acceptable formats for MatterPA name. The first is identical to + +MatterDACName, +-- i.e. the second to last RelativeDistinguishedName object in MatterPAName SEQUENCE + +SHALL contain an +-- attribute with type equal to matter-oid-vid and the last RelativeDistinguishedName + +object in the +-- SEQUENCE SHALL contain an attribute with type field set to matter-oid-pid. In the + +second acceptable +-- format, the last element of the MatterPAName SEQUENCE SHALL be an + +RelativeDistinguishedName with + +-- an attribute with type field set to matter-oid-vid + +MatterPAName ::= SEQUENCE OF RelativeDistinguishedName + +-- Object definitions and references + +-- X962 OIDs + +id-x962 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) ansi-x962(10045) } + +id-x962-ecdsa-with-sha256 OBJECT IDENTIFIER ::= { id-x962 signatures(4) ecdsa-with- + +SHA2(3) ecdsa-with-SHA256(2) } + +id-x962-prime256v1 OBJECT IDENTIFIER ::= { id-x962 curves(3) prime(1) prime256v1(7) } + +-- CSA and Matter specific OIDs + +csa-root OBJECT IDENTIFIER ::= { iso(1) identified-organization(3) dod(6) internet(1) + +private(4) enterprise(1) zigbee(37244) } + +-- root arc for attestation certificates + +matter-att-root OBJECT IDENTIFIER ::= { csa-root 2 } + +-- Matter Device Attestation Certificate DN attribute for the Vendor ID (VID) + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 327 +``` + +``` +matter-oid-vid OBJECT IDENTIFIER ::= { matter-att-root 1 } +``` +``` +-- Matter Device Attestation Certificate DN attribute for the Product ID (PID) +matter-oid-pid OBJECT IDENTIFIER ::= { matter-att-root 2 } +``` +**6.2.2.1. Device Attestation Public Key Infrastructure (PKI)** + +The Device Attestation PKI hierarchy consists of the PAA, PAI and individual DAC. The public key +from the associated PAI certificate is used to cryptographically verify the DAC signature. The PAI +certificate in turn is signed and attested to by the Product Attestation Authority (PAA) CA. The pub­ +lic key from the associated PAA certificate is used to cryptographically verify the PAI certificate sig­ +nature. The PAA certificate is an implicitly trusted self-signed root certificate. In this way, the DAC +chains up to the PAI certificate, which in turn chains up to the PAA root certificate. A PAI SHALL be +assigned to a Vendor ID value. A PAI MAY further be scoped to a single ProductID value. If a PAI is +used for multiple products, then it cannot be scoped to a ProductID value, otherwise the Device +Attestation Procedure will fail policy validations. + +Commissioners SHALL use PAA and PAI certificates to verify the authenticity of a Commissionee +before proceeding with the rest of the Commissioning flow. + +The subject of all DAC and PAI certificates SHALL be unique among all those issued by their issuer, +as intended by RFC 5280 section 4.1.2.6, through the use of RelativeDistinguishedName s that ensure +the uniqueness, such as for example a unique combination of commonName (OID 2.5.4.3), serialNumber +(OID 2.5.4.5), organizationalUnitName (OID 2.5.4.11), etc. The exact additional constraints, including +for the subject field, for PAA, PAI and DAC certificates, are presented in the following subsections. + +The following figure shows the Device Attestation PKI hierarchy. + +_Figure 39. Device Attestation PKI hierarchy_ + +``` +Page 328 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.2.2.2. Encoding of Vendor ID and Product ID in subject and issuer fields** + +The following subsections contain references to VendorID and ProductID: + +- Section 6.2.2.3, “Device Attestation Certificate (DAC)” +- Section 6.2.2.4, “Product Attestation Intermediate (PAI) Certificate” +- Section 6.2.2.5, “Product Attestation Authority (PAA) Certificate” + +The values for VendorID and ProductID, where possible or required in issuer or subject fields +SHALL be encoded by only one of two methods, without mixing the methods within a given field: + +1. The "preferred method", using Matter-specific RelativeDistinguishedName attributes: + a. VendorID encoded as AttributeTypeAndValue entry with type equal to 1.3.6.1.4.1.37244.2.1, + and value respecting encoding specified in Section 6.1.1, “Encoding of Matter-specific RDNs”. + b. ProductID encoded as AttributeTypeAndValue entry with type equal to 1.3.6.1.4.1.37244.2.2, + and value respecting encoding specified in Section 6.1.1, “Encoding of Matter-specific RDNs”. +2. A "fallback method" to support certificate authorities that only allow customary RFC 5280 OIDs + in the arc {joint-iso-itu-t(2) ds(5) attributeType(4)} for type values in AttributeTypeAndValue + entries of RelativeDistinguishedName elements is to encode them as substrings within the com­ + monName attribute type ({joint-iso-itu-t(2) ds(5) attributeType(4) commonName(3)}): + a. VendorID value encoded with substring Mvid: followed by exactly 4 uppercase hexadecimal + characters without elision of leading zeroes, anywhere within the commonName, such as for + example: + i. VendorID 0xFFF1 (65521 decimal): Mvid:FFF1 +ii. VendorID 0x2A (42 decimal): Mvid:002A + b. ProductID value encoded with substring Mpid: followed by exactly 4 uppercase hexadecimal + characters without elision of leading zeroes, anywhere within the commonName, such as for + example: + i. ProductID 0xC20A (49674 decimal): Mpid:C20A +ii. ProductID 0x3A5 (933 decimal): Mpid:03A5 +c. For both VendorID and ProductID, the following additional rules apply to the "fallback +method": +i. The leftmost match having a correct encoding SHALL be used, with other correct +matches discarded. +ii. For either of VendorID and ProductID, if the prefix string is found on its own anywhere +within the commonName, but there is no fully correct match anywhere in the commonName, the +field SHALL be considered incorrectly formatted. + +The "preferred method" leaves more space for content in the commonName attribute type if present. It +is also less ambiguous which may allow simpler processing of certificate issuance policy validations +in CAs that support the Matter-specific RelativeDistinguishedName attributes, and simplify the audit +of certificates where Vendor ID and Product ID appear. + +The "fallback method" is present to support less flexible CA infrastructure. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 329 +``` + +**Fallback method to encode VendorID and ProductID** + +The "fallback method" requires exactly 9 characters that are safe to use in both PrintableString and +UTF8String for either VendorID or ProductID encoding. Since these VendorID and ProductID sub­ +strings have unambiguous format, they MAY be provided anywhere within a commonName value, and +therefore separator selection does not need to be considered. Note that the standard RFC 5280 +length limitation for commonName attribute value is 64 characters in total (see ub-common-name in +RFC 5280). + +Using the "fallback method" for embedding of VendorID and ProductID in commonName in the subject +field of a Device Attestation Certificate claiming VendorID 0xFFF1 and ProductID 0x00B1 can be +illustrated with the following valid and invalid examples (without the double quotes): + +- "ACME Matter Devel DAC 5CDA9899 Mvid:FFF1 Mpid:00B1": valid and recommended since easily + human-readable +- "ACME Matter Devel DAC 5CDA9899 Mpid:00B1 Mvid:FFF1": valid and recommended since easily + human-readable +- "Mpid:00B1,ACME Matter Devel DAC 5CDA9899,Mvid:FFF1": valid example showing that order or + separators are not considered at all for the overall validity of the embedded fields +- "ACME Matter Devel DAC 5CDA9899 Mvid:FFF1Mpid:00B1": valid, but less readable +- "Mvid:FFF1ACME Matter Devel DAC 5CDAMpid:00B19899": valid, but highly discouraged, since + embedding of substrings within other substrings may be confusing to human readers. +- "ACME Matter Devel DAC 5CDA9899 Mvid:FF1 Mpid:00B1": invalid, since substring following Mvid: is + not exactly 4 uppercase hexadecimal digits +- "ACME Matter Devel DAC 5CDA9899 Mvid:fff1 Mpid:00B1": invalid, since substring following Mvid: + is not exactly 4 uppercase hexadecimal digits +- "ACME Matter Devel DAC 5CDA9899 Mvid:FFF1 Mpid:B1": invalid, since substring following Mpid: is + not exactly 4 uppercase hexadecimal digits +- "ACME Matter Devel DAC 5CDA9899 Mpid: Mvid:FFF1": invalid, since the prefix Mpid: was found but + there is no occurrence of Mpid: followed by exactly 4 uppercase hexadecimal digits. + +In addition, the following example shows a highly discouraged, though technically valid encoding: + +- "Mpid:Mvid:FFF1 Mpid:12cd Matter Test Mpid:FE67": VendorID 0xFFF1 and ProductID 0xFE67 + (leftmost match is the correct match for Mpid: prefix). + ◦ Instances such as this example SHOULD be avoided since they can cause confusion in differ­ + ent implementations, even if the rules are obeyed. + +If either the Vendor ID (1.3.6.1.4.1.37244.2.1) or Product ID (1.3.6.1.4.1.37244.2.2) Matter-specific +OIDs appear in any RelativeDistinguishedName in the subject or issuer fields of a certificate which +is part of the Device Attestation Certificate chain path, then that certificate within the chain SHALL +NOT have its commonName, if present, parsed for the "fallback method", in the rest of the issuer or sub­ +ject field where the Matter-specific OIDs appear. In other words, considering a field such as subject +or issuer, the presence of either of these OIDs as the type for any AttributeTypeAndValue within any +RelativeDistinguishedName of that field SHALL cause the "fallback method" to be skipped altogether +for that field. Otherwise, when the "fallback method" can legally be used, it SHALL only be used + +``` +Page 330 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +against AttributeTypeAndValue sequences where the type field is commonName ({joint-iso-itu-t(2) +ds(5) attributeType(4) commonName(3)}) in the issuer and subject fields, and any mention thereafter +of using or matching a "Vendor ID" or "Product ID" with regards to a Device Attestation Procedure +step SHALL rely on values obtained with that method. + +For example, if a given Product Attestation Intermediate certificate has a subject field employing a +particular method of encoding the VendorID and ProductID, either using only Matter-specific OIDs +or only the fallback method, then it follows that a Device Attestation Certificates issued by the cer­ +tificate authority of that Product Attestation Intermediate SHALL have the same Distinguished­ +Name content in its issuer field, so that the basic path validation algorithm works. That Device +Attestation Certificate MAY however have the "fallback method" used within its subject field, if the +Product Attestation Intermediate certificate authority is unable to encode/reflect the Matter-specific +OIDs in RelativeDistinguishedName attributes within the subject field. The rules for whether to +consider the canonical or "fallback method" for VendorID and ProductID encoding applies field by +field independently for each instance of subject or issuer field found in certificates within the DAC +chain. + +**6.2.2.3. Device Attestation Certificate (DAC)** + +The attributes in a DAC include: + +``` +Certificate ::= SEQUENCE { +tbsCertificate DACTBSCertificate, +signatureAlgorithm AlgorithmIdentifier, +signatureValue BIT STRING } +``` +``` +DACTBSCertificate ::= SEQUENCE { +version INTEGER ( v3(2) ), +serialNumber INTEGER, +signature MatterSignatureIdentifier, +issuer MatterPAName, +validity Validity, +subject MatterDACName, +subjectPublicKeyInfo SEQUENCE { +algorithm OBJECT IDENTIFIER(id-x962-prime256v1), +subjectPublicKey BIT STRING }, +extensions DACExtensions } +``` +``` +DACExtensions ::= SEQUENCE { +basicConstraint Extension({extnID id-ce-basicConstraints, critical TRUE, extnValue +BasicConstraints {cA FALSE} }), +keyUsage Extension({extnID id-ce-keyUsage, critical TRUE, extnValue +KeyUsage({digitalSignature})}), +authorityKeyIdentifier Extension({extnID id-ce-authorityKeyIdentifier}), +subjectKeyIdentifier Extension({extnID id-ce-subjectKeyIdentifier}), +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 331 +``` + +``` +extendedKeyUsage Extension({extnID id-ce-extKeyUsage}) OPTIONAL, +authorityInformationAccess Extension({extnID id-pe-authorityInfoAccess}) OPTIONAL, +subjectAlternateName Extension({extnID id-ce-subjectAltName}) OPTIONAL +} +``` +The DAC certificate SHALL follow the following constraints layered on top of the encoding specified +by RFC 5280 within the TBSCertificate structure: + +1. The version field SHALL be set to 2 to indicate v3 certificate. +2. The signature field SHALL contain the identifier for signatureAlgorithm ecdsa-with-SHA256. +3. The issuer field SHALL be a sequence of RelativeDistinguishedName s. +4. The issuer field SHALL have exactly one VendorID value present. +5. The issuer field SHALL have exactly zero or one ProductID value present. +6. The issuer field SHALL match, byte-for-byte, the subject field of the PAI certificate for the PAI + that issued this DAC. +7. The subject field SHALL be a sequence of RelativeDistinguishedName s. +8. The subject field SHALL have exactly one VendorID value present. + a.The VendorID value present in the issuer field SHALL match the VendorID value found in + subject field. +9. The subject field SHALL have exactly one ProductID value present. + a.If a ProductID value was present in the issuer field, the ProductID value found in subject + field SHALL match the value found in the issuer field. + +10.The algorithm field in subjectPublicKeyInfo field SHALL be the object identifier for prime256v1. + +11.The certificate SHALL carry the following Extensions: + +``` +a.Basic Constraint extension SHALL be marked critical and have the cA field set to FALSE. +b. Key Usage extension SHALL be marked critical +i. The KeyUsage bitstring SHALL only have the digitalSignature bit set. +ii.Other bits SHALL NOT be set +c.Authority Key Identifier +d. Subject Key Identifier +``` +12.The certificate MAY also carry the following additional Extensions: + +``` +a.Extended Key Usage +b. Authority Information Access +c.Subject Alternate Name +d. CRLDistributionPoints +e. Any other extension allowed in RFC 5280 where inclusion does not violate size limitations. +These extensions insofar not defined in this specification SHALL be ignored by commission­ +ers conforming to this specification, but MAY be present to allow flexibility in CA operation. +``` +``` +Page 332 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Valid example DAC with associated private key, in X.509 PEM format_ + +``` +-----BEGIN CERTIFICATE----- +MIIB6TCCAY+gAwIBAgIIDgY7dCvPvl0wCgYIKoZIzj0EAwIwRjEYMBYGA1UEAwwP +TWF0dGVyIFRlc3QgUEFJMRQwEgYKKwYBBAGConwCAQwERkZGMTEUMBIGCisGAQQB +gqJ8AgIMBDgwMDAwIBcNMjEwNjI4MTQyMzQzWhgPOTk5OTEyMzEyMzU5NTlaMEsx +HTAbBgNVBAMMFE1hdHRlciBUZXN0IERBQyAwMDAxMRQwEgYKKwYBBAGConwCAQwE +RkZGMTEUMBIGCisGAQQBgqJ8AgIMBDgwMDAwWTATBgcqhkjOPQIBBggqhkjOPQMB +BwNCAATCJYMix9xyc3wzvu1wczeqJIW8Rnk+TVrJp1rXQ1JmyQoCjuyvJlD+cAnv +/K7L6tHyw9EkNd7C6tPZkpW/ztbDo2AwXjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB +/wQEAwIHgDAdBgNVHQ4EFgQUlsLZJJTql4XA0WcI44jxwJHqD9UwHwYDVR0jBBgw +FoAUr0K3CU3r1RXsbs8zuBEVIl8yUogwCgYIKoZIzj0EAwIDSAAwRQIgX8sppA08 +NabozmBlxtCdphc9xbJF7DIEkePTSTK3PhcCIQC0VpkPUgUQBFo4j3VOdxVAoESX +kjGWRV5EDWgl2WEDZA== +-----END CERTIFICATE----- +``` +### -----BEGIN EC PRIVATE KEY----- + +``` +MHcCAQEEIHtcWp+0aVVH+DAQ38iXpphqmT7LfMnMD4V/kIqszwfuoAoGCCqGSM49 +AwEHoUQDQgAEwiWDIsfccnN8M77tcHM3qiSFvEZ5Pk1ayada10NSZskKAo7sryZQ +/nAJ7/yuy+rR8sPRJDXewurT2ZKVv87Www== +-----END EC PRIVATE KEY----- +``` +_Human-readable contents of example DAC X.509 certificate_ + +``` +Certificate: +Data: +Version: 3 (0x2) +Serial Number: 1010560536528535133 (0xe063b742bcfbe5d) +Signature Algorithm: ecdsa-with-SHA256 +Issuer: CN = Matter Test PAI, 1.3.6.1.4.1.37244.2.1 = FFF1, +1.3.6.1.4.1.37244.2.2 = 8000 +Validity +Not Before: Jun 28 14:23:43 2021 GMT +Not After : Dec 31 23:59:59 9999 GMT +Subject: CN = Matter Test DAC 0001, 1.3.6.1.4.1.37244.2.1 = FFF1, +1.3.6.1.4.1.37244.2.2 = 8000 +Subject Public Key Info: +Public Key Algorithm: id-ecPublicKey +Public-Key: (256 bit) +pub: +04:c2:25:83:22:c7:dc:72:73:7c:33:be:ed:70:73: +37:aa:24:85:bc:46:79:3e:4d:5a:c9:a7:5a:d7:43: +52:66:c9:0a:02:8e:ec:af:26:50:fe:70:09:ef:fc: +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 333 +``` + +``` +ae:cb:ea:d1:f2:c3:d1:24:35:de:c2:ea:d3:d9:92: +95:bf:ce:d6:c3 +ASN1 OID: prime256v1 +NIST CURVE: P-256 +X509v3 extensions: +X509v3 Basic Constraints: critical +CA:FALSE +X509v3 Key Usage: critical +Digital Signature +X509v3 Subject Key Identifier: +96:C2:D9:24:94:EA:97:85:C0:D1:67:08:E3:88:F1:C0:91:EA:0F:D5 +X509v3 Authority Key Identifier: +keyid:AF:42:B7:09:4D:EB:D5:15:EC:6E:CF:33:B8:11:15:22:5F:32:52:88 +``` +``` +Signature Algorithm: ecdsa-with-SHA256 +30:45:02:20:5f:cb:29:a4:0d:3c:35:a6:e8:ce:60:65:c6:d0: +9d:a6:17:3d:c5:b2:45:ec:32:04:91:e3:d3:49:32:b7:3e:17: +02:21:00:b4:56:99:0f:52:05:10:04:5a:38:8f:75:4e:77:15: +40:a0:44:97:92:31:96:45:5e:44:0d:68:25:d9:61:03:64 +``` +_Valid example DAC with associated private key, in X.509 PEM format, using "fallback method" for VendorID +and ProductID in Subject_ + +``` +-----BEGIN CERTIFICATE----- +MIIB0DCCAXegAwIBAgIIbec9lw3wZpAwCgYIKoZIzj0EAwIwRjEYMBYGA1UEAwwP +TWF0dGVyIFRlc3QgUEFJMRQwEgYKKwYBBAGConwCAQwERkZGMTEUMBIGCisGAQQB +gqJ8AgIMBDgwMDAwIBcNMjEwNjI4MTQyMzQzWhgPOTk5OTEyMzEyMzU5NTlaMDMx +MTAvBgNVBAMMKE1hdHRlciBUZXN0IERBQyAwMDAxIE12aWQ6RkZGMSBNcGlkOjgw +MDAwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATCJYMix9xyc3wzvu1wczeqJIW8 +Rnk+TVrJp1rXQ1JmyQoCjuyvJlD+cAnv/K7L6tHyw9EkNd7C6tPZkpW/ztbDo2Aw +XjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDAdBgNVHQ4EFgQUlsLZJJTq +l4XA0WcI44jxwJHqD9UwHwYDVR0jBBgwFoAUr0K3CU3r1RXsbs8zuBEVIl8yUogw +CgYIKoZIzj0EAwIDRwAwRAIgbvYsHaGRTg1JzPTB6TqfVFPABF8LCYkEP1AvV7Ah +yL4CIACKW3A6YixqtqKfkwuvw81mMVymqafU8kx5k1c0zqbe +-----END CERTIFICATE----- +``` +_Human-readable contents of example DAC X.509 certificate, using "fallback method" for VendorID and Pro­ +ductID in Subject_ + +``` +Certificate: +Data: +Version: 3 (0x2) +Serial Number: 7919366188737521296 (0x6de73d970df06690) +``` +``` +Page 334 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Signature Algorithm: ecdsa-with-SHA256 +Issuer: CN = Matter Test PAI, 1.3.6.1.4.1.37244.2.1 = FFF1, +1.3.6.1.4.1.37244.2.2 = 8000 +Validity +Not Before: Jun 28 14:23:43 2021 GMT +Not After : Dec 31 23:59:59 9999 GMT +Subject: CN = Matter Test DAC 0001 Mvid:FFF1 Mpid:8000 +Subject Public Key Info: +Public Key Algorithm: id-ecPublicKey +Public-Key: (256 bit) +pub: +04:c2:25:83:22:c7:dc:72:73:7c:33:be:ed:70:73: +37:aa:24:85:bc:46:79:3e:4d:5a:c9:a7:5a:d7:43: +52:66:c9:0a:02:8e:ec:af:26:50:fe:70:09:ef:fc: +ae:cb:ea:d1:f2:c3:d1:24:35:de:c2:ea:d3:d9:92: +95:bf:ce:d6:c3 +ASN1 OID: prime256v1 +NIST CURVE: P-256 +X509v3 extensions: +X509v3 Basic Constraints: critical +CA:FALSE +X509v3 Key Usage: critical +Digital Signature +X509v3 Subject Key Identifier: +96:C2:D9:24:94:EA:97:85:C0:D1:67:08:E3:88:F1:C0:91:EA:0F:D5 +X509v3 Authority Key Identifier: +keyid:AF:42:B7:09:4D:EB:D5:15:EC:6E:CF:33:B8:11:15:22:5F:32:52:88 +``` +``` +Signature Algorithm: ecdsa-with-SHA256 +30:44:02:20:6e:f6:2c:1d:a1:91:4e:0d:49:cc:f4:c1:e9:3a: +9f:54:53:c0:04:5f:0b:09:89:04:3f:50:2f:57:b0:21:c8:be: +02:20:00:8a:5b:70:3a:62:2c:6a:b6:a2:9f:93:0b:af:c3:cd: +66:31:5c:a6:a9:a7:d4:f2:4c:79:93:57:34:ce:a6:de +``` +**6.2.2.4. Product Attestation Intermediate (PAI) Certificate** + +The attributes in a PAI certificate include: + +``` +Certificate ::= SEQUENCE { +tbsCertificate PAITBSCertificate, +signatureAlgorithm AlgorithmIdentifier, +signatureValue BIT STRING } +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 335 +``` + +``` +PAITBSCertificate ::= SEQUENCE { +version INTEGER ( v3(2) ), +serialNumber INTEGER, +signature MatterSignatureIdentifier, +issuer Name, +validity Validity, +subject MatterPAName, +subjectPublicKeyInfo SEQUENCE { +algorithm OBJECT IDENTIFIER(id-x962-prime256v1), +subjectPublicKey BIT STRING }, +extensions PAIExtensions } +``` +``` +PAIExtensions ::= SEQUENCE { +basicConstraint Extension({extnID id-ce-basicConstraints, critical TRUE, extnValue +BasicConstraints {cA TRUE, pathLen 0} }), +keyUsage Extension({extnID id-ce-keyUsage, critical TRUE, extnValue KeyUsage()}), +authorityKeyIdentifier Extension({extnID id-ce-authorityKeyIdentifier}), +subjectKeyIdentifier Extension({extnID id-ce-subjectKeyIdentifier}), +extendedKeyUsage Extension({extnID id-ce-extKeyUsage}) OPTIONAL +} +``` +The PAI certificate SHALL follow the following constraints layered on top of the encoding specified +by RFC 5280 within the TBSCertificate structure: + +1. The version field SHALL be set to 2 to indicate v3 certificate. +2. The signature field SHALL contain the identifier for signatureAlgorithm ecdsa-with-SHA256. +3. The issuer field SHALL be a sequence of RelativeDistinguishedName s. +4. The issuer field SHALL have exactly zero or one VendorID value present. +5. The issuer field SHALL match, byte-for-byte, the subject field of the PAA certificate for the PAA + that issued this PAI certificate. +6. The subject field SHALL be a sequence of RelativeDistinguishedName s. +7. The subject field SHALL have exactly one VendorID value present. + a.If a VendorID value was present in the issuer field, the VendorID value found in subject + field SHALL match the value found in the issuer field. +8. The subject field SHALL have exactly zero or one ProductID value present. +9. The algorithm field in subjectPublicKeyInfo field SHALL be the object identifier for prime256v1. + +10.The certificate SHALL carry the following Extensions: + +``` +a.Basic Constraint extension SHALL be marked critical and have the cA field set to TRUE and +pathLen field set to 0. +``` +``` +Page 336 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +b. Key Usage extension SHALL be marked critical +i. Both the keyCertSign and cRLSign bits SHALL be set in the KeyUsage bitstring +ii. The digitalSignature bit MAY be set in the KeyUsage bitstring +iii. Other bits SHALL NOT be set +c. Authority Key Identifier +d. Subject Key Identifier +``` +11. The certificate MAY also carry the following additional Extensions: + +``` +a. Extended Key Usage +b. CRLDistributionPoints +c. Any other extension allowed in RFC 5280 where inclusion does not violate size limitations. +These extensions insofar not defined in this specification SHALL be ignored by commission­ +ers conforming to this specification, but MAY be present to allow flexibility in CA operation. +``` +``` +The PAI certificate presented in the following example is for the issuer of the example DAC certifi­ +cate from the previous section. +``` +``` +Valid example PAI with associated private key, in X.509 PEM format +``` +``` +-----BEGIN CERTIFICATE----- +MIIB1DCCAXqgAwIBAgIIPmzmUJrYQM0wCgYIKoZIzj0EAwIwMDEYMBYGA1UEAwwP +TWF0dGVyIFRlc3QgUEFBMRQwEgYKKwYBBAGConwCAQwERkZGMTAgFw0yMTA2Mjgx +NDIzNDNaGA85OTk5MTIzMTIzNTk1OVowRjEYMBYGA1UEAwwPTWF0dGVyIFRlc3Qg +UEFJMRQwEgYKKwYBBAGConwCAQwERkZGMTEUMBIGCisGAQQBgqJ8AgIMBDgwMDAw +WTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASA3fEbIo8+MfY7z1eY2hRiOuu96C7z +eO6tv7GP4avOMdCO1LIGBLbMxtm1+rZOfeEMt0vgF8nsFRYFbXDyzQsio2YwZDAS +BgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBBjAdBgNVHQ4EFgQUr0K3 +CU3r1RXsbs8zuBEVIl8yUogwHwYDVR0jBBgwFoAUav0idx9RH+y/FkGXZxDc3DGh +cX4wCgYIKoZIzj0EAwIDSAAwRQIhAJbJyM8uAYhgBdj1vHLAe3X9mldpWsSRETET +i+oDPOUDAiAlVJQ75X1T1sR199I+v8/CA2zSm6Y5PsfvrYcUq3GCGQ== +-----END CERTIFICATE----- +``` +### -----BEGIN EC PRIVATE KEY----- + +``` +MHcCAQEEIEZ7LYpps1z+a9sPw2qBp9jj5F0GLffNuCJY88hAHcMYoAoGCCqGSM49 +AwEHoUQDQgAEgN3xGyKPPjH2O89XmNoUYjrrvegu83jurb+xj+GrzjHQjtSyBgS2 +zMbZtfq2Tn3hDLdL4BfJ7BUWBW1w8s0LIg== +-----END EC PRIVATE KEY----- +``` +``` +Human-readable contents of example PAI X.509 certificate +``` +``` +Certificate: +Data: +Version: 3 (0x2) +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 337 +``` + +``` +Serial Number: 4498223361705918669 (0x3e6ce6509ad840cd) +Signature Algorithm: ecdsa-with-SHA256 +Issuer: CN = Matter Test PAA, 1.3.6.1.4.1.37244.2.1 = FFF1 +Validity +Not Before: Jun 28 14:23:43 2021 GMT +Not After : Dec 31 23:59:59 9999 GMT +Subject: CN = Matter Test PAI, 1.3.6.1.4.1.37244.2.1 = FFF1, +1.3.6.1.4.1.37244.2.2 = 8000 +Subject Public Key Info: +Public Key Algorithm: id-ecPublicKey +Public-Key: (256 bit) +pub: +04:80:dd:f1:1b:22:8f:3e:31:f6:3b:cf:57:98:da: +14:62:3a:eb:bd:e8:2e:f3:78:ee:ad:bf:b1:8f:e1: +ab:ce:31:d0:8e:d4:b2:06:04:b6:cc:c6:d9:b5:fa: +b6:4e:7d:e1:0c:b7:4b:e0:17:c9:ec:15:16:05:6d: +70:f2:cd:0b:22 +ASN1 OID: prime256v1 +NIST CURVE: P-256 +X509v3 extensions: +X509v3 Basic Constraints: critical +CA:TRUE, pathlen:0 +X509v3 Key Usage: critical +Certificate Sign, CRL Sign +X509v3 Subject Key Identifier: +AF:42:B7:09:4D:EB:D5:15:EC:6E:CF:33:B8:11:15:22:5F:32:52:88 +X509v3 Authority Key Identifier: +keyid:6A:FD:22:77:1F:51:1F:EC:BF:16:41:97:67:10:DC:DC:31:A1:71:7E +``` +``` +Signature Algorithm: ecdsa-with-SHA256 +30:45:02:21:00:96:c9:c8:cf:2e:01:88:60:05:d8:f5:bc:72: +c0:7b:75:fd:9a:57:69:5a:c4:91:11:31:13:8b:ea:03:3c:e5: +03:02:20:25:54:94:3b:e5:7d:53:d6:c4:75:f7:d2:3e:bf:cf: +c2:03:6c:d2:9b:a6:39:3e:c7:ef:ad:87:14:ab:71:82:19 +``` +**6.2.2.5. Product Attestation Authority (PAA) Certificate** + +The attributes in a PAA certificate include: + +``` +Certificate ::= SEQUENCE { +tbsCertificate PAATBSCertificate, +signatureAlgorithm AlgorithmIdentifier, +``` +``` +Page 338 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +signatureValue BIT STRING } +``` +``` +PAATBSCertificate ::= SEQUENCE { +version INTEGER ( v3(2) ), +serialNumber INTEGER, +signature MatterSignatureIdentifier, +issuer Name, +validity Validity, +subject Name, +subjectPublicKeyInfo SEQUENCE { +algorithm OBJECT IDENTIFIER(id-x962-prime256v1), +subjectPublicKey BIT STRING }, +extensions PAAExtensions } +``` +``` +PAAExtensions ::= SEQUENCE { +basicConstraint Extension({extnID id-ce-basicConstraints, critical TRUE, extnValue +BasicConstraints {cA TRUE, pathLen 1} }), +keyUsage Extension({extnID id-ce-keyUsage, critical TRUE, extnValue KeyUsage()}), +authorityKeyIdentifier Extension({extnID id-ce-authorityKeyIdentifier}) OPTIONAL, +subjectKeyIdentifier Extension({extnID id-ce-subjectKeyIdentifier}), +extendedKeyUsage Extension({extnID id-ce-extKeyUsage}) OPTIONAL +} +``` +``` +The PAA certificate SHALL follow the following constraints layered on top of the encoding specified +by RFC 5280 within the TBSCertificate structure: +``` +1. The version field SHALL be set to 2 to indicate v3 certificate. +2. The signature field SHALL contain the identifier for signatureAlgorithm ecdsa-with-SHA256. +3. The issuer field SHALL be a sequence of RelativeDistinguishedName s. +4. The issuer field SHALL have exactly zero or one VendorID value present. +5. The subject field SHALL be a sequence of RelativeDistinguishedName s. +6. The subject field SHALL have exactly zero or one VendorID value present. +7. The issuer and subject fields SHALL match exactly. +8. A ProductID value SHALL NOT be present in either the subject or issuer fields. +9. The algorithm field in subjectPublicKeyInfo field SHALL be the object identifier for prime256v1. +10. The certificate SHALL carry the following Extensions: + +``` +a. Basic Constraint extension SHALL be marked critical and have the cA field set to TRUE. The +'pathLen' field MAY be set and if the 'pathLen' is field is present it SHALL be set to 1. +b. Key Usage extension SHALL be marked critical. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 339 +``` + +``` +i. Both the keyCertSign and cRLSign bits SHALL be set in the KeyUsage bitstring +ii.The digitalSignature bit MAY be set in the KeyUsage bitstring +iii.Other bits SHALL NOT be set +c.Subject Key Identifier +``` +11.The certificate MAY also carry the following additional Extensions: + +``` +a.Extended Key Usage +b. Authority Key Identifier +c.Any other extension allowed in RFC 5280 where inclusion does not violate size limitations. +These extensions insofar not defined in this specification SHALL be ignored by commission­ +ers conforming to this specification, but MAY be present to allow flexibility in CA operation. +``` +The PAA certificate presented in the following example is for the issuer of the example PAI certifi­ +cate from the previous section. + +_Valid example PAA with associated private key, in X.509 PEM format_ + +``` +-----BEGIN CERTIFICATE----- +MIIBvTCCAWSgAwIBAgIITqjoMYLUHBwwCgYIKoZIzj0EAwIwMDEYMBYGA1UEAwwP +TWF0dGVyIFRlc3QgUEFBMRQwEgYKKwYBBAGConwCAQwERkZGMTAgFw0yMTA2Mjgx +NDIzNDNaGA85OTk5MTIzMTIzNTk1OVowMDEYMBYGA1UEAwwPTWF0dGVyIFRlc3Qg +UEFBMRQwEgYKKwYBBAGConwCAQwERkZGMTBZMBMGByqGSM49AgEGCCqGSM49AwEH +A0IABLbLY3KIfyko9brIGqnZOuJDHK2p154kL2UXfvnO2TKijs0Duq9qj8oYShpQ +NUKWDUU/MD8fGUIddR6Pjxqam3WjZjBkMBIGA1UdEwEB/wQIMAYBAf8CAQEwDgYD +VR0PAQH/BAQDAgEGMB0GA1UdDgQWBBRq/SJ3H1Ef7L8WQZdnENzcMaFxfjAfBgNV +HSMEGDAWgBRq/SJ3H1Ef7L8WQZdnENzcMaFxfjAKBggqhkjOPQQDAgNHADBEAiBQ +qoAC9NkyqaAFOPZTaK0P/8jvu8m+t9pWmDXPmqdRDgIgI7rI/g8j51RFtlM5CBpH +mUkpxyqvChVI1A0DTVFLJd4= +-----END CERTIFICATE----- +``` +### -----BEGIN EC PRIVATE KEY----- + +``` +MHcCAQEEIGUSyuyuz8VD1gYjFhWXFi8BRoTFZaEpti/SjCerHMxQoAoGCCqGSM49 +AwEHoUQDQgAEtstjcoh/KSj1usgaqdk64kMcranXniQvZRd++c7ZMqKOzQO6r2qP +yhhKGlA1QpYNRT8wPx8ZQh11Ho+PGpqbdQ== +-----END EC PRIVATE KEY----- +``` +_Human-readable contents of example PAA X.509 certificate_ + +``` +Certificate: +Data: +Version: 3 (0x2) +Serial Number: 5668035430391749660 (0x4ea8e83182d41c1c) +Signature Algorithm: ecdsa-with-SHA256 +Issuer: CN = Matter Test PAA, 1.3.6.1.4.1.37244.2.1 = FFF1 +``` +``` +Page 340 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Validity +Not Before: Jun 28 14:23:43 2021 GMT +Not After : Dec 31 23:59:59 9999 GMT +Subject: CN = Matter Test PAA, 1.3.6.1.4.1.37244.2.1 = FFF1 +Subject Public Key Info: +Public Key Algorithm: id-ecPublicKey +Public-Key: (256 bit) +pub: +04:b6:cb:63:72:88:7f:29:28:f5:ba:c8:1a:a9:d9: +3a:e2:43:1c:ad:a9:d7:9e:24:2f:65:17:7e:f9:ce: +d9:32:a2:8e:cd:03:ba:af:6a:8f:ca:18:4a:1a:50: +35:42:96:0d:45:3f:30:3f:1f:19:42:1d:75:1e:8f: +8f:1a:9a:9b:75 +ASN1 OID: prime256v1 +NIST CURVE: P-256 +X509v3 extensions: +X509v3 Basic Constraints: critical +CA:TRUE, pathlen:1 +X509v3 Key Usage: critical +Certificate Sign, CRL Sign +X509v3 Subject Key Identifier: +6A:FD:22:77:1F:51:1F:EC:BF:16:41:97:67:10:DC:DC:31:A1:71:7E +X509v3 Authority Key Identifier: +keyid:6A:FD:22:77:1F:51:1F:EC:BF:16:41:97:67:10:DC:DC:31:A1:71:7E +``` +``` +Signature Algorithm: ecdsa-with-SHA256 +30:44:02:20:50:aa:80:02:f4:d9:32:a9:a0:05:38:f6:53:68: +ad:0f:ff:c8:ef:bb:c9:be:b7:da:56:98:35:cf:9a:a7:51:0e: +02:20:23:ba:c8:fe:0f:23:e7:54:45:b6:53:39:08:1a:47:99: +49:29:c7:2a:af:0a:15:48:d4:0d:03:4d:51:4b:25:de +``` +**6.2.3. Device Attestation Procedure** + +The device attestation procedure SHALL be executed by Commissioners when commissioning a +device. It serves to validate whether a particular device is certified for Matter compliance and that +it was legitimately produced by the certified manufacturer. See Section 5.5, “Commissioning Flows” +for the possible outcomes based on whether the Device Attestation Procedure succeeds or fails to +attest the device. + +The Device Attestation Certificate Chain MAY be read at any time, either prior to or after receipt of +the AttestationResponse. The Commissionee SHALL make the Certificate Chain available whenever +requested using CertificateChainRequest. If the Commissioner does not already have this informa­ +tion, to proceed with the validation, it SHALL request the Commissionee’s Device Attestation Certifi­ +cate Chain using CertificateChainRequest. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 341 +``` + +The procedure is as follows: + +1. The Commissioner SHALL generate a random 32 byte attestation nonce using Crypto_DRBG(). +2. The Commissioner SHALL send the AttestationNonce to the Commissionee and request Attesta­ + tion Information using AttestationRequest. +3. The Commissionee SHALL return the signed Attestation Information to the Commissioner using + AttestationResponse. + +After execution of the procedure, the Attestation Information SHOULD be validated using the +checks described in Section 6.2.3.1, “Attestation Information Validation”. + +**6.2.3.1. Attestation Information Validation** + +A Commissioner validating the Attestation Information SHOULD record sufficient information to +provide detailed results of the validation outcome to users. Therefore, prior to validating Attesta­ +tion Information, a Commissioner SHOULD have previously obtained the Device Attestation Certifi­ +cate chain for the Commissionee, so that the DAC and PAI necessary for the procedure are available. + +In order to consider a Commissionee successfully attested, a Commissioner SHALL have success­ +fully validated at least the following: + +- The PAA SHALL be validated for presence in the Commissioner’s trusted root store, which + SHOULD include at least the set of globally trusted PAA certificates present in the Distributed + Compliance Ledger at the issuing timestamp (notBefore) of the DAC. +- The DAC certificate chain SHALL be validated using the Crypto_VerifyChainDER() function, tak­ + ing into account the mandatory presence of the PAI and of the PAA. It is especially important to + ensure the entire chain has a length of exactly 3 elements (PAA certificate, PAI certificate, + Device Attestation Certificate) and that the necessary format policies previously exposed are + validated, to avoid unauthorized path chaining (e.g., through multiple PAI certificates). + ◦ Chain validation SHALL be performed with respect to the notBefore timestamp of the DAC to + ensure that the DAC was valid when it was issued. This way of validating is abided by the + Crypto_VerifyChainDER() function. + ◦ Chain validation SHALL include revocation checks of the DAC and PAI, based on the Com­ + missioner’s best understanding of revoked entities. See Section 6.2.4, “Device attestation + revocation” for an interoperable method of obtaining revocation information in the Device + Attestation PKI. +- The VendorID value found in the subject DN of the DAC SHALL match the VendorID value in the + subject DN of the PAI certificate. +- If the PAA certificate contains a VendorID value in its subject DN, its value SHALL match the + VendorID value in the subject DN of the PAI certificate. +- The Device Attestation Signature (attestation_signature) field from Attestation Response SHALL + be validated: + +``` +Success = Crypto_Verify( +publicKey = Public key from DAC, +``` +``` +Page 342 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +message = Attestation Information TBS (attestation_tbs), +signature = Device Attestation Signature (attestation_signature) +) +``` +``` +where the fields are encoded as described in Section 11.18.4.7, “Attestation Information”. +``` +``` +◦ The AttestationChallenge SHALL be obtained from a CASE session, resumed CASE session, or +PASE session depending on the method used to establish the secure session within which +device attestation is conducted. +``` +- The AttestationNonce in Device Attestation elements SHALL match the Commissioner’s pro­ + vided AttestationNonce. +- The Certification Declaration signature SHALL be validated using the Crypto_Verify() function + and the public key obtained from the CSA’s Certificate Authority Certificate. +- The Certification Declaration SHALL be validated: + +``` +◦ The vendor_id field in the Certification Declaration SHALL match the VendorID attribute +found in the Basic Information cluster. +◦ The product_id_array field in the Certification Declaration SHALL contain the value of the +ProductID attribute found in the Basic Information cluster. +◦ The Certification Declaration SHALL be considered valid only if it contains both or neither +of the dac_origin_vendor_id and dac_origin_product_id fields. +◦ If the Certification Declaration has both the dac_origin_vendor_id and the dac_origin_produc­ +t_id fields, the following validation SHALL be done: +▪ The VendorID value from the subject DN in the DAC SHALL match the dac_origin_ven­ +dor_id field in the Certification Declaration. +▪ The VendorID value from the subject DN in the PAI SHALL match the dac_origin_ven­ +dor_id field in the Certification Declaration. +▪ The ProductID value from the subject DN in the DAC SHALL match the dac_origin_pro­ +duct_id field in the Certification Declaration. +▪ The ProductID value from the subject DN in the PAI, if such a ProductID value appears, +SHALL match the dac_origin_product_id field in the Certification Declaration. +◦ If the Certification Declaration has neither the dac_origin_vendor_id nor the dac_origin_pro­ +duct_id fields, the following validation SHALL be done: +▪ The VendorID value from the subject DN in the DAC SHALL match the vendor_id field in +the Certification Declaration. +▪ The VendorID value from the subject DN in the PAI SHALL match the vendor_id field in +the Certification Declaration. +▪ The ProductID value from the subject DN in the DAC SHALL be present in the produc­ +t_id_array field in the Certification Declaration. +▪ The ProductID value from the subject DN in the PAI, if such a Product ID is present, +SHALL match one of the values present in the product_id_array field in the Certification +Declaration. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 343 +``` + +``` +◦ If the Certification Declaration contains the authorized_paa_list field, the following valida­ +tion SHALL be done: +▪ The Subject Key Identifier (SKI) extension value of the PAA certificate, which is the root +of trust of the DAC, SHALL be present as one of the values in the authorized_paa_list +field. +◦ The certificate_id field SHOULD match the CDCertificateID field found in the entry of the +DeviceSoftwareCompliance schema in the Distributed Compliance Ledger where the entry’s +VendorID, ProductID and SoftwareVersion field match the respective VendorID, ProductID and +SoftwareVersion attributes values found in the Basic Information Cluster. For further clarity, +a scenario where a mismatch is most likely to occur is with devices that have received an +updated firmware but not an updated CD. Also, the Commissioner might not find the combi­ +nation of VendorID, ProductID and SoftwareVersion fields in the DCL information it has avail­ +able. +▪ Since it is possible certificate_id does not match the CDCertificateID field due to the +above point, a Commissioner SHOULD NOT reject the Commissionee solely because of +this mismatch. Instead, the Commissioner SHOULD separately check that the reported +SoftwareVersion in the Basic Information Cluster exists as a DeviceSoftwareVersion­ +Model in the Distributed Compliance Ledger to see if the current version is certified. For +the case of offline commissioning without access to DCL, the Commissioner SHOULD pro­ +ceed trusting that a valid CD matching the reported VendorID and ProductID at least +ensures the device has been previously certified and SHOULD check the DCL at a later +time to ensure the current SoftwareVersion is also certified. +◦ The firmware_information field in the Attestation Information, if present, SHALL match the +content of an entry in the Distributed Compliance Ledger for the specific device as explained +in Section 6.3.2, “Firmware Information”. If the Commissioner does not support Firmware +Information validation, it MAY skip checking this match. +``` +The order of execution of the above validation steps MAY be optimized by Commissioners. For +example, if some validation steps are deemed by a Commissioner to make the remainder of the +steps unnecessary because they have no chance of succeeding, then the validation steps could be +ordered such that superfluous steps or rounds trips are omitted. + +**6.2.4. Device attestation revocation** + +The Distributed Compliance Ledger contains a trusted list of revocation distribution points for the +Device Attestation PKI. The schema is documented in Section 11.23.9, “Device Attestation PKI Revo­ +cation Distribution Points Schema”. + +The format of certificates in the Device Attestation PKI is constrained to maximum sizes and a spe­ +cific format to reduce the complexity and system requirements for Device and Commissioner +implementations. Therefore, there are no requirements for common revocation information, such +as cRLDistributionPoints (see RFC 5280 section 4.2.1.13) to be included. Furthermore, OCSP (see +RFC 6960) is not used in order to allow Commissioner implementations which rely on previously +cached revocation information, or which do not have concurrent access both to the public Internet +and to the Commissionee when commissioning. The Device Attestation PKI Revocation Distribution +Points Schema in the Distributed Compliance Ledger is thus the main method of delivering interop­ +erable and universally accessible revocation information for Matter Commissioners and Adminis­ + +``` +Page 344 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +trators. + +The revocation information MAY be partitioned over multiple Device Attestation PKI Revocation +Distribution Points Schema entries, as the provider of such information deems fit. In other words, +there may be more than one record to consult to determine revocation status of a given certificate. + +If a DAC, PAI or PAA certificate contains the cRLDistributionPoints (see RFC 5280 section 4.2.1.13) +extension, it SHALL be ignored, since the Device Attestation PKI Revocation Distribution Points +Schema in the Distributed Compliance Ledger is the only supported method of determining up-to- +date revocation status. + +**6.2.4.1. Conceptual algorithm for revocation set construction** + +To build the list of revoked entities for a given PAI or PAA certificate authority, the table described +in the Device Attestation PKI Revocation Distribution Points Schema can be used with a conceptual +algorithm, which can then be used at time of revocation checks. + +To build an oracle of revoked entities, the conceptual algorithm is as follows: + +- Inputs: + ◦ List of all entries in the Device Attestation PKI Revocation Distribution Points table of the + Distributed Compliance Ledger. +- Outputs: + ◦ For each tuple of (CertificateAuthorityKeyIdentifier, CertificateAuthorityName), a set of + RevokedEntitySerialNumber and an associated tuple of (CRLSignerCertificate, CRLSignerDele­ + gator) certificates. + ▪ CertificateAuthorityKeyIdentifier is the Subject Key Identifier of a PAA or PAI as an + octet string (e.g. ASN.1 OCTET STRING, or protobuf bytes). + ▪ CertificateAuthorityName is the X.500 Name associated with the PAA or PAI whose revo­ + cation information is being aggregated, as it appears in the Issuer field of a certificate it + issues. + ▪ RevokedEntitySerialNumber is a serial number containing a large integer matchable to an + ASN.1 INTEGER as seen in the CertificateSerialNumber field of an RFC 5280-compliant cer­ + tificate. + ▪ CRLSignerCertificate is the certificate present in the CRLSignerCertificate field from the + Device Attestation PKI Revocation Distribution Points table entry processed. + ▪ CRLSignerDelegator is the certificate present in the CRLSignerDelegator field from the + Device Attestation PKI Revocation Distribution Points table entry processed, if present. + +### NOTE + +``` +While the algorithm here does not mention the recording of any other metadata per +revoked entity to simplify illustration, implementers MAY do so to allow richer diag­ +nostics information to be provided to end-users if a revoked entity is found. +``` +- Algorithm: + ◦ For each entry in the Device Attestation PKI Revocation Distribution Points + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 345 +``` + +1. If entry.RevocationType is not equal to 1 (not of type RFC 5280 CRL), stop further process­ + ing of the entry, and continue to next entry, as it is a format not defined in this Specifica­ + tion. +2. Parse the certificate found entry.CRLSignerCertificate from its PEM encoding, keeping it + as CRLSignerCertificate. +3. If entry.IsPAA is TRUE: + a.If CRLSignerCertificate encoded a VendorID, validate that it matches entry.VendorID. + In case of mismatch, stop further processing of the entry, and continue to next entry, + if any. +4. Else if entry.IsPAA is FALSE: + a.If the CRLSignerCertificate is a PAI certificate (rather than a PAI-delegated certifi­ + cate), validate that the CRLSignerCertificate 's VendorID, matches entry.VendorID. + Else validate that the 'CRLSignerDelegator' 's VendorID, matches entry.VendorID. In + case of mismatch, stop further processing of the entry, and continue to next entry, if + any. +b. If the CRLSignerCertificate is a PAI certificate (rather than a PAI-delegated certifi­ +cate), validate that the CRLSignerCertificate 's ProductID matches entry.ProductID, if +present in the certificate’s subject. Else, validate that the 'CRLSignerDelegator' 's Pro­ +ductID matches entry.ProductID, if present in the certificate’s subject. In case of mis­ +match, stop further processing of the entry, and continue to next entry, if any. +5. Validate the certification path containing CRLSignerCertificate and 'CRLSignerDelegator' + (when present), using the approved PAAs currently in force in the Distributed Compli­ + ance Ledger as the trust anchors. In case of failure, stop further processing of the entry, + and continue to next entry, if any. +6. Obtain the CRL at entry.DataUrl, keeping it as CRLFile. +7. Perform CRLFile validation: + a.Validate that the crlExtensions field of CRLFile has an Authority Key Identifier + extension matching the CRLSignerCertificate 's Subject Key Identifier. In case of + mismatch, stop further processing of the entry, and continue to next entry, if any. +b. If more than one entry exists in the Distributed Compliance Ledger where the +entry.VendorID and entry.IssuerSubjectKeyID are matching, then: +i. Validate that the CRLFile has the Issuing Distribution Point critical CRL extension +present (see RFC 5280 section 5.2.5), and then: +A. Validate that the distributionPoint field of the extension has a single General­ +Name of type uniformResourceIdentifier. +B. Validate that the uniformResourceIdentifier in the GeneralName field matches +exactly, byte-for-byte, the value found in the entry.DataUrl field. +c.If any of above validations fail, stop further processing of the entry, and continue to +next entry, if any. +8. Validate the CRL according to Section 6.3 of RFC 5280, using the certificate specified in + CRLSignerCertificate as the trust anchor. Delta CRLs are not supported, so the "use- + +Page 346 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +deltas" input variable SHALL be false. Note that since the conceptual algorithm in this +section constructs a revocation set in advance without access to the candidate certificate, +validations from Section 6.3 of RFC 5280 SHALL be adapted by the implementer, and +implementations MAY use any algorithm that conforms to the algorithm equivalence +clause of Section 6.3. In case of failure, stop further processing of the entry, and continue +to next entry, if any. +``` +9. If entry.IsPAA is true and entry.CRLSignerCertificate is not self-signed, then assign the + subject field of the PAA Certificate that signed entry.CRLSignerCertificate to Certifi­ + cateAuthorityName. Otherwise, if entry.CRLSignerDelegator is present and non-empty, + then assign its subject field to CertificateAuthorityName. Otherwise assign the subject + field of entry.CRLSignerCertificate to CertificateAuthorityName. In each case, similarly + assign the value of the corresponding subject key identifier extension to CertificateAu­ + thorityKeyIdentifier. The latter value should match entry.IssuerSubjectKeyID`. In case + of mismatch, stop further processing of the entry, and continue to next entry, if any. +10. For each entry in the CRLFile 's CertificateList.tbsCertList.revokedCertificates +sequence: +a. If the entry in revokedCertificates has the certificateIssuer entry extension (or if +that extension appears in a previous entry in the sequence but also applies to this +entry as specified in section 5.3.3 of RFC 5280) and the CertificateAuthorityName vari­ +able does not match the distinguished name found in the certificateIssuer exten­ +sion, ignore this entry. +b. Access the correct revocation set by the tuple of (CertificateAuthorityKeyIdentifier, +CertificateAuthorityName). If the set is missing, create it and assign the (CRLSignerCer­ +tificate, CRLSignerDelegator) tuple with the set. +c. Set the RevokedEntitySerialNumber to the revoked certificate’s userCertificate field +(which is a serial number). +d. Insert the RevokedEntitySerialNumber entry in the revocation set found earlier. +◦ Optionally record metadata to record when each revocation distribution point requires an +update. + +After execution of this algorithm, an oracle exists which MAY then be used to determine the revoca­ +tion of any PAI or DAC certificate. + +**6.2.4.2. Determining Revocation Status of an Entity** + +During the device attestation procedure, a Commissioner SHALL use a revocation set it maintains +to determine whether the PAI and DAC certificates are revoked, unless the Commissioner does not +have access to the revocation set due to a transient lack of access to necessary resources it uses to +maintain the revocation set. If the revocation set was unavailable, the Commissioner SHOULD +notify the user of the fact that commissioning could succeed for some non-genuine devices, due to +lack of access to some of the necessary information. + +If the revocation set is available but no updated CRL is available beyond the timestamp in the "nex­ +tUpdate" field in the PAI or the PAA CRL, the Commissioner MAY assume that no updated revoca­ +tion information is being provided by the CA. The Commissioner SHOULD notify the user of the fact +that commissioning could succeed for some non-genuine devices, due to lack of access to some of + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 347 +``` + +the necessary information. + +The revocation set SHOULD at least include the Device Attestation PKI Revocation Distribution +Points Schema of the Distributed Compliance Ledger. + +Since there may be multiple formats for revocation information developed over time, the algorithm +in this section is purposefully described in generic terms that would allow expansion to future for­ +mats. + +The following conceptual algorithm is an example of how to determine whether a DAC or PAI cer­ +tificate is "revoked" or "not revoked": + +- Inputs: + ◦ The AuthorityKeyIdentifier extension of the certificate being queried. + ◦ The issuer name field of the certificate being queried. + ◦ The serialNumber field of the certificate being queried. + ◦ A conceptual RevocationDataSet indexed by (CertificateAuthorityKeyIdentifier, Certifi­ + cateAuthorityName), yielding a set of RevokedEntitySerialNumber, and an associated tuple of + (CRLSignerCertificate, CRLSignerDelegator) values. + ▪ CertificateAuthorityKeyIdentifier is the Subject Key Identifier of a PAA or PAI as an + octet string (e.g. ASN.1 OCTET STRING, or protobuf bytes). + ▪ CertificateAuthorityName is the X.500 Name associated with the PAA or PAI whose revo­ + cation information is being looked-up. + ▪ RevokedEntitySerialNumber is a serial number containing as an ASN.1 INTEGER as seen in + the CertificateSerialNumber field of an RFC 5280-conformant certificate. + ▪ CRLSignerCertificate is the certificate that signed the CRL. + ▪ CRLSignerDelegator if present, is the certificate that signed the CRLSignerCertificate. + ▪ See Section 6.2.4.1, “Conceptual algorithm for revocation set construction” for a usable + method to generate this dataset. +- Outputs: + ◦ A boolean value IsRevoked, where true indicates that the entity is revoked, and false indi­ + cates that it is not revoked. +- Algorithm: + 1. Initialize IsRevoked to FALSE. + 2. Obtain the correct RevocationSet by indexing the RevocationDataSet by the AuthorityKeyIden­ + tifier and issuer of the certificate whose status is being determined. + 3. If no matching RevocationSet is found, return immediately. + 4. If a matching RevocationSet is found, determined if serialNumber is a member of the set. + a.If the entity type whose revocation status is being verified is a PAI, then the subject PAI’s + issuer (a PAA) SHALL fulfill one of the following two cases, otherwise return immedi­ + ately: + +``` +Page 348 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +i. The Subject and Subject Key of the PAI certificate’s issuer matches exactly the CRL­ +SignerCertificate’s subject (i.e. the CRLSignerCertificate is a PAA). +ii. The Subject and Subject Key of the PAI certificate’s issuer matches exactly the PAA +which is the issuer of the CRLSignerCertificate (i.e. the CRLSignerCertificate is a CRL +signer delegated by a PAA). +b. If the entity type whose revocation status is being verified is a DAC, then: +i. If the CRLSignerDelegator is present, then the subject DAC’s issuer (a PAI) SHALL +match the CRLSignerDelegator in both Subject Key and Subject, otherwise return +immediately. +ii. If the CRLSignerDelegator is absent, then the subject DAC’s issuer (a PAI) SHALL match +the CRLSignerCertificate in both Subject Key and Subject, otherwise return immedi­ +ately. +c. If the serialNumber is part of the set, set IsRevoked to TRUE. +``` +The certificate in question is deemed revoked if IsRevoked was TRUE after execution of the above +algorithm. + +**6.3. Certification Declaration** + +A Certification Declaration (CD) is a cryptographic document that allows a Matter device to assert +its protocol compliance. It is encoded in a CMS format described in RFC 5652. Upon successful com­ +pletion of certification by a device type, Connectivity Standards Alliance creates the CD for that +device type so that it can be included in the device firmware by the manufacturer. + +**6.3.1. Certification Declaration (CD) Format** + +The Certification Declaration is a CMS-encoded SignedData payload (see RFC 5652 section 5) whose +EncapsulatedContentInfo eContent field contains a TLV-encoded certification-elements structure +with an anonymous tag: + +_Certification Elements TLV structure_ + +``` +certification-elements => STRUCTURE [ tag-order ] +{ +format_version [0] : UNSIGNED INTEGER [ range 16-bits ] +vendor_id [1] : UNSIGNED INTEGER [ range 16-bits ] +product_id_array [2] : ARRAY [ length 1..100 ] OF UNSIGNED INTEGER [ range 16- +bits ] +device_type_id [3] : UNSIGNED INTEGER [ range 32-bits ] +certificate_id [4] : STRING [ length 19 ] +security_level [5] : UNSIGNED INTEGER [ range 8-bits ] +security_information [6] : UNSIGNED INTEGER [ range 16-bits ] +version_number [7] : UNSIGNED INTEGER [ range 16-bits ] +certification_type [8] : UNSIGNED INTEGER [ range 8-bits] +dac_origin_vendor_id [9, optional] : UNSIGNED INTEGER [ range 16-bits ] +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 349 +``` + +``` +dac_origin_product_id [10, optional] : UNSIGNED INTEGER [ range 16-bits ] +authorized_paa_list [11, optional] : ARRAY [ length 1..10 ] OF OCTET STRING [ +length 20 ] +} +``` +The Certification Elements TLV is encoded with data to form a cd_content message to be signed. + +``` +cd_content = +{ +format_version (0) = 1, +vendor_id (1) = , +product_id_array (2) = , +device_type_id (3) = , +certificate_id (4) = , +security_level (5) = 0, +security_information (6) = 0, +version_number (7) = , +certification_type (8) = , +dac_origin_vendor_id (9) = , +dac_origin_product_id (10) = , +authorized_paa_list (11) = +} +``` +The format_version field SHALL contain the value 1. + +The vendor_id field SHALL contain the Vendor ID associated with the Certification Declaration. + +The product_id_array field SHALL contain an array of a number of Product IDs which are covered +by the same certification (e.g. certification by similarity). All other fields of a Certification Declara­ +tion apply to all products in this array. + +The device_type_id field SHALL contain the device type identifier for the primary function of the +device. For example, if device_type_id is 10 (0x000A), it would indicate that the device has a pri­ +mary function of a Door Lock device type. See also the _T subtype in Section 4.3.1.3, “Commissioning +Subtypes”. + +The device_type_id field in a given Certification Declaration indicates the primary device type and +SHOULD match the device_type_id value in the DCL entries associated with the VendorID and Pro­ +ductID combinations present in that Certification Declaration. + +The certificate_id field SHALL contain a globally unique serial number allocated by the CSA for +this Certification Declaration. + +The security_level and security_information fields are reserved for future use and SHALL be +ignored at read time, and set to zero at issuance time. + +The version_number field SHALL contain a version number for the CD itself, assigned by the CSA, + +``` +Page 350 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +that matches the Vendor ID and Product ID used in a DeviceSoftwareVersionModel entry in the Dis­ +tributed Compliance Ledger matching the certification record associated with the product present­ +ing this CD. + +The value of the version_number field is not meant to be interpreted by commissioners and SHALL +be recorded as assigned. + +The value of the version_number field is not related to any of the associated products' firmware or +software version number, but is rather a numerical version number for the CD itself. + +The certification_type field SHALL contain the type of certification for this CD, interpreted accord­ +ing to the following table: + +``` +certification_type meaning +0 used for development and test purposes +1 provisional - used for a device when going into +certification testing, or to allow production and +distribution to occur in parallel with certifica­ +tion (with potential software fixes yielding a +higher SoftwareVersion which gets certification) +2 official - allocated after passing certification +other values reserved +``` +For details about the usage of the certification_type field in the Device Attestation Procedure, see +failure of Device Attestation Procedure. + +The dac_origin_vendor_id field, if present, SHALL contain the Vendor ID value expected to be found +in the Device Attestation Certificate’s subject DN. + +The dac_origin_product_id field, if present, SHALL contain the Product ID value expected to be +found in the Device Attestation Certificate’s subject DN. + +The dac_origin_vendor_id and dac_origin_product_id SHALL only be present together. + +The use of the dac_origin_vendor_id and dac_origin_product_id fields allows for a target of the +device attestation procedure to have a manufacturing provenance which differs from the entity +that obtains the ultimate certification. If present, they tie a given Certification Declaration to an +original manufacturer’s device attestation chain of trust, so that DACs MAY be issued at manufac­ +turing time without _a priori_ knowledge of the ultimate vendor. + +The optional authorized_paa_list field, if present, SHALL contain a list of one or more Product +Attestation Authority (PAA) which is/are authorized (by the device manufacturer) to sign the Prod­ +uct Attestation Intermediate (PAI) Certificate which signs the Device Attestation Certificate for a +product carrying this Certification Declaration. Each such PAA is identified by the Subject Key Iden­ +tifier (SKI) extension value of its certificate. + +Any context-specific tags not listed in the above schema for Certification Elements SHALL be +reserved for future use, and SHALL be silently ignored if seen by a Commissioner which cannot + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 351 +``` + +understand them. + +See Section 6.2.3, “Device Attestation Procedure” for more details about usage of the Certification +Declaration fields. + +_Certification Declaration CMS ASN.1 Encoding Format_ + +``` +CertificationDeclaration ::= SEQUENCE { +version INTEGER ( v3(3) ), +digestAlgorithm OBJECT IDENTIFIER sha256 (2.16.840.1.101.3.4.2.1), +encapContentInfo EncapsulatedContentInfo, +signerInfo SignerInfo } +``` +``` +EncapsulatedContentInfo ::= SEQUENCE { +eContentType OBJECT IDENTIFIER pkcs7-data (1.2.840.113549.1.7.1), +eContent OCTET STRING cd_content } +``` +``` +SignerInfo ::= SEQUENCE { +version INTEGER ( v3(3) ), +subjectKeyIdentifier OCTET STRING, +digestAlgorithm OBJECT IDENTIFIER sha256 (2.16.840.1.101.3.4.2.1), +signatureAlgorithm OBJECT IDENTIFIER ecdsa-with-SHA256 (1.2.840.10045.4.3.2), +signature OCTET STRING } +``` +The Certification Declaration encoding rules: + +1. The format SHALL only support CMS version v3. +2. The digestAlgorithm SHALL use the sha256 algorithm. +3. The signatureAlgorithm SHALL use the ecdsa-with-SHA256 (ECDSA with SHA256) and secp256r1 + curve, as defined in Section 2.4.2 of SEC 2. +4. The eContentType SHALL use the pkcs7-data type. +5. The subjectKeyIdentifier SHALL contain the subject key identifier (SKI) of a well-known Con­ + nectivity Standards Alliance certificate, that was used to generate the signature. The format of + the key identifiers supported is available as part of the Certification Policy. +6. The eContent field SHALL contain the TLV-encoded Certification Elements TLV structure (see + Certification Elements TLV structure). + +Note that Certification Declarations SHALL NOT be generated by any Node, but rather, they SHALL +be stored and transmitted to a Commissioner by a Commissionee during the conveyance of the +Attestation Information in response to an Attestation Request command. + +See Section F.1, “Certification Declaration CMS test vector” for a complete example of generating a +Certification Declaration. + +``` +Page 352 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.3.2. Firmware Information** + +Firmware Information is an optional component of the Device Attestation Information (see Section +6.2.3, “Device Attestation Procedure”). + +Firmware Information MAY contain one or more Firmware Digests that correspond to the compo­ +nents in the firmware that have been measured and recorded during the boot process (e.g., boot­ +loader, kernel, root filesystem, etc), and MAY contain other metadata. A Firmware Digest SHALL +either represent a hash of the corresponding firmware layer or a hash of the signed manifest that +was used to validate the corresponding firmware layer during secure boot. An implementation +MAY choose to hash the measurements of all components into a single hash and include only that +hash in Firmware Information. + +A device MAY report Firmware Information containing its firmware digests only if it implements a +secure subsystem that protects the device attestation private key and is able to securely collect and +report firmware digests as shown in Figure 40, “Illustration of the measured boot process”. This +process is known as "measured boot". + +Ideally, the measured boot process SHOULD be rooted in silicon such as a boot ROM, similar to the +secure boot process found in many systems-on-chip (SoCs). Since many SoCs and microcontrollers +are unable to perform measured boot in hardware, the process SHOULD start at the earliest +firmware component possible (for example, at the bootloader shown in the figure below). In this +case, this firmware component is not measured and in fact, it is the root for measurement. There­ +fore, it SHALL be resistant to attacks compromising subsequent firmware components (e.g., the +ROM must verify its authenticity (secure boot) or it may be placed in a locked partition at the fac­ +tory that cannot be updated by software in the field). + +_Figure 40. Illustration of the measured boot process_ + +The device secure subsystem SHALL use the device attestation private key to sign attestation-ele­ +ments and NOCSR-elements. The device secure subsystem SHALL fill the attestation-elements fields +using information compiled into its image or generated during the measured boot process. The +device secure subsystem SHALL validate all signing requests so that if the device software, but not +its secure subsystem, gets compromised it cannot act as a signing oracle to sign Attestation Informa­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 353 +``` + +tion Responses with fake Firmware Digests. + +The firmware_information field in attestation-elements SHALL NOT be generated by devices that do +not implement a separate secure subsystem, in software or hardware, which maintains and con­ +trols the use of the device attestation private key. + +For devices that support secure boot, it is straightforward to add support for measured boot. Specif­ +ically, the hashes of the different firmware components that are already generated and verified +sequentially during secure boot SHALL be collected and stored for reporting. Devices that do not +support secure boot MAY implement measured boot by generating the hashes in software during +the boot process implementing the root for measurement in the earliest firmware component. + +If a device that chooses to send Firmware Digests and which supports an industry-standard mea­ +sured boot architecture and which can generate signed firmware attestation reports, the secure +subsystem in the device MAY validate the firmware attestation reports locally and SHALL report +the raw firmware digests in attestation-elements so that the firmware_information field in attesta­ +tion-elements has the same values in all devices of the same model that run the specific Software +Image. + +Firmware Digests SHALL NOT be reported by devices that implement a single firmware component +in the boot chain, because there is nothing to measure and report subsequently, unless they have +support for measured boot built in the device’s boot ROM. + +Commissioners MAY use the reported firmware information to confirm that the firmware version +is authorized to run on the device, that it has not been revoked, or that it does not contain known +vulnerabilities. Commissioners and Administrators that choose to verify this information SHOULD +refer to canonical databases, such as the Distributed Compliance Ledger (see Section 11.23, “Distrib­ +uted Compliance Ledger”) to validate that the reported firmware information matches what is +expected for an authorized Software Image associated with a given Certification Declaration. The +firmware information, when validated, SHALL be validated as an opaque well-known octet string. +Internal semantic validation MAY be applied for error-reporting, but the exact format is out of the +scope of this specification. + +In cases where a Commissioner or Administrator detects such an invalid or problematic firmware +version, Commissioners and Administrators MAY, after consultation with the user, refuse to com­ +mission the device, provide it with operational credentials, or otherwise operate it, until the +firmware has been updated, to avoid putting the user at risk from compromised software. + +**6.3.3. Firmware information validation examples** + +Below is an illustrative example of the Commissioner actions to validate the firmware information. + +1. Retrieve the firmware_information field from attestation-elements +2. Retrieve all Distributed Compliance Ledger DeviceSoftwareVersionModel entries for the Com­ + missionee’s Vendor ID and Product ID. +3. Verify that there is a valid, non-revoked, entry where the FirmwareInformation field exactly + matches the firmware_information field in attestation-elements. +4. If verification fails, report error to the user + +``` +Page 354 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +5. If verification succeeds, proceed with device commissioning + +Below is an example of the corresponding Device actions. For illustrative purposes, it is assumed +that the device implements a secure subsystem that maintains the private device attestation key +and signs attestation-elements using this key but it does not have direct hardware support for mea­ +sure boot. This is expected to be the common case for many devices covered by this version of the +specification. Consequently, the measurement process can only start from the bootloader shown in +the figure above. + +1. The device bootloader produces a measurement of the OS kernel using a supported hash algo­ + rithm from RFC 5912 and delivers it to the secure subsystem. +2. The secure subsystem receives the measurement and stores in a location inaccessible to the OS. +3. The OS kernel produces a hash of the root filesystem and delivers the measurement to the + secure subsystem. +4. When the secure subsystem is asked to sign an attestation-elements structure using its private + device attestation key, it generates two FirmwareDigests or one combined FirmwareDigest from + these measurements, fills the firmware_information field in attestation-elements using these + measurements, fills the CD blob compiled into the secure environment and signs the attestation- + elements structure. + +The Device Vendor is responsible to provide the FirmwareInformation field when a new Software +Image entry is reported in the corresponding Distributed Compliance Ledger entry. + +Below is an exemplary ASN.1 schema for an encoding scheme that could be used to encode +firmware information. + +_Firmware Information encoding example_ + +``` +HashAlgorithm ::= SEQUENCE { +id OBJECT IDENTIFIER, +params ANY OPTIONAL +} +``` +``` +FirmwareDigest ::= SEQUENCE { +digestAlgorithm HashAlgorithm, +digestHash OCTET STRING +} +``` +``` +FirmwareInformation ::= SEQUENCE { +firmwareDigests SEQUENCE OF FirmwareDigest +} +``` +``` +-- Example HashAlgorithm id +id-sha256 OBJECT IDENTIFIER ::= { +joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) +csor(3) nistAlgorithms(4) hashalgs(2) 1 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 355 +``` + +### } + +``` +-- Below is an example value for the above exemplary FirmwareInformation +``` +``` +firmwareInformation FirmwareInformation ::= { +-- The firmwareDigests contain two values, for two separate components. +firmwareDigests { +{ +digestAlgorithm { +id id-sha256 +}, +digestHash '00112233445566778899AABBCCDDEEFF00112233445566778899AABBCCDDEEFF'H +}, +{ +digestAlgorithm { +id id-sha256 +}, +digestHash '101112131415161718191A1B1C1D1E1F101112131415161718191A1B1C1D1E1F'H +} +} +} +``` +The above example would yield the following DER-encoded octet string: + +``` +30663031 300d0609 60864801 65030402 01050004 20001122 33445566 778899AA +BBCCDDEE FF001122 33445566 778899AA BBCCDDEE FF303130 0D060960 86480165 +03040201 05000420 10111213 14151617 18191A1B 1C1D1E1F 10111213 14151617 +18191A1B 1C1D1E1F +``` +**6.4. Node Operational Credentials Specification** + +**6.4.1. Introduction** + +The Node Operational credentials are a collection of credentials to enable a Node to identify itself +within a Fabric. The Node Operational credentials are distinct from the Device Attestation creden­ +tials. The Node Operational credentials are installed during Commissioning. + +The Node Operational credentials include the following items: + +- Node Operational Key Pair +- Node Operational Certificate (NOC) +- Intermediate Certificate Authority (ICA) Certificate (optional) +- Trusted Root Certificate Authority (CA) Certificate(s) + +``` +Page 356 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Each Node in a Fabric is identified with a Node Operational Identifier. In order to securely identify +the Node, the Node Operational Identifier is bound to the Node Operational Public Key as both are +contained within the signed NOC. The Node Operational Identifier is a constituent part of the sub­ +ject field of the NOC, according to the rules described in Matter DN Encoding Rules. A connecting +Node can attest to the validity of the Node Operational Public Key and the Node Operational Identi­ +fier in a received NOC because the NOC is signed by a CA that the connecting Node trusts. Used with +Certificate Authenticated Session Establishment (CASE), these data provide the basis for secure +communications on the Fabric. + +**6.4.2. Node Operational Credentials Management** + +Commands from the Node Operational Credentials Cluster are used to install and update Node +Operational credentials. + +A Node receives its initial set of Node Operational credentials through the AddNOC command when it +is commissioned onto a Fabric by a Commissioner. + +Once installed, Node Operational credentials MAY be updated by an Administrator with the appro­ +priate privileges using the UpdateNOC command. + +Once installed, Node Operational credentials MAY be removed by an Administrator with the appro­ +priate privileges using the RemoveFabric command. The removal uses RemoveFabric, since the Fabric +association for the given Node Operational credentials may underpin a variety of bindings and +other fabric-scoped configuration, which would remain in an inconsistent state if the Node Opera­ +tional credentials alone were removed, as opposed to the entire associated Fabric and data. + +**6.4.3. Node Operational Identifier Composition** + +The Node Operational Identifier is used for Node discovery and network address resolution within +a network segment. The FabricID portion of the Node Operational Identifier serves a scoping pur­ +pose to identify disjoint operational Fabrics within a given network segment. The NodeID portion of +the Node Operational Identifier is the logical addressing identifier used: + +- within Message-layer messages for logical addressing (see Section 4.4, “Message Frame Format”) +- within Data Model bindings to express data subscription relationships between Nodes (see Sys­ + tem Model) +- within Access Control List Entries to refer to individual Nodes as access control grantees (sub­ + jects) when CASE sessions are used for communication (see Section 9.10, “Access Control Clus­ + ter”) + +In addition to the FabricID and NodeID, a Node Operational Identifier MAY include at most three 32- +bit CASEAuthenticatedTag (1.3.6.1.4.1.37244.1.6) attributes used to tag the operational identifier to +implement access control based on CASE Authenticated Tags. + +The Fabric ID is a 64-bit value that identifies the Fabric and is scoped to a particular Root CA. For +example, two fabrics with the same Fabric ID are not equivalent unless their Root CA are the same. +The Fabric ID MAY be chosen randomly or algorithmically but it SHALL be allocated uniquely +within the set of all possible Fabric IDs for which a given Root CA will sign operational certificates. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 357 +``` + +Before allocating the Fabric ID, the Commissioner SHOULD attempt to ensure that an existing Fab­ +ric is reused and joined, if any is applicable from the perspective of the Commissioner in the cur­ +rent commissioning context. The method used for determining local Fabric ID existence is vendor- +specific. + +The Node ID is a 64-bit value that identifies a Node within a Fabric. The Node ID MAY be chosen +randomly or algorithmically but it SHALL be allocated uniquely within the Fabric before it is given +to the Node or otherwise used. The Node ID SHALL be chosen, by a Commissioner, at the time of +Node commissioning. + +The uniqueness constraint for Fabric ID is only required to be ensured within the scope of the Root +CA serving the Commissioner. + +**6.4.4. Node Operational Key Pair** + +A Node Operational Key Pair, comprised of a Node Operational Public Key and a Node Operational +Private Key, is created using the Crypto_GenerateKeypair function. A new Node Operational Key Pair +is generated for each Commissioning Session in accordance with security requirements. + +**6.4.5. Node Operational Credentials Certificates** + +All certificates in the Node Operational credentials are X.509v3 certificates compliant with +RFC 5280, encoded in such a way that they respect the constraints in the Operational_Certificate +section. They may be encoded as X.509v3 certificates or Matter Operational Certificates ("Matter +Certificates" thereafter). The signature field of a certificate SHALL be calculated using the X.509v3 +encoding of the certificate. + +**6.4.5.1. Node Operational Certificate (NOC)** + +The NOC SHALL be issued by either a Root CA trusted within the Fabric or by an Intermediate Cer­ +tificate Authority (ICA) whose ICA certificate is directly issued by such a Root CA. The NOC is bound +to the Node Operational Key Pair through the Node Operational Credential Signing Request +(NOCSR). + +The validity period specifies the time period for which a NOC is valid. For constrained or sleepy +devices that lack accurate time, enforcement of an NOC’s validity period MAY be omitted. + +**6.4.5.2. Intermediate CA (ICA) Certificate** + +In the case where an intermediate CA (ICA) issues the NOC, the ICA certificate is used to attest to the +validity of the NOC. The Root CA certificate associated with the issuer of the ICA certificate is used +in turn to attest to the validity of the ICA certificate. + +**6.4.5.3. Trusted Root CA Certificates** + +Each Node has one or more trusted Root CA certificates in its Node Operational credentials that it +uses to verify ICA certificates and Node Operational Certificates presented by other Nodes, treating +them as trust anchors as described in RFC 5280. A Root CA certificate is self-signed. They are not +verified but rather trusted because they were provisioned by a trusted Commissioner. + +``` +Page 358 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +In the case where a Root CA issues the NOC, the Root CA certificate is used to attest to the validity of +the NOC. + +The trusted Root CA certificates that a Device trusts when the Device is verifying operational certifi­ +cates are those stored in the TrustedRootCertificates attribute of that Device’s Node Operational +Credentials cluster. + +A device MAY have Root CA certificates that it trusts for purposes other than for operational creden­ +tial verification. These certificates SHALL NOT appear in any Node’s TrustedRootCertificates +attribute of the Node Operational Credentials cluster. The certificates configured in that cluster +SHALL only be added during the commissioning process by the Commissioner, or during root rota­ +tion operations by an Administrator already trusted by the Node. Nodes SHALL NOT modify the +TrustedRootCertificates attribute outside of the processing of Node Operational Credentials cluster +commands. + +The figures below show the Node Operational Certificate hierarchies, with and without optional +ICAC. + +_Figure 41. Node Operational Certificate PKI hierarchy with optional ICAC_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 359 +``` + +_Figure 42. Node Operational Certificate PKI hierarchy without optional ICAC_ + +**6.4.6. Node Operational Credentials Procedure** + +The following procedure is used by a Node to obtain an Operational Credential. This procedure is +part of Commissioning. + +**6.4.6.1. Node Operational Certificate Signing Request (NOCSR) Procedure** + +After the Commissioner validates Device Attestation Information, the following procedure is used +to generate a Node Operational Key Pair and obtain the NOCSR. + +1. The Commissioner SHALL generate a random 32 byte nonce named CSRNonce using Crypto_­ + DRBG(). +2. The Commissioner SHALL send the CSRNonce to the Node and request NOCSR Information + using the CSRRequest Command. + a.The Node SHALL create a new candidate Node Operational Key Pair, using Crypto_Gener­ + ateKeyPair(), valid for the duration of the Fail-Safe Context currently in progress. +b. The Node SHOULD verify that the newly generated candidate Node Operational Key Pair +does not match any other existing Node Operational Key Pair on the device. If such a key col­ +lision was to be found, it would indicate a key pair that was not properly randomly gener­ +ated. The procedure SHALL fail if such a collision is detected. See CSRRequest for the error +generated in that situation. +c.The candidate Node Operational Key Pair SHALL only be committed to persistent storage +upon successful execution of the next AddNOC Command executed with a Node Operational +Certificate whose public key matches the candidate key. +d. The Node SHALL create a Certificate Signing Request (CSR) by following the format and pro­ +cedure in PKCS #10, which includes a signature using the Node Operational Private Key (see +RFC 2986 section 4.2). + e. The CSR’s subject MAY be any value and the device SHOULD NOT expect the final opera­ + tional certificate to contain any of the CSR’s subject DN attributes. +3. The Node SHALL generate and return the NOCSR Information (see Section 11.18.4.9, “NOCSR + +``` +Page 360 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Information” for encoding) to the Commissioner using the CSRResponse Command. The NOCSR +Information includes a signature using the Device Attestation Private Key. +``` +**Node Operational CSR Information Validation** + +1. The Commissioner SHALL validate the Device Attestation Signature (attestation_signature) + field from CSRResponse Command: + +``` +Success = Crypto_Verify( +publicKey = Public key from DAC, +message = NOCSR Information TBS (nocsr_tbs), +signature = Device Attestation Signature (attestation_signature) +) +``` +``` +where the fields are encoded as described in Section 11.18.4.9, “NOCSR Information”. +``` +``` +◦ The AttestationChallenge SHALL be obtained from a CASE session, resumed CASE session, or +PASE session depending on the method used to establish the secure session within which +device attestation is conducted. +◦ The CSR Nonce in NOCSR Information SHALL match the Commissioner’s CSR Nonce. +``` +2. The inner signature in the PKCS#10 csr sub-field of the CSRResponse Command's NOCSRElements + field SHALL be verified, per the definition of CSR signatures in PKCS #10. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 361 +``` + +_Figure 43. Node Operational Credentials flow_ + +**6.4.7. Node Operational Certificate Signing Request (NOCSR)** + +A Node creates a NOCSR in response to the Commissioner, so that the Commissioner can request a +NOC on the Node’s behalf from its trusted Certificate Authority. The CSR itself SHALL follow the +encoding and rules from PKCS #10, with the minimum attributes shown in the example below. + +Note that the subject field MAY be any value. + +_NOCSR_ + +``` +Certificate Request: +Data: +Version: 1 (0x0) +Subject: ............... +Subject Public Key Info: +Public Key Algorithm: id-ecPublicKey +Public-Key: (256 bit) +pub: +``` +``` +Page 362 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +04:12:3b:90:f5:....... +ASN1 OID: prime256v1 +NIST CURVE: P-256 +Attributes: +Requested Extensions: +Signature Algorithm: ecdsa-with-SHA256 +30:46:02:21:00:95:ff:...... +``` +**6.4.8. Node Operational Certificate Renewal** + +A NOC can be renewed by an Administrator (a Node that has Administer privileges on the Node to +be updated). The Administrator triggers the process by sending an CSRRequest Command. + +**6.4.9. Node Operational Certificate Revocation** + +A Node’s access to other Nodes can be revoked by removing the associated Node ID from Access +Control Entry subjects where it appears. This action is taken by an Administrator which has the +privilege to update the Access Control Cluster for its Nodes. + +**6.4.10. VendorID Validation Procedure** + +Whenever a client requires determining whether a given ICAC/RCAC is associated with a fabric +administered by a given vendor, a VendorID Validation Procedure SHALL be used. The Vendor ID +validation procedure takes the following arguments: + +- ec-pub-key belonging to an ICAC/RCAC. +- pub-key-algo and ec-curve-id associated with ec-pub-key. +- Vendor ID to validate against the chain. + +The procedure is as follows: + +1. Use the ec-pub-key for computation of the subject-key-id as described in Section 6.5.11.4, “Sub­ + ject Key Identifier Extension” +2. Search in the DCL OperationalTrustAnchors Schema to determine if there is any entry matching + the subject-key-id and the Vendor ID. +3. Convert the certificate returned by DCL from PEM to Matter TLV Certificate and execute the fol­ + lowing operations on it: + a. Validate the DN Encoding Rules, including valid value range checks for identifiers such as + Fabric ID. + b. Check that values for ec-pub-key, pub-key-algo, ec-curve-id match with the ones provided as + input. + +If all the validations above have succeeded, return a list containing the ICAC/RCAC. Otherwise +return an empty list. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 363 +``` + +### NOTE + +``` +Vendors operating operational CAs need to consider whether they are operationally +sharing a root with other vendors. This could cause the potential for that other ven­ +dor to associate NOC chains with a different vendor, since validation of chaining is +done only against the trust anchor (root). +``` +``` +Support for VendorID Validation Procedure is provisional. +``` +**6.4.11. Security Considerations** + +A NOC is a Node’s credential to operate on a Fabric. It SHALL be protected against the following +threats: + +1. The Node Operational Private Key SHALL be protected from unauthorized access. +2. The Node Operational Private Key SHOULD never leave the device. +3. The NOC SHALL NOT contain information that may violate the user’s privacy. +4. The NOC SHALL be wiped if the Node is factory reset. + +**6.5. Operational Certificate Encoding** + +**6.5.1. Introduction** + +This section details the **Matter certificate data structure** (hereafter "Matter certificate"), a specific +encoding that is sometimes used as a compact alternative to the standard X.509 certificate format +[RFC 5280] for bandwidth-efficient transmission. A Node Operational Certificate (NOC), Intermedi­ +ate CA certificate and Root CA certificate MAY all be encoded as a Matter certificate. + +To compress the structure more efficiently than an X.509 certificate, a Matter certificate SHALL be +encoded with the Matter TLV structured data interchange language [Appendix A, _Tag-length-value +(TLV) Encoding Format_ ] instead of the ASN.1 Distinguished Encoding Rules (DER) [X.690]. + +This section provides a technical specification of the structure of data comprising a Matter certifi­ +cate with accompanying requirements for their semantic validation, and their conversion to and +from X.509 certificates. In some cases, as noted, the limitations on the semantic interpretation of +parts of a Matter certificate follow from limitations applied by [RFC 5280]. + +A certificate comprises a record of the following conceptual fields: + +``` +Certificate Text +Version Number +Serial Number +Signature Algorithm ID +Issuer Name +Validity period +Not Before +Not After +``` +``` +Page 364 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Subject name +Subject Public Key Info +Public Key Algorithm +Subject Public Key +Issuer Unique Identifier +Subject Unique Identifier +Extensions +Certificate Signature Algorithm +Certificate Signature +``` +**6.5.1.1. ASN.1 Object Identifiers (OID)** + +Several important components of X.509 certificates follow the pattern commonly used in ASN.1 +data models where some types are constructed with an ASN.1 object identifier (OID) to identify +each variant. For example, the cryptographic algorithm used in the digital signature is identified by +its OID. + +Matter certificates do not use ASN.1 OIDs. Instead, each valid ASN.1 OID SHALL be mapped to a +Matter TLV tag within its reference category. Each reference category defines the context of the +Matter tag, and tag values are assigned to the reference categories according to the type of fields +where they can appear in X.509 certificates. + +**6.5.2. Matter certificate** + +A Matter certificate encodes a subset of the object identifiers (OIDs) specified in X.509. Only some +attribute types for relative distinguished names are valid, only certain cryptographic algorithms +(corresponding to the algorithms as defined in Chapter 3, _Cryptographic Primitives_ ) are used, and +only a limited set of extensions are used. Therefore, every Matter certificate can be represented as a +corresponding X.509 certificate. However, the converse is not true; not every X.509 certificate can +be represented as a Matter certificate. + +The signature included in a Matter certificate is the signatureValue of the corresponding X.509 cer­ +tificate, not a signature of the preceding Matter TLV data in the Matter certificate structure. Accord­ +ingly, validating the signature in a Matter certificate entails its logical conversion to the correspond­ +ing X.509 certificate to recover the original tbsCertificate of the basic syntax signed by the Certifi­ +cate Authority (CA). + +``` +matter-certificate [anonymous] => STRUCTURE [tag-order] +{ +serial-num [1] : OCTET STRING [ length 0..20 ], +sig-algo [2] : signature-algorithm, +issuer [3] : LIST [ length 1.. ] OF dn-attribute, +not-before [4] : UNSIGNED INTEGER [ range 32-bits ], +not-after [5] : UNSIGNED INTEGER [ range 32-bits ], +subject [6] : LIST [ length 1.. ] OF dn-attribute, +pub-key-algo [7] : public-key-algorithm, +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 365 +``` + +``` +ec-curve-id [8] : elliptic-curve-id, +ec-pub-key [9] : OCTET STRING, +extensions [10] : LIST [ length 1.. ] OF extension, +signature [11] : ec-signature, +} +``` +**6.5.3. Version Number** + +Matter certificates SHALL only support version X.509 v3. This field is not encoded in the Matter cer­ +tificate structure. + +**6.5.4. Serial Number** + +The context-specific tag serial-num [1] SHALL be used to identify the serial number field in the +Matter certificate structure. + +A Matter certificate follows the same limitation on admissible serial numbers as in [RFC 5280], i.e., +that implementations SHALL admit serial numbers up to 20 octets in length, and certificate authori­ +ties SHALL NOT use serial numbers longer than 20 octets in length. + +**6.5.5. Signature Algorithm** + +Like an X.509 certificate, a Matter certificate SHALL include a digital signature in its signature com­ +ponent. The signature algorithm component of a Matter certificate specifies the cryptographic algo­ +rithm used for composing and validating the signature embedded in the signature component of +the certificate. The signature algorithm SHALL match the algorithm in Section 3.5.3, “Signature and +verification”. + +The context-specific tag sig-algo [2] SHALL be used to identify the signature algorithm field in the +Matter certificate structure. + +``` +signature-algorithm => UNSIGNED INTEGER [ range 8-bits ] +{ +ecdsa-with-sha256 = 1, +} +``` +The following values SHALL be defined for signature-algorithm: + +_Table 63. Signature Algorithm Object Identifiers_ + +``` +Value ASN.1 OID +1 iso(1) member-body(2) us(840) ansi-x962(10045) signatures(4) ecdsa-with-SHA2(3) ecdsa- +with-SHA256(2) +``` +**6.5.6. Issuer and Subject** + +The context-specific tags issuer [3] and subject [6] SHALL be used to identify the issuer and the + +``` +Page 366 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +subject DN fields in the Matter certificate structure. The entries in the lists SHALL be Distinguished +Names (DNs), which are described in Section 6.5.6.1, “X.501 Distinguished Names”. + +**6.5.6.1. X.501 Distinguished Names** + +The Issuer Name and Subject Name components of an X.509 certificate contain DNs as defined in +[RFC 5280]. The ASN.1 format of a DN is a sequence of Relative Distinguished Names (RDNs). Two +distinguished names DN1 and DN2 match if they have the same number of RDNs, for each RDN in +DN1 there is a matching RDN in DN2, and the matching RDNs appear in the same order in both DNs. + +The RDN in an X.509 certificate may be encoded as a set of one or more DN attributes, although in +practice it is usually a single DN attribute. The RDN in a Matter certificate SHALL be always a single +DN attribute. Two relative distinguished names RDN1 and RDN2 match if the attribute in RDN1 +matches the attribute in RDN2. + +``` +dn-attribute => CHOICE OF +{ +// Standard and Matter-specific DN attributes. +// Of these, all are encoded as UTF8String except domain-component, +// which is encoded as IA5String in X.509 form. +common-name [1] : STRING, +surname [2] : STRING, +serial-num [3] : STRING, +country-name [4] : STRING, +locality-name [5] : STRING, +state-or-province-name [6] : STRING, +org-name [7] : STRING, +org-unit-name [8] : STRING, +title [9] : STRING, +name [10] : STRING, +given-name [11] : STRING, +initials [12] : STRING, +gen-qualifier [13] : STRING, +dn-qualifier [14] : STRING, +pseudonym [15] : STRING, +domain-component [16] : STRING, +matter-node-id [17] : UNSIGNED INTEGER, +matter-firmware-signing-id [18] : UNSIGNED INTEGER, +matter-icac-id [19] : UNSIGNED INTEGER, +matter-rcac-id [20] : UNSIGNED INTEGER, +matter-fabric-id [21] : UNSIGNED INTEGER, +matter-noc-cat [22] : UNSIGNED INTEGER, +``` +``` +// Standard DN attributes when encoded as PrintableString in X.509 form +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 367 +``` + +``` +// NOTE: The tags for these SHALL be the base tags + 0x80. +common-name-ps [129] : STRING, +surname-ps [130] : STRING, +serial-num-ps [131] : STRING, +country-name-ps [132] : STRING, +locality-name-ps [133] : STRING, +state-or-province-name-ps [134] : STRING, +org-name-ps [135] : STRING, +org-unit-name-ps [136] : STRING, +title-ps [137] : STRING, +name-ps [138] : STRING, +given-name-ps [139] : STRING, +initials-ps [140] : STRING, +gen-qualifier-ps [141] : STRING, +dn-qualifier-ps [142] : STRING, +pseudonym-ps [143] : STRING, +} +``` +Table 64, “Standard DN Object Identifiers” lists the context-specific tags defined for the standard DN +attribute types used in Matter that can be encoded in X.509 certificates as either UTF8String or as +PrintableString format. In Matter certificates, the context-specific tag is logically-ORed with 0x80 +(and its name given a corresponding -ps suffix) to indicate that the corresponding X.509 encoding +of the attribute uses the PrintableString format instead of UTF8String. + +_Table 64. Standard DN Object Identifiers_ + +``` +Tag +base +``` +``` +Matter name base ASN.1 OID +``` +``` +1 common-name joint_iso_ccitt(2) ds(5) attributeType(4) commonName(3) +2 surname joint_iso_ccitt(2) ds(5) attributeType(4) surname(4) +3 serial-num joint_iso_ccitt(2) ds(5) attributeType(4) serialNumber(5) +4 country-name joint_iso_ccitt(2) ds(5) attributeType(4) countryName(6) +5 locality-name joint_iso_ccitt(2) ds(5) attributeType(4) localityName(7) +6 state-or-province-name joint_iso_ccitt(2) ds(5) attributeType(4) stateOrProvinceName(8) +7 org-name joint_iso_ccitt(2) ds(5) attributeType(4) organizationName(10) +8 org-unit-name joint_iso_ccitt(2) ds(5) attributeType(4) organizationalUnit­ +Name(11) +9 title joint_iso_ccitt(2) ds(5) attributeType(4) title(12) +10 name joint_iso_ccitt(2) ds(5) attributeType(4) name(41) +11 given-name joint_iso_ccitt(2) ds(5) attributeType(4) givenName(42) +12 initials joint_iso_ccitt(2) ds(5) attributeType(4) initials(43) +``` +``` +Page 368 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Tag +base +``` +``` +Matter name base ASN.1 OID +``` +``` +13 gen-qualifier joint_iso_ccitt(2) ds(5) attributeType(4) generationQualifier(44) +14 dn-qualifier joint_iso_ccitt(2) ds(5) attributeType(4) dnQualifier(46) +15 pseudonym joint_iso_ccitt(2) ds(5) attributeType(4) pseudonym(65) +``` +Table 65, “Standard DN Domain Component Object Identifier” lists the context-specific tag defined +for the standard DN attribute type used in Matter that is encoded in X.509 certificates as IA5String. + +_Table 65. Standard DN Domain Component Object Identifier_ + +``` +Tag Matter name ASN.1 OID +16 domain-component itu_t(0) data(9) pss(2342) ucl(19200300) pilot(100) pilotAttribute­ +Type(1) domainComponent(25) +``` +In addition to the standard DN attribute types, there are Matter-specific DN attribute types under +the 1.3.6.1.4.1.1.37244 private arc. See Section 6.1.1, “Encoding of Matter-specific RDNs” for con­ +straints and examples related to usage of Matter-specific DN attribute types. + +**6.5.6.2. Matter Certificate Types** + +The Matter-specific DN attribute types convey information about Matter-specific certificate types as +listed in Table 66, “Matter Certificate Types”. + +_Table 66. Matter Certificate Types_ + +``` +Matter name Description +matter-node-id Certifies the identity of a Matter Node Operational Certificate (NOC). +matter-firmware-signing-id Certifies the identity of a firmware signing certificate. +matter-icac-id Certifies the identity of a Matter Intermediate CA (ICA) Certificate. +matter-rcac-id Certifies the identity of a Matter Root CA Certificate. +``` +The value of matter-icac-id and matter-rcac-id DN attribute types MAY be any 64-bit identifier +desired by the certificate’s issuer. Apart from marking what type of certificates are involved, they +MAY be used for debugging purposes to determine the specific CA in use, for example if different +production tiers or regions are used. + +**6.5.6.3. Matter DN Encoding Rules** + +The rules that SHALL be followed for Matter-specific attribute types when encoding the subject DN +are: + +- For a Matter Node Operational Certificate (NOC): + ◦ The subject DN SHALL encode exactly one matter-node-id attribute. + ▪ The matter-node-id attribute’s value SHALL be in the Operational Node ID range + (0x0000_0000_0000_0001 to 0xFFFF_FFEF_FFFF_FFFF), see Table 4, “Node Identifier Allo­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 369 +``` + +``` +cations”. +◦ The subject DN SHALL encode exactly one matter-fabric-id attribute. +▪ The matter-fabric-id attribute’s value SHALL NOT be 0 (see Section 2.5.1, “Fabric Refer­ +ences and Fabric Identifier”). +◦ The subject DN SHALL NOT encode any matter-icac-id attribute. +◦ The subject DN SHALL NOT encode any matter-rcac-id attribute. +◦ The subject DN MAY encode at most three matter-noc-cat attributes. +▪ Each matter-noc-cat attribute present, if any, SHALL encode a different CASE Authenti­ +cated Tag identifier (upper 16 bits of value) than is used by other matter-noc-cat attrib­ +utes (CATs). +``` +- For a Matter ICA Certificate: + ◦ The subject DN SHALL NOT encode any matter-node-id attribute. + ◦ The subject DN MAY encode at most one matter-fabric-id attribute. + ▪ If present, the matter-fabric-id attribute’s value SHALL NOT be 0 (see Section 2.5.1, “Fab­ + ric References and Fabric Identifier”). + ◦ The subject DN SHALL encode exactly one matter-icac-id attribute. + ◦ The subject DN SHALL NOT encode any matter-rcac-id attribute. + ◦ The subject DN SHALL NOT encode any matter-noc-cat attribute. +- For a Matter Root CA Certificate: + ◦ The subject DN SHALL NOT encode any matter-node-id attribute. + ◦ The subject DN MAY encode at most one matter-fabric-id attribute. + ▪ If present, the matter-fabric-id attribute’s value SHALL NOT be 0 (see Section 2.5.1, “Fab­ + ric References and Fabric Identifier”). + ◦ The subject DN SHALL NOT encode any matter-icac-id attribute. + ◦ The subject DN SHALL encode exactly one matter-rcac-id attribute. + ◦ The subject DN SHALL NOT encode any matter-noc-cat attribute. +- The attributes SHALL appear in the same order in the Matter certificate and in the correspond­ + ing X.509 certificates. +- When any matter-fabric-id attributes are present in either the Matter Root CA Certificate or the + Matter ICA Certificate, the value SHALL match the one present in the Matter Node Operational + Certificate (NOC) within the same certificate chain. +- The order of the attributes can be issuer-specific and is not enforced by Matter specifications. +- All implementations SHALL accept, parse, and handle Matter certificates with up to 5 RDNs in a + single DN. +- All implementations SHALL reject Matter certificates with more than 5 RDNs in a single DN. + +In addition to the above rules, the encoding constraints in Section 6.1.1, “Encoding of Matter-spe­ +cific RDNs” SHALL be followed. + +``` +Page 370 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.5.6.4. Matter DN Examples** + +The following is an example of subject DN encoding for a Matter Node Operational Certificate +(NOC). Typically, it is a list of two RDN attributes: + +``` +subject = [[ +matter-node-id = 0x0102030405060708U, +matter-fabric-id = 0xFAB000000000001DU +]] +``` +In addition to the mandatory attributes, it may also encode other supported RDN attributes such as +common-name and CASE Authenticated Tags as presented below: + +``` +subject = [[ +common-name = "NOC Example", +matter-node-id = 0x0102030405060708U, +matter-fabric-id = 0xFAB000000000001DU, +matter-noc-cat = 0xABCD0002U +]] +``` +The following subject DN example illustrates that multiple RDN attributes of the same type can be +encoded. The specific order of attributes is not enforced. Note that number of RDN attributes in the +subject field SHALL NOT exceed five: + +``` +subject = [[ +matter-noc-cat = 0xABCD0004U, +matter-node-id = 0x0102030405060708U, +matter-noc-cat = 0xABCE0018U, +matter-fabric-id = 0xFAB000000000001DU, +matter-noc-cat = 0xABCF0002U +]] +``` +The following example illustrates an illegal subject DN due to the presence of the same CASE +Authenticated Tag value with two different version numbers. + +``` +subject = [[ +matter-node-id = 0x0102030405060708U, +matter-fabric-id = 0xFAB000000000001DU, +matter-noc-cat = 0xABCD0004U, # <-- Value 0xABCD, Version 0x0004 +matter-noc-cat = 0xABCD0002U, # <-- Value 0xABCD, Version 0x0002 +]] +``` +The following is an example of subject DN encoding for a Matter Root CA certificate. In this case, the + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 371 +``` + +Matter Root CA certificate is not associated with a specific Matter fabric: + +``` +subject = [[ +matter-rcac-id = 0xCA0000000000001DU +]] +``` +The following is another example of subject DN encoding for a Matter Root CA certificate. In this +case, the Matter Root CA certificate is associated with a specific Matter fabric. This DN also encodes +an issuer-specific common-name RDN attribute: + +``` +subject = [[ +matter-rcac-id = 0xCA0000000000001DU, +matter-fabric-id = 0xFAB000000000001DU, +common-name = "ROOT CA HOME 3" +]] +``` +**6.5.7. Validity** + +The context-specific tags not-before [4] and not-after [5] SHALL be used to identify the not-before +and not-after fields in the Matter certificate structure, which indicate the period of validity for the +certificate. These two fields SHALL be encoded as unsigned integers. The value of these fields +SHALL be encoded as a UTC time of type epoch-s (Epoch Time in Seconds). + +Special value 0, when encoded in the not-after field, corresponds to the X.509/RFC 5280 defined +special time value 99991231235959Z meaning no well-defined expiration date. + +**6.5.8. Public Key Algorithm** + +The context-specific tag pub-key-algo [7] SHALL be used to identify the public key algorithm field +in the Matter certificate structure. + +``` +public-key-algorithm => UNSIGNED INTEGER [ range 8-bits ] +{ +ec-pub-key = 1, +} +``` +The following values SHALL be defined for public-key-algorithm: + +_Table 67. Public Key Algorithm Object Identifiers_ + +``` +Value ASN.1 OID +1 iso(1) member-body(2) us(840) ansi-x962(10045) keyType(2) ecPublicKey(1) +``` +``` +Page 372 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.5.9. EC Curve Identifier** + +The context-specific tag ec-curve-id [8] SHALL be used to identify the elliptic curve field in the +Matter certificate structure. + +``` +elliptic-curve-id => UNSIGNED INTEGER [ range 8-bits ] +{ +prime256v1 = 1, +} +``` +The following values SHALL be defined for elliptic-curve-id: + +_Table 68. Elliptic Curve Object Identifiers_ + +``` +Value ASN.1 OID +1 iso(1) member_body(2) us(840) ansi-x962(10045) curves(3) prime(1) prime256v1(7) +``` +**6.5.10. Public Key** + +The context-specific tag ec-pub-key [9] SHALL be used to identify the elliptic curve public key mate­ +rial field in the Matter certificate structure. The public key SHALL be a byte string representation of +an uncompressed elliptic curve point as defined in section 2.3.3 of SEC 1. + +**6.5.11. Extensions** + +The context-specific tag extensions [10] SHALL be used to identify the extensions field in the Mat­ +ter certificate structure. The extensions list SHALL NOT contain more than one instance of a partic­ +ular extension. The following table summarizes context-specific tags defined for the certificate +extension types used in Matter. + +``` +extension => CHOICE OF +{ +basic-cnstr [1] : basic-constraints, +key-usage [2] : UNSIGNED INTEGER [ range 16-bits ], +extended-key-usage [3] : ARRAY [ length 1.. ] OF key-purpose-id, +subject-key-id [4] : OCTET STRING [ length 20 ], +authority-key-id [5] : OCTET STRING [ length 20 ], +future-extension [6] : OCTET STRING, +} +``` +_Table 69. Extensions Object Identifiers_ + +``` +Tag Matter Name ASN.1 OID +1 basic-cnstr joint-iso-itu-t(2) ds(5) certificateExtension(29) basic­ +Constraints(19) +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 373 +``` + +``` +Tag Matter Name ASN.1 OID +2 key-usage joint-iso-itu-t(2) ds(5) certificateExtension(29) keyUsage(15) +3 extended-key-usage joint-iso-itu-t(2) ds(5) certificateExtension(29) extended­ +KeyUsage(37) +4 subject-key-id joint-iso-itu-t(2) ds(5) certificateExtension(29) subjectKeyIdenti­ +fier(14) +5 authority-key-id joint-iso-itu-t(2) ds(5) certificateExtension(29) authorityKeyI­ +dentifier(35) +6 future-extension any valid ASN.1 OID (future extension) +``` +These context-specific tags identify the extension entries in the extensions list. The type of each +extension is further described in the subsections below. + +**6.5.11.1. Basic Constraints Extension** + +The basic constraints extension identifies whether the subject of the certificate is a CA and the max­ +imum depth of valid certification paths that include this certificate. + +When present, the basic constraints extension SHALL be treated as critical and it SHALL be +marked as critical in the corresponding X.509 certificate. The critical field SHALL NOT be +encoded in the Matter certificate structure. + +The context-specific tag basic-cnstr [1] SHALL be used to identify a basic constraints extension +entry in the Matter certificate extensions list. + +``` +basic-constraints => STRUCTURE [tag-order] +{ +is-ca [1] : BOOLEAN, +path-len-constraint [2, optional] : UNSIGNED INTEGER [ range 8-bits ], +} +``` +The is-ca field SHALL be encoded regardless of the value (true or false). The path-len-constraint +MAY be present only when is-ca == true. + +**6.5.11.2. Key Usage Extension** + +The key usage extension defines the purpose of the key contained in the certificate. + +When present, the key usage extension SHALL be treated as critical and it SHALL be marked as +critical in the corresponding X.509 certificate. The critical field SHALL NOT be encoded in the +Matter certificate structure. + +The context-specific tag number key-usage [2] SHALL be used to identify a key usage extension +entry in the Matter certificate extensions list. + +The key-usage field is derived as a logical OR of all key-usage-flag values that apply to the corre­ + +``` +Page 374 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +sponding public key: + +``` +key-usage-flag => UNSIGNED INTEGER [ range 16-bits ] +{ +digitalSignature = 0x0001, +nonRepudiation = 0x0002, +keyEncipherment = 0x0004, +dataEncipherment = 0x0008, +keyAgreement = 0x0010, +keyCertSign = 0x0020, +CRLSign = 0x0040, +encipherOnly = 0x0080, +decipherOnly = 0x0100, +} +``` +**6.5.11.3. Extended Key Usage Extension** + +The extended key usage extension indicates one or more purposes for which the certified public +key may be used, in addition to or in place of the basic purposes indicated in the key usage exten­ +sion. + +When present, the extended key usage extension SHALL be treated as critical and it SHALL be +marked as critical in the corresponding X.509 certificate. The critical field SHALL NOT be +encoded in the Matter certificate structure. + +The context-specific tag number extended-key-usage [3] SHALL be used to identify an extended key +usage extension entry in the Matter certificate extensions list. + +The extended-key-usage field SHALL be encoded as an array of key-purpose-id values, where each +key-purpose-id value SHALL be encoded as 8-bit unsigned integer: + +``` +key-purpose-id => UNSIGNED INTEGER [ range 8-bits ] +``` +The following values SHALL be defined for key-purpose-id: + +_Table 70. Key Purpose Object Identifiers_ + +``` +Value ASN.1 OID +1 iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, server­ +Auth(1) +2 iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, clien­ +tAuth(2) +3 iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, code­ +Signing(3) +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 375 +``` + +``` +Value ASN.1 OID +4 iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, email­ +Protection(4) +5 iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, time­ +Stamping(8) +6 iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, OCSP­ +Signing(9) +``` +The key-purpose-id values in the extended-key-usage array SHALL be encoded in the same order as +they appeared in the corresponding X.509 certificate. + +**6.5.11.4. Subject Key Identifier Extension** + +The subject key identifier extension provides a means of identifying Matter certificates that contain +a particular public key. + +When present, the subject key identifier extension SHALL be treated as non-critical and it SHALL +be marked as non-critical in the corresponding X.509 certificate. The critical field SHALL NOT be +encoded in the Matter certificate structure. + +The context-specific tag number subject-key-id [4] SHALL be used to identify a subject key identi­ +fier extension entry in the Matter certificate extensions list. + +The Subject Key Identifier field SHALL be derived from the public key using method (1) described +in section 4.2.1.2 of [RFC 5280]. Thus, the subject-key-id SHALL be composed of the 160-bit SHA-1 +hash of the certificate’s subject public key value. + +See Section 6.1.2, “Key Identifier Extension Constraints” for additional constraints. + +**6.5.11.5. Authority Key Identifier Extension** + +The authority key identifier extension provides a means of identifying the public key correspond­ +ing to the private key used to sign a Matter certificate. + +When present, the authority key identifier extension SHALL be treated as non-critical and it +SHALL be marked as non-critical in the corresponding X.509 certificate. The critical field SHALL +NOT be encoded in the Matter certificate structure. + +The context-specific tag number authority-key-id [5] SHALL be used to identify an authority key +identifier extension entry in the Matter certificate extensions list. + +Note that the authority key identifier extension field in an X.509 certificate may optionally include +issuer and serial number fields, which are not supported by Matter certificates. + +The Authority Key Identifier field SHALL be derived from the public key using method (1) described +in section 4.2.1.2 of [RFC 5280]. Thus, the authority-key-id SHALL be composed of the 160-bit SHA-1 +hash of the public key used to verify the certificate’s signature. + +See Section 6.1.2, “Key Identifier Extension Constraints” for additional constraints. + +``` +Page 376 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.5.11.6. Future Extension** + +The Matter certificate is designed with extensibility in mind and this field is added to support arbi­ +trary certificate extension in the future. + +Note that implementations that do not support specific future extension will ignore it but will be +able to use it for the Matter certificate signature validation. If ignored extension is marked as criti­ +cal then validation of the corresponding Matter certificate SHALL fail. + +The context-specific tag number future-extension [6] SHALL be used to identify all future exten­ +sion entries in the Matter certificate extensions list. There MAY be more than one future extension +field. + +The future-extension field SHALL be encoded as OCTET STRING and it SHALL be an exact copy of +the DER encoded extension field (including the DER encoded ASN.1 OID of the extension) in the cor­ +responding X.509 certificate. These extension fields in a Matter certificate SHALL be encoded in the +same order as they appeared in the original X.509 certificate. + +**6.5.12. Matter certificate Extensions Encoding Rules** + +The rules that SHALL be followed when encoding the Matter certificate are: + +- For a Matter Node Operational Certificate (NOC): + ◦ The basic constraints extension SHALL be encoded with is-ca set to false. + ◦ The key usage extension SHALL be encoded with exactly one flag: digitalSignature. + ◦ The extended key usage extension SHALL be encoded with exactly two key-purpose-id val­ + ues: serverAuth and clientAuth. + ◦ The subject key identifier extension SHALL be present. + ◦ The authority key identifier extension SHALL be present. +- For Matter ICA Certificate and Matter Root CA Certificate: + ◦ The basic constraints extension SHALL be encoded with is-ca set to true. + ◦ The key usage extension SHALL be encoded with at least the two flags keyCertSign and CRL­ + Sign included, and MAY include a third flag: digitalSignature. No additional flags are per­ + mitted. + ◦ The extended key usage extension SHALL NOT be present. + ◦ The subject key identifier extension SHALL be present. + ◦ The authority key identifier extension SHALL be present. + ◦ For the Matter Root CA Certificate the authority key identifier extension SHALL be equal to + the subject key identifier extension. +- For a Matter Firmware Signing Certificate these rules SHALL be followed: + ◦ The basic constraints extension SHALL be encoded with is-ca set to false. + ◦ The key usage extension SHALL be encoded with exactly one flag: digitalSignature. + ◦ The extended key usage extension SHALL be encoded with exactly one key-purpose-id val­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 377 +``` + +``` +ues: codeSigning. +◦ The subject key identifier extension SHALL be present. +◦ The authority key identifier extension SHALL be present. +``` +- The extensions SHALL appear in the same order in the Matter certificate and in the correspond­ + ing X.509 certificates. + +Note that Matter doesn’t specify how firmware images are signed and implementation of firmware +image signing is manufacturer-specific. However, since firmware image signing is a common fea­ +ture, the format for Matter TLV certificates has affordances for encoding firmware signing certifi­ +cates. + +**6.5.13. Signature** + +The context-specific tag signature [11] SHALL be used to identify the signature field in the Matter +certificate structure. + +An ec-signature is the encoding of the signature as defined in Section 3.5.3, “Signature and verifica­ +tion”. + +``` +ec-signature => OCTET STRING [ length (CRYPTO_GROUP_SIZE_BYTES * 2) ] +``` +**6.5.14. Invalid Matter certificates** + +The Matter certificate is considered invalid if it violates Matter certificate encoding rules defined in +this section. The processing of invalid Matter certificate SHOULD fail and an error SHOULD be +reported to the application. Here is a non-exhaustive list of errors that may invalidate the certifi­ +cate: + +- Matter certificate structure includes elements that are not defined in this section. +- Matter certificate elements are encoded in a wrong order. +- Matter certificate element has wrong type. +- Length of an element is outside of its valid range, for example: + ◦ serial-num field is longer than 20 octets. + ◦ not-before or not-after field is longer than 32-bits. + ◦ subject-key-id or authority-key-id field is different from 20 octets. +- Matter OID values encoded in Matter certificate are not defined in this section, for example: + ◦ sig-algo field encodes value, which is not defined in Table 63, “Signature Algorithm Object + Identifiers”. + ◦ pub-key-algo field encodes value, which is not defined in Table 67, “Public Key Algorithm + Object Identifiers”. + ◦ ec-curve-id field encodes value, which is not defined in Table 68, “Elliptic Curve Object Iden­ + tifiers”. + +``` +Page 378 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +◦ key-purpose-id field of the Extended Key Usage Extension encodes value, which is not +defined in Table 70, “Key Purpose Object Identifiers”. +``` +- Invalid Matter Distinguished Names encoding for Issuer and Subject DNs. Refer to Section + 6.5.6.3, “Matter DN Encoding Rules” for more details. For example: + ◦ Node Subject DN doesn’t include Matter specific matter-node-id or matter-fabric-id + attribute. + ◦ Firmware signing Subject DN doesn’t include Matter specific matter-firmware-signing-id + attribute. + ◦ Intermediate CA Subject DN doesn’t include Matter specific matter-icac-id attribute. + ◦ Root CA Subject DN doesn’t include Matter specific matter-rcac-id attribute. + ◦ Certificate Subject DN encodes matter-node-id and matter-rcac-id, which contradict each + other. + ◦ Multiple matter-cat-id with the same identifier value and different version numbers, or any + matter-cat-id with a version number of 0. +- CA certificate doesn’t have Basic Constraints Extension is-ca field set to 'true'. +- key-usage field of the Key Usage Extension has undefined flags. +- Certificate extension that SHALL be marked as critical is marked as non-critical in the X.509 + representation and vise versa. + +**6.5.15. Examples** + +**6.5.15.1. Example of Operational Root CA Certificate (RCAC)** + +The same RCAC in X.509 and Matter TLV formats is presented in this section. + +_RCAC with Corresponding Private Key in an X.509 PEM Format_ + +``` +-----BEGIN CERTIFICATE----- +MIIBnTCCAUOgAwIBAgIIWeqmMpR/VBwwCgYIKoZIzj0EAwIwIjEgMB4GCisGAQQB +gqJ8AQQMEENBQ0FDQUNBMDAwMDAwMDEwHhcNMjAxMDE1MTQyMzQzWhcNNDAxMDE1 +MTQyMzQyWjAiMSAwHgYKKwYBBAGConwBBAwQQ0FDQUNBQ0EwMDAwMDAwMTBZMBMG +ByqGSM49AgEGCCqGSM49AwEHA0IABBNTo7PvHacIxJCASAFOQH1ZkM4ivE6zPppa +yyWoVgPrptzYITZmpORPWsoT63Z/r6fc3dwzQR+CowtUPdHSS6ijYzBhMA8GA1Ud +EwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBQTr4GrNzdLLtKp +ZJsSt6OkKH4VHTAfBgNVHSMEGDAWgBQTr4GrNzdLLtKpZJsSt6OkKH4VHTAKBggq +hkjOPQQDAgNIADBFAiBFgWRGbI8ZWrwKu3xstaJ6g/QdN/jVO+7FIKvSoNoFCQIh +ALinwlwELjDPZNww/jNOEgAZZk5RUEkTT1eBI4RE/HUx +-----END CERTIFICATE----- +``` +### -----BEGIN EC PRIVATE KEY----- + +``` +MHcCAQEEIH1zW+/pFqHAygL4ypiB5CZjqq+aucQzsom+JnAQdXQaoAoGCCqGSM49 +AwEHoUQDQgAEE1Ojs+8dpwjEkIBIAU5AfVmQziK8TrM+mlrLJahWA+um3NghNmak +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 379 +``` + +``` +5E9ayhPrdn+vp9zd3DNBH4KjC1Q90dJLqA== +-----END EC PRIVATE KEY----- +``` +_RCAC Printed in an X.509 DER Format_ + +``` +Certificate: +Data: +Version: 3 (0x2) +Serial Number: 6479173750095827996 (0x59eaa632947f541c) +Signature Algorithm: ecdsa-with-SHA256 +Issuer: 1.3.6.1.4.1.37244.1.4 = CACACACA00000001 +Validity +Not Before: Oct 15 14:23:43 2020 GMT +Not After : Oct 15 14:23:42 2040 GMT +Subject: 1.3.6.1.4.1.37244.1.4 = CACACACA00000001 +Subject Public Key Info: +Public Key Algorithm: id-ecPublicKey +Public-Key: (256 bit) +pub: +04:13:53:a3:b3:ef:1d:a7:08:c4:90:80:48:01:4e: +40:7d:59:90:ce:22:bc:4e:b3:3e:9a:5a:cb:25:a8: +56:03:eb:a6:dc:d8:21:36:66:a4:e4:4f:5a:ca:13: +eb:76:7f:af:a7:dc:dd:dc:33:41:1f:82:a3:0b:54: +3d:d1:d2:4b:a8 +ASN1 OID: prime256v1 +NIST CURVE: P-256 +X509v3 extensions: +X509v3 Basic Constraints: critical +CA:TRUE +X509v3 Key Usage: critical +Certificate Sign, CRL Sign +X509v3 Subject Key Identifier: +13:AF:81:AB:37:37:4B:2E:D2:A9:64:9B:12:B7:A3:A4:28:7E:15:1D +X509v3 Authority Key Identifier: +keyid:13:AF:81:AB:37:37:4B:2E:D2:A9:64:9B:12:B7:A3:A4:28:7E:15:1D +``` +``` +Signature Algorithm: ecdsa-with-SHA256 +30:45:02:20:45:81:64:46:6c:8f:19:5a:bc:0a:bb:7c:6c:b5: +a2:7a:83:f4:1d:37:f8:d5:3b:ee:c5:20:ab:d2:a0:da:05:09: +02:21:00:b8:a7:c2:5c:04:2e:30:cf:64:dc:30:fe:33:4e:12: +00:19:66:4e:51:50:49:13:4f:57:81:23:84:44:fc:75:31 +``` +``` +Page 380 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_RCAC in Matter TLV Format_ + +``` +15 30 01 08 59 ea a6 32 94 7f 54 1c 24 02 01 37 03 27 14 01 00 00 00 ca +ca ca ca 18 26 04 ef 17 1b 27 26 05 6e b5 b9 4c 37 06 27 14 01 00 00 00 +ca ca ca ca 18 24 07 01 24 08 01 30 09 41 04 13 53 a3 b3 ef 1d a7 08 c4 +90 80 48 01 4e 40 7d 59 90 ce 22 bc 4e b3 3e 9a 5a cb 25 a8 56 03 eb a6 +dc d8 21 36 66 a4 e4 4f 5a ca 13 eb 76 7f af a7 dc dd dc 33 41 1f 82 a3 +0b 54 3d d1 d2 4b a8 37 0a 35 01 29 01 18 24 02 60 30 04 14 13 af 81 ab +37 37 4b 2e d2 a9 64 9b 12 b7 a3 a4 28 7e 15 1d 30 05 14 13 af 81 ab 37 +37 4b 2e d2 a9 64 9b 12 b7 a3 a4 28 7e 15 1d 18 30 0b 40 45 81 64 46 6c +8f 19 5a bc 0a bb 7c 6c b5 a2 7a 83 f4 1d 37 f8 d5 3b ee c5 20 ab d2 a0 +da 05 09 b8 a7 c2 5c 04 2e 30 cf 64 dc 30 fe 33 4e 12 00 19 66 4e 51 50 +49 13 4f 57 81 23 84 44 fc 75 31 18 +``` +_RCAC Printed in Matter TLV Schema Format_ + +``` +matter-certificate = { +serial-num = 59 EA A6 32 94 7F 54 1C, +sig-algo = 0x01U, +issuer = [[ matter-rcac-id = 0xCACACACA00000001U ]], +not-before = 0x271B17EFU, +not-after = 0x4CB9B56EU, +subject = [[ matter-rcac-id = 0xCACACACA00000001U ]], +pub-key-algo = 0x01U, +ec-curve-id = 0x01U, +ec-pub-key = 04 13 53 A3 B3 EF 1D A7 08 C4 90 80 48 01 4E 40 +7D 59 90 CE 22 BC 4E B3 3E 9A 5A CB 25 A8 56 03 +EB A6 DC D8 21 36 66 A4 E4 4F 5A CA 13 EB 76 7F +AF A7 DC DD DC 33 41 1F 82 A3 0B 54 3D D1 D2 4B +A8, +extensions = [[ +basic-constraints = { +is-ca = true +}, +key-usage = 0x60U, +subject-key-id = 13 AF 81 AB 37 37 4B 2E D2 A9 64 9B 12 B7 A3 A4 +28 7E 15 1D, +authority-key-id = 13 AF 81 AB 37 37 4B 2E D2 A9 64 9B 12 B7 A3 A4 +28 7E 15 1D, +]], +signature = 45 81 64 46 6C 8F 19 5A BC 0A BB 7C 6C B5 A2 7A +83 F4 1D 37 F8 D5 3B EE C5 20 AB D2 A0 DA 05 09 +B8 A7 C2 5C 04 2E 30 CF 64 DC 30 FE 33 4E 12 00 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 381 +``` + +### 19 66 4E 51 50 49 13 4F 57 81 23 84 44 FC 75 31 + +### } + +**6.5.15.2. Example of Operational Intermediate CA Certificate (ICAC)** + +The same ICAC in X.509 and Matter TLV formats is presented in this section. An issuer of this ICAC is +RCAC from previous section. + +_ICAC with Corresponding Private Key in an X.509 PEM Format_ + +``` +-----BEGIN CERTIFICATE----- +MIIBnTCCAUOgAwIBAgIILbREhVZBrt8wCgYIKoZIzj0EAwIwIjEgMB4GCisGAQQB +gqJ8AQQMEENBQ0FDQUNBMDAwMDAwMDEwHhcNMjAxMDE1MTQyMzQzWhcNNDAxMDE1 +MTQyMzQyWjAiMSAwHgYKKwYBBAGConwBAwwQQ0FDQUNBQ0EwMDAwMDAwMzBZMBMG +ByqGSM49AgEGCCqGSM49AwEHA0IABMXQhhu4+QxAXBIxTkxevuqTn3J3S8wzI54v +Wfb0avjcfUaCoOPMxkbm3ynqhr9WKucgqJgzfTg/MsCgnkFgGeqjYzBhMA8GA1Ud +EwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBRTUtcFnpwVpQiQ +aGKGSAGinx9B0zAfBgNVHSMEGDAWgBQTr4GrNzdLLtKpZJsSt6OkKH4VHTAKBggq +hkjOPQQDAgNIADBFAiEAhBoG1Dten+zSToexJE61HGos8g2bXmugfxHmAC9+DKMC +IE4ypgLDYJ0AktNIvb0ZihFGRr1BzxA3g2Qa4l4/I/0m +-----END CERTIFICATE----- +``` +### -----BEGIN EC PRIVATE KEY----- + +``` +MHcCAQEEIBGEO9zwrSBtsQJRpU2sWB11+ZL8tSJ1KiFs15xxdUapoAoGCCqGSM49 +AwEHoUQDQgAExdCGG7j5DEBcEjFOTF6+6pOfcndLzDMjni9Z9vRq+Nx9RoKg48zG +RubfKeqGv1Yq5yComDN9OD8ywKCeQWAZ6g== +-----END EC PRIVATE KEY----- +``` +_ICAC Printed in an X.509 DER Format_ + +``` +Certificate: +Data: +Version: 3 (0x2) +Serial Number: 3293332566983159519 (0x2db444855641aedf) +Signature Algorithm: ecdsa-with-SHA256 +Issuer: 1.3.6.1.4.1.37244.1.4 = CACACACA00000001 +Validity +Not Before: Oct 15 14:23:43 2020 GMT +Not After : Oct 15 14:23:42 2040 GMT +Subject: 1.3.6.1.4.1.37244.1.3 = CACACACA00000003 +Subject Public Key Info: +Public Key Algorithm: id-ecPublicKey +Public-Key: (256 bit) +pub: +``` +``` +Page 382 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +04:c5:d0:86:1b:b8:f9:0c:40:5c:12:31:4e:4c:5e: +be:ea:93:9f:72:77:4b:cc:33:23:9e:2f:59:f6:f4: +6a:f8:dc:7d:46:82:a0:e3:cc:c6:46:e6:df:29:ea: +86:bf:56:2a:e7:20:a8:98:33:7d:38:3f:32:c0:a0: +9e:41:60:19:ea +ASN1 OID: prime256v1 +NIST CURVE: P-256 +X509v3 extensions: +X509v3 Basic Constraints: critical +CA:TRUE +X509v3 Key Usage: critical +Certificate Sign, CRL Sign +X509v3 Subject Key Identifier: +53:52:D7:05:9E:9C:15:A5:08:90:68:62:86:48:01:A2:9F:1F:41:D3 +X509v3 Authority Key Identifier: +keyid:13:AF:81:AB:37:37:4B:2E:D2:A9:64:9B:12:B7:A3:A4:28:7E:15:1D +``` +``` +Signature Algorithm: ecdsa-with-SHA256 +30:45:02:21:00:84:1a:06:d4:3b:5e:9f:ec:d2:4e:87:b1:24: +4e:b5:1c:6a:2c:f2:0d:9b:5e:6b:a0:7f:11:e6:00:2f:7e:0c: +a3:02:20:4e:32:a6:02:c3:60:9d:00:92:d3:48:bd:bd:19:8a: +11:46:46:bd:41:cf:10:37:83:64:1a:e2:5e:3f:23:fd:26 +``` +_ICAC in Matter TLV Format_ + +``` +15 30 01 08 2d b4 44 85 56 41 ae df 24 02 01 37 03 27 14 01 00 00 00 ca +ca ca ca 18 26 04 ef 17 1b 27 26 05 6e b5 b9 4c 37 06 27 13 03 00 00 00 +ca ca ca ca 18 24 07 01 24 08 01 30 09 41 04 c5 d0 86 1b b8 f9 0c 40 5c +12 31 4e 4c 5e be ea 93 9f 72 77 4b cc 33 23 9e 2f 59 f6 f4 6a f8 dc 7d +46 82 a0 e3 cc c6 46 e6 df 29 ea 86 bf 56 2a e7 20 a8 98 33 7d 38 3f 32 +c0 a0 9e 41 60 19 ea 37 0a 35 01 29 01 18 24 02 60 30 04 14 53 52 d7 05 +9e 9c 15 a5 08 90 68 62 86 48 01 a2 9f 1f 41 d3 30 05 14 13 af 81 ab 37 +37 4b 2e d2 a9 64 9b 12 b7 a3 a4 28 7e 15 1d 18 30 0b 40 84 1a 06 d4 3b +5e 9f ec d2 4e 87 b1 24 4e b5 1c 6a 2c f2 0d 9b 5e 6b a0 7f 11 e6 00 2f +7e 0c a3 4e 32 a6 02 c3 60 9d 00 92 d3 48 bd bd 19 8a 11 46 46 bd 41 cf +10 37 83 64 1a e2 5e 3f 23 fd 26 18 +``` +_ICAC Printed in Matter TLV Schema Format_ + +``` +matter-certificate = { +serial-num = 2D B4 44 85 56 41 AE DF, +sig-algo = 0x01U, +issuer = [[ matter-rcac-id = 0xCACACACA00000001U ]], +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 383 +``` + +``` +not-before = 0x271B17EFU, +not-after = 0x4CB9B56EU, +subject = [[ matter-icac-id = 0xCACACACA00000003U ]], +pub-key-algo = 0x01U, +ec-curve-id = 0x01U, +ec-pub-key = 04 C5 D0 86 1B B8 F9 0C 40 5C 12 31 4E 4C 5E BE +EA 93 9F 72 77 4B CC 33 23 9E 2F 59 F6 F4 6A F8 +DC 7D 46 82 A0 E3 CC C6 46 E6 DF 29 EA 86 BF 56 +2A E7 20 A8 98 33 7D 38 3F 32 C0 A0 9E 41 60 19 +EA, +extensions = [[ +basic-constraints = { +is-ca = true +}, +key-usage = 0x60U, +subject-key-id = 53 52 D7 05 9E 9C 15 A5 08 90 68 62 86 48 01 A2 +9F 1F 41 D3, +authority-key-id = 13 AF 81 AB 37 37 4B 2E D2 A9 64 9B 12 B7 A3 A4 +28 7E 15 1D, +]], +signature = 84 1A 06 D4 3B 5E 9F EC D2 4E 87 B1 24 4E B5 1C +6A 2C F2 0D 9B 5E 6B A0 7F 11 E6 00 2F 7E 0C A3 +4E 32 A6 02 C3 60 9D 00 92 D3 48 BD BD 19 8A 11 +46 46 BD 41 CF 10 37 83 64 1A E2 5E 3F 23 FD 26 +} +``` +**6.5.15.3. Example of Node Operational Certificate (NOC)** + +The same NOC in X.509 and Matter TLV formats is presented in this section. An issuer of this NOC is +ICAC from previous section. + +_NOC with Corresponding Private Key in an X.509 PEM Format_ + +``` +-----BEGIN CERTIFICATE----- +MIIB4DCCAYagAwIBAgIIPvz/FwK5oXowCgYIKoZIzj0EAwIwIjEgMB4GCisGAQQB +gqJ8AQMMEENBQ0FDQUNBMDAwMDAwMDMwHhcNMjAxMDE1MTQyMzQzWhcNNDAxMDE1 +MTQyMzQyWjBEMSAwHgYKKwYBBAGConwBAQwQREVERURFREUwMDAxMDAwMTEgMB4G +CisGAQQBgqJ8AQUMEEZBQjAwMDAwMDAwMDAwMUQwWTATBgcqhkjOPQIBBggqhkjO +PQMBBwNCAASaKiFvs53WtvohG4NciePmr7ZsFPdYMZVPn/T3o/ARLIoNjq8pxlMp +TUju4HCKAyzKOTk8OntG8YGuoHj+rYODo4GDMIGAMAwGA1UdEwEB/wQCMAAwDgYD +VR0PAQH/BAQDAgeAMCAGA1UdJQEB/wQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAd +BgNVHQ4EFgQUn1Wia35DA+YIg+kTv5T0+14qYWEwHwYDVR0jBBgwFoAUU1LXBZ6c +FaUIkGhihkgBop8fQdMwCgYIKoZIzj0EAwIDSAAwRQIgeVXCAmMLS6TVkSUmMi/f +KPie3+WvnA5XK9ihSqq7TRICIQC4PKF8ewX7Fkt315xSlhMxa8/ReJXksqTyQEuY +``` +``` +Page 384 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +FzJxWQ== +-----END CERTIFICATE----- +``` +### -----BEGIN EC PRIVATE KEY----- + +``` +MHcCAQEEIKVls/ooqO1qdPtvD/ik00DZ4a6Y8h36HwpZpOoCGhYnoAoGCCqGSM49 +AwEHoUQDQgAEmiohb7Od1rb6IRuDXInj5q+2bBT3WDGVT5/096PwESyKDY6vKcZT +KU1I7uBwigMsyjk5PDp7RvGBrqB4/q2Dgw== +-----END EC PRIVATE KEY----- +``` +_NOC Printed in an X.509 DER Format_ + +``` +Certificate: +Data: +Version: 3 (0x2) +Serial Number: 4538782998777667962 (0x3efcff1702b9a17a) +Signature Algorithm: ecdsa-with-SHA256 +Issuer: 1.3.6.1.4.1.37244.1.3 = CACACACA00000003 +Validity +Not Before: Oct 15 14:23:43 2020 GMT +Not After : Oct 15 14:23:42 2040 GMT +Subject: 1.3.6.1.4.1.37244.1.1 = DEDEDEDE00010001, 1.3.6.1.4.1.37244.1.5 = +FAB000000000001D +Subject Public Key Info: +Public Key Algorithm: id-ecPublicKey +Public-Key: (256 bit) +pub: +04:9a:2a:21:6f:b3:9d:d6:b6:fa:21:1b:83:5c:89: +e3:e6:af:b6:6c:14:f7:58:31:95:4f:9f:f4:f7:a3: +f0:11:2c:8a:0d:8e:af:29:c6:53:29:4d:48:ee:e0: +70:8a:03:2c:ca:39:39:3c:3a:7b:46:f1:81:ae:a0: +78:fe:ad:83:83 +ASN1 OID: prime256v1 +NIST CURVE: P-256 +X509v3 extensions: +X509v3 Basic Constraints: critical +CA:FALSE +X509v3 Key Usage: critical +Digital Signature +X509v3 Extended Key Usage: critical +TLS Web Client Authentication, TLS Web Server Authentication +X509v3 Subject Key Identifier: +9F:55:A2:6B:7E:43:03:E6:08:83:E9:13:BF:94:F4:FB:5E:2A:61:61 +X509v3 Authority Key Identifier: +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 385 +``` + +``` +keyid:53:52:D7:05:9E:9C:15:A5:08:90:68:62:86:48:01:A2:9F:1F:41:D3 +``` +``` +Signature Algorithm: ecdsa-with-SHA256 +30:45:02:20:79:55:c2:02:63:0b:4b:a4:d5:91:25:26:32:2f: +df:28:f8:9e:df:e5:af:9c:0e:57:2b:d8:a1:4a:aa:bb:4d:12: +02:21:00:b8:3c:a1:7c:7b:05:fb:16:4b:77:d7:9c:52:96:13: +31:6b:cf:d1:78:95:e4:b2:a4:f2:40:4b:98:17:32:71:59 +``` +_NOC in Matter TLV Format_ + +``` +15 30 01 08 3e fc ff 17 02 b9 a1 7a 24 02 01 37 03 27 13 03 00 00 00 ca +ca ca ca 18 26 04 ef 17 1b 27 26 05 6e b5 b9 4c 37 06 27 11 01 00 01 00 +de de de de 27 15 1d 00 00 00 00 00 b0 fa 18 24 07 01 24 08 01 30 09 41 +04 9a 2a 21 6f b3 9d d6 b6 fa 21 1b 83 5c 89 e3 e6 af b6 6c 14 f7 58 31 +95 4f 9f f4 f7 a3 f0 11 2c 8a 0d 8e af 29 c6 53 29 4d 48 ee e0 70 8a 03 +2c ca 39 39 3c 3a 7b 46 f1 81 ae a0 78 fe ad 83 83 37 0a 35 01 28 01 18 +24 02 01 36 03 04 02 04 01 18 30 04 14 9f 55 a2 6b 7e 43 03 e6 08 83 e9 +13 bf 94 f4 fb 5e 2a 61 61 30 05 14 53 52 d7 05 9e 9c 15 a5 08 90 68 62 +86 48 01 a2 9f 1f 41 d3 18 30 0b 40 79 55 c2 02 63 0b 4b a4 d5 91 25 26 +32 2f df 28 f8 9e df e5 af 9c 0e 57 2b d8 a1 4a aa bb 4d 12 b8 3c a1 7c +7b 05 fb 16 4b 77 d7 9c 52 96 13 31 6b cf d1 78 95 e4 b2 a4 f2 40 4b 98 +17 32 71 59 18 +``` +_NOC Printed in Matter TLV Schema Format_ + +``` +matter-certificate = { +serial-num = 3E FC FF 17 02 B9 A1 7A, +sig-algo = 0x01U, +issuer = [[ matter-icac-id = 0xCACACACA00000003U ]], +not-before = 0x271B17EFU, +not-after = 0x4CB9B56EU, +subject = [[ matter-node-id = 0xDEDEDEDE00010001U, +matter-fabric-id = 0xFAB000000000001DU ]], +pub-key-algo = 0x01U, +ec-curve-id = 0x01U, +ec-pub-key = 04 9A 2A 21 6F B3 9D D6 B6 FA 21 1B 83 5C 89 E3 +E6 AF B6 6C 14 F7 58 31 95 4F 9F F4 F7 A3 F0 11 +2C 8A 0D 8E AF 29 C6 53 29 4D 48 EE E0 70 8A 03 +2C CA 39 39 3C 3A 7B 46 F1 81 AE A0 78 FE AD 83 +83, +extensions = [[ +basic-constraints = { +is-ca = false +``` +``` +Page 386 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### }, + +``` +key-usage = 0x01U, +extended-key-usage = [ 0x02U, 0x01U ], +subject-key-id = 9F 55 A2 6B 7E 43 03 E6 08 83 E9 13 BF 94 F4 FB +5E 2A 61 61, +authority-key-id = 53 52 D7 05 9E 9C 15 A5 08 90 68 62 86 48 01 A2 +9F 1F 41 D3, +]], +signature = 79 55 C2 02 63 0B 4B A4 D5 91 25 26 32 2F DF 28 +F8 9E DF E5 AF 9C 0E 57 2B D8 A1 4A AA BB 4D 12 +B8 3C A1 7C 7B 05 FB 16 4B 77 D7 9C 52 96 13 31 +6B CF D1 78 95 E4 B2 A4 F2 40 4B 98 17 32 71 59 +} +``` +**6.6. Access Control** + +**6.6.1. Scope and Purpose** + +This section specifies the features related to controlling access to a Node’s Endpoint Clusters ("Tar­ +gets" hereafter) from other Nodes. The overall features are collectively named "Access Control" +hereafter. + +The Access Control features aim to ensure that only authorized Nodes are permitted access to given +application-layer functionality exposed by the Data Model, through the Interaction Model. Access +Control is the fundamental link between the Secure Channel and the Interaction Model. + +In order to implement a policy of Access Control, Administrators on the fabric create and maintain +a consistent distributed configuration of Access Control Lists (ACLs) across all Nodes. Each Node has +an ACL containing Access Control Entries which codify the policy. The Access Control Cluster +exposes a data model view of a Node’s ACL which enables its maintenance. In addition to the ACL, a +per-fabric Access Restriction List (ARL), which is set by the device, MAY exist. The ARL contains +Access Restriction Entries, which identify the attributes, commands and events on specific endpoint +clusters which are not accessible on a given fabric. The Access Control Cluster exposes a data model +view of a Node’s ARL, which enables its discovery. + +**6.6.2. Model** + +The Access Control system is rule-based with no implicit access permitted by default. Access to a +Node’s Targets is denied unless the Access Control system grants the required privilege level to a +given Subject to interact with given Targets on that Node. Initial Access Control privileges are boot­ +strapped during the commissioning phase, and maintained thereafter by Administrators. + +All access privileges, from the AccessControlEntryPrivilegeEnum enumeration, SHALL be granted +by Access Control. Thus, the Initiator ("Subject" hereafter) of any Interaction Model action SHALL +NOT succeed in executing a given action on a Node’s Target unless that Node’s Access Control sys­ +tem explicitly grants the required privilege to that Subject for that particular action. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 387 +``` + +The Access Control system grants privileges by checking and verifying all attempted access against +rules explicitly codified in Access Control Entries within the Node’s Access Control List and its +Access Restriction List. Additionally, Access Control implicitly grants administrative access privi­ +leges to an Administrative Subject during a Node’s commissioning phase, with the exception of +commands, attributes and events identified by the Node’s Commissioning Access Restriction List. + +Access Control Entries contain: + +- A FabricIndex scoping the entry to the Associated Fabric. +- A Privilege level granted by the entry (see AccessControlEntryPrivilegeEnum) + ◦ _View_ : reading or subscribing to data from a non-Proxy + ◦ _Proxy View_ : reading or subscribing to data from a Proxy + ◦ _Operate_ : writing operational data and invoking operational commands + ◦ _Manage_ : writing configuration data and invoking configuration commands (for example, + Binding and Group Clusters access) + ◦ _Administer_ : writing administrative data and invoking administrative commands (for exam­ + ple, Access Control and Commissioning Clusters access) +- A list of target Clusters to which the entry applies +- A list of source Subjects to which the entry applies +- An Authentication Mode that describes the type of secure channel authentication method to + which the entry’s subjects apply + +Access Restriction Entries contain: + +- A FabricIndex scoping the entry to the Associated Fabric (entries applied during commissioning + do not include a Fabric Index) +- An endpoint to which the entry applies +- A cluster to which the entry applies +- A list of restricted data model elements (attributes, commands and events) for the cluster + +**6.6.2.1. Subjects** + +The meaning of a "Subject" is primarily that of describing the source for an action, using a given +authentication method provided by the Secure Channel architecture. A subject SHALL be one of: + +- A passcode, identified by a Passcode ID, authenticated locally by a PASE session, during the com­ + missioning phase. +- Note that any Passcode ID other than 0, which is the default commissioning passcode, is + reserved for future use. +- Furthermore, ACL entries with a PASE authentication mode SHALL NOT be explicitly added to + the Access Control List, since there is an invisible implicit administrative entry (see Section + 6.6.2.9, “Bootstrapping of the Access Control Cluster”) always equivalently present on the Com­ + missionee (but not the Commissioner) during PASE sessions. + +``` +Page 388 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- A source node, authenticated by a CASE session using its Operational Certificate, during the + operational phase. The source node can be identified by its Node ID and/or by CASE Authenti­ + cated Tags. +- A destination group, identified by a destination Group ID in the message, authenticated by an + Operational Group Key from the Group Key Management Cluster, during the operational phase. + +**6.6.2.1.1. PASE and Group Subjects** + +Note that the subject is not considered to be an individual Node when the authentication is via pass­ +code or group symmetric key; in these cases, the administrative root of trust is conditional only +upon bearing the correct passcode during session establishment, or bearing the Operational Group +Key when constructing a group message. + +**6.6.2.1.2. Subjects identified by CASE Authenticated Tag** + +In contrast, a CASE Authenticated Tag (CAT) is a special subject distinguished name within the Oper­ +ational Certificate shared during CASE session establishment that functions as a group-like tag. +Such a tag can be applied to several Nodes, thereby facilitating management of Access Control +Entries that use the same set of Nodes as subjects. Because these tags are authenticated within the +CASE session context, the administrative root of trust does chain back through the individual +source Node to the Fabric’s trusted root. This makes CATs suitable for group-like use while main­ +taining secure authentication and attribution ability. + +Each CAT is 32-bit and equally divided into identifier value and its corresponding version: + +- The upper 16-bits are allocated to identifier value +- The lower 16-bits are allocated to the version number + +The identifier value uniquely identifies a CAT. + +The CAT identifier value space is allocated as described in the Table 71, “CAT Identifier Value Alloca­ +tions”. This table reserves space for the use of CAT identifiers that SHOULD NOT be used for any +other purposes other than specified. Table 71, “CAT Identifier Value Allocations” lists the allocation +rules of CAT identifiers that SHALL be used for the Joint Fabric. + +_Table 71. CAT Identifier Value Allocations_ + +``` +Range Type +0xFFFF Administrator identifier +0xFFFE Anchor identifier +0xFFFD Datastore identifier +0xFFFC Anchor and Datastore identifier +0xF000 to 0xFFFB Reserved for future use +0x0000 to 0xEFFF Generally available +``` +The CAT Identifier Space reserves the following identifiers for special use within the context of the +Joint Fabric and SHALL NOT apply to fabrics other than the Joint Fabric. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 389 +``` + +- 0xFFFF SHALL represent the Administrator CAT identifier. The Administrator CAT SHALL be + used to grant Administer privilege to a group of Administrator Nodes participating in the context + of the Joint Fabric. See Administrator CAT for more details. The version number of the Adminis­ + trator CAT SHALL be initially set to 0x0001. +- 0xFFFE SHALL represent the Anchor CAT identifier. The Anchor CAT SHALL be used to validate + a Node as a Joint Fabric Anchor. See Anchor CAT for more details. The version number of the + Anchor CAT SHALL be initially set to 0x0001. +- 0xFFFD SHALL represent the Datastore CAT identifier. The Datastore CAT SHALL be used to vali­ + date a Node as a Joint Fabric Datastore. See Datastore CAT for more details. If the Node is also a + Joint Fabric Anchor then the Anchor/Datastore CAT SHALL be used instead. The version number + of the Datastore CAT SHALL be initially set to 0x0001. +- 0xFFFC SHALL represent the Anchor/Datastore CAT that serves as a combination of the Anchor + CAT and Datastore CAT identifiers as a single identifier. The Anchor/Datastore CAT SHALL be + used to validate a Node as both a Joint Fabric Anchor and Joint Fabric Datastore. See + Anchor/Datastore CAT for more details. The version number of the Anchor/Datastore CAT + SHALL be initially set to 0x0001. + +The version number represents the current version of specific identifier value. An Administrator +MAY increment the version number on any changes in the set of Nodes sharing the given tag. Ver­ +sion number is a monotonically increasing natural number in the range of 1 to 65535. A version +number of 0 is invalid and SHALL NOT be used. On reaching the maximum value (65535), wrap- +around is not supported and the tag identifier SHOULD be retired by an Administrator since ver­ +sion increase will no longer be possible. + +When a CAT appears in the Subjects list of an Access Control Entry, it SHALL be encoded within the +CASE Authenticated Tag sub-space of Node Identifiers, with the upper 32 bits set to 0xFFFF_FFFD. +Note that this encoding cannot appear as an operational Node ID. It is merely a sub-encoding allow­ +ing the 64-bit scalars in an Access Control Entry’s Subjects list to represent both Node IDs and CATs. + +**6.6.2.1.2.1. Example CASE Authenticated Tags** + +- Joint Fabric Administrator Tag identifier 0xFFFF, Version 0x0001 + ◦ CAT value: 0xFFFF_0001 + ◦ Appears in Access Control Entry Subjects list as 0xFFFF_FFFD_FFFF_0001 + ◦ Appears in Node Operational Certificate subject under OID 1.3.6.1.4.1.37244.1.6 with value + 0xFFFF0001 + ▪ Would appear in X.509 certificate subject under OID 1.3.6.1.4.1.37244.1.6 as UTF8String + FFFF0001 for signature validation purposes. +- Tag identifier 0xAB12, Version 0x0003 + ◦ CAT value: 0xAB12_0003 + ◦ Appears in Access Control Entry Subjects list as 0xFFFF_FFFD_AB12_0003 + ◦ Appears in Node Operational Certificate subject under OID 1.3.6.1.4.1.37244.1.6 with value + 0xAB120003 + ▪ Would appear in X.509 certificate subject under OID 1.3.6.1.4.1.37244.1.6 as UTF8String + +``` +Page 390 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +AB120003 for signature validation purposes. +``` +- Tag identifier 0x071C, Version 0x1074 + ◦ CAT value: 0x071C_1074 + ◦ Appears in Access Control Entry Subjects list as 0xFFFF_FFFD_071C_1074 + ◦ Appears in Node Operational Certificate subject under OID 1.3.6.1.4.1.37244.1.6 with value + 0x071C1074 + ▪ Would appear in X.509 certificate subject under OID 1.3.6.1.4.1.37244.1.6 as UTF8String + 071C1074 for signature validation purposes. + +**6.6.2.2. Wildcards** + +The Subjects list of an Access Control Entry MAY grant a given privilege to more than one Subject, if +the Authentication Mode allows it, such as in the case of the CASE and Group Authentication Modes. +An empty Subjects list SHALL mean that every possible Subject employing the stated Authentication +Mode is granted the entry’s privilege over the Targets. + +The Targets list of an Access Control Entry MAY grant a given privilege to more than one Target. An +empty Targets list SHALL mean that every Cluster on every Endpoint exposed by the Node is acces­ +sible using the granted privilege to any matching Subject. Each Target in the Targets list SHALL +specify Cluster instances directly by Cluster ID (on any Endpoint, or limited to particular End­ +points), indirectly by Endpoint ID (all Cluster instances on that Endpoint), or indirectly by Device +Type ID (all Cluster instances on all Endpoints containing that Device Type). + +For both the Subjects list and Targets list of an Access Control Entry, empty lists permit a rudimen­ +tary form of "wildcard" behavior, which is especially useful for codifying policies providing com­ +mon view/read/discover access to a given subset of Nodes based on Authentication Mode. + +### CAUTION + +``` +Given that "wildcard" (that is, any subject/target) granting is possible with an +empty Subjects list or an empty Targets list, it follows that care must be taken by +Administrators generating and distributing Access Control Lists to ensure unin­ +tended access does not arise. It is RECOMMENDED to avoid updating Access +Control Entries in such a way as to remove Subjects or Targets one by one, +which may result in a wildcard after individual actions. Rather, entire Tar­ +gets/Subjects lists SHOULD be written atomically in a single action, to ensure a +complete final state is achieved, with either wildcard or not, and that no acci­ +dental wildcards arise. Furthermore, such ACL entries with wildcard subject +should be deployed with care as they grant the named privilege level to poten­ +tially many senders, especially when Group Authentication Mode is specified. +``` +**6.6.2.3. Subjects do not correspond to users** + +The Subjects for an Access Control Entry are logical subjects, configured through policy by an +Administrator, including possibly a Commissioner during the commissioning phase. A given imple­ +mentation of administrative logic MAY assign authentication identities to Nodes directly associated +with physical end-users (for example, a mobile device of a given end-user). However, since Nodes +are logical networking entities, the specific policy of how Node identities are mapped to physical +end-users and physical devices is implementation-specific. Therefore, the access granted by a given + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 391 +``` + +Node’s Access Control system should not be construed as having any particular meaning in regards +to physical end-users other than the fact that a given set of Administrators computed a consistent +set of Access Control Lists to effect a desired system functionality across all Nodes they administer +and end-users they represent. + +**6.6.2.4. Implementation-specific Rules** + +Since the target of a given Access Control Entry is a list of Targets, and since Targets (that is, Clusters +on Endpoints) are Interaction Model constructs, it should be assumed that access control function­ +ality as described within this model is constrained to the interaction model layer. However, con­ +straints on incoming session establishment requests MAY be affected by the Access Control system, +based on implementation-defined rules. For example, a Node MAY deny CASE session establishment +from an initiator whose identity doesn’t match any Access Control Entry. These types of rules are +implementation-specific and SHOULD be carefully considered, if applied at all. For example, due to +the richness of Access Control Entry encoding for Subjects, significant care has to be taken to avoid +incorrectly rejecting an incoming CASE session establishment that could be valid. Rejecting valid +connections could cause a Node to become unreachable. Any constraints on transport-level and net­ +work-level functionality, including but not limited to the availability of commissioning-mode con­ +nectivity, are out of Access Control scope. + +**6.6.2.5. Incoming Subject Descriptors** + +The Message Layer SHALL provide sufficient metadata (e.g. Authentication Mode, source identity) +about incoming messages to the Interaction Model protocol layer in order to properly enforce +Access Control. + +An Incoming Subject Descriptor (ISD) is a mapping from the security layer fields of an incoming +Message to a tuple of that can map unambiguously to an Access Con­ +trol Entry’s Subjects and AuthMode fields. See Section 6.6.6.1.3, “Incoming Subject Descriptor (ISD) +Structure” for further details. + +**6.6.2.6. Access Control Extensions** + +An implementation MAY use Access Control Extensions to extend the base Access Control model. +Since all extensions are installed by Administrators for a fabric, it is expected that only extensions +that would improve overall security will be applied. Since every Vendor MAY implement extensions +as they see fit, it SHOULD NOT be expected that an extension will be supported by every Node. It is +therefore RECOMMENDED that careful consideration of interoperability concerns be given when +implementing Access Control Extensions. A fabric’s Administrators MAY always read a given Node’s +Access Control Entries and Access Control Extensions pertaining to the fabric. Therefore, Adminis­ +trators MAY use extensions to record auditing metadata about Access Control Entries which are not +for operational use by the Node. + +A Node SHALL preserve every field of the installed Access Control Cluster, including extensions +when present, without internally-initiated modifications, so that they may be read-back verbatim +upon receiving an appropriate request from an Administrator. + +``` +Page 392 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**6.6.2.7. Application-level Permissions** + +The Access Control Cluster SHALL NOT be used to encode application-level permissions and config­ +urations such as smart lock PIN codes or similar user-facing security functionality. Application-level +security is best served by finer-grained capabilities described and addressed by application- +domain-specific clusters. + +**6.6.2.8. Access Restrictions** + +An Access Control Entry in the ACL describes permissions granted by the fabric Administrator. In +contrast, an Access Restriction Entry in the ARL describes restrictions imposed by the device. The +ARL restrictions override permissions granted in the ACL. + +**6.6.2.9. Bootstrapping of the Access Control Cluster** + +Updates to the Access Control List through Access Control Cluster attributes and commands SHALL +be restricted by the same Access Control mechanisms as all other clusters on the Node, and there­ +fore require a grant of Administer privilege. Administrators are able to bootstrap a Node’s Access +Control List during the commissioning phase due to the Access Control Privilege Granting algorithm +implicitly granting the Administer privilege to Administrative Subject Nodes over a PASE commis­ +sioning channel; this implicit privilege grant applies for the Commissioner to administer the Com­ +missionee, but not in the opposite direction. + +**6.6.2.10. Action attribution** + +The recording of a given Interaction Model Action’s attribution to a source entity is distinct from +the contents of an Access Control Entry. Action Attribution SHALL be recorded against the Incoming +Subject Descriptor (see Section 6.6.6.1.3, “Incoming Subject Descriptor (ISD) Structure”) rather than +against any matched Access Control Entry’s contents. + +**6.6.2.11. Restrictions on Administer Level Privilege Grant** + +Since the Administer privilege level grants wide access to a Node for a given Subject, it SHALL NOT +be valid to have an Administer privilege set on an Access Control Entry, unless the AuthMode's Auth­ +ModeCategory is "CASE". For example, an AuthModeCategory of "Group", which admits no source Node +authentication and reduced attribution ability, SHALL NOT be used to grant Administer privilege. + +**6.6.3. Access Control List Examples** + +The following Access Control Lists illustrate the flexibility of codifying access control policy using +concrete examples. + +Upon Factory Data Reset, the Access Control Cluster is empty, having an Access Control List with no +entries. + +``` +Access Control Cluster: { +ACL: [], // empty +Extension: [], // empty (omitted hereafter) +ARL: [] // empty for this example (omitted hereafter) +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 393 +``` + +### } + +However, the Access Control Privilege Granting algorithm behaves as if, over a PASE commission­ +ing channel during the commissioning phase, the following implicit Access Control Entry were +present on the Commissionee (but not the Commissioner) to grant Administer privilege for the +entire Node. + +``` +Access Control Cluster: { +ACL: [ +0: { // implicit entry only; does not explicitly exist! +FabricIndex: 0, // not fabric-specific +Privilege: Administer, +AuthMode: PASE, +Subjects: [], +Targets: [] // entire node +} +] +} +``` +During the commissioning phase, the AddNOC command automatically creates an Access Control +Entry granting Administer privilege for the appropriate CaseAdminSubject. + +In the scenario the node is being commissioned onto a separately-administered fabric, Administer +privilege is granted for the entire Node, using the appropriate CASE authenticated Subject (in this +case, Node ID 0xAAAA_AAAA_AAAA_AAAA) on the appropriate Fabric (in this case, Fabric +0xFAB0_0000_0000_001D as Fabric index 1). + +``` +Access Control Cluster: { +ACL: [ +0: { +FabricIndex: 1, +Privilege: Administer, +AuthMode: CASE, +Subjects: [ 0xAAAA_AAAA_AAAA_AAAA ], +Targets: [] +} +] +} +``` +In the scenario the node is being commissioned onto the Joint Fabric the Administer privilege +SHALL be granted for all Nodes with the Administrator CAT as the CaseAdminSubject (in this case, +0xFFFF_FFFD_FFFF_0001) on the appropriate Fabric (in this case, Fabric 0xFAB0_0000_0000_001D +as Fabric index 1). + +``` +Page 394 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Access Control Cluster: { +ACL: [ +0: { +FabricIndex: 1, +Privilege: Administer, +AuthMode: CASE, +Subjects: [ 0xFFFF_FFFD_FFFF_0001 ], +Targets: [] +} +] +} +``` +An Administrator adds an Access Control Entry which grants View privilege, for the entire Node, to +all CASE authenticated Nodes. + +``` +Access Control Cluster: { +ACL: [ +... +1: { +FabricIndex: 1, +Privilege: View, +AuthMode: CASE, +Subjects: [], +Targets: [] +} +] +} +``` +An Administrator adds an Access Control Entry which grants Manage privilege, for endpoints 1 and 3, +to any Nodes which can authenticate as members of Group 1. + +``` +Access Control Cluster: { +ACL: [ +... +2: { +FabricIndex: 1, +Privilege: Manage, +AuthMode: Group, +Subjects: [ 0x0000_0000_0000_0001 ], +Targets: [ { Endpoint: 1 }, { Endpoint: 3 } ] +} +] +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 395 +``` + +### } + +An Administrator revises this Access Control Entry to grant the same privilege, for only the pump +configuration and control cluster (0x0202) on endpoint 3, and for any door lock cluster (0x0101) on +the entire Node, to the same Nodes. + +``` +Access Control Cluster: { +ACL: [ +... +2: { +FabricIndex: 1, +Privilege: Manage, +AuthMode: Group, +Subjects: [ 0x0000_0000_0000_0001 ], +Targets: [ { Endpoint: 1 }, { Endpoint: 3, Cluster: 0x0000_0202 }, { Cluster: +0x0000_0101 } ] +} +] +} +``` +An Administrator adds an Access Control Entry which grants Operate privilege, for all endpoints +containing the extended color light device (0x010D) on the entire Node, to CASE authenticated +Nodes 0x1111_1111_1111_1111 and 0x2222_2222_2222_2222. + +``` +Access Control Cluster: { +ACL: [ +... +3: { +FabricIndex: 1, +Privilege: Operate, +AuthMode: CASE, +Subjects: [ 0x1111_1111_1111_1111, 0x2222_2222_2222_2222 ], +Targets: [ { DeviceType: 0x0000_010D } ] +} +] +} +``` +A Commissioner adds four more Nodes into an existing fabric. These new Nodes have Node IDs +0x3333_3333_3333_3333, 0x4444_4444_4444_4444, 0x5555_5555_5555_5555 and +0x6666_6666_6666_6666 respectively. The Fabric Administration policy requires associating these +four nodes and an existing node (0x2222_2222_2222_2222) into a CAT group. + +To achieve this, an Administrator will issue NOCs to all five nodes in this CAT group with a CAT +value of 0xABCD_0001, which is tag identifier value 0xABCD and version 1, and encoded as subject + +``` +Page 396 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +value 0xFFFF_FFFD_ABCD_0001. To distribute these CATs, an Administrator obtains NOCs from its +certificate authority with the requisite subjects including the desired CAT. They are either initially +provisioned with the AddNOC command during initial commissioning (for the new Nodes) or updated +with UpdateNOC (for existing Nodes). + +Then the Administrator grants permissions to the five nodes by updating the ACL of all relevant tar­ +gets by adding an entry with subject of CAT (0xFFFF_FFFD_ABCD_0001). The Administrator may +also remove entries where Node 0x2222_2222_2222_2222 appears as an explicit Subject if presenta­ +tion of the CAT identifier value 0xABCD and version value 0x0001 confers an equivalent privilege. +Note that any Node with CAT identifier value of 0xABCD and version value 0x0001 or higher in +their NOC will have this privilege. + +``` +Access Control Cluster: { +ACL: [ +... +3: { +FabricIndex: 1, +Privilege: Operate, +AuthMode: CASE, +Subjects: [ 0x1111_1111_1111_1111, 0xFFFF_FFFD_ABCD_0001], +Targets: [ { DeviceType: 0x0000_010D } ] +} +] +} +``` +An Administrator wants to remove the Node with Node ID 0x3333_3333_3333_3333 from the CAT +group defined by CAT identifier value of 0xABCD, as installed in the previous example. + +The Administrator could follow the steps outlined below: + +1. Administrator will ensure that the removed node having Node ID 0x3333_3333_3333_3333 will + not receive a new NOC with an CAT identifier value of 0xABCD. Note that the node removed + from the group will continue to hold existing NOC (with CAT identifier of 0xABCD and version + 0x0001). +2. An Administrator updates NOCs with CAT identifier value of 0xABCD and version 0x0002 + (encoded as subject 0xFFFF_FFFD_ABCD_0002) in all remaining currently reachable Nodes + within the CAT group to ensure they continue to have same privilege as before. In this example, + Nodes having Node IDs 0x2222_2222_2222_2222, 0x4444_4444_4444_4444 and + 0x5555_5555_5555_5555 are currently reachable. +3. Node with Node ID 0x6666_6666_6666_6666 from this CAT group is a valid member but was not + reachable by an Administrator at the time of this change. This Node will continue to hold exist­ + ing NOC with CAT of 0xABCD_0001. +4. After updating NOCs of all reachable Nodes, the Administrator SHOULD revise the Access Con­ + trol Entry of all reachable nodes who have the previous CAT (encoded as subject 0xFFF­ + F_FFFD_ABCD_0001) in an ACL entry, to remove privilege from the Node no longer in the group­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 397 +``` + +``` +ing (i.e. those with version 0x0001) by increasing trusted version value to be higher than +0x0001. The Administrator decides to increment version value by one to set the new version +value to be 0x0002. +``` +5. Once ACL changes are propagated to all controlled nodes, they will no longer allow access privi­ + leges to any Node with older version (i.e. value less than 0x0002) of CAT identifier value + 0xABCD. Hence, the node removed from the group, having Node ID 0x3333_3333_3333_3333 and + CAT with identifier 0xABCD and version of 0x0001, can no longer access any of the controlled + nodes whose ACL entries were updated to have a subject of 0xFFFF_FFFD_ABCD_0002 (CAT + identifier value 0xABCD, version 0x0002). +6. Node having Node ID of 0x6666_6666_6666_6666 will not be able to access any Nodes by relying + on CAT, since it does not have an NOC with latest CAT (with version 0x0002). However, it can still + access Nodes that list it as a subject Node ID explicitly. When an Administrator eventually estab­ + lishes connection to this Node, the Administrator SHOULD update the NOC to the latest version, + with CAT set to 0xABCD_0002. After having its NOC updated to have the newest version of the + CAT, the Node with Node ID 0x6666_6666_6666_6666 will again have access to Nodes that list + subject 0xFFFF_FFFD_ABCD_0002 (CAT identifier value 0xABCD, version 0x0002), with no fur­ + ther updates to ACL entries of existing Nodes. +7. Any controlled Node which previously held an ACL Entry with prior version of the updated CAT + (subject 0xFFFF_FFFD_ABCD_0001) but was not reachable by an Administrator at the time of + update, will continue to hold the previous Access Control Entry with a subject allowing CAT with + identifier of 0xABCD and version 0x0001 or higher. Thus, these Nodes will grant privileges to + any Node from the original CAT group (including Node ID 0x3333_3333_3333_3333). When an + Administrator eventually establishes connection to this Node with older ACL entry, the Adminis­ + trator SHOULD update it with the latest value, so that Node ID 0x3333_3333_3333_3333 no + longer has privileges. + +Note that in the above example, the CAT identifier value remained the same (0xABCD) in NOCs and +ACL entries throughout these steps. Only the version portion was updated to effect changes to the +meaning of the CAT. + +As can be seen in the example above, there are multiple steps involving updates to NOCs and ACL +entries to affect CAT-based grouping and aliasing policies. It is therefore possible that some Nodes +may not receive these changes immediately, due to network reachability issues, such as being pow­ +ered down for an extended period, and thus have ACL entries or NOCs that grant temporarily obso­ +lete privileges. This is true as well with direct Node ID subjects, in general. + +Administrators SHOULD aim for best-effort eventual consistency while executing the steps outlined +above. + +``` +Access Control Cluster: { +ACL: [ +... +3: { +FabricIndex: 1, +Privilege: Operate, +AuthMode: CASE, +``` +``` +Page 398 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Subjects: [ 0x1111_1111_1111_1111, 0xFFFF_FFFD_ABCD_0002], +Targets: [ { DeviceType: 0x0000_010D } ] +} +] +} +``` +**6.6.4. Access Control Cluster update side-effects** + +Updates to the Access Control Cluster SHALL take immediate effect in the Access Control system. +For example, given an Interaction Model action message containing the following actions, the +Access Control Privilege Granting algorithm would grant a privilege of None for the second action, +since the first action would take effect immediately beforehand. + +- Pre-conditions: +- Access Control List has single entry: [{Privilege: Administer, Authmode: CASE (2), Subjects: + [0x0011223344556677], Targets: []}] +- Node ID 0x0011223344556677 over CASE is allowed Administer privilege for all targets +- Incoming message Source is Node ID 0x0011223344556677 over CASE: matches Access Control + Entry subject +- Actions: + 1. Action: Write (1st path) + 1. Path: Endpoint[0]/Cluster[AccessControl]/Attribute[ACL]/ListIndex[0]/Field[Targets] + 2. Value: [{Endpoint: 2}] + ▪ Single entry updated to target only Endpoint 2 + 3. **Granted** : Administer privilege granted, due to Access Control Entry match + 2. Action: Write (2nd path) + 1. Path: Endpoint[1]/Cluster[OnOff ]/Attribute[OnTime] + 2. **Denied** : No privilege granted, because prior action **in the same message** had updated + Access Control List to only allow access to Endpoint 2, and this action targets Endpoint 1 +- Post-conditions: +- Access Control List has single entry, updated by first path of Write Action: [{Privilege: Adminis­ + ter, Authmode: CASE (2), Subjects: [0x0011223344556677], Targets: [{Endpoint: 2}]}] +- Node ID 0x0011223344556677 over CASE is allowed Administer privilege for only Endpoint 2 tar­ + get + +Note that in this example, the Node has inadvertently lost its ability to update the Access Control +Cluster by limiting its Administer privilege to Endpoint 2. + +**6.6.5. Access Control Cluster handling of Access Restrictions** + +In the example above, the ARL was empty, meaning that there were no access restrictions imposed +upon the fabric by the device. However, the following Access Control Cluster examples illustrate + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 399 +``` + +how access restrictions would impact access granted to a given client. + +Upon Factory Data Reset, the Access Control Cluster has an Access Control List with no entries, an +Access Restriction List with no entries, and a CommissioningARL set by the device which applies +during commissioning sessions. + +``` +Access Control Cluster: { +ACL: [], // empty +Extension: [], // empty (omitted hereafter) +CommissioningARL: [ +0: { +Endpoint: 1, // application endpoint 1 +Cluster: 0x0453, // application cluster 0x0453 +Restrictions: [ +0: { +Type: AttributeAccessForbidden, // access limitation for attribute +Id: 0x0000 // attribute 0x0000 +}, +1: { +Type: CommandForbidden, // command limitation +Id: NULL // all commands +}, +2: { +Type: EventForbidden, // event limitation +Id: NULL // all events +} +] +} +] +ARL: [] // empty +} +``` +Upon allocation of a new FabricIndex during commissioning (see Node Operational Credentials +Cluster AddNOC command), one or more ARL entries with the new FabricIndex MAY be added to +the ARL attribute at the time that the initial ACL entry for the new FabricIndex is added. Until Com­ +missioningComplete command is invoked in the GeneralCommissioning cluster, the Commis­ +sioningARL continues to apply. + +Example: + +``` +Access Control Cluster: { +ACL: [ +0: { +FabricIndex: 1, +``` +``` +Page 400 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Privilege: Administer, + +AuthMode: CASE, + +Subjects: [ 0xAAAA_AAAA_AAAA_AAAA ], +Targets: [] + +} + +], +Extension: [], // empty (omitted hereafter) + +CommissioningARL: [ + +0: { + +Endpoint: 1, // application endpoint 1 +Cluster: 0x0453, // application cluster 0x0453 + +Restrictions: [ + +0: { +Type: AttributeAccessForbidden, // access limitation for attribute + +Id: 0x0000 // attribute 0x0000 + +}, + +1: { +Type: CommandForbidden, // command limitation + +Id: NULL // all commands + +}, +2: { + +Type: EventForbidden, // event limitation + +Id: NULL // all events + +} +] + +} + +] +ARL: [ + +0: { + +FabricIndex: 1, + +Endpoint: 1, // application endpoint 1 +Cluster: 0x0453, // application cluster 0x0453 + +Restrictions: [ + +0: { +Type: AttributeAccessForbidden, // access limitation for attribute + +Id: 0x0000 // attribute 0x0000 + +}, + +1: { +Type: CommandForbidden, // command limitation + +Id: NULL // all commands + +}, +2: { + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 401 +``` + +``` +Type: EventForbidden, // event limitation +Id: NULL // all events +} +] +} +] +} +``` +In this example, the restrictions during commissioning, expressed by the CommissioningARL +attribute, include 3 limitations on Cluster 0x0453 of Endpoint 1: access to attribute 0x0000, all com­ +mands, all events. The restrictions for the fabric at FabricIndex 1, expressed by the ARL attribute, +include the same 3 limitations on Cluster 0x0453 of Endpoint 1. + +The CommissioningARL and ARL attributes SHALL NOT include limitations that would prevent +commissioning (see Section 9.10.4.2.1, “Managed Device Feature Usage Restrictions”). If a wildcard +restriction appears in the ARL that would restrict access in such a case, the wildcard MAY appear +but the restriction SHALL NOT take effect. + +Superimposing this ARL value upon the example earlier in this section, when an Administrator +adds, for example, an Access Control Entry which grants Operate privilege for the entire Node, to all +CASE-authenticated subjects), this grant MAY be further limited by restrictions imposed by the ARL. +In other words, even though the ACL entry grants Operate privilege to all data model elements, +attempts to read or write attribute 0x0000, or to invoke commands upon Cluster 0x0453 of End­ +point 1 would result in an error of ACCESS_RESTRICTED, since the Access Restriction List is a subse­ +quent overriding of an initial privilege granted. + +``` +Access Control Cluster: { +ACL: [ +... +1: { +FabricIndex: 1, +Privilege: View, +AuthMode: CASE, +Subjects: [], +Targets: [] +} +], +CommissioningARL [ ... ], // (omitted hereafter) +ARL: [ +0: { +FabricIndex: 1, +Endpoint: 1, // application endpoint 1 +Cluster: 0x0453, // application cluster 0x0453 +Restrictions: [ +``` +``` +Page 402 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### 0: { + +``` +Type: AttributeAccessForbidden, // access limitation for attribute +Id: 0x0000 // attribute 0x0000 +}, +1: { +Type: CommandForbidden, // command limitation +Id: NULL // all commands +}, +2: { +Type: EventForbidden, // event limitation +Id: NULL // all events +} +] +} +] +} +``` +Updates to the ARL attribute can happen at any time, for example, as a result of configuration +changes made by the user within an external management user interface, out of band of the Matter +protocol. In particular, the fabric Administrator can request that the device initiates a review of +fabric restrictions using the ReviewFabricRestrictions command on the Access Control Cluster. This +command returns a ReviewFabricRestrictionsResponse containing a Token which can be used to cor­ +relate with a FabricRestrictionReviewUpdate event, indicating completion of the fabric restriction +review. Such a review can result in an asynchronous update to the ARL attribute and an AccessRe­ +strictionEntryChanged event. + +In this example, after the fabric restriction review, the ARL value is updated: the result is a single +limitation on Cluster 0x0453 of Endpoint 1: access to command 0x0000. In other words, restrictions +on attributes and events on Cluster 0x0453 of Endpoint 1 have been removed, and all command +restrictions on the cluster except command 0x0000 have been removed. + +``` +Access Control Cluster: { +ACL: [ +... +1: { +FabricIndex: 1, +Privilege: View, +AuthMode: CASE, +Subjects: [], +Targets: [] +} +], +ARL: [ +... +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 403 +``` + +### 1: { + +``` +FabricIndex: 1, +Endpoint: 1, // application endpoint 1 +Cluster: 0x0453, // application cluster 0x0453 +Restrictions: [ +0: { +Type: CommandForbidden, // command limitation +Id: 0x0000 // command 0x0000 +} +] +} +] +} +``` +**6.6.6. Conceptual Access Control Privilege Granting Algorithm** + +This section describes an overall Conceptual Access Control Privilege Granting algorithm. Imple­ +mentations of this algorithm SHALL have an identical outcome to the output of this conceptual +algorithm described below. + +The Interaction Model protocol, through its message handling, SHALL determine the privilege level +granted per Target, on every instance where a Target is referenced for use. + +**6.6.6.1. Necessary Data Structures** + +**6.6.6.1.1. Access Control List** + +The Access Control List contains several Access Control Entries, previously described in Section +6.6.2, “Model”. + +The entry fields are: + +- Subjects List (SubjectID[] Subjects) +- Targets List (TargetStruct[] Targets) +- Authentication Mode value (AuthModeEnum AuthMode) +- Privilege value (PrivilegeEnum Privilege) + +**6.6.6.1.2. Access Restriction List** + +The Access Restriction List contains several Access Restriction Entries, previously described in Sec­ +tion 6.6.2, “Model”. + +The entry fields are: + +- Endpoint (endpoint-no Endpoint) +- Cluster (cluster-id Cluster) + +``` +Page 404 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Restrictions List (AccessRestrictionStruct[] Restrictions) + +**6.6.6.1.3. Incoming Subject Descriptor (ISD) Structure** + +Each incoming message has a unique applicable to it, whose deriva­ +tion is deterministic based on both incoming message fields and session metadata fields. For exam­ +ple, if a message arrives that matches a given CASE Session ID, then the metadata for that CASE ses­ +sion would be used. + +Computation of the ISD is described in Section 6.6.6.3, “Derivation of ISD from Incoming Message”. + +The ISD fields are as follows: + +- Commissioning Flag (bool IsCommissioning), whether the authentication is over a commission­ + ing channel for an ongoing commissioning. +- Authentication Mode (AuthModeEnum AuthMode), mapping to an authentication mode, directly com­ + parable to Access Control Entry AuthMode. +- Subjects List (list Subjects), mapping incoming message source to a type of subject, + such as a CASE session Source Node ID. +- Fabric Index (FabricIndex FabricIndex), mapping to a fabric reference. + +**6.6.6.2. Overall Algorithm** + +The algorithm takes as input: + +- the Access Control List (acl) from the Access Control Cluster +- the Privilege (request_privilege) required for the given request +- the ISD of Incoming Message (subject_desc) +- the Endpoint ID (endpoint_id) for which the querier requires a Privilege level +- the Cluster ID (cluster_id) for which the querier requires a Privilege level +- the Cluster Element (cluster_element) for which the querier requires a Privilege level +- the Request Type (request_type) for which the querier requires a Privilege level (ReadAttribute, + ReadEvent, WriteAttribute, InvokeCommand) +- the ARL attribute (arl_attr) from the Access Control Cluster +- the CommissioningARL attribute (commissioning_arl_attr) from the Access Control Cluster + +The output of the algorithm is: + +- The access control status of the request, which is one of {AccessGranted, AccessRestricted, + AccessDenied}. + +The algorithm first determines the set of privileges granted for the Action Path, which is a subset of +{View, ProxyView, Operate, Manage, Administer} as described in AccessControlEntryPrivi­ +legeEnum. If the Privilege required for the request is contained within this set, and the request is +not restricted by the Access Restriction List, then the AccessGranted status is returned. If the Privi­ +lege required for the request is contained within this set, and the request is restricted by the Access + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 405 +``` + +Restriction List, then the AccessRestricted status is returned. Otherwise, the AccessDenied status is +returned. + +The computation of the ISD is a pre-condition to the algorithm and is described in Section 6.6.6.3, +“Derivation of ISD from Incoming Message”. + +The goal is to find the complete set of privileges granted given the input. The principle of least privi­ +lege is respected by virtue of the entire Access Control List having been computed with rules such +that the least privilege is granted to all subjects. Therefore, any Access Control Entry granting the +required privilege to the subject for a given target is sufficient to determine whether access is +allowed. + +The algorithm SHALL function as follows: + +``` +def subject_matches(acl_subject, isd_subject): +# Subjects must match exactly, or both are CAT +# with matching CAT ID and acceptable CAT version +return (acl_subject == isd_subject) or +(is_cat(acl_subject) and is_cat(isd_subject) and +(get_cat_id(acl_subject) == get_cat_id(isd_subject)) and +(get_cat_version(isd_subject) >= get_cat_version(acl_subject)) +``` +``` +def add_granted_privilege(granted_privileges, privilege): +# Add the new privilege to the granted privileges set +granted_privileges.add(privilege) +# Also add any privileges subsumed by the new privilege +if (privilege == PrivilegeEnum.ProxyView): +granted_privileges.add(PrivilegeEnum.View) +elif (privilege == PrivilegeEnum.Operate): +granted_privileges.add(PrivilegeEnum.View) +elif (privilege == PrivilegeEnum.Manage): +granted_privileges.add(PrivilegeEnum.Operate) +granted_privileges.add(PrivilegeEnum.View) +elif (privilege == PrivilegeEnum.Administer): +granted_privileges.add(PrivilegeEnum.Manage) +granted_privileges.add(PrivilegeEnum.Operate) +granted_privileges.add(PrivilegeEnum.ProxyView) +granted_privileges.add(PrivilegeEnum.View) +``` +``` +def get_granted_privileges(acl, subject_desc, endpoint_id, cluster_id) -> +set[Privilege]: +# Granted privileges set is initially empty +granted_privileges = set() +``` +``` +Page 406 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +# PASE commissioning channel implicitly grants administer privilege to commissioner +if subject_desc.AuthMode == AuthModeEnum.PASE and + +subject_desc.IsCommissioneeDuringCommissioning(): +add_granted_privilege(granted_privileges, PrivilegeEnum.Administer) + +for acl_entry in acl: + +# End checking if highest privilege is granted +if PrivilegeEnum.Administer in granted_privileges: break + +# FabricIndex must match, there are no valid entries with FabricIndex == 0 +# other than the implicit PASE entry, which we will not see explicitly in the + +# access control list + +if acl_entry.FabricIndex == 0: continue + +if acl_entry.FabricIndex != subject_desc.FabricIndex: continue + +# Auth mode must match + +if acl_entry.AuthMode != subject_desc.AuthMode: continue + +# Subject must match, or be "wildcard" + +if is_empty(acl_entry.Subjects): +# Precondition: only CASE and Group auth can have empty subjects + +assert(acl_entry.AuthMode in [AuthModeEnum.CASE, AuthModeEnum.Group]) + +# Empty is wildcard, no match required + +else: +# Non-empty requires a match + +matched_subject = False + +for acl_subject in acl_entry.Subjects: +for isd_subject in subject_desc.Subjects: + +if subject_matches(acl_subject, isd_subject): + +matched_subject = True + +break +if matched_subject: break + +if not matched_subject: continue + +# Target must match, or be "wildcard" + +if is_empty(acl_entry.Targets): + +# Empty is wildcard, no match required + +else: +# Non-empty requires a match + +matched_target = False + +for target in acl_entry.Targets: +# Precondition: target cannot be empty +assert(target.Cluster != null or target.Endpoint != null or target.DeviceType + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 407 +``` + +``` +!= null) +# Precondition: target cannot specify both endpoint and device type +assert(target.Endpoint == null or target.DeviceType == null) +# Cluster must match, or be wildcard +if target.Cluster != null and target.Cluster != cluster_id: +continue +# Endpoint must match, or be wildcard +if target.Endpoint != null and target.Endpoint != endpoint_id: +continue +# Endpoint may be specified indirectly via device type +if target.DeviceType != null and not +endpoint_contains_device_type(endpoint_id, target.DeviceType): +continue +matched_target = True +break +if not matched_target: continue +``` +``` +# Extensions processing must not fail +if not extensions_are_valid(acl, acl_entry, subject_desc, endpoint_id, +cluster_id): continue +``` +``` +# All checks have passed, add privilege to granted privilege set +add_granted_privilege(granted_privileges, acl_entry.privilege) +``` +``` +# Should never grant Administer privilege to a Group. +if subject_desc.AuthMode == AuthModeEnum.Group: +assert (PrivilegeEnum.Administer not in granted_privileges) +``` +``` +return granted_privileges +``` +``` +# Note that `arl` is either the `arl_attr` or `commissioning_arl_attr`. +def is_request_restricted(arl, subject_desc, request_type, endpoint_id, cluster_id, +cluster_element): +# Handles ensuring that only endpoints and clusters for which access restrictions +are allowed +# are subject to the restriction. Only mandatory clusters on endpoints with device +type allowing +# Managed Device ACL cluster feature can be restricted. Some specific clusters and +elements can +# never be restricted. See the Managed Device feature section of the ACL cluster for +details. +if are_restrictions_disallowed(request_type, endpoint_id, cluster_id, +cluster_element): +return False +``` +Page 408 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +for arl_entry in arl: + +if not subject_desc.IsCommissioning: +if arl_entry.FabricIndex != subject_desc.FabricIndex: continue + +if arl_entry.Endpoint != endpoint_id: continue + +if arl_entry.Cluster != cluster_id: continue + +for arl_restriction in arl_entry.Restrictions: +# if the restriction is attribute access +if arl_restriction.Type == AccessRestrictionTypeEnum.AttributeAccessForbidden + +and request_type in [RequestTypeEnum.AttributeRead, RequestTypeEnum.AttributeWrite]: + +# if the attribute id is NULL (wildcard) or matches the cluster_element +if arl_restriction.ID == NULL or arl_restriction.ID == cluster_element: + +# then no granted privileges + +return True + +if arl_restriction.Type == AccessRestrictionTypeEnum.AttributeWriteForbidden and + +request_type == RequestTypeEnum.AttributeWrite: + +# if the attribute id is NULL (wildcard) or matches the cluster_element +if arl_restriction.ID == NULL or arl_restriction.ID == cluster_element: + +# then no granted privileges + +return True + +if arl_restriction.Type == AccessRestrictionTypeEnum.CommandForbidden and + +request_type == RequestTypeEnum.CommandInvoke: + +# if the command id is NULL (wildcard) or matches the cluster_element +if arl_restriction.ID == NULL or arl_restriction.ID == cluster_element: + +# then no granted privileges + +return True + +if arl_restriction.Type == AccessRestrictionTypeEnum.EventAccessForbidden and + +request_type == RequestTypeEnum.EventRead: + +# if the event id is NULL (wildcard) or matches the cluster_element +if arl_restriction.ID == NULL or arl_restriction.ID == cluster_element: + +# then no granted privileges + +return True + +return false + +def get_access_status( +acl, arl_attr, commissioning_arl_attr, +request_privilege, subject_desc, request_type, endpoint_id, cluster_id, + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 409 +``` + +``` +cluster_element) -> access_status: +granted_privileges = get_granted_privileges(acl, subject_desc, endpoint_id, +cluster_id) +``` +``` +if request_privilege in granted_privileges: +# Select the correct source of ARL depending on context. +arl = commissioning_arl_attr if subject_desc.IsCommissioning else arl_attr +if is_request_restricted(arl, subject_desc, request_type, endpoint_id, cluster_id, +cluster_element): +return AccessStatusEnum.AccessRestricted +else: +return AccessStatusEnum.AccessGranted +``` +``` +return AccessStatusEnum.AccessDenied +``` +**6.6.6.3. Derivation of ISD from Incoming Message** + +The algorithm to derive the ISD from an incoming message takes as input: + +- The incoming message (message) +- The Session ID of the incoming message (session_id) +- A conceptual Sessions Metadata database (sessions_metadata) +- The Group Key Management Cluster (group_key_management_cluster) + +The output of the algorithm is the SubjectDescriptor structure below: + +### DEFAULT_COMMISSIONING_PASSCODE = 0 + +``` +enum AuthModeEnum { +None = 0, # conceptual "no auth" value +PASE = 1, +CASE = 2, +Group = 3 +} +``` +``` +struct SubjectDescriptor { +bool IsCommissioning; +AuthModeEnum AuthMode; +list Subjects; # max 3 items +FabricIndex FabricIndex; +} +``` +The algorithm SHALL function as follows: + +``` +Page 410 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +def get_isd_from_message(message) -> SubjectDescriptor: + +isd = { + +IsCommissioning: False, +AuthMode: AuthModeEnum.None, + +Subjects: [], + +FabricIndex: 0 +} + +session_id = message.get_session_id() + +if sessions_metadata.get_auth_mode(session_id) == AuthModeEnum.PASE: + +isd.AuthMode = AuthModeEnum.PASE + +isd.IsCommissioning = True +isd.Subjects.append(DEFAULT_COMMISSIONING_PASSCODE) + +isd.FabricIndex = sessions_metadata.get_fabric_index(session_id) # may be zero + +else if sessions_metadata.get_auth_mode(session_id) == AuthModeEnum.CASE: +isd.IsCommissioning = sessions_metadata.get_fabric_index(session_id) == +sessions_metadata.get_pending_fabric_index() + +isd.AuthMode = AuthModeEnum.CASE + +isd.Subjects.append(sessions_metadata.get_src_node_id(session_id)) +# CASE session may contain CATs which also serve as subjects + +# Append all CATs if present (can be up to 3) + +if sessions_metadata.has_src_case_authenticated_tags(session_id): + +isd.Subjects.append(sessions_metadata.get_src_case_authenticated_tags(session_id)) + +isd.FabricIndex = sessions_metadata.get_fabric_index(session_id) + +assert(isd.FabricIndex != 0) # cannot be zero +else if sessions_metadata.get_auth_mode(session_id) == AuthModeEnum.Group: + +# Message is assumed to have been decrypted and matched properly prior to + +# this procedure occurring. + +group_id = message.get_dst_group_id() +group_key_id = sessions_metadata.get_group_key_id(message) + +# Group membership must be verified against Group Key Management Cluster + +if group_key_management_cluster.group_key_map_has_mapping(group_id, group_key_id): +isd.AuthMode = AuthModeEnum.Group + +isd.Subjects.append(group_id) + +isd.FabricIndex = sessions_metadata.get_fabric_index(message) + +assert(isd.FabricIndex != 0) # cannot be zero +else: + +# Do nothing on error, ISD remains unchanged + +assert(isd.IsCommissioning == False) +assert(isd.AuthMode == AuthModeEnum.None) + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 411 +``` + +``` +assert(is_empty(isd.Subjects)) +assert(isd.FabricIndex == 0) +``` +``` +return isd +``` +**6.6.7. Applying Privileges to Action Paths** + +The Data Model specifies which privilege is required for each data element, via its access qualities. + +The Interaction Model specifies how each action is processed, for both its request and its response. +This includes details on how the Interaction Model uses Access Control to determine whether to +allow the request (i.e. continue processing), or to deny the request (and whether/how that is indi­ +cated in the response). + +Determining whether to allow or deny an action for a request path entails: + +- Determining the required privilege for the action, given the action, request path and type of + access requested; +- Determining the set of granted privileges for the action, given the request path and requesting + subject; +- Checking whether the required privilege is present in the set of granted privileges: + ◦ If present, the action is allowed; + ◦ If not present, the action is denied. + +Note that the Interaction Model may allow the action for some request paths while denying it for +other request paths in the same action. Also, note that Access Control is merely one of the checks +used by the Interaction Model, and an action that is allowed by Access Control may fail for other +reasons. + +``` +Page 412 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 7. Data Model Specification** + +**7.1. Practical Information** + +**7.1.1. Revision History** + +Please note that Matter revision 1 SHALL be considered equivalent to revision 16, Subsequent +releases SHALL start at revision 17. + +``` +Revision Description +1 Equivalent to revision 16 (1st Matter release of +the Data Model) +2-11 Approved specifications, but not released for +implementation. +12-15 Released as revisions of the Dotdot Architecture +Model specification +16 Initial release of this specification +17 Added tag data type +18 Added the LocationDescriptorStruct data type +``` +**7.1.2. Scope & Purpose** + +This is part of a package of Data Model specifications that are agnostic to underlying layers (encod­ +ing, message, network, transport, etc.). Each specification below may be independently maintained. +This package, as a whole, SHALL be independently maintained as agnostic and decoupled from +lower layers. This package may be referenced by inclusion in vertical protocol stack specifications. + +``` +Data Model Defines first order elements and namespace for endpoints, clusters, +attributes, data types, etc. +``` +``` +Interaction Model Defines interactions, transactions and actions between nodes. +``` +``` +System Model Defines relationships that are managed between endpoints and clusters. +``` +``` +Cluster Library Reference library of cluster specifications. +``` +``` +Device Library Reference library of device type specifications. +``` +**7.1.3. Origin Story** + +The origin of this section is the Dotdot Architecture Model [Dotdot Architecture] and parts of Chap­ +ter 2 of the Zigbee Cluster Library specification [ZCL] that define the data model. + +The purpose of this document is to extend and better define the data model architecture, while not +breaking the certifiable cluster specifications in the Zigbee Cluster Library (currently at revision 8). +Under the Matter project, new and existing clusters and device types may take advantage of + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 413 +``` + +extended architecture elements. Ultimately, the plan is that this architecture is available and main­ +tained for all underlying certifiable protocol stacks. + +**7.1.4. Overview** + +This document defines first order elements and namespace of the data model and can also be called +the meta-model (of the data model). This document is the "read me first" specification in the data +model. This data model is ultimately implemented in the application layer of a communication +stack. + +This specification does not define how data is stored, encoded or what interactions are allowed on +the data. + +**7.1.5. Glossary** + +``` +Term Description +MS Manufacturer or Vendor Specific +N/A not applicable +desc see detailed description section +``` +**7.1.6. Conventions** + +See the Conventions section for conventions used in the Data Model specifications. + +**7.2. Data Qualities** + +Cluster specifications and device type definitions have tables that define the qualities of elements +that make up the cluster or device type. Not all elements have all qualities. For example, a com­ +mand does not have the read quality. Some elements have intrinsic qualities, that are not listed. For +example, an event always has the read quality. Qualities SHALL be defined in columns in tables that +describe data model elements. + +**7.2.1. Common Data Table Columns** + +The following columns are common across tables describing attributes, commands, events and +structs: + +**ID** + +``` +Defines an identifier for the data model element that is unique at its context. +``` +**Name** + +``` +Defines a CamelCase name of the element to be used in specification text, not the protocol. Text +usage SHALL always be followed with the element name (e.g. CurrentLevel attribute, Stopped +event, or Left field). +``` +**Field** + +``` +Same as Name. Other headers like "Field", "Bit Field", and "Command Field", are deprecated. Use +``` +``` +Page 414 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Name. +``` +**Conformance** + +``` +Defines dependencies on whether an element is optional or mandatory. +``` +**Access** + +``` +Defines how an element is accessed (e.g. read or write) and what privileges are required to +access the data. +``` +**Summary** + +``` +A short summary of the element with no normative text. +``` +**7.2.2. Description Section** + +A separate section, describing a table row element, is required to include normative text, such as +behavior associated with the element. + +**7.2.3. Other Data Table Columns** + +Other columns specific to the element: + +**Data Type** + +``` +A data field requires this column for attribute, event or command data. +``` +**Other Qualities** + +``` +This is a catchall column for uncategorized qualities. +``` +**Default** + +``` +This defines a default value for data fields. +``` +**Response** + +``` +Cluster command tables have this column. +``` +**Direction** + +``` +Cluster command tables have this column. +``` +**Priority** + +``` +Event tables have this column. +``` +**Value** + +``` +Enumerations use this column instead of the ID column. +``` +**7.3. Conformance** + +A Conformance column defines optionality and dependency for any data model element or set of +elements. This column is valid for attributes, commands, events, enumerations, and fields of com­ +mands, events or structures. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 415 +``` + +``` +Conformance Column Name Summary +M Mandatory This is part of the base manda­ +tory feature set and is manda­ +tory for current revision. +O Optional This is a purely optional ele­ +ment with no dependencies, +except the M set. +P Provisional See Provisional below. +D Deprecated This is a deprecated item that +MAY occur in legacy implemen­ +tations, but not in the current +revision. +X Disallowed This is disallowed for the clus­ +ter derivation. +AB Mandatory This SHALL be supported if AB +is true. AB is a boolean expres­ +sion +[ AB ] Optional This MAY be supported only if +AB is true. Brackets also act as +parentheses. +EF Operand True if EF feature or element is +supported. +EF == v Equal True if EF is equal to the fixed +and non-changing value v. +EF != v UnEqual True if EF does not equal the +non-changing value v. +AB | CD Or True if either AB or CD is true. +AB ^ CD Xor True if only one of AB or CD is +true, not both. +AB & CD And True if both AB and CD are true. +! AB Exclusivity True if AB is false. +( AB & CD ) Parentheses Parentheses can be put around +any conformance expression to +combine. +C1 , C2 ... Otherwise A conformance that is a list of +boolean expressions, processed +left to right. +C. an Choice Exclusive choices between a +number of elements with the +same conformance +``` +Page 416 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**7.3.1. Operands in Conformance** + +Supported operands in a conformance expression are: + +- feature code +- element in the same table (e.g. attribute, field or value) + +**7.3.2. Feature Code in Conformance** + +A feature code evaluates to TRUE, if the feature is supported. + +**7.3.3. Element in Conformance** + +An element name, by itself, SHALL evaluate to TRUE if the element exists. Only an attribute with +the Fixed quality SHALL support evaluation as a value. + +**7.3.4. Optional Conformance** + +Optionality with "[]" SHALL be defined for an entire expression and not for parts of an expression. +Individual conformance list entries MAY define optionality with "[]", but not the entire list. + +For example: The expression "[AA] & BB" is illegal, however, "[AA & BB]" or "AA & BB" is legal. + +For example: The expression "AA | [BB]" is illegal, however, "[AA | BB]" or "AA, [BB]" is legal. + +The tag "O" SHALL define the element as optional for the revision. "O" SHALL only be used by itself, +without operators, to mean optional without dependencies, or SHALL be used in a conformance list +ending in ", O", to mean otherwise optional. + +**7.3.5. Provisional Conformance** + +The tag "P" defines the element as provisional. "P" may be used in a list, where the intended confor­ +mance or list follows the "P". If the intended conformance has not been determined, then nothing +appears after the "P". + +It is recommended that the intended future conformance be noted, so that when the provisional +marking is removed, the intended conformance becomes the current conformance. + +For example: "P, M" means provisional, but mandatory, when not provisional in the future. + +For example: "P, [AA & BB]" means provisional for now, but optional if AA & BB are true, when not +provisional in the future. + +For example: "[AA], P" means optional for AA and provisional otherwise, where the future confor­ +mance is unknown at this time. + +Each provisional element SHALL be listed in a higher level specification, that includes the data +model, and data model derived specifications that use this notation. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 417 +``` + +**7.3.6. Mandatory Conformance** + +The tag "M" SHALL define the element as mandatory. "M" SHALL only be used by itself, without +operators, to mean mandatory without dependencies, or SHALL be used in a conformance list end­ +ing in ", M", to mean otherwise mandatory. + +**7.3.7. Disallowed Conformance** + +The tag "X" is used when a derived cluster removes support for some elements. The tag "X" SHALL +define the element as disallowed for the revision of the derivation. "X" SHALL only be used by itself, +without operators. + +**7.3.8. Deprecated Conformance** + +The tag "D" SHALL define the element as disallowed for the revision. Previous revisions MAY sup­ +port this element and conformance is defined in such previous revisions. "D" SHALL only be used +by itself, without operators, to mean disallowed for the current revision, or SHALL be used in a con­ +formance list ending in ", D", to mean that now it is still allowed (based on the conformance preced­ +ing the ", D"), but it is planned to be deprecated in the future after some grace period. + +**7.3.9. Exclusivity Conformance** + +Exclusivity occurs when the entire expression only excludes. + +It is recommended to not use exclusive conformance. Inclusive conformance is recommended. + +For example: Excluding an element with "!Matter" means that it is mandatory otherwise. Better to +use inclusive conformance with (e.g. "Zigbee"). For example: Excluding an element with "[!Matter]" +means that it is optional otherwise. Better to use inclusive conformance with (e.g. "[Zigbee]"). + +**7.3.10. Otherwise Conformance** + +Otherwise conformance is a list evaluated from top to bottom (see Quality Conformance), and left to +right, where an expression is mutually exclusive to the previous expressions (above and to the left). +It is a shorthand that allows defining conformance which depends on the previously evaluated true +expression. + +Some examples: + +- "AB, O" means mandatory for AB and optional otherwise. +- "AB, [CD]" means mandatory for AB, optional if CD is true and AB is false, otherwise not allowed. +- "!AB, O" means mandatory if AB is false, otherwise optional (if AB is true). +- "[AB], M" is the equivalent to "!AB, O", and a clearer way to define the conformance. +- "[AA], [BB], [CC]" is the equivalent to "[AA | BB | CC]". + +**7.3.11. Quality Conformance** + +To support differing quality conformance for an element, the element row is duplicated with the + +``` +Page 418 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +qualities that differ and the conformance for those qualities. Duplicating the rows requires top to +bottom evaluation, similar to left to right evaluation for Otherwise Conformance. However, if 2 +adjacent rows evaluate to the same conformance (e.g. "AB, O" and "O" when AB is false), then the +choice of qualities is optional, if the row element is implemented. + +For the example below, the MinLevel element is mandatory for LT with the minimum of 1 (not +zero), mandatory for AB with the minimum of 0 (zero), otherwise the element is optional with a +minimum of 0 (zero). + +``` +ID Name Type Constraint Quality Access Default Confor­ +mance +43 MinLevel uint8 1 to 100 F R V 1 LT +43 MinLevel uint8 0 to 100 F R V 0 AB, O +``` +For the example below, the MaxLevel element is fixed, read only and mandatory for LT, writeable +and mandatory for AB, otherwise the element is optional and access may be read only or writable. + +``` +ID Name Type Constraint Quality Access Default Confor­ +mance +44 MaxLevel uint8 1 to 100 F R V 100 LT +44 MaxLevel uint8 0 to 100 RW VM 100 AB, O +44 MaxLevel uint8 0 to 100 F R V 100 O +``` +**7.3.12. Expressions and Optionality** + +A conformance expression supports conformance tags as operands. A conformance tag for a cluster +MAY be the name of a cluster feature (see FeatureMap). A conformance tag for a cluster MAY be the +name of an element in the Name column of the same table. A conformance tag for a device type def­ +inition MAY also include a condition of the node. + +Expressions SHALL represent a dependency with boolean logic using: + +- the NOT operator such as "!AA" +- the OR operator such as “AA | BB” +- the AND operator such as “AA & BB” +- the XOR (exclusive or) operator such as "AA ^ BB" +- the equal operator such as "AA==10" +- the not equal operator such as "AA!=10" + +Equality operators require that a value can be resolved for the left operand. If the left operand is +not supported, the default is the value. "null" is a valid value for the equality operator. + +Simple dependencies MAY also be defined in conformance. If a Max attribute has a dependency on +a Min attribute, then the conformance for Max is "Min". Exclusive logic also applies. For example, if +the Absolute attribute is mutually exclusive to the Percentage attribute, and one of the two must be + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 419 +``` + +supported, then conformance for Absolute would be "!Percentage", and conformance for Percent­ +age would be "!Absolute". + +Unless overridden with parentheses, the order of operations is: + +- NOT operator "!" +- AND operator "&", OR operator "|", XOR operator "^" +- equal "==", not equal "!=" + +If an expression is false, there SHALL be no assumption of general optionality. If the conformance +expression evaluates to false but optional, the expression is false. + +Some examples of conformance definitions: + +- "[AB]" means the element is not allowed, if AB evaluates to false. +- "[AA & BB]" means optional if AA and BB are both true, but excluded (and not optional) other­ + wise. +- "[!AA & BB]" means only optional if AA is false and BB is true. + +**7.3.13. Choice Conformance** + +Choice conformance defines requirements for implementing a set of elements at the same level. +This set of elements is called the choice set. + +Choice parameters determine the requirements for a choice set and are added to a conformance +expression following a period, for example _C.an+_. + +_C_ is any logical optional _[AB]_ conformance expression or optional conformance list, including "O" +(optional), but not "M", "X", "D", or "P". If _C_ is a conformance list, then the list SHALL be surrounded +by parentheses. A conformance list may also include optional choice expressions among others in +the list that do not support a choice. + +It is invalid to use mandatory conformance for choice such as "M.a", "AB.a+" or "!AB.a-". This gives +the reader the false impression that the individual element is mandatory. + +The choice parameters are _a_ , _n_ , "+" (plus sign) and "-" (minus sign): + +- _a_ is a lower case letter identifying 2 or more elements in the choice set, that SHALL be at the + same scope (in the same table). +- _n_ determines the number from the choice set that SHALL be supported after evaluation of the + conformance _C_ and subject to the conditions described below. _n_ SHALL only be present as a suf­ + fix to a choice set. +- _+_ and _-_ serve to limit the number of elements that may be included from the choice set in an + implementation and SHALL only be present as a suffix to _n_ or to the choice set if _n_ is omitted. + These choice parameters SHALL NOT appear together in the same conformance designation. + +The _n_ , _+_ , and _-_ choice parameters, if present, are interpreted as follows: + +``` +Page 420 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- If _n_ is omitted, then _n_ is considered to be one. +- If _n_ appears without a plus ("+") or minus ("-") sign choice parameter, _n_ represents the exact + number of elements from the choice set that SHALL be included in an implementation. _n_ SHALL + be between 1 and the number of elements in the choice set minus 1. +- If _n_ appears with a plus ("+") sign choice parameter, _n_ represents that at least _n_ elements of the + choice set SHALL be included in an implementation. _n_ SHALL be between 1 and the number of + elements in the choice set minus 1. +- If _n_ appears with a minus ("-") sign choice parameter, _n_ represents that at most _n_ elements of the + choice set SHALL be included in an implementation. _n_ SHALL be between 1 and the number of + elements in the choice set minus 1. +- _n_ can appear as a range, e.g. 2-4, without a trailing plus ("+") or minus ("-") sign, to indicate that + the number of elements included in an implementation SHALL be within the indicated range + inclusive. The values in the range SHALL be between 1 and the number of elements in the + choice set minus 1. If a range is used, trailing choice parameters plus ("+") and minus ("-") + SHALL NOT be used. + +When choice conformance notation is used, each element in the choice set SHALL have identical +choice parameters. + +Invalid example: It is illegal to use "O.a" for one element and "O.a2" for another. + +Choice sets SHALL NOT be shared between tables within the same device type or cluster specifica­ +tion. For example, if choice set a is used in the Attributes table and a second choice set is used in +another table within the cluster specification, the second set must use a different choice set identi­ +fier, such as b. + +Invalid example: It is illegal to have one attribute marked as O.a in the attributes table and one +command marked as O.a in the commands table. + +Valid examples: + +- "O.a" means exactly one of the "a" elements SHALL be supported. +- "O.a2" means exactly two of the "a" elements SHALL be supported. +- "O.a2+" means at least two of the "a" elements SHALL be supported. +- "O.a+" means at least one of the "a" elements SHALL be supported. +- "O.a2-" means at most two of the "a" elements SHALL be supported. +- "O.a-" means at most one of the "a" elements SHALL be supported. +- "O.a2-4" means 2, 3 or 4 of the "a" elements SHALL be supported. + +Although individual element conformance such as "O.a", "O.a+", "[AB].a+" or "[AB].a2-4" allows an +individual element to be optional, the restrictions on the choice set defined by the choice set para­ +meters must be satisfied once the conformance expression is evaluated and an implementation +SHALL support a number of elements as allowed by the choice set parameters. This may be a spe­ +cific number of elements, or one of a range of possible numbers of elements, depending on the +choice set parameters. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 421 +``` + +For example: The following is valid, because the _n_ value of 1 or more is always supported. + +If AB is true and CD is false then AbsoluteValue must be supported and optionally PercentValue. If +AB is false and CD is true then PercentValue must be supported and optionally AbsoluteValue. If AB +is true and CD is true then both elements must be supported. If AB is false and CD is false then +either one or both elements must be supported. + +``` +ID Name Type Constraint Default Conformance +43 AbsoluteValue uint16 0 to 5000 0 AB, O.a1+ +44 PercentValue uint8 0 to 100 0 CD, O.a1+ +``` +Different expressions for _C_ are allowed, which may limit the choices, based on conformance, to +greater than zero, but less than _n_. In such cases, consideration is needed to define the choices and +conformance so that the _n_ value is satisfied in every valid combination. + +For example: The following is invalid if conformance allows AB to be false and CD to be true, +because the _n_ value of 2 is not satisfied. + +``` +ID Name Type Constraint Default Conformance +43 AbsoluteCm uint16 0 to 5000 0 [AB & CM].a2 +44 AbsoluteIn uint16 0 to 2000 0 [AB & IN].a2 +45 Percent uint8 0 to 100 0 [CD].a2 +``` +**7.3.14. Blank Conformance** + +If an element does not have a designated conformance (the column is blank or omitted), then it +SHALL inherit conformance from the next highest element in the model hierarchy. For example: A +data field in a struct attribute inherits its conformance from the attribute. + +**7.3.15. Feature Conformance** + +The above examples use (all capitalized) cluster feature codes in conformance expressions. + +If a feature table has no conformance column then each feature is considered to be optional for +that revision and therefore either true (feature supported) or false (feature unsupported). + +If a feature table has a Conformance column then these are the allowed conformance: + +``` +Conformance Feature Meaning +M true This means the feature is now +mandatory, and the confor­ +mance expression is true, and +the feature supported (true). +``` +``` +Page 422 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Conformance Feature Meaning +O implementation This is the default conformance +(if blank), which means the fea­ +ture support is indicated by the +implementation (true or false). +D false The conformance expression is +false, and the feature is unsup­ +ported (false). A legacy imple­ +mentation may still support the +feature with a true value. +X false This is used in a device type +that overrides cluster specifica­ +tion conformance, which means +the conformance expression is +false, and the feature is unsup­ +ported (false). +P false This means the conformance +expression is false, and the fea­ +ture is provisional and unsup­ +ported. +false mandatory expression false Conformance expressions are +used to define more complex +feature dependencies. A list of +expressions evaluates to a sin­ +gle expression. Choice options +only support optional expres­ +sions. +``` +``` +false optional expression false +``` +``` +true mandatory expression true +``` +``` +true optional expression implementation +``` +- If the feature indicator (bit) is unsupported, then the feature indicator SHALL be false and the + feature SHALL be unsupported (false). +- Otherwise, if the conformance expression evaluates to false, then the feature indicator SHALL + be false and the feature SHALL be unsupported (false). +- Otherwise, if the conformance expression evaluates to mandatory, then the feature indicator + and feature support SHALL be the value of the conformance expression. +- Otherwise: + ◦ the feature support (true or false) SHALL be the value or the feature indicator (bit) as imple­ + mented. + ◦ If the conformance expression evaluates to a choice conformance, then the indicators for + the choice set SHALL also conform to the choice parameters. + +**7.4. Element** + +An element of the data model is a data construct that supports an instance of data. Listed below are + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 423 +``` + +the elements of the data model. + +**First order elements** + +``` +fabric, node, endpoint, cluster +``` +**Cluster first order elements** + +``` +command, event, attribute +``` +**Nested elements** + +``` +command field, event field, struct field +``` +**Dynamic element** + +``` +list entry +``` +**Semantic elements** + +``` +device type, data type +``` +**Attribute data** + +``` +elements (above) that are part of an attribute +``` +**Data field** + +``` +attribute, field element, or list entry (see Data Field) +``` +**7.4.1. Encoded Element Processing** + +When parsing or processing encoded payloads of elements as represented by an encoding layer, +such as TLV format, the following general rules apply: + +- Unknown elements SHALL be ignored and skipped. This provides forward compatibility with + future elements. +- Elements SHALL be present when conveyed according to the element’s conformance. +- Elements that are present and conformant SHALL be processed. + +**7.5. Fabric** + +A fabric is a set of nodes that interact by accessing data model elements as defined in the Interac­ +tion Model. A fabric is a security domain that allows a set of nodes to be identified and communi­ +cate within the context of the domain. A node is considered to be 'on' a fabric, when it can be identi­ +fied and interact in the context of that fabric. An interaction is considered to occur 'on' a fabric, +when the interaction occurs in the context of that fabric (see Accessing Fabric). Each interaction +occurs either on a single fabric, or without a fabric context (see Accessing Fabric). + +A node MAY be identified and interact on one or more fabrics. + +How a fabric is established and how a node comes to be on a fabric is not defined here and left to +the lower layers. + +``` +Page 424 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.5.1. Accessing Fabric** + +If an interaction is associated with a particular fabric, that fabric is called the "accessing fabric". + +If the interaction is not associated with a fabric, the accessing fabric does not exist. In this case any +comparison of the accessing fabric to any existing fabric SHALL consider them not equal. + +**7.5.2. Fabric-Index** + +Each fabric supported on a node is referenced by fabric-index that is unique on the node. This fab­ +ric-index enables the look-up of the full fabric information from the fabric-index. A fabric-index of +0 (zero) or null SHALL indicate that there is no fabric associated with the context in which the fab­ +ric-index is being used. If fabric-index is used in a context that is exclusively associated with a fab­ +ric, such as fabric-scoped data model elements, then the fabric-index values SHALL NOT include 0 +(zero) or null. + +The fabric-index corresponding to the accessing fabric is called the "accessing fabric-index". If the +accessing fabric does not exist, the accessing fabric-index SHALL indicate no fabric with a fabric- +index of 0. + +**7.5.3. Fabric-Scoped Data** + +Most cluster data instances are accessible regardless of the accessing fabric. However, data that is +exclusively associated with a particular fabric SHALL be defined as being fabric-scoped. Fabric- +scoped data SHALL be defined with the fabric-scoped quality. + +The fabric associated with fabric-scoped data is called the "associated fabric". + +Fabric-scoped data allows multiple accessing fabrics to manipulate a list of data items without +interfering with each other. See Fabric Filtered List. + +Fabric-scoped data SHALL be limited to the following: + +- list of fabric-scoped structs, which MAY include fabric-sensitive fields +- fabric-sensitive event + +A fabric-scoped data instance is always a composite struct-like data instance, with multiple fields. + +Fabric-scoped data SHALL always include the FabricIndex field to indicate the associated fabric. +The FabricIndex field for fabric-scoped data SHALL NOT be 0 or null. + +Any interaction, including cluster commands, SHALL NOT cause modification of fabric-scoped data, +directly or indirectly, if the interaction has an accessing fabric different than the associated fabric +for the data, except in the case of a cluster command that explicitly defines an exception to this +rule. + +Data fields in a fabric-scoped struct MAY also have the fabric-sensitive quality. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 425 +``` + +**7.5.4. Fabric-Scoped IDs** + +Some data types are fabric-scoped IDs, including, but not limited to, node ID and group ID. + +A fabric-scoped ID MAY require the presence of a fabric-index data type field within the same nest­ +ing scope to indicate the fabric associated with the ID in these cases: + +- If the fabric-scoped ID is not part of fabric-scoped data. +- If the fabric-scoped ID is part of fabric-scoped data with an associated fabric that is not the fab­ + ric associated with the ID. + +Fabric-scoped IDs SHALL only be indicated in these elements: + +- structs +- events +- commands + +Where necessary, specification text SHOULD define the data to which the fabric-index applies. + +**7.6. Access** + +Data model elements have access qualities. Some elements have intrinsic access or access limita­ +tions. For example: Cluster commands or command fields are not writable. + +An Access column defines access to a data model element or set of elements. This column is valid +for attributes, commands, events, and nested attribute data fields. + +``` +Access Column Description +R Read Access +W Write Access +R[W] Read Access and optionally Write Access +R*W Deprecated: use R[W] +Privileges - separate with space +V Read Access or Invoke Access requires View +privilege +O Read Access, Write Access, or Invoke Access +requires Operate privilege +M Read Access, Write Access, or Invoke Access +requires Manage privilege +A Read Access, Write Access, or Invoke Access +requires Administer privilege +Fabric - separate with space +F Fabric-Scoped Quality +``` +``` +Page 426 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Access Column Description +S Fabric-Sensitive Quality +Timed - separate with space +T Write Access or Invoke Access with timed inter­ +action only +``` +Attributes, commands, and events SHALL define their access, and SHALL include privileges in their +access definition. For example: An attribute defines whether it is readable or writable, and what +privileges are required to do so. + +Attributes, commands, and events that do not define any privileges as access qualities SHALL be +deemed to have the following: + +- View privilege required for Read access, +- Operate privilege required for Write access, +- Operate privilege required for Invoke access for request commands. +- No privileges defined for response commands. + +For example: An event with implicit read access or explicit 'R' access defaults to access 'R V'. An +attribute with access 'RW' defaults to access 'RW VO'. A request command with implicit invoke +access defaults to privilege 'O'. + +Nested elements MAY define their access, but SHALL NOT include privileges in their access defini­ +tion. Nested elements SHALL inherit their privileges from the next highest element in the model +hierarchy. Nested elements that do not define their access SHALL inherit their access from the next +highest element in the model hierarchy. For example: A data field in a struct attribute inherits its +access qualities from attribute. + +Elements SHALL only include the lowest required privilege for a type of access. + +That means: + +- An event SHALL define the single privilege required for Read access. +- A command SHALL define the single privilege required for Invoke access. +- A readable attribute SHALL define the single privilege required for Read access. +- A writable (but not readable) attribute SHALL define the single privilege (that is not View or + ProxyView) required for Write access. +- A readable and writable attribute MAY define a single privilege (that is not View or ProxyView) + required for both Read and Write access. +- A readable and writable attribute MAY define the View or ProxyView privilege as required for + Read access and one other privilege (that is not View or ProxyView) as required for Write + access. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 427 +``` + +**7.6.1. Read Access** + +Read access means that a request for data values associated with an element SHALL be supported. +This quality SHALL only be defined for cluster event and attribute data definitions. This quality +SHALL NOT be defined for cluster command definitions. + +This quality is implicitly defined for cluster events and does not need to be stipulated explicitly. + +**7.6.2. Write Access** + +Write access means that a request to modify attribute data values SHALL be supported. This quality +SHALL only be defined for cluster attribute data definitions. This quality SHALL NOT be defined for +cluster event and command definitions. + +A cluster specification SHALL define the conditions when write access attribute data is not +writable, and SHALL define normative or recommended behavior to follow when this occurs. + +An implementation that does not support write access for a field with optional write access SHALL +have this declared in its product Declaration of Conformity. + +**7.6.3. Invoke Access** + +Invoke access means that a request to execute a command SHALL be supported. This quality SHALL +only be defined for cluster command definitions, by defining an appropriate privilege level for the +command. This quality SHALL NOT be defined for cluster event and attribute data definitions. + +**7.6.4. Fabric-Scoped Quality** + +This defines fabric-scoped data that is scoped to an associated fabric. + +This quality acts as an additional constraint over those imposed by the existing Read and Write +qualities, namely: + +- Fabric-scoped attribute data SHALL NOT be writable unless the accessing fabric is the associ­ + ated fabric of the data. +- A cluster command SHALL NOT alter fabric-scoped data if the associated fabric is not the + accessing fabric. + +**7.6.5. Fabric-Sensitive Quality** + +This further restricts access to data that is sensitive to the associated fabric. + +This quality acts as an additional constraint over those imposed by the fabric-scoped quality, +namely: + +- Fabric-sensitive data SHALL NOT be readable unless the accessing fabric is the associated fabric + of the data. See fabric-scoped data. + +Data that is fabric-sensitive SHALL always be fabric-scoped. + +``` +Page 428 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Only event definitions and the fields of a fabric-scoped struct MAY be fabric-sensitive. + +**7.6.6. View Privilege** + +An element with the View privilege SHALL support Read (if readable) and Invoke (if invocable) +access if the source of the request is granted the View privilege. + +A command with the View privilege defined SHALL NOT alter data that is part of its function (e.g. +settings, configuration), but MAY alter data that is internal or diagnostic in nature (e.g. usage statis­ +tics). + +**7.6.7. Operate Privilege** + +An element with the Operate privilege defined SHALL support Read (if readable), Write (if +writable), and Invoke (if invocable) access if the source of the request is granted the Operate privi­ +lege. + +**7.6.8. Manage Privilege** + +An element with the Manage privilege defined SHALL support Read (if readable), Write (if +writable), and Invoke (if invocable) access if the source of the request is granted the Manage privi­ +lege. + +**7.6.9. Administer Privilege** + +An element with the Administer privilege defined SHALL support Read (if readable), Write (if +writable), and Invoke (if invocable) access if the source of the request is granted the Administer +privilege. + +**7.6.10. Timed Interaction** + +This quality requires the use of a timed interaction. + +Timed interactions are used to limit the amount of time an action message is valid and can interact +with a node. They are used to prevent a timing attack on the system. For example, a malicious +attacker could perform an "intercept, interfere, and replay" procedure whereby a legitimate mes­ +sage is intercepted, receipt by the intended destination is jammed, and the attacker sends the mes­ +sage at a later time to cause a malicious action such as unlocking a door at an unintended time. +While the practical difficulties of such an attack are high, and the malicious eavesdropper cannot +decrypt the action message, the timed interaction provides further mitigation of risk for critical +actions. + +The timed interaction can be thought of as a 2-phase commit. A precursor action (Timed Request +Action) is sent to indicate the valid time window for arrival of some subsequent, primary action. +Since the timed request requires a response, an attacker cannot do the store-and-forward timing +attack anymore. The lack of an authenticated response from the intended destination will prevent +the subsequent primary action from being sent. + +A command with this quality SHALL require a timed invoke interaction. A writable attribute with + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 429 +``` + +this quality SHALL require a timed write interaction. + +An attempted untimed write interaction to a writable attribute with this quality SHALL generate an +error response. + +An untimed invoke interaction for a request command with this quality SHALL generate an error +response. + +**7.7. Other Qualities** + +A Quality column defines other qualities not covered in other columns. Some qualities are limited +to a specific set of elements. If an element does not have designated qualities, then it SHALL inherit +qualities from the next highest element in the model hierarchy. For example: A data field in a struct +attribute inherits its access qualities from attribute. + +``` +Quality Column Name Elements Description +C Changes Omitted attribute data Fast changing data or +data where deltas are +meaningless to report, +and which will not +cause delta changes on +subscriptions +F Fixed attribute data The read only value is a +fixed value that never +changes, unless the +program image +changes +I Singleton cluster The cluster is a single­ +ton on the node for the +device type +K Diagnostics cluster The cluster is a verbose +diagnostics cluster, +which could be omitted +from wildcard expan­ +sion +L Large Message command The command payload +can be large, resulting +in the message exceed­ +ing the minimum IPv6 +MTU of 1280 bytes. +N Non-Volatile attribute data The attribute data +value is non-volatile +and is persistent across +restarts +``` +``` +Page 430 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Quality Column Name Elements Description +P Reportable attribute If best effort reporting +is supported then the +attribute supports a +reporting configuration +Q Quieter Reporting attribute data Data with fluctuating +data rate or where +some deltas are mean­ +ingless or undesirable +to report. +S Scene attribute The attribute is part of +a scene +T Atomic attribute The attribute requires +writes to be part of an +atomic interaction +X Nullable data fields The data type of the +data field is nullable +``` +**7.7.1. Changes Omitted Quality** + +This quality MAY be given to attribute data that is deemed to have a high rate of change or where +changes are not meaningful or too large to convey as part of Subscribe interaction. + +Attribute data with this quality SHALL support Read Access, but SHALL NOT have delta changes +published as part of a Subscribe interaction. + +**7.7.2. Fixed Quality** + +Data with this quality is read only and has a fixed value that never changes, unless the program +image changes. + +**7.7.3. Singleton Quality** + +This quality indicates that a cluster is a singleton on the node, representing the entire node. + +**7.7.4. Diagnostics Quality** + +This quality is given to Clusters which contain very large amounts of seldom-consulted attributes. + +Such a cluster SHALL be omitted from Request Path Expansion when the WildcardSkipDiagnostic­ +sClusters bit in WildcardPathFlags is set. + +**7.7.5. Large Message Quality** + +Command messages with this quality are typically larger than the minimum IPv6 MTU of 1280 +bytes and cannot be transported over MRP. They SHALL require TCP for communication. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 431 +``` + +**7.7.6. Non-Volatile Quality** + +See Persistence. + +**7.7.7. Reportable Quality** + +The Subscribe interaction supports all attribute data. This quality is supported by other interactions +that only require attribute data with this quality to support interval or change reporting. + +**7.7.8. Quieter Reporting Quality** + +This quality MAY be given to attribute data that changes in a way where some of the changes are +considered to have a high rate of change or where changes are not meaningful or desirable to +report. + +This quality can be used for fast changing attributes, where the majority of reports would have lit­ +tle to no value for the client (e.g. the continuous countdown of a timer in the server where the +client can have a local digital twin) but where some reports may be important to synchronize the +local twin, (e.g. when a countdown starts, stops or is changed). Another case where this quality can +be used is for attributes that can change value for a long period (e.g. the CurrentLevel of a light per­ +forming a ramp with a long transition time) or where the measured value can change quite often. +This prevents over-reporting of such an attribute to many subscribed clients which could lead to +link degradation on bandwidth-constrained links. + +Attributes with this quality SHALL specify, in the attribute description, the details of the conditions +under which changes to the attribute value SHALL, SHOULD or MAY be reported. + +Changes to the value under conditions other than those specified in the attribute description +SHOULD NOT be reported. To ensure clients can understand the parameters related to specifics of +that attribute’s reporting, the description MAY include details regarding when the attribute value +might change without being reported. + +Attributes MAY get this quality assigned in a revision of a cluster, to limit the amount of reporting, +therefore Clients SHALL generally be resilient to more reporting than constrained by the attribute +description, from older revisions of the cluster. + +Attribute data with this quality SHALL support Read Access. + +**7.7.9. Scene Quality** + +This quality is supported and described in the Scenes Management cluster. It relates to the ability of +a field to be settable by Scenes. This quality SHALL only apply to attributes having unsigned integer +or boolean data types of size at most 4 bytes from the Base Data Types list (e.g. bool, uint8, uint16, +uint32), or derived types thereof (e.g. enum8, map8). This quality has no effect in contexts unrelated +to the Scenes Management cluster. + +**7.7.10. Nullable Quality** + +See Nullable. + +``` +Page 432 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.7.11. Atomic Quality** + +This quality indicates that an attribute requires atomic writes. See Atomic Writes. + +An attribute with this quality SHALL support Write Access. + +**7.8. Node** + +A Node encapsulates an addressable, unique resource on the network that has a set of functions +and capabilities that a user recognizes distinctly as a functional whole. + +This distinction is usually physical, such as the physical device itself, or a logical instance of a physi­ +cal device. + +A node is the highest or outermost first order element in the data model. A node is the outermost +unique addressable element of the data model. + +A node MAY have multiple node IDs, each ID scoped to a particular fabric. When a node ID is used +as the target address of an interaction, the fabric under which the node ID is scoped, is the access­ +ing fabric for the interaction. + +The lower layers in a communication stack supporting this data model SHALL support interactions +between nodes on a logical inter-network of nodes. Please see the Interaction Model and System +Model specifications that describe relationships and interactions between nodes and data model +elements on each node. + +It is possible for parts of a node to reside on different processors (e.g. separate application and net­ +work processors). + +A single physical product may support more than one node. + +**7.9. Endpoint** + +A node is composed of one or more endpoints. An endpoint is an instance of something that could +be a service or virtual device as indicated by a device type. + +Each endpoint conforms to one or more device type definitions that define the clusters supported +on the endpoint. Clusters are object classes that are instantiated on an endpoint. + +The word 'device', depending on the context, may be used as shorthand to denote the device type +definition as represented by a device type ID, a device type implementation, or an endpoint (device +type instance). + +There are also many examples in specification text where 'device' is used, when it would be better, +and more accurate to use 'node', 'physical device', or 'product'. + +The word 'device' may also be used in cluster specifications to describe application software that is +supporting an instance of a cluster server or client. In this case, it would be better, and more accu­ +rate to use either 'client' or 'server'. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 433 +``` + +One must be careful to make sure there is no ambiguity when using the word 'device' in specifica­ +tion text, or better yet, use another word. + +**7.10. Cluster** + +Clusters are the functional building block elements of the data model. A cluster specification +defines both a client and server side that correspond with each other through interactions. A clus­ +ter may be considered an interface, service, or object class and is the lowest independent functional +element in the data model. Each cluster is defined by a cluster specification that defines elements of +a cluster including attributes, events, commands, as well as behavior associated with interactions +with these elements. Cluster attributes, events, commands and behaviors are mandatory or +optional depending on the definition of the cluster. Optional items may have dependencies. + +A cluster specification SHALL list one or more Cluster Identifiers. A Cluster Identifier SHALL refer­ +ence a single cluster specification and SHALL define conformance to that specification. A cluster +instance SHALL be indicated and discovered by a Cluster Identifier on an endpoint. A Cluster Iden­ +tifier also defines the purpose of the instance. + +The server cluster supports attribute data, events and cluster commands. The client cluster initiates +interactions, including invocation of cluster commands. + +**7.10.1. Cluster Revision** + +The revision of a cluster is to enforce backward and forward compatibility, but still allow clusters to +be enhanced, fixed, or updated, without changing the cluster’s basic function. + +A cluster revision SHALL be associated with an approved revision and release of a cluster specifica­ +tion. The revision of an instance of a cluster SHALL be represented by the global, mandatory, and +read only ClusterRevision attribute. Please see ClusterRevision attribute. + +Changes to a cluster specification SHALL only augment, not modify the primary function of the +cluster. Changes to a cluster specification SHALL be represented by incrementing the cluster revi­ +sion. New revisions of a client cluster SHALL interoperate with older revisions of the server cluster +and vice versa. Interoperability between corresponding cluster instances MAY require reading the +cluster revision. + +``` +For example: If a new product client application supporting revision 3 of cluster X wishes to +take advantage of the new behavior that is mandated by revision 3, then the application can +read the revision of the corresponding server cluster X in each remote endpoint. If a corre­ +sponding cluster X supports revision 3 or greater, then the behavior is supported. +``` +``` +Examples of changes to a cluster that require incrementing the revision: +``` +- Changing the behavior of the cluster +- Changing a read only attribute to become writable +- Adding new attributes (e.g. min and max of an existing attribute value) +- Adding new commands, actions, or behavior + +``` +Page 434 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Adding one or more fields to an existing command +- Adding a new enumerated value to an attribute +- Adding qualities to an existing attribute (e.g. Q) +- Changing anything that is optional to mandatory +- Changing dependencies of optional items +- Deprecating parts of the cluster specification +- Any non-editorial specification text change + +**7.10.2. Cluster Optional Features** + +In general, as the number of optional elements in a cluster specification increases, the number of +possible combinations increases, which could decrease the interoperability of that cluster. + +Each cluster has a mandatory feature set that consists of mandatory elements such as attributes, +commands, fields, values, dependencies, behavior, etc. + +A cluster specification MAY have optional feature sets, each supported by a set of elements (see Fea­ +tureMap). + +There is no requirement that each cluster instance supports the same set of optional elements. + +If an application knows the ClusterRevision and FeatureMap supported by a cluster instance, then it +knows the exact specification text required to be implemented by that instance. + +**7.10.3. Cluster Data Version** + +A cluster data version is a metadata increment-only counter value, maintained for each cluster +instance. A cluster data version represents an exact & coherent state of cluster attribute data at +present. An application may externally hold a data version (called a held data version) published by +a cluster instance which then represents a cluster instance state at some time in the past. An appli­ +cation may use a held data version to optimize future interactions, by indicating the held data ver­ +sion. A cluster data version is surfaced in the Interaction Model when data is requested. It is used to +optimize data read transactions by reducing the need to send the same data. Write interactions may +also be qualified with a held data version to disallow changes, unless the cluster instance has the +same data version (see Interaction Model). A cluster data version is published as information in +some interactions (See Interaction Model). An externally held data version may be included as +information in some interactions (See Interaction Model). + +A cluster data version SHALL increment or be set (wrap) to zero if incrementing would exceed its +maximum value. A cluster data version SHALL be maintained for each cluster instance. A cluster +data version SHALL be initialized randomly when it is first published. A cluster data version SHALL +be incremented if any attribute data changes. + +**7.10.4. New Cluster** + +When considering the creation of a new cluster specification, it is recommended to consider + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 435 +``` + +reusing and extending an existing cluster specification. These are the mechanisms to consider, in +order, to extend a cluster: + +1. Optional elements: attribute data, commands, events, enumerations, etc. +2. Optional feature(s) in the FeatureMap attribute for a set of elements (see 1) +3. Cluster Aliasing to reuse a cluster specification as a whole, but with a different semantic +4. Cluster Inheritance +5. A new cluster specification + +**7.10.5. Cluster Aliasing** + +Cluster aliasing allows the reuse of approved and validated specifications and derived documents, +such as test plans, scripts, etc. + +- More than one Cluster Identifier, each with unique purpose and semantic content, MAY map to + a single cluster specification. + +``` +For example: A Concentration Measurement cluster specification may be quite abstract but +have many mapped Cluster Identifiers each with a more concrete purpose, such as CO 2 or O 2 +concentration measurement. +``` +**7.10.6. Cluster Inheritance** + +Cluster inheritance allows the reuse of approved and validated specifications and derived docu­ +ments, such as test plans, scripts, etc. This allows a new cluster specification to be defined as +extending or reducing the requirements of an existing cluster specification, called the base cluster. +This also allows an existing cluster specification to be defined as a derived cluster, by creating a +new base cluster that is more generic, allowing potential new clusters to be derived from the new +base cluster. + +- A derived cluster specification MAY have mandatory requirements that are optional in the base + specification. +- A derived cluster specification MAY remove requirements that are optional in the base specifi­ + cation. +- A derived cluster specification MAY remove or make optional a requirement that is mandatory + in the base specification, if the resulting specification is deemed useful in its reduced form, and + logically a subset of the base clusters. + +``` +For example: The Bridged Device Basic Information cluster is derived as a reduced form of +the base Basic Information cluster, where many informational attributes are not mandatory, +because the information is not available from devices behind the bridge. However, the +derived cluster provides the same, but reduced, function as the base cluster. +``` +- It is RECOMMENDED that a derived cluster makes changes to the base cluster by extending or + +``` +Page 436 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +reducing one or more features or independent elements, and not by modifying features, ele­ +ments or cluster behavior. +``` +Such modifications SHOULD be defined as a feature, which can be used to extend or reduce. + +- All new features, elements or behavior introduced by the derived cluster that may be useful + across other derivations SHOULD be defined in the base cluster specification and made optional + (in that base cluster specification), to maintain the entire set of requirements and identifier + namespace in one place. +- A range of ID values SHALL be reserved for the base clusters. The remaining values SHALL be + reserved for use by the derived clusters. The ranges reserved for base clusters are as follows: + ◦ Feature bits: 0-19 + ◦ Attribute IDs: 0x0000-0x7FFF + ◦ Command IDs: 0x00-0x7F + ◦ Event IDs: 0x00-0x7F +- A derived cluster specification SHALL define its own revision (ClusterRevision attribute) that is + independent of the base specification, with the single exception that if the base specification is + modified/updated in a way that requires its revision to be increased, as detailed in Cluster Revi­ + sion, then the revision of any derived cluster specifications SHALL also be increased. +- A base cluster specification MAY be created from an original base cluster, which then becomes a + derived cluster to the newly created base cluster. + +If an endpoint supports multiple server clusters that derive or map to the same base cluster specifi­ +cation, then each SHALL represent a single implementation and operate as a single entity or +instance. This makes it possible to deploy a new device endpoint with both a base and a derived +cluster identifier, which SHALL remain backward compatible to legacy devices that support only +the original cluster identifier. Cluster identifiers that are mapped to a single base cluster specifica­ +tion, but are defined for distinctly different purposes, MAY exist together on a device endpoint. If +there is no base cluster identifier defined, or no base cluster identifier exists on the same endpoint, +then each cluster identifier SHALL represent a separate instance. + +It is a good practice to explore the possibility of either deriving a cluster from an existing cluster or +creating a base cluster to map or derive new and existing cluster identifiers. See New Cluster for +other options. + +**7.10.7. Status Codes** + +A cluster specification defines status code responses to actions depending on the cluster instance +state. A status code is either a global Interaction Model status code, or a cluster specific status code +that is unique to the cluster specification. A global status code is either scoped to the entire action, +or to a cluster request path. A cluster specific status code scoped to a cluster instance is indicated by +a cluster path. When an interaction defines a Status Response response, the responder SHALL +return a global Interaction Model status code. When an interaction response needs to communicate +a cluster specific status code, the responder SHALL return the path to the cluster instance, the +global status code SUCCESS or FAILURE, and the cluster specific status code. Each cluster specific +status code SHALL be associated with either SUCCESS or FAILURE, not both. A cluster specific status + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 437 +``` + +code SHALL be, by default, associated with FAILURE unless it is defined as associated with SUCCESS. +The global SUCCESS status code means the action was executed for the request path; the global +FAILURE status code means that it was not executed. + +- Cluster-specific status code SHALL be defined using the status type. +- Cluster-specific status codes MAY have the same numeric values as global status codes. Interac­ + tion model messages SHALL make it clear whether a particular message field is a global status + code or a cluster-specific status code. +- Cluster-specific status codes SHALL communicate more information than just a generic success + or failure condition. Global status codes SHALL be used to communicate such conditions. +- A server cluster SHALL NOT return a cluster-specific code from another cluster. + +**7.10.8. Cluster Classification** + +A cluster SHALL be defined as either a utility cluster or an application cluster. + +**7.10.8.1. Utility Cluster** + +A utility cluster is not part of the primary application operation of an endpoint. It may be used for +configuration, discovery, addressing, diagnostics, monitoring device health, software update, etc. It +may have a temporary relationship with its cluster counterpart. + +``` +Utility cluster examples scoped to an endpoint: Identify, Descriptor, Binding, Groups, etc. Util­ +ity cluster examples scoped to the node: Basic Information, various Diagnostics clusters, OTA +update related clusters, etc. +``` +**7.10.8.2. Application Cluster** + +An application cluster supports the primary operation of the endpoint. An application cluster sup­ +ports one or more persistent application interactions between client and server. + +``` +Example application cluster transactions: +``` +- On/Off cluster - client sends command to server +- Temperature Measurement cluster - server reports data to client + +An application cluster is not a utility cluster even though it may support utility functions for itself, +such as calibration, modes of operation, etc. An application cluster specification SHALL be agnostic +about layers and processes outside of its application domain. + +``` +Example: A particular temperature measurement cluster may exist on different devices, or in +different networks, each with different security & commissioning mechanisms and/or poli­ +cies. +``` +``` +Example: A commissioning cluster’s domain is commissioning, but not temperature measure­ +``` +``` +Page 438 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ment. +``` +**7.11. Command** + +A cluster command is a set of data fields, each of a data type that is conveyed between client and +server cluster instances to invoke a behavior on the receiver of the command. + +Each command SHALL be listed in a table with data quality columns: ID, Name, Direction, +Response, Access, Conformance. + +The command table SHALL define the direction of the command as either client to server or server +to client. The command table SHALL define the access privileges for each request command or omit +the privileges for the default (see default access privileges). The command table SHALL NOT define +privileges for a response command. The command table SHALL define a possible response to the +command, if any. The command table SHALL define conformance for each command. + +A command that is not a response (in the Response column) is a request command. Conformance +for a client to server command means the server SHALL recognize and support the client to server +command and generate responses as defined. Conformance for a server to client command means +the server SHALL send the command as cluster behavior defines, such as in response to a client to +server command. Conformance for a command can depend on supported server features. A client +SHALL NOT be required to support optional commands or commands depending on an optional +feature. + +A command description SHALL define when a command is generated. A command description +SHALL define the effect upon receipt of a command which may be: + +- a response command +- a success status response +- an error status response +- no response + +A command definition SHALL clearly define any side-effects on fabric-scoped data, if applicable. + +A command is identified and indicated with a command ID that SHALL be unique to the cluster*. + +### NOTE + +``` +Some legacy clusters have reused the same command ID twice to indicate one +command from the client and another from the server. Moving forward, com­ +mand IDs SHALL NOT be reused in that fashion. +``` +A cluster command table SHALL have a Response column with the following values: + +``` +Response Column Description +N no response is returned for this command +Y status only is returned for this command +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 439 +``` + +``` +Response Column Description +command name of the response command to this com­ +mand +``` +A cluster command table SHALL have a Direction column with the following values: + +``` +Direction Column Description +client ⇒ server command is conveyed from the client to the +server cluster +client ⇐ server command is conveyed from the server to the +client cluster +``` +Each command SHALL be described in its own section with a table defining command fields (if +any). + +**7.11.1. Command Fields** + +A command MAY indicate zero or more fields that are defined in a table. Each command field is +defined as a row in the table with these columns: + +``` +Column Description +ID This is the unique field ID of the field +Name This is the unique name of the field +Type This is the data type of the field +Constraint see Constraint +Quality see qualities +Default see Default +Conformance see Conformance +``` +Command field conformance defines the sender requirements to include the field in a well-formed +command for the revision of the cluster. A new command field or a newly made-mandatory com­ +mand field in a newly revised cluster specification may be omitted by a legacy sender. The cluster +specification SHALL define clear behavior upon receipt of any possible well-formed command with +fields that are not present. The cluster specification SHALL take into consideration the revision his­ +tory of possible well-formed commands from legacy implementations. To allow deprecation, it is +recommended that command fields have a well-defined default value (such as null), and associated +default behavior, that is equivalent to omitting the field. Well-defined behavior, for a field that is +not present, may be no behavior at all. + +``` +For example +A newly revised Noise cluster adds a new mandatory Volume field to the MakeNoise com­ +mand. Legacy receivers will ignore the Volume field, and legacy senders will not include +the field. +``` +``` +Page 440 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Another example +The Volume field is mandatory for the original cluster and there is a proposal to make it +optional. The Volume field null value has the semantic of ignoring the field, so instead of +making it optional, the default value is used. This would make the receiver logic simpler. +``` +**7.12. Attribute** + +An attribute is cluster data. Each attribute SHALL be listed in a table with data quality columns: ID, +Name, (Data) Type, Constraint, other Quality, Access, Default (value), and Conformance. An +attribute SHALL also define its associated semantics and behavior. Attributes reflect queryable/set­ +table state, configuration and capabilities of a device. If no privileges are explicitly defined for an +attribute, then default access privileges take effect. Attribute data MAY also have these other quali­ +ties: + +``` +Quality Short Description +Scene S indicates that the data is part of +a scene +Persistent N indicates that the data value is +persistent across restarts +Fixed F indicates that the read only +data value will never change +Nullable X indicates that the data may +have a value of null +Atomic T indicates that the attribute may +only be written to in the context +of an atomic write +``` +Fabric-scoped attribute data SHALL be defined as a fabric-scoped list. + +**7.12.1. Persistence** + +Persistent data retains its value across a restart. + +A restart is: + +- a program restart or reboot +- power cycle reboot +- user-initiated reboot +- reboot initiated from a program image upgrade + +A factory reset is not such a restart. A factory reset is a deliberate behavior to reset persistent data +back to its original state when the product left the factory. + +Cluster attributes that represent configuration data SHALL be persistent data unless otherwise + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 441 +``` + +specified. + +``` +For example: a writable attribute that persistently changes the behavior (or mode) of the clus­ +ter. +``` +``` +Examples of non-configuration data: device state data, data that is calculated or comes from +an external source, such as a sensor value, a time value, etc. +``` +Many clusters define persistent data that is not surfaced as attributes, but is managed by com­ +mands. Commissioning or configuration data that is created to allow the cluster to perform its func­ +tion is persistent data. A group table entry and binding entries are both persistent data across a +restart. + +When a persistent cluster attribute represents controlled state of the device, the device SHALL +restore the attribute value to the value before the restart was initiated, and put the device in the +state that is represented by the restored value. + +``` +For example: After an OTA cluster restart, clusters that have visible state attributes, such as +the state of a light, or a window shade SHALL be persistent and define these attributes as per­ +sistent. +``` +Some cluster specifications add a dependency with a persistent configuration attribute A that con­ +tains a value to use to restore persistent state attribute B after a restart. This is perfectly valid but +cluster specific. + +Cluster state data that is not controlled, such as sensor data, is not considered persistent. + +The cluster specification may put dependencies and limitations on persistent data. + +**7.13. Global Elements** + +Below is a list of global elements. These are used for self-description of the server. + +_Table 72. Global Attributes_ + +``` +ID Name Element Type Con­ +straint +``` +``` +Quality Access Default Confor­ +mance +0xFFFD Cluster­ +Revision +``` +``` +attribute uint16 min 1 F R V M +``` +``` +0xFFFC Fea­ +tureMap +``` +``` +attribute map32 F R V 0 M +``` +``` +0xFFFB Attribut­ +eList +``` +``` +attribute list[attrib- +id] +``` +### F R V M + +``` +0xFFFA EventList attribute D +``` +``` +Page 442 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Element Type Con­ +straint +``` +``` +Quality Access Default Confor­ +mance +0xFFF9 Accept­ +edCom­ +mandList +``` +``` +attribute list[com­ +mand-id] +``` +### F R V M + +``` +0xFFF8 Generat­ +edCom­ +mandList +``` +``` +attribute list[com­ +mand-id] +``` +### F R V M + +_Table 73. Global Fields_ + +``` +ID Name Element Type Con­ +straint +``` +``` +Quality Access Default Confor­ +mance +0xFE FabricIn­ +dex +``` +``` +struct or +event +field +``` +``` +fabric-idx 1 to 254 R V F fabric- +scoped +``` +_Table 74. Global Commands_ + +``` +ID Name Direction Response Access Conformance +0xFE AtomicRe­ +quest +``` +``` +client ⇒ server AtomicRe­ +sponse +``` +``` +O desc +``` +``` +0xFD AtomicRe­ +sponse +``` +``` +client ⇐ server N AtomicRequest +``` +**7.13.1. ClusterRevision Attribute** + +The ClusterRevision attribute indicates the revision of the server cluster specification supported by +the cluster instance. An implementation of a cluster specification before the ClusterRevision +attribute was added SHALL have an assumed cluster revision of 0 (zero). For a new cluster specifi­ +cation, the initial value for the ClusterRevision attribute SHALL be 1 (not zero). + +A history of revision numbers for a cluster specification release is listed in the Revision History sec­ +tion for a cluster specification. Each new revision of a cluster specification SHALL specify a new +revision number incremented (by 1) from the last. The highest revision number in a cluster specifi­ +cation’s Revision History is the revision number for the cluster specification. Therefore, a Cluster­ +Revision attribute value SHALL be the (highest) revision number of the cluster specification that +has been implemented. + +**7.13.2. FeatureMap Attribute** + +Each instance of a cluster SHALL support this attribute. + +The FeatureMap attribute SHALL indicate whether the server supports zero or more optional clus­ +ter features. A cluster feature is a set of cluster elements that are mandatory or optional for a +defined feature of the cluster. If a cluster feature is supported by the cluster instance, then the cor­ +responding bit SHALL be set to 1, otherwise the bit SHALL be set to 0 (zero). All undefined bits in + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 443 +``` + +this attribute SHALL be set to 0 (zero). + +The set of cluster elements that are designated as mandatory (M) are implicitly part of the manda­ +tory cluster feature set, and do not have a bit in the FeatureMap attribute. + +A cluster specification SHALL support this attribute if the cluster supports features. If a cluster +specification is revised to support features (and so this attribute), each bit in the FeatureMap +attribute SHALL have a defined default value (1 or 0), to conform with the previous revision of the +cluster specification, that did not support the FeatureMap attribute. The value of 1 means the fea­ +ture elements were mandatory (M) in the previous revision. The value of 0 (zero) means the ele­ +ments were optional in the previous revision. + +Any newly created feature set of a cluster SHALL be dependent on that cluster. + +Feature sets are revision controlled as part of a cluster using the ClusterRevision attribute. The clus­ +ter specification is the independent element that is revision controlled. A remote application read­ +ing the FeatureMap and ClusterRevision Attribute will then know exactly what features are sup­ +ported in the cluster instance. + +Each feature set SHALL be well defined within the cluster specification. Each feature SHALL be +mapped to a short capitalized code name for the feature set to be referenced as a conformance tag +in the cluster specification text, including the Conformance columns defining the elements of the +cluster. + +If a cluster defines more than 32 feature sets, then it will be necessary to add another feature +bitmap attribute. Any client trying to reference the new feature set will know about the new +bitmap, because it knows about the new feature set(s). Legacy products will not know about the +new feature set nor the new bitmap. + +For a cluster whose definition which does not define a FeatureMap, the server SHALL set this +attribute to 0 (zero). + +Please see Feature Conformance for details on conformance. + +**7.13.3. AttributeList Attribute** + +Each instance of a cluster SHALL support this attribute. This attribute SHALL be a list of the +attribute IDs of the attributes supported by the cluster instance. + +**7.13.4. AcceptedCommandList Attribute** + +This attribute is a list of client generated commands which are supported by this cluster server +instance. + +Each instance of a cluster SHALL support this attribute. + +This attribute SHALL be a list of the command IDs for client generated commands that are sup­ +ported and processed by the server. + +For each client request command in this list that mandates a response from the server, the + +``` +Page 444 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +response command SHALL be indicated in the GeneratedCommandList attribute. + +If any attribute on a server supports atomic writes, this attribute SHALL contain the command ID +for AtomicRequest. + +**7.13.5. GeneratedCommandList Attribute** + +This attribute is a list of server generated commands. A server generated command is a server to +client command. + +Each instance of a cluster SHALL support this attribute. + +This attribute SHALL be a list of the command IDs for server generated commands. + +For each command in this list that is a response to a client command request, the request command +SHALL be indicated in the AcceptedCommandList attribute. + +If any attribute on a server supports atomic writes, this attribute SHALL contain the command ID +for AtomicResponse. + +**7.13.6. FabricIndex Field** + +This field SHALL be present for fabric-scoped data. This field does not have to be defined explicitly +in the field table for fabric-scoped data. + +This field SHALL NOT be present in a write interaction. For a write interaction, the server SHALL +provide the value of the accessing fabric-index as the FabricIndex field value to processing logic, +after receipt of the interaction. For a read interaction this field SHALL be included in all reported +data that is defined as fabric-scoped. + +**7.13.7. AtomicRequest Command** + +This command begins, commits or rolls back atomic writes. See AtomicRequest. + +This command SHALL be supported by any cluster instance which has attributes with the Atomic +Quality. + +**7.13.8. AtomicResponse Command** + +This command is returned in response to an AtomicRequest command. See AtomicResponse. + +This command SHALL be supported by any cluster instance which has attributes with the Atomic +Quality. + +**7.14. Event** + +An event defines a record of something that occurred in the past. In this regard, an event record +can be thought of as a log entry, with an event record stream providing a chronological view of the +events on the node. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 445 +``` + +Unlike attributes, which do not provide any edge-preserving capabilities (i.e. no guarantees that +every attribute change will be conveyed to observers), events permit capturing every single edge or +change and conveying it reliably to an observer. This is critical for safety and security applications +that rely upon such guarantees for correct behavior. + +Each cluster event is listed in a table that defines: ID, Priority, Access, Quality, Conformance. + +Absence of a Quality column implies that the event does not support any qualities. + +Event records are readable, and do not require the read access quality to be explicitly defined. + +Each generated event record SHALL have an event priority that MAY override the defined priority +for that event. + +Each event SHALL be described in a section that defines the purpose of the event and the data +fields of the event (if any). + +**7.14.1. Event Record** + +An event record is created by the node at the time the event happens. That record SHALL have the +following data fields associated with it that are common to all events: + +``` +Name Type Conformance +Number event-no M +SystemTimeStamp systime-ms O.a +EpochTimeStamp posix-ms O.a +Priority priority M +Data struct O +``` +**7.14.1.1. Number Field** + +This is an event number value that is scoped to the node. This number SHALL be monotonically +increasing for the life of the node. This monotonicity guarantee SHALL be preserved across +restarts. + +Between restarts, each event record SHALL be assigned a number that is exactly 1 greater than the +last created event record on that Node. + +When a node restarts, the event number MAY increase by a larger step than 1. _Rationale_ : Nodes do +not need to write every new value of the event number counter to permanent storage each time it +is increased (e.g. to prevent flash wear due to many write operations). One example strategy to +achieve reduction of non-volatile storage updates is described below: + +1. Read the counter value at start-up. +2. Before processing any message, write counter + N to storage, where N is a carefully chosen + number (e.g. 1000). This number N should be chosen carefully in order not to exhaust the life­ + time 64-bit counter space. + +``` +Page 446 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +3. Process messages normally until the counter has a value one less than the counter in storage. + When this happens, store counter + N to storage. + +**7.14.1.2. SystemTimeStamp and EpochTimeStamp Fields** + +Each event record SHALL have a timestamp at the time it was created (and not when it is reported +to a client). This timestamp SHALL either be System Time in milliseconds or POSIX Time in millisec­ +onds. + +**7.14.1.3. Priority Field** + +Each event record has an associated priority. This priority describes the usage semantics of the +event. + +**7.14.1.4. Data Field** + +Event data fields SHALL be defined in the form of a struct in a table with the following columns for +each field: ID, Name, Type, Constraint, Quality, Default, Conformance. + +**7.14.2. Buffering** + +Event records SHALL be buffered on the Node, with priority given to events of a higher priority +level over a lower priority level. Within a priority level, newer event records SHALL overwrite +older event records. The Node SHOULD only overwrite older events if there are newer events cre­ +ated and there is insufficient space to retain both. + +**7.14.3. Event Filtering** + +Interactions that report event records MAY be filtered by event ID and/or event number. + +**7.14.4. Fabric-Sensitive Event** + +An entire event MAY be defined as having the fabric-sensitive quality; otherwise, it SHALL NOT be +associated with a fabric. + +A read interaction SHALL NOT filter event records, based on fabric, for event records that are not +associated with a fabric. + +A read interaction SHALL NOT report fabric-sensitive event records that are associated with a fab­ +ric different than the accessing fabric. + +A fabric-sensitive event SHALL include the global FabricIndex field. For a fabric-sensitive event it is +not required to define the FabricIndex field in the event field table. + +**7.15. Atomic Writes** + +Atomic writes allow a client to make multiple writes to certain sets of attributes atomically, such +that changes are either applied entirely or none at all. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 447 +``` + +**7.15.1. Atomic Write Flow** + +``` +Stage Action Action Flow Description +``` +### 1 + +``` +Invoke AtomicRequest Client ⇒ Server Begins atomic write +Return AtomicResponse Client ⇐ Server Acknowledges beginning +of atomic write or returns +error +``` +### 2 + +``` +Repeate +d +``` +``` +Read/Write Request Client ⇒ Server Reads or writes to attrib­ +utes +Read/Write Response Client ⇐ Server Acknowledges write or +errors +``` +### 3 + +``` +Invoke AtomicRequest Client ⇒ Server Commits or cancels +atomic write +Return AtomicResponse Client ⇐ Server Acknowledges commit of +atomic write or returns +error +``` +Atomic writes have three stages: + +1. The client requests to begin an atomic write by providing a list of attributes with the Atomic + Write quality and a timeout for completing its expected writes + a.The server responds with a list of attribute statuses, and possibly an alternative timeout +b. If the client does not accept the statuses or the alternative timeout, then the client SHALL +cancel the atomic write using a Rollback Write request. +2. Otherwise, the client makes a series of write requests to the attributes + a.The server pends these writes in an internal buffer, potentially returning errors if a write + can not possibly succeed during a commit +3. If the client no longer wants to continue, then it requests to roll back the atomic write; other­ + wise, the client requests to commit the atomic write + a.The server evaluates all the writes, and either applies all of them or returns an error to the + client, discarding the pending writes + +**7.15.2. Atomic Writer ID** + +An Atomic Writer ID is an Operational Node ID which identifies the client within the accessing fab­ +ric. + +If the session context for the transaction is a Secure Session Context, the Atomic Writer ID SHALL +be the Peer Node ID stored in the context. + +If the session context for the transaction is a Groupcast Session Context, the Atomic Writer ID +SHALL be invalid. + +An Atomic Writer ID that is not a valid Operational Node ID SHALL be invalid. + +``` +Page 448 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.15.3. Atomic Write State** + +An Atomic Write State associates a client with a set of atomic attributes on a server. It is the combi­ +nation of: + +1. An endpoint-no +2. A cluster-id +3. An Atomic Writer ID +4. The accessing fabric +5. A set of attrib-ids + +An attribute on a given server cluster instance is associated with an Atomic Write State if the state’s +set of attrib-ids contains the ID of the attribute, the cluster-id matches the ID of the cluster instance +and its endpoint-no matches the endpoint of cluster instance. + +A client is associated with an Atomic Write State if both its Atomic Writer ID and accessing fabric +match the Atomic Writer ID and accessing fabric of the client. + +If a server receives a Write Request for an attribute that is not associated with an Atomic Write +State that is also associated with the client making the request, the server SHALL return the error +code INVALID_IN_STATE. + +Reading an attribute with the Atomic quality from a client with an associated Atomic Write State +SHALL return the current value of the attribute if the client has not successfully written to the +attribute; if the client has written to the attribute while having an associated Atomic Write State, +the server SHALL return the updated value of the attribute. + +When writing to any attribute associated with an Atomic Write State, any integrity checks SHALL +be evaluated in the context of the pending values of all the attributes associated with the Atomic +Write State. + +Any writes to attributes with the Atomic quality from a client associated with an Atomic Write State +SHALL only be visible to that client until committed, and SHALL NOT have any effect on the opera­ +tion of the server. + +If a server receives a command which modifies an attribute with the Atomic quality while a client +has an Atomic Write State containing the attrib-id of that attribute, it SHALL apply these changes as +if there were no atomic write; this MAY cause the atomic write to fail when the client attempts to +commit (see Commit Write). + +**7.15.4. AtomicRequestTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 BeginWrite Begin an atomic write M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 449 +``` + +``` +Value Name Summary Conformance +1 CommitWrite Commit an atomic +write +``` +### M + +``` +2 RollbackWrite Rollback an atomic +write, discarding any +pending changes +``` +### M + +**7.15.5. AtomicAttributeStatusStruct Type** + +This struct indicates the status of an attribute during an atomic write. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Attribut­ +eID +``` +``` +attrib-id M +``` +``` +1 Status­ +Code +``` +``` +status M +``` +**7.15.5.1. AttributeID Field** + +This field SHALL indicate the ID of the attribute with the associated StatusCode. + +**7.15.5.2. StatusCode Field** + +This field SHALL indicate the atomic status of an attribute. + +**7.15.6. AtomicRequest Command** + +This command is used to begin, commit or cancel an atomic write. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Request­ +Type +``` +``` +AtomicRe­ +questType­ +Enum +``` +### M + +``` +1 Attribut­ +eRequests +``` +``` +list[attrib-id] M +``` +``` +2 Timeout uint16 desc +``` +**7.15.6.1. RequestType Field** + +This field SHALL indicate the type of atomic request being made by the client. + +**7.15.6.2. AttributeRequests Field** + +This field SHALL indicate a list of attribute IDs the client wishes to write to during an atomic + +``` +Page 450 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +request. + +**7.15.6.3. Timeout Field** + +This field SHALL indicate an interval in milliseconds in which the client will either commit or roll­ +back the atomic write. If the value of the RequestType field is BeginWrite, this field SHALL be +included, otherwise it SHALL be omitted. + +**7.15.6.4. Effect on Receipt** + +If an AtomicRequest command is received without an accessing fabric, the server SHALL return a +status code of INVALID_COMMAND. + +If an AtomicRequest command is received with an Atomic Writer ID which is either unavailable or +not a valid Operational Node ID, the server SHALL return a status code of INVALID_COMMAND. + +For AtomicRequests with any RequestType: + +1. If the AttributeRequests field is empty, the server SHALL return an error code of INVALID_COM­ + MAND. +2. If the AttributeRequests field contains duplicate values, the server SHALL return an error code + of INVALID_COMMAND. +3. If the AttributeRequests contains attrib-ids for attributes not supported by the server, the server + SHALL return an error code of INVALID_COMMAND. + +**Begin Write** + +If the RequestType of the AtomicRequest is BeginWrite, the server SHALL attempt to begin an +atomic write and return an AtomicResponse: + +1. If the client is already associated with an Atomic Write State that is associated with any attrib­ + utes on the same cluster and endpoint, the server SHALL return a status code of INVALID_IN_S­ + TATE. +2. If the request does not have a Timeout Field, the server SHALL return an error code of + INVALID_COMMAND. +3. Otherwise, the server SHALL return an AtomicResponse: + a. For each attrib-id in AttributeRequests, the server SHALL return a matching AtomicAttribut­ + eStatusStruct in AttributeStatus: + i. If the client does not have sufficient privilege to write to the attribute, the status SHALL + be UNSUPPORTED_ACCESS. +ii. If the specified attribute does not support atomic writes, the status SHALL be INVALID_­ +COMMAND. +iii. If the specified attribute is currently being used by a different atomic write, the status +SHALL be BUSY. +iv. If the server does not have enough resources to pend writes to the attribute, the status +SHALL be RESOURCE_EXHAUSTED. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 451 +``` + +``` +v. Otherwise, the status SHALL be SUCCESS to indicate that the attribute is available for +writing. +b. For internal reasons, a server MAY implement atomic writes for a set of attributes with a +shared resource, such that beginning an atomic write to any of the attributes in the set +requires including all of the attributes in the set. If attributes other than the requested +attributes are included in an atomic write, the server SHALL return statuses for those attrib­ +utes as if they had been requested. +c.Subsequent invocations of AtomicRequest of type Commit Write or Rollback Write MUST +provide the attrib-ids returned in AttributeStatus, not the attrib-ids requested in Attribut­ +eRequests. +d. If any of the requested attributes have a status code other than SUCCESS, the StatusCode of +the AtomicResponse SHALL be FAILURE. +i. The server SHALL NOT associate an Atomic Write State with the client. +ii.Depending on the status codes received for individual attributes, the client MAY choose +to try again; e.g. if the attribute the client was attempting to write to has status BUSY, the +client could attempt to write to it again after a pause. +e. Otherwise, the StatusCode SHALL be SUCCESS. +i. The server SHALL create an Atomic Write State with the endpoint number and ID of the +cluster instance handling the AtomicRequest command, the accessing fabric, the Atomic +Writer ID, and the set of attrib-ids returned. +ii.If the requested timeout is longer than the maximum timeout the server allows for the +requested set of attributes, the server MAY return the maximum timeout for the +requested set of attributes in the Timeout field. Otherwise, the server SHALL return the +requested timeout in the Timeout field. +iii.If the server does not receive a matching AtomicRequest with a RequestType of Com­ +mitWrite from the associated client before the timeout provided by the server in the +AtomicResponse, the server SHALL roll back any pending writes and discard the atomic +write. +``` +**Commit Write** + +If the RequestType of the AtomicRequest is CommitWrite, the server SHALL attempt to commit any +pending writes and return an AtomicResponse: + +1. If the client is not associated with an Atomic Write State whose endpoint-no and cluster-id + match the endpoint number and ID of the cluster instance handling the request, and whose set + of attrib-ids match the attrib-ids requested, irrespective of order, the server SHALL return an + error code of INVALID_IN_STATE. +2. The server SHALL process all pending writes to the requested atomic attributes as if they had + arrived in a single message. +3. The server SHALL create a list of attribute statuses for each attribute that would be modified by + the processing of the atomic write: + a.If the server is able to determine that the atomic write will not succeed, the status code + SHALL indicate the error code that would have been received on the first failed write to that + +``` +Page 452 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +attribute. +i. For example, if a write is an attempt to replace a list, but the data version has changed +since the atomic write began due to a command invocation, the status code would be +DATA_VERSION_MISMATCH. +b. Otherwise, the status code SHALL be SUCCESS. +``` +4. If the status code of any AtomicAttributeStatusStruct in the list is not SUCCESS, then the server + SHALL: + a. Discard all pending writes to the attributes associated with the Atomic Write State associ­ + ated with the client + b. Discard the Atomic Write State associated with the client + c. Return an AtomicResponse with the list of attribute statuses and an atomic status code of + FAILURE. +5. Otherwise, if the writes would collectively violate a constraint, then the server SHALL: + a. Discard all pending writes to the attributes associated with the Atomic Write State associ­ + ated with the client + b. Discard the Atomic Write State associated with the client + c. Return an AtomicResponse with the list of attribute statuses and an atomic status code of + CONSTRAINT_ERROR. +6. Otherwise, the server SHALL: + a. Create a list of attribute statuses for each attribute referenced by a pending write + b. Attempt to apply all pending writes to the attributes in the Atomic Write State associated + with the client: + i. For each pending write, write the pending value to the attribute, and store the returned + status code in the status code field on the attribute status whose AttributeID matches the + ID of the attribute. +ii. If any pending write fails, return an AtomicResponse with an atomic status code of FAIL­ +URE and the list of attribute statuses. +iii. Otherwise, return an AtomicResponse with an atomic status code of SUCCESS and an +empty list of attribute statuses. + c. Discard the Atomic Write State associated with the client + +**Rollback Write** + +If the RequestType of the AtomicRequest is RollbackWrite, the server SHALL attempt to rollback +any pending writes and return an AtomicResponse. + +1. If the client is not associated with an Atomic Write State whose endpoint-no and cluster-id + match the endpoint number and ID of the cluster instance handling the request, and whose set + of attrib-ids match the attrib-ids requested, irrespective of order, the server SHALL return an + error code of INVALID_IN_STATE. +2. Otherwise, the server SHALL: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 453 +``` + +``` +a.Discard all pending writes to the attributes associated with the Atomic Write State associ­ +ated with the client +b. Discard the Atomic Write State associated with the client +c.Return an AtomicResponse with an atomic status code of SUCCESS. +``` +**7.15.7. AtomicResponse Command** + +The AtomicResponse command is sent by a server in response to an AtomicRequest command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StatusCode status M +1 AttributeS­ +tatus +``` +``` +list[Atomi­ +cAttributeS­ +tatusStruct] +``` +### M + +``` +2 Timeout uint16 desc +``` +**7.15.7.1. StatusCode Field** + +This field SHALL indicate the status of the atomic write. See AtomicRequest. + +**7.15.7.2. AttributeStatus Field** + +This field SHALL indicate a list of statuses for the attributes involved in the atomic write. This list +SHALL contain a status for each of the attribute IDs provided in the AtomicRequest. See AtomicRe­ +quest. + +**7.15.7.3. Timeout Field** + +This field SHALL indicate an effective timeout provided by the server. If the value of the Request­ +Type field in the AtomicRequest is BeginWrite, this field SHALL be included, otherwise it SHALL be +omitted. See AtomicRequest. + +**7.16. Device Type** + +In this architecture model, a device type is the highest semantic element. A device type defines con­ +formance for a set of one or more endpoints. A device type defines a set of requirements for the +node or endpoint in the market. + +A device type SHALL define the cluster support for an endpoint. A composed device type MAY +define one or more other device types as part of the composed device type. + +A device type definition MAY define or use predefined conditions from requirements, limitations +and/or capabilities of the node. A device type definition MAY define or use predefined conditions on +one or more underlying stack standard(s). + +A device type MAY define support of a cluster as dependent upon a condition. A device type defini­ + +``` +Page 454 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +tion MAY specify optional clusters that are recommended as enhancements. + +A device type definition MAY refine cluster conformance: + +- Support of optional cluster elements or features MAY be changed to mandatory depending on + device type conditions. +- Support of optional cluster elements or features MAY depend on device type conditions. + +A device type definition SHALL specify a device type ID, device revision, and a set of one or more +mandatory clusters including each cluster’s minimum revision. + +A device type definition MAY be generic and allow many similar clusters, where at least one +instance SHALL be required. + +``` +For example: a simple sensor device. +``` +If all sensor devices are common in cluster requirements (except the clusters that perform the sens­ +ing), then there is no reason to create a device type for each sensor cluster. + +A device type definition MAY be very specific and list particular clusters as mandatory. + +``` +For example: a door lock device or thermostat. +``` +**7.16.1. Device Type Revision** + +A device type revision is an unsigned integer that is associated with an approved revision and +release of a device type definition. The initial value for a device type revision SHALL be 1. The ini­ +tial revision (1) of a device type definition SHALL require the latest (at the time of definition the +cluster) certifiable revisions of the clusters it mandates. Any mandatory changes to the device type +definition SHALL only augment, not modify, the function of the device. Any changes SHALL incre­ +ment the version of the device. Newer versions of the device SHALL interoperate with older revi­ +sions at the older revision’s level of functionality. + +``` +Examples of changes to a device type definition that require incrementing the revision: +``` +- Mandating a higher revision of one or more mandatory clusters +- Changing an item from optional to mandatory +- Deprecating parts of the device type definition + +**7.16.2. Device Type Composition** + +A device type definition MAY be a composed device type and therefore require other device types +for its composition. A device type instance MAY be composed of other endpoints that support extra +cluster instances. Please see the System Model specification for more details. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 455 +``` + +**7.16.3. Device Type Classification** + +Each device type definition SHALL specify the endpoint as being either a Utility, or Application. +Each device type definition SHALL specify the scope as either endpoint or node. Each Application +device type definition SHALL specify the endpoint as being either Simple or Dynamic. + +**7.16.3.1. Utility Device Type** + +A Utility device type supports configuration and settings. A utility device type definition SHALL +define requirements for utility clusters. A utility device type MAY also represent the physical device +or product. There MAY be more than one endpoint supporting a utility device type on a node. + +Examples of utility device types: Root Node, Power Source, Bridged Node. + +**7.16.3.2. Application Device Type** + +Application devices types are typically the most common endpoints on a node and in the network. +An endpoint supporting an application device type is an application endpoint. An Application +device type SHALL be scoped to the endpoint. An application endpoint SHALL support clusters the +primary application function of the endpoint. + +Examples of application device type categories: HVAC, lighting, sensing, etc. + +**7.16.3.3. Simple Device Type** + +A Simple device type supports local control that is persistent, independent, and unsupervised. A +Simple device type is an Application device type. Simple devices types are typically the most com­ +mon endpoints in the network. Simple device type examples: sensors, actuators, lights, on/off +switches, on/off power outlets, etc. Simple endpoints support independent operation without cen­ +tral control or gateways. An endpoint supporting a simple device type is a simple endpoint. Simple +endpoints SHALL support relationships through bindings. + +**7.16.3.4. Dynamic Device Type** + +A Dynamic device type supports intelligent and supervisory services, such as commissioning, moni­ +toring, trend analysis, scheduling and central management. A dynamic device type is an application +device type. An endpoint supporting a dynamic device type is a dynamic endpoint. A dynamic end­ +point is typically found on a central controller where there exists an intelligent supervisory applica­ +tion that manages simple device control applications. Typically, a dynamic endpoint supports client +clusters for central control, management, monitoring or supervisory functions. Typically, the prod­ +uct supporting a dynamic endpoint has visibility into the entire network (or part thereof ) of simple +endpoints. + +A dynamic endpoint client cluster instance MAY be used to multiplex transactions to or from multi­ +ple simple device server clusters in the network. A dynamic endpoint client cluster MAY initiate +interactions to many server clusters in the network. A dynamic endpoint client cluster MAY receive +data from many server clusters in the network. Dynamic endpoints MAY support relationships +through bindings. A dynamic device endpoint MAY support one or more external agents, outside +the node stack, that manage relationships. External agents include, but are not limited to, a cloud +application, a smartphone, an in-home display, or a configuration tool. + +``` +Page 456 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.16.3.5. Device Type Scope** + +A node device type is a utility device type scoped to a node. A node device type definition SHALL +support clusters that represent the entire node. An endpoint supporting a node device type is a +node endpoint. A node endpoint MAY also represent the physical device or product. There MAY be +more than one node endpoint on a node. + +Other classes of device types are endpoint scoped device types. + +**7.16.4. Extra Clusters on an Endpoint** + +An endpoint MAY support extra clusters not mandated by the device type definition. An endpoint +MAY support optional features or cluster items (attributes, commands, events, etc.), that are not +mandated by the device type definition. Extra clusters, features, or cluster items, SHALL only aug­ +ment, not modify, the function of the device type or clusters. + +A device type definition MAY list clusters as optional, which implies they can augment the device +type. Clients MAY use those clusters to augment the operation of the other clusters for the device +type. + +In case of clusters appearing on an endpoint which are not listed in the Cluster Requirements table +of a device type definition, there may not be a well-defined standard interpretation with respect to +the context of that device type, so clients MAY ambiguously interpret how, or when, the extra clus­ +ters are intended to be used. Clients MAY ignore any clusters which are not listed in the Cluster +Requirements table of a device type definition when interacting with the endpoint. This is true even +for clusters that would otherwise appear to a client’s or server’s implementer as "obvious". + +**7.16.5. Primary Device Type** + +The Primary Device Type is selected according to the following rules: + +- When a device combines multiple application device types, the manufacturer SHALL choose the + application device type identifier of the primary function of the device as the Primary Device + Type. +- When a device has a single application device type, the manufacturer SHALL use that as the Pri­ + mary Device Type. +- For devices exposing multiple application device types for which the superset device type condi­ + tion holds, the superset device type of the set of device types SHALL be used as Primary Device + Type. + +The Primary Device Type is used in the DCL (field DeviceTypeID), in the Certification Declaration +(field device_type_id) and in announcements (TXT key for device type). Since the DCL field Device­ +TypeID is not mutable, the Primary Device Type cannot change over the lifecycle of a product (e.g. +via a software update). + +Example: A desk lamp contains a light (Extended Color Light) and a switch (Generic Switch) to con­ +trol the light. The Extended Color Light matches the primary function of the device, so this is +selected as Primary Device Type. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 457 +``` + +Example: A dimmable light bulb exposes Dimmable Light and On/Off Light device types. Since Dim­ +mable Light is the superset device type, this is selected as Primary Device Type. + +**7.17. Non-Standard** + +This architecture model provides mechanisms for non-standard or manufacturer specific items +such as clusters, commands, events, attributes and attribute data fields. These items MAY be sup­ +ported on a certified product. Such vendor specific items SHALL NOT change the standard behavior +of the standard items. The specific function of a vendor specific item cannot be tested as part of cer­ +tification. They can only be tested to verify that they do no harm, and conform to proper behavior +with regard to identification, discovery, error processing, etc. A non-standard item SHOULD NOT +take the place of a standard item that provides the same function. It is up to the certification +authority to make a judgment call that is in keeping with the spirit of these requirements. Imple­ +menters are encouraged to develop and certify standard items, not non-standard items. + +**7.18. Data Field** + +A data field is any attribute, field or entry that is not a collection data type, or data that is not sur­ +faced as an attribute, but defined in a cluster specification. + +Optional attribute data MAY be referenced as data fields in other attribute specifications within the +same cluster specification. Cluster specifications also define data fields that are not surfaced, such +as temporary calculated values, or persistent state values. Any defined data value in a cluster speci­ +fication is a data field. + +Each cluster data field SHALL be defined with a table including these columns for data qualities: + +- Data Type +- Constraint +- Quality +- Access +- Default +- Conformance + +A data field SHALL inherit (if possible) the qualities from the cluster first-order element of which it +is part, unless overridden. It SHOULD be rare to override inherited qualities. + +``` +For example: If an attribute is a struct data type, that is readable and writable, then all fields +of the struct are readable and writable. +``` +New or optional data fields might not be recognized by a receiver, such as a legacy receiver. The +data field description SHALL define default behavior (such as absence of behavior) when a new or +optional data field is not present. It is recommended to define or use a feature when adding new or +optional data fields, to better indicate conformance. It is recommended to define a default value, +such as a null value, that indicates such default behavior. + +``` +Page 458 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.18.1. Nullable** + +When a data field value is required to designate an unknown, invalid, or undefined data value, and +there is no obvious data value (e.g. zero), that is within the valid range to indicate this, the data field +MAY be designated as nullable, so that an implemented instance of data MAY have the value of null. + +In this context, these wordings have the same meaning: + +- The data field has the value of null. +- The data field has the null value. +- The data field is the null value. +- The data field is null. + +Representation of null for the implementation of the Data Model is a consideration of the underly­ +ing encoding specification. The encoding layer SHALL have the capability to indicate null for any +nullable data field. How the encoding layer indicates null is outside the scope of the Data Model +specification. + +All data fields MAY be defined to be nullable, regardless of data type. + +A cluster specification SHALL define whether a data field is nullable. A cluster specification SHALL +define the meaning of the null value. + +Composite data types that have a length (i.e. octet string and list), and derived types that have those +as the base type, SHALL NOT differentiate semantically between the null value and the empty (zero +length) value. In particular a zero-length value SHALL be allowed for nullable values of these types +no matter what other length constraints are imposed on the value, and SHALL have the same +semantics as the null value. + +A fabric-scoped list SHALL NOT be nullable. + +**7.18.2. Optional or Deprecated** + +An optional or deprecated data field that is not implemented, and therefore does not exist, SHALL +NOT be indicated as the null value. How the encoding layer encodes non-existent data is outside the +scope of the Data Model specification. + +The Conformance column SHALL define if a data field is optional or deprecated. To manage the +data identifier namespace, a deprecated data field SHALL NOT be removed from text that lists its +identifier and default value. The description text of a deprecated data field SHALL be removed for +new revisions of specification text. + +If the specification text of a cluster depends on the value of an optional or deprecated data field of +the same cluster, then the data field SHALL have a well-defined default value that SHALL be used +when the data field is not implemented. + +**7.18.3. Constraint & Value** + +The tables below describe the nomenclature for describing constraints and default data values. This + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 459 +``` + +nomenclature is used in the cluster specifications for data value constraints, defaults, and other +definitions. + +**7.18.3.1. Common Literal Values** + +These values are commonly used in cluster text and Default columns in cluster data definition +tables. + +``` +Value Description +0 The numeral zero is used to indicate the zero +value for analog data. This is equivalent to the +boolean value FALSE. +1 This is used for any analog data type to mean +that the value is 1. This is equivalent to the +boolean value TRUE. +FALSE "FALSE", "false" or "False" is a boolean value and +is equivalent to 0 (zero). +TRUE "TRUE", "true" or "True" is a boolean value and +is equivalent to 1. +NaN Not a Number defined for any floating point val­ +ues. +null This indicates the value of null. +empty This indicates empty list or string data. +min The minimum possible data value for the data +type. +max The maximum possible data value for the data +type. +numeric units Some number in some well-defined units as +described in the data type (e.g. 100o C) +``` +**7.18.3.2. Constraint** + +The Constraint column is valid for any composed device type, attribute or data field of an attribute, +event, command or struct. It is RECOMMENDED to always define a constraint for any data field. + +``` +Constraint Description +desc Defines the constraint is defined in the descrip­ +tion section +Composed Device Type Constraints +x * Defines the exact number of endpoints, greater +than zero, supporting this device type as a part +of the composed device type +``` +``` +Page 460 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Constraint Description** + +_x_ to _y_ Defines the allowed number of endpoints, +greater than zero, supporting this device type as +a part of the composed device + +max _y_ Defines the maximum number of endpoints, +greater than zero, supporting this device type as +a part of the composed device + +min _x_ Defines the minimum number of endpoints, +greater than zero, supporting this device type as +a part of the composed device + +**Numeric Data Type Constraints** + +_x_ Defines a value that is supported. + +_x_ to _y_ Defines a supported value range. + +max _y_ Defines the value range from min to _y_ + +min _x_ Defines the value range from _x_ to max. + +all Defines that all values are supported. Same as +"min to max". + +_constraint_ , _constraint_ ... Defines support of a union of two or more value +and value range constraints + +**Octet String Data Type Constraints** + +_x_ * Defines the size range in bytes to be exactly _x_ + +_x_ to _y_ Defines the size range in bytes from _x_ to _y_ + +min _x_ Defines that the size limit supported is a mini­ +mum of _x_ bytes + +max _y_ Defines the size limit supported is a maximum +of _x_ bytes + +all Defines no constraint on size of the string. Same +as "min to max". + +_constraint_ , _constraint_ ... Defines support of a union of two or more size +range or size limit constraints + +**List Data Type Constraints** + +_x_ * Defines the range of entries to be exactly _x_ + +_x_ to _y_ Defines the range of entries from _x_ to _y_ + +min _x_ defines the limit supported is a minimum of _x_ +entries + +max _y_ Defines the limit supported is a maximum of _x_ +entries + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 461 +``` + +``` +Constraint Description +all Defines no constraint on the number of entries +in the list. Same as "min to max". +constraint , constraint ... Defines support of a union of two or more list +range or limit constraints +list_constraint [ entry_constraint ] Defines list_constraint as a list constraint and +entry_constraint as a constraint on the entry +data type. See also list entry qualities +Character String Data Type Constraints +char_constraint { z } Defines char_constraint as the string constraint +in bytes and z as the maximum number of Uni­ +code codepoints. +``` +* _x_ , _y_ , or _z_ are literal values of the data type or from the Common Literal Values. + +**7.18.3.3. List and String Constraint** + +The minimum number of entries for list or size of a string SHALL be 0 (zero), unless redefined +using the above notation. + +A comma delimited set of constraints for a list or string defines a union constraint. A union con­ +straint SHALL only have one minimum (min _x_ ) constraint and one maximum (max _y_ ) constraint. A +union constraint SHALL NOT define a range below the minimum constraint or range greater than +the maximum constraint, including the defined minimum (min) and maximum (max) for the data +type. + +A constraint on a list or string data means that the data SHALL always be indicated within that con­ +straint. A constraint on a writeable list or string data means that the data SHALL support writing +within the constraint, and SHALL NOT support writing outside the constraint. + +**7.18.3.4. Effective Maximum for Character String Data Type** + +A server SHALL support up to the maximum in _char_constraint_ for a character string data type. The +character string data SHALL NOT contain more than _z_ Unicode codepoints. + +``` +Example: A string with a constraint of "max 128{32}" dictates that the server provide for a +128 byte string, but the string may contain up to 32 Unicode codepoints. +``` +**7.18.3.5. Nullable in Range** + +If data is nullable then null SHALL be a valid value. + +If the data type is a list or derived from a list, and the list is nullable, then a length of 0 (zero) SHALL +be supported, and defined in the constraint column. + +If the data type is an octet string, or derived from an octet string (e.g. character string), and the data + +``` +Page 462 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +is nullable, then a length of 0 (zero) SHALL be supported, and defined in the constraint column. + +**7.18.4. Default Column** + +A default value defined in the Default column is not meant to be the value used when the server +returns to factory fresh settings. Specified conformance for data fields may be optional or change +over time. A default value is defined to complete dependencies when the actual data field value is +not present. + +A data field SHALL have a defined default value when: + +- the data field is new, and a default is required for backwards compatibility with legacy + instances +- the data field is optional, deprecated, or obsolete and therefore is not always present +- an initial value is needed before the application starts +- the value cannot be determined by the application for the instance +- there is a dependency on the attribute value to formulate other data or affect behavior + +If a default value is not defined for a data field, the default value is determined by the following +conditions: + +- If the data field is nullable then the default value SHALL be null +- Else the default value SHALL be one of the following, depending on type: + ◦ Boolean: false + ◦ Analog: 0 or 0.0, depending on range + ◦ Bitmaps: 0 + ◦ Enumeration: MS + ◦ Composite: + ▪ String: empty + ▪ List: empty + ▪ Struct: default is recursively composited from the defaults of its member fields + ◦ Derived types: use the default value of the base type + +These are the options for the Default column used for attributes or attribute, command or event +data: + +``` +Default Column Description +x a literal value x of the data type, or as defined in +Common Literal Values +MS a manufacturer or implementation specific +value +``` +If the default value of a data field is specified as manufacturer specific, then there SHALL be no + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 463 +``` + +defined default value and the application SHALL support a manufacturer specific value that is in +the valid range. + +**7.19. Data Types** + +Each data field in a cluster specification SHALL have a well-defined data type. Each attribute in a +cluster specification SHALL map to a single data type. + +The table indicates for each data type whether it defines an analog or discrete value. Values of ana­ +log types MAY be added to or subtracted from other values of the same type and are typically used +to measure the value of physical properties that can vary continuously over a range. Values of dis­ +crete data types only have meaning as individual values and SHALL NOT be added or subtracted. + +Some data types specify bit-widths for future potential growth in range (analog) or number of val­ +ues (discrete). + +Cluster specifications SHALL use the unique data type short name to reduce the text size of the +specification. + +**7.19.1. Base Data Types** + +``` +Class Data Type Short ID Size +``` +``` +Discrete +``` +``` +Boolean +Boolean bool 0x10 1 byte +Bitmap +8-bit bitmap map8 0x18 1 byte +16-bit bitmap map16 0x19 2 bytes +32-bit bitmap map32 0x1B 4 bytes +64-bit bitmap map64 0x1F 8 bytes +``` +``` +Page 464 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Class Data Type Short ID Size** + +Analog + +``` +Unsigned Integer +Unsigned 8-bit +integer +``` +``` +uint8 0x20 1 byte +``` +``` +Unsigned 16-bit +integer +``` +``` +uint16 0x21 2 bytes +``` +``` +Unsigned 24-bit +integer +``` +``` +uint24 0x22 3 bytes +``` +``` +Unsigned 32-bit +integer +``` +``` +uint32 0x23 4 bytes +``` +``` +Unsigned 40-bit +integer +``` +``` +uint40 0x24 5 bytes +``` +``` +Unsigned 48-bit +integer +``` +``` +uint48 0x25 6 bytes +``` +``` +Unsigned 56-bit +integer +``` +``` +uint56 0x26 7 bytes +``` +``` +Unsigned 64-bit +integer +``` +``` +uint64 0x27 8 bytes +``` +``` +Signed Integer +Signed 8-bit inte­ +ger +``` +``` +int8 0x28 1 byte +``` +``` +Signed 16-bit inte­ +ger +``` +``` +int16 0x29 2 bytes +``` +``` +Signed 24-bit inte­ +ger +``` +``` +int24 0x2A 3 bytes +``` +``` +Signed 32-bit inte­ +ger +``` +``` +int32 0x2B 4 bytes +``` +``` +Signed 40-bit inte­ +ger +``` +``` +int40 0x2C 5 bytes +``` +``` +Signed 48-bit inte­ +ger +``` +``` +int48 0x2D 6 bytes +``` +``` +Signed 56-bit inte­ +ger +``` +``` +int56 0x2E 7 bytes +``` +``` +Signed 64-bit inte­ +ger +``` +``` +int64 0x2F 8 bytes +``` +Analog + +``` +Floating Point +Single precision single 0x39 4 bytes +Double precision double 0x3A 8 bytes +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 465 +``` + +``` +Class Data Type Short ID Size +``` +``` +Composite +``` +``` +String +Octet string octstr 0x41 desc +Collection +List list 0x48 desc +Struct struct 0x4C desc +``` +**7.19.1.1. Boolean Type** + +The Boolean type represents a logical value, either FALSE or TRUE. + +- FALSE SHALL be equivalent to the value 0 (zero). +- TRUE SHALL be equivalent to the value 1 (one). + +**7.19.1.2. Bitmap Type (8, 16, 32 and 64-bit)** + +This data type is typically used to represent simple cluster settings or state that are treated as +whole. + +The Reserved Bit Fields conventions define reserved bitmap data. + +- It is RECOMMENDED to define more bits than initially needed to be able to support more values + for later revisions. +- The Bitmap type MAY be used to support up to 8, 16, 32 or 64 boolean values. +- Bits MAY be combined to enumerate other values. +- Bits SHOULD be combined as contiguous bit fields. +- Future revisions MAY require non-contiguous bit fields. +- The conformance for a bit in a bitmap SHALL be mandatory or dependent upon an existing dis­ + coverable element, and therefore SHALL NOT be purely optional. + +Allowable Conformance for a bit in a bitmap: + +- Mandatory +- Dependent upon a Feature supported in the FeatureMap attribute. +- Dependent upon the support of an attribute. + +A nullable bitmap SHALL NOT permit use of the most significant bit. + +**7.19.1.3. Unsigned Integer (8, 16, 24, 32, 40, 48, 56 and 64-bit)** + +This type represents an unsigned integer with length of N bits and a usable range of: + +- [0..2N-1] if not nullable OR +- [0..2N-2] if nullable. + +``` +Page 466 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The following table presents the representable values following the above rules: + +``` +Width N (bits) Minimum value Maximum value +if nullable +``` +``` +Maximum value +if not nullable +8 0 +(0x00) +``` +### 254 + +``` +(0xFE) +``` +### 255 + +``` +(0xFF) +16 0 +(0x0000) +``` +### 65534 + +``` +(0xFFFE) +``` +### 65535 + +``` +(0xFFFF) +24 0 +(0x000000) +``` +### 16777214 + +``` +(0xFFFFFE) +``` +### 16777215 + +``` +(0xFFFFFF) +32 0 +(0x00000000) +``` +### 4294967294 + +``` +(0xFFFFFFFE) +``` +### 4294967295 + +``` +(0xFFFFFFFF) +40 0 +(0x0000000000) +``` +### 1099511627774 + +``` +(0xFFFFFFFFFE) +``` +### 1099511627775 + +``` +(0xFFFFFFFFFF) +48 0 +(0x000000000000) +``` +### 281474976710654 + +``` +(0xFFFFFFFFFFFE) +``` +### 281474976710655 + +``` +(0xFFFFFFFFFFFF) +56 0 +(0x00000000000000) +``` +### 72057594037927934 + +``` +(0xFFFFFFFFFFFFFE) +``` +### 72057594037927935 + +``` +(0xFFFFFFFFFFFFFF) +64 0 +(0x0000000000000000) +``` +### 18446744073709551614 + +``` +(0xFFFFFFFFFFFFFFFE) +``` +### 18446744073709551615 + +``` +(0xFFFFFFFFFFFFFFFF) +``` +**7.19.1.4. Signed Integer Type (8, 16, 24, 32, 40, 48, 56 and 64-bit)** + +This type represents an signed integer with length of N bits and a usable range of: + +- [-(2(N-1))..2(N-1)-1] if not nullable OR +- [-(2(N-1)-1)..2(N-1)-1] if nullable. + +Whether to use two’s complement or another representation for the implementation of the Data +Model is a consideration of the underlying encoding specification. + +The following table presents the representable values in base-10 following the above rules: + +``` +Width N (bits) Minimum value +if nullable +``` +``` +Minimum value +if not nullable +``` +``` +Maximum value +``` +### 8 -127 -128 127 + +### 16 -32767 -32768 32767 + +### 24 -8388607 -8388608 8388607 + +### 32 -2147483647 -2147483648 2147483647 + +### 40 -549755813887 -549755813888 549755813887 + +### 48 -140737488355327 -140737488355328 140737488355327 + +### 56 -36028797018963967 -36028797018963968 36028797018963967 + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 467 +``` + +``` +Width N (bits) Minimum value +if nullable +``` +``` +Minimum value +if not nullable +``` +``` +Maximum value +``` +### 64 -9223372036854775807 -9223372036854775808 9223372036854775807 + +**7.19.1.5. Single-Precision Type** + +The single precision number format is based on the IEEE 754-2019 single precision (32-bit) format +for binary floating-point arithmetic. + +See IEEE 754-2019 for more details on the representable values. + +**7.19.1.6. Double Precision Type** + +The double precision number format is based on the IEEE 754-2019 double precision (64-bit) format +for binary floating-point arithmetic. + +The format and interpretation of values of this data type follow the same rules as given for the sin­ +gle precision data type, but with wider mantissa and exponent ranges. + +See IEEE 754-2019 for more details on the representable values. + +**7.19.1.7. Octet String Type** + +The octet string data type defines a sequence of octets with a finite octet count from 0 to 65534. It is +RECOMMENDED to define a constraint on the maximum possible count. + +**7.19.1.8. List** + +A list is defined as a collection of entries of the same data type, with a finite count from 0 to 65534. +A cluster specification may define further constraints on the maximum possible count. The list +entry data type SHALL be any defined data type, except a list data type, or any data type derived +from a list. + +The quality columns for a list definition are for the list. + +The list entries are indicated with an index that is an unsigned integer starting at 0 (zero). The +maintained order of entries, by index, is defined in the cluster specification, or undefined. Data that +is defined as a list is indicated with "list[ _X_ ]" where _X_ is the entry type. The data type of the list entry +has its own qualities, constraints, and conformance. + +To define qualities for the list entry data type, make the list entry data type a defined local derived +data type, with a table including the columns required to define and constrain the data type. + +``` +For example: Derived data types defined here: +``` +``` +Name Type Constraint Quality ... +Month­ +NameString +``` +``` +string 3 F ... +``` +``` +Page 468 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +MonthNumber uint8 1 to 12 ... +``` +``` +SummerStruct defined here: +``` +``` +ID Name Type Constraint Quality ... +0 Year int16 -1000 to 3000 ... +1 Summer­ +Months +``` +``` +list[Month­ +Number] +``` +``` +max 12 N ... +``` +``` +Used Here: +``` +``` +ID Name Type Constraint Quality ... +0 MonthNames list[Month­ +NameString] +``` +### 12 N ... + +``` +1 SummerYears list[Summer­ +Struct] +``` +``` +max 50 ... +``` +There is an inline shortcut to define the list entry data type constraints. See List Constraints. + +``` +For example: +``` +``` +ID Name Type Constraint Quality ... +0 MonthNames list[string] 12[3] N .... +``` +It is RECOMMENDED to put a maximum constraint on the list and list entry data types. + +It is RECOMMENDED that a list entry data type be a struct, to enable the addition of new fields to +the list’s entries in the future. + +- The cluster data version SHALL be incremented when the list order or entries change. +- An entry SHALL NOT be null. +- The list SHALL support reading and reporting all entries. +- The list SHALL support reporting, updates, and/or deletion of one or more entries. +- If the list is writable, it SHALL support writing or deleting the entire list. +- If the list is writable, it SHALL support updating one or more individual entries by indicating an + index per updated entry. +- If the list is writable, it SHALL support deleting one or more individual entries by indicating an + index per deleted entry. +- If the list is writable, it SHALL support adding one or more individual entries. +- A list MAY define an entry that is a struct that is fabric-scoped (see Fabric-Scoped Quality). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 469 +``` + +**Fabric-Scoped List** + +- A fabric-scoped list SHALL define an entry data type that is a struct, which SHALL also be fab­ + ric-scoped (see Fabric-Scoped Struct). + +Each entry in a fabric-scoped list SHALL be fabric-scoped to a particular fabric or no fabric. + +**Fabric-Filtered List** + +A fabric-scoped list supports a fabric-filter that filters the view of the list for read and write interac­ +tions. This filter simplifies client side logic that does not want to read or write fabric data that is not +associated with the accessing fabric. + +- An interaction upon a list with fabric-filtering SHALL only indicate and access entries where the + associated fabric matches the accessing fabric, and all other entries SHALL be ignored. +- Fabric-filtered list entries SHALL be in the same order as the full list. +- Fabric-filtered list entries SHALL be indexed from 0 with no gaps, as if the other entries did not + exist. +- For a write interaction, fabric-filtering SHALL be enabled. +- When writing to a fabric-scoped list, the write interaction SHALL be on an accessing fabric, oth­ + erwise, the write interaction SHALL fail (see Interaction Model). +- For a read interaction on a list, fabric-filtering MAY be enabled. +- For a read interaction on a list, with fabric-filtering disabled, the list SHALL be reported as a full + list with all entries. + +``` +For example: A fabric-scoped full list with each entry having an associated FabricIndex and +Value field: +``` +``` +list = [ { FabricIndex = A, Value = 20 }, +{ FabricIndex = B, Value = 30 }, +{ FabricIndex = A, Value = 40 }, +{ FabricIndex = B, Value = 50 }, +{ FabricIndex = B, Value = 60 } ] +``` +``` +would be a fabric-filtered list when accessed with fabric B: +``` +``` +list = [ { FabricIndex = B, Value = 30 }, +{ FabricIndex = B, Value = 50 }, +{ FabricIndex = B, Value = 60 } ] +``` +``` +Reading a fabric-filtered list entry index 2 accessed with fabric B reports: +``` +``` +list[2] = [ { FabricIndex = B, Value = 60 } ] +``` +``` +Page 470 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Writing fabric-filtered list entry index 1 when accessed with fabric B: +``` +``` +list[1] = [ { FabricIndex = B, Value = 55 } ] +``` +``` +changes the full list to: +``` +``` +list = [ { FabricIndex = A, Value = 20 }, +{ FabricIndex = B, Value = 30 }, +{ FabricIndex = A, Value = 40 }, +{ FabricIndex = B, Value = 55 }, +{ FabricIndex = B, Value = 60 } ] +``` +**7.19.1.9. Struct Type** + +A struct is a sequence of fields of any data type. Individual fields are identified by a field ID of +unsigned integer, starting at 0 (zero), for the first field. + +- A struct itself SHALL have no constraint qualities. +- Each struct field SHALL have its own qualities. +- Access, conformance and persistence qualities, when not explicitly defined, SHALL be inherited + from the instance of the struct itself. +- Struct fields MAY have optional conformance. +- A struct SHALL support reading and reporting of all fields. +- A struct SHALL support reporting changes to one or more fields. +- If the struct is writable, it SHALL support writing the entire struct. +- If a field of the struct is writable, the struct SHALL support updating the field. +- Because of optional struct field conformance, instances of the same struct MAY support multiple + 'flavors' of the same struct data type, but with a different set of optional fields. + +**Fabric-Scoped Struct** + +- A fabric-scoped struct SHALL only be defined and occur as an entry in a fabric-scoped list. +- A fabric-scoped struct SHALL support the global FabricIndex field of type fabric-index, which + indicates the associated fabric of the struct, or indicates that there is no associated fabric. +- The table that defines fields of a fabric-scoped struct SHALL NOT list the global FabricIndex + field, which is a global field and defined implicitly. +- The global FabricIndex field of a fabric-scoped struct SHOULD NOT be indicated in a write inter­ + action. +- The global FabricIndex field of a fabric-scoped struct SHALL be ignored in a write interaction. +- The global FabricIndex field SHOULD NOT be indicated on a fabric-scoped struct contained in + the payload of a command request. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 471 +``` + +- The global FabricIndex field SHALL be ignored on a fabric-scoped struct contained in the pay­ + load of a command request. +- When a write interaction creates a fabric-scoped struct entry (in a fabric-scoped list), the server + SHALL implicitly load the accessing fabric-index into the global FabricIndex field of the struct. +- When the payload of a command request contains a fabric-scoped struct, the server SHALL + implicitly load the accessing fabric-index into the global FabricIndex field of the struct. +- A fabric-scoped struct MAY be defined with some fields that are fabric-sensitive. +- For interactions on a fabric-scoped struct that report back data, fabric-sensitive struct fields + SHALL NOT be indicated when reporting data back to the client, when the struct has an associ­ + ated fabric, and it is not the accessing fabric. + +**7.19.2. Derived Data Types** + +These data types are commonly used and derived from the base data types. If a data type is used by +more than one cluster specification, then it SHALL be listed here as a derived data type. Such com­ +mon data types can then be reused instead of redefined in each cluster specification. + +``` +Page 472 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Class Data Type Short Base Type ID Size** + +Analog + +``` +Relative +Percentage +units 1% +``` +``` +percent uint8 0xE6 1 bytes +``` +``` +Percentage +units 0.01% +``` +``` +percent100ths uint16 0xE7 2 bytes +``` +``` +Time +Time of day tod struct 0xE0 4 bytes +Date date struct 0xE1 4 bytes +Epoch Time in +microseconds +``` +``` +epoch-us uint64 0xE3 8 bytes +``` +``` +Epoch Time in +seconds +``` +``` +epoch-s uint32 0xE4 4 bytes +``` +``` +UTC Time utc same as Epoch Time in Seconds but Deprecated +POSIX Time in +milliseconds +``` +``` +posix-ms uint64 0xE5 8 bytes +``` +``` +System Time in +microseconds +``` +``` +systime-us uint64 0xD0 8 bytes +``` +``` +System Time in +milliseconds +``` +``` +systime-ms uint64 0xD1 8 bytes +``` +``` +Elapsed Time +in seconds +``` +``` +elapsed-s uint32 0xD2 4 bytes +``` +``` +Physical Quantities +Temperature temperature int16 0xD8 2 bytes +Power power-mW int64 0xD9 8 bytes +Amperage amperage-mA int64 0xDA 8 bytes +Voltage voltage-mW int64 0xDB 8 bytes +Energy energy-mWh int64 0xDC 8 bytes +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 473 +``` + +``` +Class Data Type Short Base Type ID Size +``` +``` +Discrete +``` +``` +Enumeration +8-bit enumera­ +tion +``` +``` +enum8 uint8 0x30 1 byte +``` +``` +16-bit enumer­ +ation +``` +``` +enum16 uint16 0x31 2 bytes +``` +``` +Priority priority enum8 0x32 1 byte +Status Code status enum8 0x33 1 byte +Identifier +Group ID group-id uint16 0xC0 2 bytes +Endpoint Num­ +ber +``` +``` +endpoint-no uint16 0xC1 2 bytes +``` +``` +Vendor ID vendor-id uint16 0xC2 2 bytes +Device Type ID devtype-id uint32 0xC3 4 bytes +Fabric ID fabric-id uint64 0xC4 8 bytes +Fabric Index fabric-idx uint8 0xC5 1 byte +Cluster ID cluster-id uint32 0xE8 4 bytes +Attribute ID attrib-id uint32 0xE9 4 bytes +Field ID field-id uint32 0xEB 4 bytes +Event ID event-id uint32 0xEC 4 bytes +Command ID command-id uint32 0xED 4 bytes +Action ID action-id uint8 0xEE 1 bytes +Transaction ID trans-id uint32 0xEF 4 bytes +Node ID node-id uint64 0xF0 8 bytes +IEEE Address EUI64 same as Node ID but Deprecated +Index +Entry Index entry-idx uint16 0xC6 2 bytes +Counter +Data Version data-ver uint32 0xC7 4 bytes +Event Number event-no uint64 0xC8 8 bytes +``` +Page 474 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +Class Data Type Short Base Type ID Size +``` +``` +Composite +``` +``` +String +Character +String +``` +``` +string octstr 0x42 desc +``` +``` +Address +IP Address ipadr octstr 0xF2 4 or 16 bytes +IPv4 Address ipv4adr octstr 0xF3 4 bytes +IPv6 Address ipv6adr octstr 0xF4 16 bytes +IPv6 Prefix ipv6pre octstr 0xF5 1 to 17 bytes +Hardware +Address +``` +``` +hwadr octstr 0xF6 6 or 8 bytes +``` +``` +Tag +Semantic Tag semtag struct 0xC9 4 bytes +Namespace namespace enum8 0xCA 1 byte +Tag tag enum8 0xCB 1 byte +Location +Location +Descriptor +``` +``` +locationdesc struct 0xCC variable +``` +**7.19.2.1. Percentage Type** + +A Percentage is an unsigned 8-bit value representing percent with a resolution of 1%. The range is +from 0 (0%) to 100 (100%). + +**7.19.2.2. Percentage100ths Type** + +A Percentage 100ths is an unsigned 16-bit value representing percent with a resolution of 0.01%. +The range is from 0 (0.00%) to 10000 (100.00%). + +**7.19.2.3. Time of Day Type** + +The Time of Day data type SHALL be a struct with these fields: Hours, Minutes, Seconds, and Hun­ +dredths. + +The hours field represents hours according to a 24-hour clock. The range is from 0 to 23. The min­ +utes field represents minutes of the current hour. The range is from 0 to 59. The seconds field repre­ +sents seconds of the current minute. The range is from 0 to 59. The hundredths field represents +100ths of the current second. The range is from 0 to 99. A value of null in any subfield indicates an +unused subfield. If all subfields have a value of null, this indicates a null time of day. + +**7.19.2.4. Date Type** + +This data type SHALL be a struct as defined below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 475 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Year uint8 all X null M +1 Month uint8 1 to 12 X null M +2 Day uint8 1 to 31 X null M +3 Day­ +OfWeek +``` +``` +uint8 1 to 7 X null M +``` +Valid combinations using null fields are shown below: + +``` +Year Month Day DayOfWeek Meaning +2023 6 9 5 2023-June-09 +which is a Friday +2023 6 null null 2023-June +2023 null null null 2023 +null 6 9 null June-09 if this year +null null 9 null the 9th of this +month +null null null 5 Friday of this +week +null null null null no date +``` +**Year Field** + +The year subfield represents years from 1900 (0) to 2155 (255). + +**Month Field** + +This field represents months January (1) to December (12). + +**Day Field** + +This field represents the day of the month. Note that values in the range 29 to 31 may be invalid, +depending on the month and year. + +**DayOfWeek Field** + +This represents the day of the week from Monday (1) to Sunday (7). + +**7.19.2.5. Epoch Time in Microseconds Type** + +This type represents an offset, in microseconds, from 0 hours, 0 minutes, 0 seconds, on the 1st of +January, 2000 UTC (the Epoch), encoded as an unsigned 64-bit scalar value. + +This offset is the sum of two parts: time elapsed, not counting leap-seconds, and a local time offset. +The local time offset MAY include a timezone offset and a MAY include a DST offset. + +``` +Page 476 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Any use of this type SHALL indicate how the associated local time offset is determined in the spe­ +cific context of that use. This MAY be done, for example, by simply saying the time is a UTC time, in +which case the local time offset is 0. + +A given Epoch Time value MAY be interpreted in at least two ways: + +1. The value can be converted to a local clock date/time (year, month, day, hours, minutes, sec­ + onds, microseconds) by treating the local time offset as 0 and finding the UTC (year, month, day, + hours, minutes, seconds, microseconds) tuple that corresponds to an elapsed time since the + epoch time equal to the given value. The value then represents that tuple, but interpreted in the + specific timezone and DST situation associated with the value. This procedure does not require + knowing the local time offset of the value. +2. The value can be converted to a UTC time by subtracting the associated local time offset from + the Epoch Time value and then treating the resulting value as an elapsed count of microseconds + since the epoch time. + +For example, an Epoch Time value of 0x0000_0BF1_B7E1_0000 corresponds to an offset of exactly +152 days. This can be interpreted as "00:00:00 on June 1, 2000" in whatever local time zone is associ­ +ated with the value. That corresponds to the following times in ISO 8601 notation: + +- 2000-06-01T00:00Z if the associated local time offset is 0 (i.e. the value is in UTC). +- 2000-05-31T23:00Z if the associated local time offset is +1 hour (e.g. the CET timezone, without + daylight savings). +- 2000-06-01T00:00+02 if the associated local time offset is +1 hour. +- 2000-06-01T04:00Z if the associated local time offset is -4 hours (e.g. the EDT time zone, which + includes daylight savings). +- 2000-06-01T00:00-04 if the associated local time offset is -4 hours. + +**Conversion from NTP timestamps** + +Timestamps from NTP also do not count leap seconds, but have a different epoch. NTP 128-bit time­ +stamps consist of a 64-bit seconds portion (NTP(s)) and a 64-bit fractional seconds portion +(NTP(frac)). NTP(s) at 00:00:00 can be calculated from the Modified Julian Day (MJD) as follows: + +NTP(s) = (MJD-15020) * (24*60*60) + +where 15020 is the MJD on January 1, 1900 (the NTP epoch) + +NTP(s) on January 1, 2000 00:00:00 UTC (MJD = 51544) is 3155673600 (0xBC17C200) + +Epoch Time has a microsecond precision, and this precision can be achieved by using the most sig­ +nificant 32 bits of the fractional portion (NTP(frac32)). Conversion between the 128-bit NTP time­ +stamps and a UTC Epoch Time in Microseconds is as follows: + +UTC Epoch Time = (NTP(s) - 0xBC17C200)*10^6 + ((NTP(frac32)*10^6) / 2^32) where all numbers are +treated as unsigned 64-bit integers and the division is integer division. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 477 +``` + +**7.19.2.6. Epoch Time in Seconds Type** + +This type has the same semantics as Epoch Time in Microseconds, except that: + +- the value encodes an offset in seconds, rather than microseconds; +- the value is encoded as an unsigned 32-bit scalar, rather than 64-bit. + +This type is employed where compactness of representation is important and where the resolution +of seconds is still satisfactory. + +**7.19.2.7. POSIX Time in milliseconds Type** + +This type represents an offset, in milliseconds, from the UNIX epoch (1970-01-01 00:00:00 UTC), +encoded as an unsigned 64-bit scalar value. + +This type is employed for compatibility reasons. + +**7.19.2.8. System Time in microseconds Type** + +System time in microseconds is an unsigned 64-bit value representing the number of microseconds +since boot. + +**7.19.2.9. System Time in milliseconds Type** + +System time in milliseconds is an unsigned 64-bit value representing the number of milliseconds +since boot. + +This type is employed for compatibility reasons. + +**7.19.2.10. Elapsed Time in seconds Type** + +Elapsed time in seconds is an unsigned 32-bit value representing the time that has elapsed for an +operation or other activity, as determined by the definition of the attribute using this type. + +**7.19.2.11. Temperature Type** + +This type, derived from int16, represents a temperature on the Celsius scale with a resolution of +0.01°C. + +- _value_ = ( _temperature in °C_ ) x 100 + +### • -4°C ⇒ -400 + +### • 123.45°C ⇒ 12345 + +The range is constrained by absolute zero: -273.15°C to 327.67°C. + +**Conversion of Temperature Values for Display** + +When converting temperature values for display manufacturers SHOULD ensure that calculations +**round** to the nearest representable value. Particular care is needed when using integer arithmetic. + +``` +Page 478 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +For example, assuming a display resolution of 0.5: +``` +``` +Attribute value Temperature Display as +°C/100 °C °F °C °F +1965 19.65 67.37 19.5 67.5 +-545 -5.45 22.19 -5.5 22 +-1823 -18.23 -0.81 -18 -1 +``` +**Sample Conversion Code** + +Sample code provided to ensure consistent Fahrenheit to Celsius and vice-versa conversion +between devices and across vendors. + +For degF: the value is a int8u representing 2x temperature +value in Fahrenheit (to get 0.5 resolution). + +For degC: the value is a int16s representing Celsius in +0.01 resolution as expected by the ZCL format. + +### /* + +``` + * Function : translateZclTemp() + * Description : Converts the temperature setpoints in ZCL + * to the half degF format. + * The half degF format is 8-bit unsigned, + * and represents 2x temperature value in + * Fahrenheit (to get 0.5 resolution). + * The format used in ZCL is 16-bit signed + * in Celsius and multiplied by 100 + * to get 0.01 resolution. + * e.g. 2500 (25.00 deg C) ---> 0x9A (77 deg F) + * Input Para : Temperature in ZCL (degC) format + * Output Para: Temperature in half DegF format + */ +int8u translateZclTemp(int16s temperature) +{ +int32s x = temperature; +// rearrangement of +// = (x * (9/5) / 100 + 32) * 2; +// the added 250 is for proper rounding. +// a rounding technique that only works +// with positive numbers +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 479 +``` + +``` +return (int8u) ((x*9*2 + 250)/ (5*100) + 64); +} +``` +### /* + +``` + * Function : translateDegFTemp + * Description : Converts the temperature in DegF + * protocol to the format + * expected by the cluster attribute + * Measured Value in the + * Temperature Measurement + * Information Attribute Set. + * The half deg F format is 8-bit + * unsigned, and represents + * 2x temperature value in + * Fahrenheit (to get 0.5 resolution). + * The format expected by cluster + * is 16-bit signed in Celsius and + * multiplied by 100 to get + * 0.01 resolution. + * e.g. 0x9A (77 deg F) ---> 2500 (25.00 deg C) + * Input Para : temperature in DegF format + * Output Para: temperature in ZCL format + */ +int16s translateDegFTemp(int8u temperature) +{ +int32s x = temperature; +``` +``` +// rearrangement of +// = 100 * (x/2 - 32) * 5/9 +// *1000 (should be 100), +90, then /10, +// is for rounding. +``` +``` +return (int16s) (((x - 64)*5*1000 + 90) / (10*2*9)); +} +``` +**7.19.2.12. Power Type** + +This type, derived from int64, represents power measured in milliwatts. + +**7.19.2.13. Amperage Type** + +This type, derived from int64, represents amperage measured in milliamps. + +``` +Page 480 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.19.2.14. Voltage Type** + +This type, derived from int64, represents voltage measured in millivolts. + +**7.19.2.15. Energy Type** + +This type, derived from int64, represents energy measured in milliwatt-hours. + +**7.19.2.16. Enumeration Type (8-bit, 16-bit)** + +This data type employs scalars to represent context-specific values available from an enumerated +set. This data type is nullable. + +A data field of this type SHALL have well-defined values with well-defined conformance for imple­ +mentation. A base cluster that requires derivation MAY defer the definition of all or some enumer­ +ated values to the derivation that can be implemented. Such a base cluster MAY also define con­ +straints, such as ranges and semantics of those ranges for the enumeration. + +Values for an enumeration MAY be defined directly in a cluster specification, in a derived cluster +specification, or in a separate namespace defined in the cluster specification. For examples, please +see uses of the SemanticTagStruct data type that supports many (and any) standard namespaces. + +Undefined values or ranges SHALL be considered reserved and SHALL NOT be implemented. + +External standards may be referenced as well as listing the values for the external standard. If the +external standard adds values after a specification is adopted, those new values are allowed, but +optional. + +Enumeration values are defined in a table with a Conformance column. When the definition of an +enumeration is missing a Conformance column, all values SHALL be considered to have mandatory +conformance. + +All mandatory readable enumeration values SHALL be understood by the client. All mandatory +writable enumeration values SHALL be understood by the server. + +If a client indicates an enumeration value to the server, that is not supported by the server, because +it is optional, deprecated, or a new value unrecognized by a legacy server, then the server SHALL +respond with the status code CONSTRAINT_ERROR, unless the cluster defines alternate behavior, +such as: + +- convert the value to a mandatory value +- ignore the value +- generate a cluster specific error + +With regard to revising a cluster specification: + +- It is RECOMMENDED that a client be as strict as possible by indicating only values that a server + supports. +- It is RECOMMENDED that the server be as forgiving as possible when processing unsupported + values. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 481 +``` + +Note that indicated enumerations MAY comprise only a strict subset of the required enumerations. + +``` +For example: If a server implementation can never enter an enumerated state XYZ , then the +value XYZ would never be indicated, therefore the server would not have to support XYZ. +``` +**8-bit Enumeration** + +This type is used for enumeration types that need no more than 256 possible values. + +**16-bit Enumeration** + +This type is used for enumeration types that need more than 256 (but less than 65,536) possible val­ +ues. + +**7.19.2.17. Priority Type** + +This is an enumeration of priority used to tag events and possibly other data. The data type does +not define any particular ordering among the values. Specific uses of the data type may assign +semantics to the values that imply an ordering relationship. + +``` +Value Priority Description +0 DEBUG Information for engineering +debugging/troubleshooting +1 INFO Information that either drives +customer facing features or pro­ +vides insights into device func­ +tions that are used to drive ana­ +lytics use cases +2 CRITICAL Information or notification that +impacts safety, a critical func­ +tion, or ongoing reliable opera­ +tion of the node or application +supported on an endpoint. +``` +**7.19.2.18. Status Code Type** + +An enumeration value that means a success or error status. A status code is indicated as a response +to an action in an interaction (see Interaction Model). + +A status code SHALL be one of: + +- a common status code from the set defined in the Interaction Model status code table; +- a cluster status code that is scoped to a particular cluster. + +The following table defines the enumeration ranges for status codes. + +``` +Page 482 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Status Code Range Description +0x00 common status code: SUCCESS +0x01 common status code: FAILURE +0x02 to 0x10 cluster scoped status codes +0x70 to 0xCF other common status codes defined in Interac­ +tion Model Status Code Table. +``` +Status codes in an undefined range, or status codes undefined within a range are reserved and +SHALL NOT be indicated. + +**7.19.2.19. Fabric ID Type** + +A value to identify a fabric. + +**7.19.2.20. Fabric Index Type** + +This is an index that maps to a particular fabric on the node, see Fabric-Index. It is used for: + +- the accessing fabric index of an interaction +- the FabricIndex global field in fabric-scoped data + +**7.19.2.21. Node ID Type** + +A 64-bit ID for a node scoped and unique to a particular fabric as indicated by an accompanying +fabric-index adjacent instantiation. + +**7.19.2.22. Group ID Type** + +A 16-bit ID for a group scoped to a particular fabric as indicated by an accompanying fabric index +adjacent instantiation. + +**7.19.2.23. Endpoint Number Type** + +An unsigned number that indicates an instance of a device type. Endpoint numbers SHALL NOT be +0xFFFF, to allow all endpoint number values to be expressible in nullable endpoint-no fields. + +**7.19.2.24. Vendor ID Type** + +A Vendor ID. + +Vendor IDs MAY be used as a prefix in a Manufacturer Extensible Identifier format. + +**7.19.2.25. Device Type ID Type** + +An identifier that indicates conformance to a device type. + +Device Type IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation +are described in Data Model Types. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 483 +``` + +**7.19.2.26. Cluster ID Type** + +An identifier that indicates conformance to a cluster specification. + +Cluster IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are +described in Data Model Types. + +**7.19.2.27. Attribute ID Type** + +An identifier that indicates an attribute defined in a cluster specification. + +Attribute IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are +described in Data Model Types. + +**7.19.2.28. Field ID Type** + +An identifier that indicates a field defined in a struct. + +Field IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are +described in Data Model Types. + +**7.19.2.29. Event ID Type** + +An identifier that indicates an Event defined in a cluster specification. + +Event IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are +described in Data Model Types. + +**7.19.2.30. Command ID Type** + +An identifier that indicates a command defined in a cluster specification. + +Command IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation +are described in Data Model Types. + +**7.19.2.31. Action ID Type** + +An identifier that indicates an action as defined in the Interaction Model specification. + +**7.19.2.32. Transaction ID Type** + +An identifier for a transaction as defined in the Interaction Model specification, see Transaction ID. + +**7.19.2.33. Entry Index Type** + +This is an index for a list data type. + +**7.19.2.34. Data Version Type** + +An unsigned number that indicates a Data Version Type. + +``` +Page 484 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.19.2.35. Event Number Type** + +An unsigned number that indicates an Event instance. + +**7.19.2.36. Character String Type** + +The character string data type is derived from an octet string. The octets SHALL be characters with +UTF-8 encoding. An instance of this data type SHALL NOT contain truncated code points. + +Note that the character string type is a bounded sequence of characters whose size bound format is +not specified in the data model, but rather a property of the underlying encoding. Therefore, no +assumptions are to be made about the presence or absence of a length prefix or null-terminator +byte, or other implementation considerations. + +It is RECOMMENDED to define constraints on the maximum possible string length. + +If at least one of the code points within the string has value 31 (0x1F), which is Unicode INFORMATION +SEPARATOR 1 and ASCII Unit Separator, then any client making use of the string SHALL only consider +the code points that appear before the first INFORMATION SEPARATOR 1 as being the textual informa­ +tion carried by the string. Any comparison between such a string and other strings SHALL use the +textual component before the first INFORMATION SEPARATOR 1. The remainder of the character string +after a first INFORMATION SEPARATOR 1 is reserved for future use by this specification. Implementa­ +tions of this version of the specification SHALL NOT produce character strings containing INFORMA­ +TION SEPARATOR 1. + +**7.19.2.37. IP Address Types** + +Either an IPv4 or an IPv6 address as defined below. + +**7.19.2.38. IPv4 Address Type** + +The IPv4 address data type is derived from an octet string. The octets SHALL correspond to the four +octets in network byte order that comprise an IPv4 address represented utilizing quad-dotted nota­ +tion. + +Examples of encoding: + +- Address 192.168.2.235 → C0A802EB +- Address 10.4.200.75 → 0A04C84B + +**7.19.2.39. IPv6 Address** + +The IPv6 address data type is derived from an octet string. The octets SHALL correspond to the full +16 octets that comprise an IPv6 address as defined by RFC 4291. The octets SHALL be presented in +network byte order. + +Examples of encoding: + +- Address 2001:DB8:0:0:8:800:200C:417A → 20010DB80000000000080800200C417A +- Address 2001:0DB8:1122:3344:5566:7788:99AA:BBCC → 20010DB8112233445566778899AABBCC + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 485 +``` + +**7.19.2.40. IPv6 Prefix** + +The IPv6 prefix data type is derived from an octet string. The octets SHALL be encoded such that: + +- The first octet SHALL encode the prefix length, in bits, in the range of 0 to 128. + ◦ A value of 0 indicates an absent/invalid prefix. +- The subsequent octets SHALL encode the contiguous leftmost bits of the prefix, in network byte + order, with left justification, such that the first bit of the prefix is in the most significant bit of + the first octet. Encoding SHOULD use the least number of bytes to encode the prefix but MAY + include unused trailing zeroes. + +Examples of encoding: + +- Preferred minimal encoding: Prefix 2001:0DB8:0:CD30::/60 → 9 octets → 3C20010DB80000CD30 +- Preferred minimal encoding: Prefix 2001:0DB8:BB00::/40 → 6 octets → 2820010DB8BB +- Allowed non-minimal encoding: Prefix 2001:0DB8:BB00::/40 → 7 octets → 2820010DB8BB00 + +**7.19.2.41. Hardware Address Type** + +The Hardware Address data type SHALL be either a 48-bit IEEE MAC Address or a 64-bit IEEE MAC +Address (e.g. EUI-64). The order of bytes is Big-Endian or display mode, where the first byte in the +string is the left most or highest order byte. + +**7.19.2.42. SemanticTagStruct Type** + +This data type SHALL be represented by the following structure: + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 MfgCode vendor-id X null M +1 Name­ +spaceID +``` +``` +namespace M +``` +``` +2 Tag tag M +3 Label string max 64 X null MfgCode != +null, O +``` +**MfgCode Field** + +If the MfgCode field is not null, it SHALL be the Vendor ID of the manufacturer who has defined a +certain namespace and the NamespaceID field SHALL be the ID of a namespace defined by the +manufacturer identified in the MfgCode field. + +If a manufacturer specific Tag field is indicated in a list of SemanticTagStruct entries, the list SHALL +include at least one standard tag which is not from any manufacturer’s namespace. A standard tag +is a tag from a common namespace, a derived cluster namespace, or an applicable device-specific +namespace. + +``` +Page 486 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +If MfgCode is null, the NamespaceID field SHALL indicate a standard namespace. + +**NamespaceID Field** + +The NamespaceID field SHALL identify a namespace. + +The common and device-specific semantic tag namespaces are listed in StandardNamespaces. + +**Tag Field** + +The Tag field SHALL be the ID of a semantic tag located within the namespace indicated by Name­ +spaceID. + +A device MAY expose tags from the common or device-specific namespaces and from manufac­ +turer-specific namespaces in a single TagList. + +**Label Field** + +The Label field, if present, SHALL contain human-readable text suitable for display on a client. The +content of the Label field is defined by the manufacturer. + +This field SHALL be present when the MfgCode is not null. This field SHOULD NOT be used if the +Tag is from a standard namespace, unless the Tag requires further qualification. For example: A +Tag that has the meaning of "room" in a location namespace, would require the a label string to +qualify the type of room, such as "1", "2b", "Bathroom", etc. + +**7.19.2.43. Namespace Type** + +The Namespace type identifies the namespace used for a semantic tag. + +**7.19.2.44. Tag Type** + +The Tag type SHALL identify a semantic tag located within a namespace. + +**7.19.2.45. LocationDescriptorStruct** + +This data type SHALL be represented by the following structure: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Location­ +Name +``` +``` +string max 128 M +``` +``` +1 FloorNum­ +ber +``` +``` +int16 X M +``` +``` +2 AreaType tag X M +``` +**LocationName Field** + +This field SHALL indicate the name of the location. For example, "blue room". + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 487 +``` + +If the location name is not user provided, the logic that generates it (clients, devices etc.) SHOULD +utilize synthesized user-friendly, understandable, names for the location, rather than opaque val­ +ues such as "private" or "2fe7c241-a50a-4863-896e-c5878da5ed68". + +**FloorNumber Field** + +This field SHALL indicate the level number. Negative values correspond to basement levels. + +Value zero indicates this is the main floor, which typically includes the main entrance to the user’s +home. For a building with multiple levels, it is the client’s responsibility to map each level to/from a +FloorNumber tag value, using the level numbering convention of the region where the client oper­ +ates. For example, if the client operates in Europe, building level 1, which is one level up from the +street level, SHOULD be mapped to FloorNumber tag value 0x1. If the client operates in North +America, building level 1, which is at street level, SHOULD be mapped to FloorNumber tag value +0x0. + +A null value indicates that this information is not available. + +When the clients present the level information for user selection, they SHOULD use the operating +region to determine how to render and map this data. For example, if the client operates in North +America it SHOULD present the user a list that includes entries labeled "basement", "first", "second", +and internally mapped to floor numbers -1, 0, and 1. If operating in Europe, the client SHOULD +present a list that includes entries labeled "basement", "ground", "first", internally mapped to floor +numbers -1, 0, and 1. + +The floor number information is expected to be mostly useful to the clients, rather than the devices, +such as for grouping devices that are located on the same level. For example, an automation may be +defined for all devices located at the basement level (floor number -1). + +### NOTE + +``` +Handling complex level situations, such as half levels (side split houses), or the lev­ +els from an apartment building, is up to the client and/or user. +``` +**AreaType Field** + +This field SHALL be the ID of an area semantic tag, located within the Common Area Namespace. +For example, this tag may indicate that the location refers to a bedroom. + +If this field is null, that indicates that the area type information is not available. + +### NOTE + +``` +This field only indicates the type of the area. Multiple areas of the same type, such +as bedrooms, MAY exist in a user’s home. +``` +**7.20. Manufacturer Specific Extensions** + +This section covers Manufacturer Specific (MS) extensions and how they are supported by identi­ +fiers, paths, wildcards, discoverability, etc. + +``` +Page 488 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.20.1. Manufacturer Extensible Identifiers** + +A Manufacturer Extensible Context (MEC) contains a collection of items which MAY be extended by +manufacturers. Each item in a MEC has a source which is either Standard, Scoped or a particular +Manufacturer Code (MC). + +- A Standard source references definitions described in Matter standard clusters. +- A Scoped source adopts the same source as that of the cluster that contains its definition. +- An MC-based source references manufacturer-specific definitions. + +_Table 75. MEC Example_ + +``` +Context Source Items +``` +### MEC + +``` +Standard +``` +``` +Item 0 +Item 1 +Item 2 +``` +``` +Scoped +``` +``` +Item 0 +Item 1 +Item 2 +``` +### MC 1 + +``` +Item 0 +Item 1 +Item 2 +``` +### MC 2 + +``` +Item 0 +Item 1 +Item 2 +``` +A Manufacturer Extensible Identifier (MEI) identifies an item in an MEC and has no meaning +beyond the context of that MEC. + +**7.20.2. Manufacturer Extensible Identifier (MEI)** + +An MEI has the following format: + +_Table 76. MEI Format_ + +``` +Field Prefix Suffix +Description Encodes a source +(standard, scoped or a particu­ +lar MC) +``` +``` +Encodes an item’s key +(in context of MEC + source) +``` +``` +Width 16-bit 16-bit +Bit Positions 31..16 15..0 +``` +The MEI permits encoding of ~65K keys in the suffix. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 489 +``` + +A specific MEI MAY only permit certain combinations of the above. + +**7.20.2.1. Encoding** + +The MEI prefix encodes the source Vendor ID and follows the same rules as outlined in Table 1, +“Vendor ID Allocations”, with the exception that a Scoped source is encoded using the same prefix +as a Standard source. Consequently, a given MEI SHALL NOT permit both Standard and Scoped +source types given the ambiguity in telling them apart. + +Given the above, the encoding is as follows: + +_Table 77. MEI Prefix_ + +``` +Prefix Source +0x0000 Standard OR Scoped +0x0001 - 0xFFF0 Manufacturer Code as per CSA Manufacturer +Code Database +0xFFF1 - 0xFFF4 Test Vendor MC +``` +The MEI suffix encodes a key as follows: + +_Table 78. MEI Suffix_ + +``` +Suffix Item +0x0000 - 0xFFFE Item 0 to 65534 +``` +**7.20.2.2. Data Model Types** + +The following data model types SHALL be represented as MEIs: + +_Table 79. MEI Suffix_ + +``` +Type Permitted Source Types Suffix Range +Device Type ID Standard or MC 0x0000 - 0xBFFF +Cluster ID Standard or MC Standard Cluster: 0x0000 - +0x7FFF +Manufacturer-Specific Cluster: +0xFC00 - 0xFFFE +Attribute ID (Global) Standard 0xF000 - 0xFFFE +Attribute ID (Non-Global) Scoped or MC 0x0000 - 0x4FFF +Event ID Scoped or MC 0x00 - 0xFF +Command ID (Global) Standard 0xE0 - 0xFF +Command ID (Non-Global) Scoped 0x00 - 0xDF +Command ID MC 0x00 - 0xFF +Field ID (Global) Standard 0xE0 - 0xFE +``` +``` +Page 490 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Type Permitted Source Types Suffix Range +Field ID (Non-Global) Scoped or MC 0x00 - 0xDF +``` +For those types which are listed with an 8 bit suffix range in this table (i.e. Event ID, Command ID +and Field ID), the 16-bit MEI Suffix SHALL be constructed by padding the 8-bit data with a most sig­ +nificant byte set to zero. + +For example: + +_Table 80. MEI Decoding Example_ + +``` +MEI Description +0x0000_0000 Standard/Scoped item 0 +0x0000_0001 Standard/Scoped item 1 +0x0000_0002 Standard/Scoped item 2 +0x0000_FFFE Standard/Scoped item 65534 +0x0001_0000 MC 1 item 0 +0x0001_0001 MC 1 item 1 +0x0001_0002 MC 1 item 2 +0x0001_FFFE MC 1 item 65534 +0x0002_0000 MC 2 item 0 +0x0002_0001 MC 2 item 1 +0x0002_0002 MC 2 item 2 +0x0002_FFFE MC 2 item 65534 +0xFFFF_0000 Invalid +``` +**7.20.3. Manufacturer Extensions** + +A manufacturer extensible context MAY be extended with items from any manufacturer. Such +extensions SHALL be identified using an MEI with prefix for that particular manufacturer, and +SHALL NOT use a standard/scoped prefix. + +There are further constraints: + +- MS extensions SHALL only be permitted on standard clusters or another existing MS extension + of a standard cluster from another manufacturer. +- An extended cluster MAY instantiate a struct definition defined in the standard cluster. +- A struct that has been extended with new fields SHALL have the same definition in all instances + of that struct within a given cluster definition. +- A defined element (struct, command, event) SHALL NOT be re-used or instantiable in a different + cluster (except in extended clusters) + +This is illustrated by the following hypothetical scenario. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 491 +``` + +Suppose the standard provides cluster ABCD which contains related counters and their recent statis­ +tics. The counter values are available as attributes 1 and 2 , which are reset daily. The statistics are +grouped into a SummarizedStats struct, available as attributes 3 and 4 , and track summary statistics +for each counter over a recent period (last month). Each instance of the statistics struct has fields 1 , +2 , and 3 , for minimum, maximum, and mean values for that period. + +Suppose manufacturer A extends the standard cluster with additional statistics (marked with^1 +below). A adds lifetime counts as attributes 0x000A_0001 and 0x000A_0002, which are never reset. A +also adds quartiles Q1, Q2, and Q3 to the standard SummarizedStats struct, as fields 0x000A_0001, +0x000A_0002, and 0x000A_0003. These quartiles are available for all existing instances of the standard +struct, such as standard attributes 3 and 4. + +Suppose manufacturer B, a partner of manufacturer A, extends the standard cluster further +(marked with^2 below). B wishes to add instances of the standard statistics struct, as attributes +0x000B_0001 and 0x000B_0002, to track summary statistics for each counter, over a different recent +period (last year instead of last month). Since manufacturer A had already extended the standard +statistics struct, the instantiation of that struct will contain both standard and A’s fields. If B desires +to create a new version of that statistics struct without A’s changes, it would have to declare a new +definition of that struct with new fields in it. + +Suppose manufacturer C, a partner of manufacturers B and A, adds a MS cluster 0x000C_FC01 +(marked with^3 below) that doesn’t extend an existing standard cluster. This cluster has a sensor +available as attribute 0x0000_0001 of type SensorStats, which has fields 0x0000_0001, 0x0000_0002, and +0x0000_0003, for the sensor’s value, precision, and accuracy. Since Attribute and Field IDs are +defined using the 'Scoped' source type, the prefix of '0000' implicitly equates to the same source as +the cluster it is defined in, i.e Manufacturer C. C also wishes to add an instance of the Summarized­ +Stats struct as attribute 0x000C_0002, to track summary statistics for the sensor over a recent period +(last hour). Since this cluster does not extend any previous cluster, it cannot instantiate any of the +extended versions of the SummarizedStats struct as defined previously. Instead, C will have re-define +that structure definition within its cluster definition and use it. + +_Table 81. Hypothetical Standard Cluster_ + +``` +Endpoint Cluster Attribute Attribute Description Struct Field Field +Description +0x0001 0x0000_ABCD 0x0000_0001 Counter 1 current value (reset daily) - - +0x0000_0002 Counter 2 current value (reset daily) - - +0x0000_0003 Counter 1 (period = month) 0x0000_0001 Min count +0x0000_0002 Max count +0x0000_0003 Mean count +0x0000_0004 Counter 2 (period = month) 0x0000_0001 Min count +0x0000_0002 Max count +0x0000_0003 Mean count +``` +_Table 82. Hypothetical Manufacturer A Extension Scenario_ + +``` +Page 492 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Endpoint Cluster Attribute Attribute Description Struct Field Field +Description +0x0001 0x0000_ABCD 0x0000_0001 Counter 1 current value (reset daily) - - +0x0000_0002 Counter 2 current value (reset daily) - - +0x0000_0003 Counter 1 (period = month) 0x0000_0001 Min count +0x0000_0002 Max count +0x0000_0003 Mean count +0x000A_0001^1 Q1 count^1 +0x000A_0002^1 Q2 count^1 +0x000A_0003^1 Q3 count^1 +0x0000_0004 Counter 2 (period = month) 0x0000_0001 Min count +0x0000_0002 Max count +0x0000_0003 Mean count +0x000A_0001^1 Q1 count^1 +0x000A_0002^1 Q2 count^1 +0x000A_0003^1 Q3 count^1 +``` +_Table 83. Hypothetical Manufacturer B Extension of A Scenario_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 493 +``` + +``` +Endpoint Cluster Attribute Attribute Description Struct Field +^ +``` +``` +Field +Description +0x0001 0x0000_ABCD 0x0000_0001 Counter 1 current value (reset daily) - - +0x0000_0002 Counter 2 current value (reset daily) - - +0x0000_0003 Counter 1 (period = month) 0x0000_0001 Min count +0x0000_0002 Max count +0x0000_0003 Mean count +0x000A_0001^1 Q1 count^1 +0x000A_0002^1 Q2 count^1 +0x000A_0003^1 Q3 count^1 +0x0000_0004 Counter 2 (period = month) 0x0000_0001 Min count +0x0000_0002 Max count +0x0000_0003 Mean count +0x000A_0001^1 Q1 count^1 +0x000A_0002^1 Q2 count^1 +0x000A_0003^1 Q3 count^1 +0x000B_0001^2 Counter 1 (period = month)^2 0x0000_0001 Min count +0x0000_0002 Max count +0x0000_0003 Mean count +0x000A_0001^1 Q1 count^1 +0x000A_0002^1 Q2 count^1 +0x000A_0003^1 Q3 count^1 +0x000B_0002^2 Counter 2 (period = month)^2 0x0000_0001 Min count +0x0000_0002 Max count +0x0000_0003 Mean count +0x000A_0001^1 Q1 count^1 +0x000A_0002^1 Q2 count^1 +0x000A_0003^1 Q3 count^1 +``` +_Table 84. Hypothetical Manufacturer C Custom Cluster_ + +``` +Page 494 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Endpoint Cluster Attribute Attribute Description Struct Field Field +Description +0x0001 0x000C_FC01^3 0x0000_0001^3 Sensor 1 Stats^3 0x0000_0001^3 Value^3 +0x0000_0002^3 Precision^3 +0x0000_0003^3 Accuracy^3 +0x0000_0002^3 Counter 1 (period = hour )^3 0x0000_0001^3 Min daily +count^3 +0x0000_0002^3 Max daily +count^3 +0x0000_0003^3 Mean daily +count^3 +``` +Note the following potential combinations of path components: + +_Table 85. Hypothetical Manufacturer Extension Path Examples_ + +``` +Description +0x0001/0x0000_ABCD/0x0000_0003/0x0000_0001 Cluster ID = Standard, Attribute ID = Scoped, +Field ID = Scoped: +Counter 1 min value +0x0001/0x0000_ABCD/0x0000_0003/0x000A_0001 Cluster ID = Standard, Attribute ID = Scoped, +Field ID = MS(A): +Counter 1 Q1 daily count over last month +0x0001/0x0000_ABCD/0x000B_0001/0x0000_0001 Cluster ID = Standard, Attribute ID = MS(B), +Field ID = Scoped: +Counter 1 Q1 daily count over last year +0x0001/0x0000_ABCD/0x000B_0001/0x000A_0001 Cluster ID = Standard, Attribute ID = MS(B), +Field ID = MS(A): +Counter 1 Q1 daily count over last year +0x0001/0x000C_FC01/0x0000_0001/0x0000_0002 Cluster ID = MS(C), Attribute ID = Scoped, Field +ID = Scoped: +Sensor 1 precision +0x0001/0x000C_FC01/0x0000_0002/0x0000_0003 Cluster ID = MS(C), Attribute ID = Scoped, Field +ID = Scoped: +Counter 1 (period = hour) Mean +0x0001/0x000C_FC01/0x0000_FFFD Cluster ID = MS(C), Attribute ID = Standard: +Cluster revision +``` +**7.20.4. Discoverability** + +The Descriptor Cluster reports the device types and clusters on a node’s endpoints, whether they +are standard or from a particular manufacturer. + +For example, if a node supports cluster 0x000C_ABCD on endpoints 1 and 2, that information is avail­ +able in the Descriptor Cluster. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 495 +``` + +The Read Interaction provides a means to read the contents of all or part of a cluster. + +For example, reading cluster 0x0000_ABCD on endpoint 1 might return mandatory attribute +0x0000_0001, optional attribute 0x0000_0009, and MS attributes 0x000A_0001 and 0x000A_0002. + +``` +Page 496 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 8. Interaction Model Specification** + +**8.1. Practical Information** + +**8.1.1. Revision History** + +Please note that Matter revision 1.0 SHALL be considered equivalent to revision 10. + +``` +Revision Description +1 Equivalent to revision 10 (1st Matter release of +the Interaction Model) +2-9 Released as versions of the Zigbee Cluster +Library chapter 2 which combined the interac­ +tion model with encoding +10 Initial release of this specification (Matter 1.0) +11 Updated Event error processing (Matter 1.2) +12 Added WildcardPathFlags to AttributeDataIB, +and associated behavior; added support for mul­ +tiple CommandDataIB in one Invoke Request +(Matter 1.3) +``` +**8.1.2. Scope & Purpose** + +This is part of a package of Data Model specifications that are agnostic to underlying layers (encod­ +ing, message, network, transport, etc.). Each specification below may be independently maintained. +This package, as a whole, SHALL be independently maintained as agnostic and decoupled from +lower layers. This package may be referenced by inclusion in vertical protocol stack specifications. + +``` +Data Model Defines first order elements and namespace for endpoints, clusters, +attributes, data types, etc. +``` +``` +Interaction Model Defines interactions, transactions and actions between nodes. +``` +``` +System Model Defines relationships that are managed between endpoints and clusters. +``` +``` +Cluster Library Reference library of cluster specifications. +``` +``` +Device Library Reference library of devices type definitions. +``` +**8.1.3. Origin Story** + +The original baseline for this section comes from the Zigbee Cluster Library [ZCL] Chapter 2 relat­ +ing to ZCL commands and interactions. This specification addresses these gaps determined by the +Data Model Tiger Team: + +- Multi-Element Message support + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 497 +``` + +- Synchronized Reporting +- Reduce message types (commands & actions) +- Complex data type support in all messages +- Events +- Interception attack + +**8.1.4. Purpose** + +The purpose is to define a layer that abstracts interactions from other layers, including security, +transport, message format & encoding. The intent is that this document will align with current clus­ +ter specifications in the ZCL (revision 8 at this time), and still support cluster evolution over time. + +**8.1.5. Glossary** + +``` +Term Short Spec Details Description +Wildcardable A this spec able to indicate all cur­ +rent instances of the +data +Optional O Data Model only required for some +action behavior +Quality Qual, Q Data Model quality of information +in an information block +Action Flow this spec direction flow of +actions +Path this spec a path to an element +(see Path) +Group Path this spec a path with a group ID +instead of node ID and +endpoint number (see +Group Path) +Wildcard Path this spec a path with one or +more elements that are +wildcards (see Wild­ +card Path) +Attribute Path this spec a path to an attribute +data field path for +attribute data (see +Attribute Path) +Request Path this spec a path that may be a +group or wildcard path +(see Request Path) +``` +``` +Page 498 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Term Short Spec Details Description +Concrete Path this spec a path that is not a +group or wildcard path +(see Concrete Path) +Existent Path this spec a concrete path that +exists on a server clus­ +ter (see Existent Path) +Supported Data Model the indicated element is +supported by the imple­ +mented instance +Unsupported Data Model the indicated element is +not supported by the +implemented instance +``` +**8.1.6. Conventions & Conformance** + +Please see the Data Model specification. + +**8.2. Concepts** + +Relationships between devices are established using data model elements and interactions defined +here. Please see the System Model specification for more information. + +An interaction is a sequence of transactions. A transaction is a sequence of actions. + +An action is a single logical communication from a source node to one or more destination nodes. +An action is conveyed by one or more messages. + +The actual construction and encoding of messages is left to the message layer, which is the layer +below this layer. + +- The protocol layers below this layer MAY have constraints that only support a subset of the + functionality described here. + +``` +Examples: +``` +- A client may choose Read interactions instead of Subscribe interactions. +- A client may choose to not Write or Invoke commands. + +**8.2.1. Path** + +A path is used to indicate one or more element instances in the data model. The path has the form +as described in Augmented Backus–Naur: + +``` + ::= +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 499 +``` + +``` + ::= | + ::= + ::= + ::= | + ::= | + ::= | | +``` +An Attribute Path is a path indicating an . + +A Command Path is a path indicating a . + +An Event Path is a path indicating an . + +**8.2.1.1. Concrete Path** + +- A concrete path SHALL NOT have group IDs or wildcards. +- A concrete path SHALL indicate a single element instance that is either: + ◦ an event with the path ending in an event ID + ◦ a command with the path ending in a command ID + ◦ an attribute with the path ending in an attribute ID + ◦ a struct field with the path ending in a field ID + ◦ a list entry with the path ending in a list entry index. + +**8.2.1.2. Existent Path** + +- An existent path is a concrete path that indicates a single existing instance on the node indi­ + cated in the path. + +**8.2.1.3. Group Path** + +A group path is a path that targets endpoints that are members of a group, using group ID, instead +of indicating a node and endpoint. + +- A group path SHALL resolve into zero or more paths. +- A group path SHALL include a group ID that indicates zero or more endpoints that are members + of the group. +- A group path MAY include a wildcard cluster indication and therefore also be a Wildcard Path. + +**8.2.1.4. Wildcard Path** + +A wildcard path is a path with a wildcard endpoint indication and/or wildcard cluster indication. + +- A wildcard path SHALL resolve into zero or more paths. +- A wildcard path SHALL indicate zero or more element instances. +- A wildcard path MAY include a group ID and therefore also be a Group Path. + +``` +Page 500 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.2.1.5. Request Path** + +A request path is used in actions that request data model elements. + +- A request path SHALL be either a concrete path, a group path or a wildcard path. + +**8.2.1.6. Request Path Expansion** + +Many actions specify this process step to expand a request path into a list of existent paths. This +process does not check access qualities, such as read or write access, privileges, or fabric qualities. + +- If the path is a Group Path, it SHALL be replaced with a list of paths, one for each endpoint that + is a member of the group on the target node. + ◦ All concrete paths that are not existent paths in the list generated by the above-mentioned + group-to-endpoint path expansion SHALL be removed. +- Else the list SHALL be the path. +- Each path in the list that is a Wildcard Path SHALL be replaced with a complete list of existent + paths, which are the permutations from substituting the wildcarded elements with existent ele­ + ments, but excluding the paths that must be omitted due to processing of the Attribute Wildcard + Path Flags. + +This process produces zero or more existent paths. + +**8.2.1.7. Attribute Path** + +An attribute path is used to indicate all or part of a cluster attribute. An attribute path may indicate +deeper parts of collection type data. + +Associated Information Block: AttributePathIB + +If the attribute data type is a collection data type, such as a struct or list, then the path may indicate +deeper nested parts of the data. + +The nesting of collection data is conceptually unlimited, but the actual structure of the data is well- +defined in the cluster specification. Attribute data structures are similar to data structures sup­ +ported in a programming language (see Data Types in the Data Model specification). An attribute +path is conceptually similar to the path or dot notation used to reference programming language +data structures. + +A field ID for structure data or an entry index for list data are currently the only options in an +attribute path, after the attribute ID itself. + +- The component of an attribute path SHALL have the following form: + +``` + ::= * + ::= | +``` +* occurs zero or more times as defined in a cluster specification. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 501 +``` + +The endpoint component is subject to wildcard expansion, as constrained in particular actions and +contexts. + +**Attribute Wildcard Path Flags** + +Processing wildcard expansion of an Attribute Path MAY be affected by the associated Wildcard­ +PathFlags field. + +When expanding a wildcard path indicated in an AttributePathIB into one or more concrete paths, +paths SHALL be omitted from the result set if they satisfy any of the conditions below, each of +which depends on the value of WildcardPathFlags and the path being considered: + +- if the WildcardSkipRootNode bit is set and the concrete path targets endpoint 0; +- if the WildcardSkipGlobalAttributes bit is set and the concrete path refers to one of the following + attribute IDs: + ◦ GeneratedCommandList/0xFFF8 + ◦ AcceptedCommandList/0xFFF9 + ◦ AttributeList/0xFFFB +- if the WildcardSkipAttributeList bit is set and the concrete path refers to the AttributeList (ID + 0xFFFB) attribute; +- if the WildcardSkipCommandLists bit is set and the concrete path refers to the either the Generat­ + edCommandList (ID 0xFFF8) or AcceptedCommandList (ID 0xFFF9) attributes; +- if the WildcardSkipCustomElements bit is set, and the concrete path targets: + ◦ any element whose Cluster ID has an MEI prefix not equal to zero; + ◦ any attribute whose ID has an MEI prefix not equal to zero, even if included in a standard + cluster; +- if the WildcardSkipFixedAttributes bit is set and the concrete path refers to an attribute with the + Fixed (F) quality; +- if the WildcardSkipChangesOmittedAttributes bit is set and the concrete path refers to an attribute + with the Changes Omitted (C) quality; +- if the WildcardSkipDiagnosticsClusters bit is set and the concrete path refers to a cluster with + the Diagnostics (K) quality. + +If the client is including WildcardPathFlags in an AttributePathIB destined to a server that pre-dates +the introduction of WildcardPathFlags (Interaction Model revision 12), the client SHALL tolerate +the inclusion of reports for paths that would otherwise be omitted by servers compliant with this +feature. + +``` +NOTE WildcardPathFlags support is provisional. +``` +**8.2.1.8. Command Path** + +A command path is used to indicate a cluster command. + +Associated Information Block: CommandPathIB + +``` +Page 502 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- The component of a command path SHALL have the following form: + +``` + ::= +``` +- The endpoint field is wildcardable, though this may be disallowed in the various uses of the + Command Path in different actions and contexts. + +**8.2.1.9. Event Path** + +A event path is used to indicate a cluster event. + +Associated Information Block: EventPathIB + +- The component of an event path SHALL have the following form: + +``` + ::= +``` +Please see Event for a description of a cluster event and event data fields. + +The endpoint, cluster and event ID fields are wildcardable. These are further constrained in the +various uses of the Event Path in different actions and contexts. + +- An event path SHALL NOT be a group path. + +**8.2.2. Interaction** + +An interaction is a sequence of one or more transactions between nodes, that occurs in the context +of an accessing fabric, or no fabric. + +How a fabric, or no fabric, context is established for an interaction, is not defined here. + +The first transaction (of an interaction) starts with the first action from the node called the **initia­ +tor**. The first action destination is called the **target** , which is either a node or group. For the remain­ +der of the interaction, the initiator remains the same. + +An interaction may be a single transaction (e.g. Read). An interaction may be an unbounded num­ +ber of transactions (e.g. Subscribe). + +``` +Interaction Transactions Description +Read Interaction Read This interaction is a request for +cluster attributes and/or event +data. +Subscribe Interaction Subscribe, Report This interaction subscribes to +cluster attributes and/or event +data. +Write Interaction Write This interaction modifies clus­ +ter attributes. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 503 +``` + +``` +Interaction Transactions Description +Invoke Interaction Invoke This interaction invokes cluster +commands. +``` +**8.2.3. Transaction** + +A transaction is either the whole, or part of an interaction. A transaction is a sequence of one or +more actions. Actions in a transaction are defined as first or following, to better describe dependen­ +cies in this specification. + +- The first action of a transaction SHALL be initiated by a single node. +- An action in a transaction SHALL have a target destination that is either a single node, called a + unicast action or a group of nodes, called groupcast action. + +**8.2.3.1. Transaction ID** + +The transaction ID is a field present in all actions (see Common Action Information) that indicates +the logical grouping of those actions. + +- All following actions in a transaction SHALL have the same transaction ID as the first action. +- A groupcast action SHALL end a transaction and any subsequent action in the interaction + SHALL NOT use the same transaction ID. + +The table below lists all transactions. + +``` +Transaction Description +Read Transaction This transaction is a request for cluster attribute +and/or event data. +Subscribe Transaction This transaction creates a subscription to cluster +attributes and/or events. +Report Transaction This transaction maintains a subscription for the +Subscribe interaction. +Write Transaction This transaction modifies cluster attributes. +Invoke Transaction This transaction invokes cluster commands. +``` +**8.2.4. Action** + +The table below lists all actions. + +``` +Action Description Outgoing Message +Status Response Action This action is a success or error +response. +``` +``` +Unicast +``` +``` +Read Request Action This action is a request for clus­ +ter attribute data and/or events. +``` +``` +Unicast +``` +``` +Page 504 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Action Description Outgoing Message +Report Data Action This action responds to a Read +Request Action or Subscribe +Request Action. +``` +``` +Unicast +``` +``` +Subscribe Request Action This action is a request for a +subscription to cluster attribute +data and/or events. +``` +``` +Unicast +``` +``` +Subscribe Response Action This action is a response to a +Subscribe Request Action. +``` +``` +Unicast +``` +``` +Write Request Action This action is a request to mod­ +ify cluster attribute data. +``` +``` +Unicast | Groupcast +``` +``` +Write Response Action This action responds to a Write +Request Action. +``` +``` +Unicast +``` +``` +Invoke Request Action This action executes a cluster +command. +``` +``` +Unicast | Groupcast +``` +``` +Invoke Response Action This action is used to respond to +an Invoke Request Action with +cluster defined responses. +``` +``` +Unicast +``` +``` +Timed Request Action This action indicates that +another action will take place +within a Timed interval. +``` +``` +Unicast +``` +**8.2.5. Common Action Behavior** + +The message layer below this interaction layer encodes an action into one or more messages and +delivers the messages to a destination. This interaction layer delivers action information to the mes­ +sage layer by passing action information, through some interface (not defined here). The message +layer delivers action information, from an incoming message, to this interaction layer. + +In all action descriptions in this specification, action information (or information blocks), refers to +the information that is transferred to and from the message layer. + +There is no designation of mandatory or optional for such information because the implementation +is undefined. However, some information fields may be omitted, meaning the information may not +be needed for all actions. + +**8.2.5.1. Common Action Information** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 505 +``` + +``` +Action Field Type Conformance Description +InteractionModelRevi­ +sion +``` +``` +uint8 M the revision number of +the implemented Inter­ +action Model specifica­ +tion under which the +sending node was certi­ +fied +Action action-id M the action +TransactionID trans-id M the transaction ID +FabricIndex fabric-idx M the accessing fabric +index, based on the ses­ +sion used to deliver the +action +SourceNode node-id M the node ID of the node +that generates the +action +DestinationNode node-id O.a the node ID of the desti­ +nation where the action +is sent +DestinationGroup group-id O.a the group ID of the des­ +tination where the +action is sent +action specific variable M specific action informa­ +tion described in each +action section +``` +**8.2.5.2. Outgoing Action** + +- Each generated action SHALL provide the action information above to the message layer. +- If the action is the first action of a transaction, the TransactionID SHALL be a value that + uniquely identifies the transaction on the source of the action. +- If the action is a following action, the TransactionID SHALL be the same as the TransactionID in + the first action of the transaction. +- If the action is a unicast following action the DestinationNode SHALL be the SourceNode of the + previous action in the transaction. +- The generated action information SHALL be submitted to the message layer. + ◦ Upon receipt of this action information, the message layer SHALL construct and convey one + or more messages for this action to the target. + ◦ If the message layer encounters an error that prevents the complete construction, encoding + and/or conveyance of the action, then the message layer SHALL inform this layer of the + error. + ◦ If the action is not completely conveyed, the action, with the associated transaction and + +``` +Page 506 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +interaction, SHALL terminate. +▪ If the failed action is NOT a Status Response action, this layer SHOULD, if possible, sub­ +mit a Status Response action to the message layer, with a status code of FAILURE and the +same TransactionID. +``` +**8.2.5.3. Incoming Action** + +- If the message layer receives a valid message for an action, it SHALL be delivered to this layer + with the action information above. +- If this layer receives a message for an action that is not expected semantically, has invalid action + information, or has an error not described in this specification, a Status Response action with + an INVALID_ACTION Status Code SHALL be generated as defined in Status Response Action, and + the associated transaction and interaction SHALL terminate. +- If during the receipt and decoding of messages for an action by the message layer, an error + occurs that prevents a complete receipt of a valid action, then the message layer SHALL inform + this layer of the error. + ◦ When informed of an error from a message layer, the action, with the associated transaction + and interaction, SHALL terminate. +- If the action is not able to be executed due to insufficient resources, a Status Response SHALL be + sent to the initiator with a status code of either: + ◦ PATHS_EXHAUSTED if there are not enough resources to support the number of paths in the + action information, + ◦ and the number of paths in the action exceeds the number of paths that is guaranteed to be + supported for the action (see Interaction Model Limits), + ◦ BUSY in all other recoverable resource exhausted situations (e.g. if too many Read interac­ + tions are already in progress), + ◦ or RESOURCE_EXHAUSTED for any other resource insufficiency, + ◦ and the interaction SHALL be terminated. + +It is implementation specific whether the message layer submits logical parts of an action to this +layer as it receives and processes each message. The only requirement above is that all the informa­ +tion, or an error, be submitted to this layer. + +Global common interaction Status Codes are defined in this document in Status Codes. Cluster spe­ +cific Status Codes are defined in each cluster specification. + +**8.3. Status and Interaction** + +There is no Status interaction, but an error status may be generated as part of any interaction. + +**8.3.1. Status Response Action** + +This action is defined as a following action for some actions, or is generated when there is an +unspecified transaction or interaction error. This action conveys status to this layer or conveys sta­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 507 +``` + +tus from this layer to another node. The status indicates success or an error as part of a transaction +or interaction. + +Please see Common Action Behavior for behavior common to all actions. The specific action infor­ +mation for this action is shown below. + +**8.3.1.1. Status Response Information** + +``` +Action Field Type Conformance Description +Status status M a status code (see Status +Codes) +``` +**8.3.1.2. Outgoing Status Response Action** + +- This action SHALL be unicast. +- This action SHALL NOT be generated in response to a groupcast. +- This action SHALL be generated as specified in interactions defined here. +- If this action is generated with an error Status, the current transaction and interaction SHALL + be terminated. +- This action SHALL only be generated with an error Status when an error occurs as a result of + the immediate previous received action in the current transaction. +- This action’s DestinationNode field SHALL be the immediate previous received action’s + SourceNode. +- This action’s TransactionID field SHALL be the immediate previous received action’s Transac­ + tionID. +- If there is no well-defined Status Code for an error or exception, the Status Code of FAILURE + SHALL be used. + +**8.3.1.3. Incoming Status Response Action** + +- Upon receipt of this action with a success Status Code, this layer SHALL consume the status and + continue the current transaction and interaction. +- Upon receipt of this action with an error Status, this layer SHALL terminate the current transac­ + tion and interaction. +- Upon receipt of this action with an error Status, this layer SHALL submit the error to the layer + above. + +**8.4. Read Interaction** + +This interaction is generated when an initiator wishes to determine the value of one or more attrib­ +utes or events located on a node. + +``` +Page 508 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.4.1. Read Transaction** + +``` +Action Action Flow Description +Read Request Initiator ⇒ Target data report request +Report Data Initiator ⇐ Target response report with data +``` +**8.4.2. Read Request Action** + +Read Request action is the first action of a Read transaction (and interaction). Please see Common +Action Behavior for behavior common to all actions. The specific action information for this action +is shown below. + +**8.4.2.1. Read Request Action Information** + +``` +Action Field Type Conformance Description +AttributeRequests list[AttributePathIB] M a list of zero or more +request paths to cluster +attribute data +DataVersionFilters list[DataVersionFil­ +terIB] +``` +``` +AttributeRequests a list of zero or more +cluster instance data +versions +EventRequests list[EventPathIB] M a list of zero or more +request paths to cluster +events +EventFilters list[EventFilterIB] EventRequests a list of zero or more +minimum event num­ +bers per specific node +FabricFiltered bool M limits the data read +within fabric-scoped +lists to the accessing +fabric +``` +**8.4.2.2. Outgoing Read Request Action** + +- This action SHALL be unicast. +- This action SHALL be generated as the first action in a Read transaction. +- A valid AttributePathIB for attribute data SHALL be one in the table Valid Read Attribute Paths. +- A valid EventPathIB for an event SHALL be one in the table Valid Event Paths. +- A path indicated in AttributeRequests or EventRequests SHALL NOT target a group. + +**8.4.2.3. Incoming Read Request Action** + +- Upon receipt of this action, this layer SHALL generate a Report Data action to the subscriber, as + defined in Incoming Read Request and Subscribe Request Action Processing. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 509 +``` + +- If the Report Data was generated successfully, it SHALL be submitted to the message layer. + +**8.4.3. Report Data Action** + +This action is either a first action in a Report transaction (as part of a Subscribe interaction), or a +following action to a Read Request action or Subscribe Request action. + +Please see Common Action Behavior for behavior common to all actions. The specific action infor­ +mation for this action is shown below. + +**8.4.3.1. Report Data Action Information** + +``` +Action Field Type Conformance Description +SuppressResponse bool M do not send a response +to this action +SubscriptionId uint32 O a SubscriptionId only +used in a Subscribe +interaction +AttributeReports list[AttributeReportIB] O a list of zero or more +attribute data reports +EventReports list[EventReportIB] O a list of zero or more +event reports +``` +**8.4.3.2. Incoming Read Request and Subscribe Request Action Processing** + +- Each path indicated by the Report Data action SHALL be a Concrete Path. +- Upon receipt of a Read Request action or Subscribe Request action, this process SHALL be fol­ + lowed: +- Each request path in the AttributeRequests field SHALL be processed as follows: + ◦ If the path does not conform to Valid Read Attribute Paths then: + ▪ a Status Response with the INVALID_ACTION Status Code SHALL be generated as defined + in Status Response Action, + ▪ a Report Data action SHALL NOT be generated, + ▪ and this interaction and process SHALL terminate. + ◦ Else if the path is a concrete path: + ▪ If the path indicates a node that is unsupported, an AttributeStatusIB SHALL be gener­ + ated with the UNSUPPORTED_NODE Status Code. + ▪ Else if reading from the attribute in the path requires a privilege that is not granted to + access the cluster in the path, an AttributeStatusIB SHALL be generated with the UNSUP­ + PORTED_ACCESS Status Code. + ▪ Else if the path indicates a specific attribute that is restricted (see ManagedDevice), an + AttributeStatusIB SHALL be generated with the ACCESS_RESTRICTED Status Code. + ▪ Else if the path indicates an endpoint that is unsupported, an AttributeStatusIB SHALL + +``` +Page 510 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +be generated with the UNSUPPORTED_ENDPOINT Status Code. +▪ Else if the path indicates a cluster that is unsupported, an AttributeStatusIB SHALL be +generated with the UNSUPPORTED_CLUSTER Status Code. +▪ Else if the path indicates an attribute or attribute data field that is unsupported, an +AttributeStatusIB SHALL be generated with the UNSUPPORTED_ATTRIBUTE Status Code +with the Path field indicating the first unsupported data field (not the entire attribute +data path). +▪ Else if the path indicates attribute data that is not readable, an AttributeStatusIB SHALL +be generated with the UNSUPPORTED_READ Status Code. +▪ If an AttributeStatusIB was generated, the path SHALL be discarded. +◦ Else perform Request Path Expansion and process each expanded existent path as follows: +▪ If the path indicates attribute data that is not readable, or is restricted (see ManagedDe­ +vice), then the path SHALL be discarded. +▪ Else if reading from the attribute in the path requires a privilege that is not granted to +access the cluster in the path, then the path SHALL be discarded. +``` +- If no error free existent paths remain, then AttributeRequests are considered empty. +- Else each remaining error free existent path is processed as follows: + +``` +◦ If the DataVersionFilters field indicates DataVersionFilterIB entries with a Path field that +matches the path, where all matching entries have a DataVersion field that matches the data +version of the cluster instance in the path, then the path SHALL be ignored +◦ Else an AttributeDataIB SHALL be generated with the Data and Path as indicated by the path +being processed. If the attribute indicated by the path or any struct field nested inside that +attribute (at any level of nesting) is a fabric-scoped list, then any such list within the gener­ +ated Data shall be filtered based on the value of the FabricFiltered parameter: +▪ If the FabricFiltered parameter is true, any such list SHALL be generated as a fabric-fil­ +tered list of entries. +▪ Else if the FabricFiltered parameter is false, any such list SHALL be generated as an +unfiltered list of entries, with each entry indicated as a fabric-sensitive struct. +◦ Each AttributeDataIB or AttributeStatusIB generated from processing AttributeRequests +SHALL be added to the AttributeReports action field in the Report Data action. +``` +- Each request path in the EventRequests field SHALL be processed as follows: + +``` +◦ If the path is a concrete path: +▪ If the path indicates a node that is unsupported, an EventStatusIB SHALL be generated +with the UNSUPPORTED_NODE Status Code. +▪ Else if reading the event in the path requires a privilege that is not granted to access the +cluster in the path, an EventStatusIB SHALL be generated with the UNSUPPORTED_AC­ +CESS Status Code. +▪ Else if the path indicates a specific event that is restricted (see ManagedDevice), an +EventStatusIB SHALL be generated with the ACCESS_RESTRICTED Status Code. +▪ Else if the path indicates an endpoint that is unsupported, an EventStatusIB SHALL be +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 511 +``` + +``` +generated with the UNSUPPORTED_ENDPOINT Status Code. +▪ Else if the path indicates a cluster that is unsupported, an EventStatusIB SHALL be gen­ +erated with the UNSUPPORTED_CLUSTER Status Code. +▪ Else if the path indicates a cluster event that is not supported, an EventStatusIB SHALL +be generated with the UNSUPPORTED_EVENT Status Code. +▪ If an EventStatusIB was generated, the path SHALL be discarded. +◦ Else if the path does not conform to Valid Event Paths then: +▪ a Status Response with the INVALID_ACTION Status Code SHALL be generated as defined +in Status Response Action, +▪ a Report Data action SHALL NOT be generated, +▪ and this interaction and process SHALL terminate. +◦ Else perform Request Path Expansion and process each expanded existent path as follows: +▪ If reading the event in the path requires a privilege that is not granted to access the clus­ +ter in the path, or is restricted (see ManagedDevice), then the path SHALL be discarded. +``` +- If no error free existent paths remain, then EventRequests are considered empty. +- Else for each unique node indicated in the remaining existent paths: + ◦ Each event record currently queued in the node, in order from lowest to highest event num­ + ber, SHALL generate an EventDataIB except for any of the following: + ▪ If the node indicated matches the Node information field of an EventFilterIB from Event­ + Filters, and the event number is less than the EventMin field in the EventFilterIB. + ▪ If the event record path does not match a path in the remaining existent event paths. + ▪ If the event record path is fabric-sensitive, and the associated fabric does not match the + accessing fabric. + ◦ Each information block generated from processing EventRequests SHALL be added to the + EventReports action field in the Report Data action. +- If this action is in response to a Subscribe Request action, + ◦ If both AttributeRequests and EventRequests are empty + ▪ a Status Response Action with the INVALID_ACTION Status Code SHALL be sent to the + initiator, + ▪ a Report Data action SHALL NOT be generated, + ▪ and the interaction and process SHALL terminate. + ◦ Else a SubscriptionId which uniquely identifies this subscription on the publisher SHALL be + indicated in the Report Data action +- Else the SubscriptionId SHALL be omitted. + +**8.4.3.3. Outgoing Report Data Action** + +- This action SHALL be unicast. +- This action MAY have an empty list of AttributeReports and/or EventReports. + +``` +Page 512 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- This action SHALL NOT include any nested attribute data field or nested event data field that is + defined as fabric-sensitive, if the associated fabric for that field does not match the accessing + fabric for the interaction. +- SuppressResponse MAY be set to TRUE for a Report Data action that initiates a Report transac­ + tion that conveys an empty list of AttributeReports and EventReports, otherwise: + ◦ SuppressResponse SHALL be set to TRUE for a Report Data action that is part of a Read + transaction. + ◦ SuppressResponse SHALL be set to FALSE for a Report Data action that is part of a Subscribe + transaction. +- This action SHALL be generated as either: + ◦ part of a Read transaction in direct response to a Read Request action. + ◦ part of a Subscribe transaction in direct response to a Subscribe Request action. + ◦ part of a Subscribe interaction as the first action of each synchronized Report Transaction. + +**8.4.3.4. Incoming Report Data Action** + +- Upon receipt of this action, if SuppressResponse is TRUE, a response SHALL NOT be generated; +- Otherwise a Status Response Action SHALL be generated with a status code of + ◦ SUCCESS to continue the interaction, + ◦ INVALID_SUBSCRIPTION if the action is part of a Subscribe interaction and the Subscrip­ + tionID is invalid, + ◦ FAILURE to terminate the interaction, + ◦ The Status Response Action SHALL be submitted to the message layer to deliver to the + source of this action. + +**8.5. Subscribe Interaction** + +The Subscribe interaction is composed of these transactions: + +``` +Transaction Description +Subscribe start and prime a reporting session +Report synchronized Report transaction +more reports continuous Report transactions for the life of the +subscription +``` +This interaction allows a subscriber to create a subscription with a publisher on another node for +the purposes of receiving data reports from that publisher thereafter, for the duration of the sub­ +scription. This allows the subscriber to maintain a coherent snapshot, or twin, of the subscription +data as it currently exists on the publisher. The session itself is kept synchronized on both sides +through the receipt of timely data reports with the intervals defined by a negotiated maximum +interval subscription parameter. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 513 +``` + +This interaction is started when the initiator (or subscriber), wishes to subscribe to one or more +attributes or events located on a target node (the publisher). The attribute data and events +requested in the Subscribe transaction are the subscription data. + +This interaction starts by creating a subscription with a Subscribe transaction, which primes the +subscriber with initial subscription data. The rest of the subscription is a sequence of Report trans­ +actions initiated by the publisher as defined by parameters of the subscription. Each Report trans­ +action in a subscription reports changes to the subscription data. + +To keep the subscription alive, a Report transaction is sent from the publisher every maximum +interval, or possibly more frequently. + +Report transactions from the publisher are rate limited by the minimum interval subscription para­ +meter, as negotiated between the subscriber and publisher. + +The Subscribe Request action provides boundary values (floor or ceiling) for the publisher to deter­ +mine the final minimum and maximum interval parameters of the subscription. The time units for +these intervals are seconds. + +Each Subscribe interaction is a subscription that is identified by a Subscription ID as generated by +the publisher. + +- The Subscribe interaction SHALL start with one Subscribe transaction followed by a periodic + sequence of Report transactions (see Report Transaction). +- A Report transaction SHALL be initiated by a Report Data action as part of an active subscrip­ + tion for a Subscribe interaction. +- All Report Data actions in a Subscribe interaction SHALL have the same SubscriptionId parame­ + ter value that uniquely identifies the interaction among all subscriptions on the publisher. +- Each Report transaction in a subscription SHALL report the path for each delta change in the + subscription data, including the attribute data that has changed and/or the event that has + occurred, since the last Report transaction, with the exception of attribute data with the + Changes Omitted (C) quality. +- Each Report transaction initiated by the publisher SHALL complete successfully before another + Report transaction is initiated by the publisher. +- Each Report transaction SHALL NOT be initiated by the publisher until the minimum interval + has expired since the last Report transaction in the subscription. +- Attribute changes SHALL be delivered as soon as possible, taking into account the minimum + interval. +- Events SHALL always be queued and buffered. Each Report containing events SHALL deliver + queued events without reordering the queue. Queued events MAY be opportunistically deliv­ + ered whenever some other activity triggers a Report transaction. Absent any such triggers, + queued events SHALL be delivered in a Report transaction generated at the maximum interval. +- When the IsUrgent flag is FALSE or absent for a subscription’s event path in the EventPathIB, + event queueing does not automatically trigger a Report transaction. +- When the IsUrgent flag is TRUE for a subscription’s event path in the EventPathIB, the queueing + of such an event SHALL trigger a Report transaction for the subscription, subject to all Report + +``` +Page 514 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +transaction rules. This Report transaction will report the events that have been queued by the +time the Report transaction happens. +``` +- If the subscriber does not receive a Report transaction within the maximum interval from the + last Report Data, the subscriber SHALL terminate the Subscribe interaction. +- If a node receives a Report Data action with an inactive SubscriptionId, a Status Response action + SHALL be sent with an INVALID_SUBSCRIPTION Status Code. +- If, in response to a Report Data action, the publisher receives a Status Response action with a + status code that is not SUCCESS, the publisher SHALL terminate the Subscribe interaction. +- If the publisher does not receive a Status Response action in response to a Report Data action + with SuppressResponse set to FALSE, the publisher MAY terminate the Subscribe interaction or + SHALL re-synchronize the subscription in the next Report Data transaction by: + ◦ Including all subscription data to re-prime the subscription, or + ◦ Including all deltas since the last successful Report Data transaction. +- The subscriber MAY terminate the subscription and interaction by responding with a Status + Response action with an INVALID_SUBSCRIPTION Status Code. +- The publisher MAY terminate the subscription and interaction by not generating a Report trans­ + action within the maximum interval. +- When a Subscribe interaction is terminated on the publisher or subscriber, the subscription, + identified by a SubscriptionId, SHALL also be terminated. + +**8.5.1. Subscribe Transaction** + +``` +Action Action Flow Description +Subscribe Request Initiator ⇒ Target list of event and attribute data +identifiers supported on a +server cluster +Report Data Initiator ⇐ Target primed published data +Status Response Initiator ⇒ Target success, or otherwise an error +to terminate the subscription +Subscribe Response Initiator ⇐ Target provides subscription parame­ +ters +``` +**8.5.2. Subscribe Request Action** + +Subscribe Request action is a first action. Please see Common Action Behavior for behavior com­ +mon to all actions. The specific action information for this action is shown below. + +**8.5.2.1. Subscribe Request Action Information** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 515 +``` + +``` +Action Field Type Conformance Description +KeepSubscriptions bool M false to terminate exist­ +ing subscriptions from +initiator +MinIntervalFloor uint16 M the requested mini­ +mum interval bound­ +ary floor in seconds +MaxIntervalCeiling uint16 M the requested maxi­ +mum interval bound­ +ary ceiling in seconds +AttributeRequests list[AttributePathIB] O a list of zero or more +request paths to cluster +attribute data +DataVersionFilters list[DataVersionFil­ +terIB] +``` +``` +AttributeRequests a list of zero or more +cluster instance data +versions +EventRequests list[EventPathIB] O a list of zero or more +request paths to cluster +events +EventFilters list[EventFilterIB] EventRequests a list of zero or more +minimum event num­ +bers per specific node +FabricFiltered bool M limits the data read +within fabric-scoped +lists to the accessing +fabric +``` +**8.5.2.2. Outgoing Subscribe Request Action** + +- This action SHALL initiate a Subscribe interaction. +- A Subscribe Request action SHALL be unicast from the subscriber to the publisher. +- This action SHALL be generated to initiate a Subscribe interaction (see Subscribe Interaction). +- This action SHALL include a requested ceiling (highest) maximum interval value as MaxInter­ + valCeiling. +- This action SHALL include a requested floor (lowest) minimum interval value as MinInter­ + valFloor. + +### NOTE + +``` +If the publisher is an intermittently connected device, the MinIntervalFloor +SHOULD be 0. To avoid needing to switch to Active Mode to process the event and a +second time to send the information, an ICD MAY try to synchronize its updates +towards various subscribers so that it only needs to go to Active Mode once and can +stay idle for a full idle interval. If the MinIntervalFloor is too high, this limits the +freedom for an ICD to synchronize its updates. The higher the MinIntervalFloor is, +``` +``` +Page 516 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +the higher the likelihood an ICD will not be able to send updates to various sub­ +scribers in a synchronized pattern, which might negatively impact energy usage +(e.g. battery life). +``` +- At least one attribute or event SHALL be indicated in the action. +- A valid AttributePathIB SHALL be one in the table Valid Read Attribute Paths. +- A valid EventPathIB SHALL be one in the table Valid Event Paths. +- A path indicated in AttributeRequests or EventRequests SHALL NOT target a group. + +**8.5.2.3. Incoming Subscribe Request Action** + +- If KeepSubscriptions is FALSE, all existing or pending subscriptions on the publisher for this + subscriber SHALL be terminated. +- This layer SHALL process the Subscribe Request action as defined in Incoming Read Request + and Subscribe Request Action Processing. + +**8.5.3. Subscribe Response Action** + +Subscribe Response action is the last following action in a Subscribe Transaction. This action acti­ +vates the subscription. Please see Common Action Behavior for behavior common to all actions. The +specific action information for this action is shown below (see Subscribe Interaction). + +**8.5.3.1. Subscribe Response Action Information** + +``` +Action Field Type Conformance Description +SubscriptionId uint32 M identifies the subscrip­ +tion +MaxInterval uint16 M the final maximum +interval for the sub­ +scription in seconds +``` +**8.5.3.2. Outgoing Subscribe Response Action** + +- Upon receipt of a successful Status Response action from the subscriber for the Report Data + action that primes the subscription, this action SHALL be generated and submitted to the mes­ + sage layer to send to the subscriber. +- This action SHALL be unicast. +- The SubscriptionId value SHALL be the same as the one used in Report Data generated to prime + this subscription. +- The publisher SHALL compute an appropriate value for the MaxInterval field in the action. This + SHALL respect the following constraint: MinIntervalFloor ≤ MaxInterval ≤ MAX(SUBSCRIPTION_­ + MAX_INTERVAL_PUBLISHER_LIMIT, MaxIntervalCeiling) +- Upon sending a Subscribe Response action, the subscription, as indicated by the SubscriptionId, + SHALL become active on the publisher with a min interval equal to the requested MinInter­ + valFloor and a max interval equal to the MaxInterval field in the response. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 517 +``` + +**8.5.3.3. Incoming Subscribe Response Action** + +- Upon receipt of a Subscribe Response action, the subscription, as indicated by the Subscrip­ + tionId, SHALL become active to the subscriber. + +**8.5.3.4. Subscription Activation** + +- The paths to the subscription data SHALL only be error free existent paths generated from pro­ + cessing the Subscribe Request. + +The EventFilters and DataVersionFilters fields in the Subscribe Request are one time parameters for +the priming of the subscription. + +- Subsequent ReportData actions, as part of the subscription, SHALL include the latest: + ◦ EventNo associated with each node generating new events. + ◦ DataVersion associated with each cluster where there are data changes. +- The FabricFiltered parameter from the Subscribe Request SHALL remain in effect for all data + reported during the interaction. +- Upon subscription activation, the minimum and maximum interval parameters SHALL take + effect to determine the timing and expectation of subsequent Report transactions. + +**8.6. Report Transaction** + +There is no Report interaction. A Report transaction is part of a Subscribe interaction. Please see +Subscribe Interaction for details. + +The valid Report transactions are: + +**8.6.1. Report Transaction Non-Empty** + +``` +Action Action Flow Description +Report Data Initiator ⇐ Target report of data and/or events +with SuppressResponse set to +FALSE +Status Response Initiator ⇒ Target an error ends the interaction +``` +**8.6.2. Report Transaction Empty** + +``` +Action Action Flow Description +Report Data Initiator ⇐ Target report with no data or events +with SuppressResponse set to +TRUE +``` +``` +Page 518 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.7. Write Interaction** + +This interaction is started when an initiator wishes to modify the values of one or more attributes +located on one or more nodes. An optional Timed Request action defines a Timeout interval that +starts at the sending of the Status Response action. + +**8.7.1. Write Transaction** + +- A Write interaction SHALL consist of one of the transactions shown below. + +**8.7.1.1. Timed Write Transaction** + +``` +Action Action Flow Description +Timed Request Initiator ⇒ Target time interval defined to send +Write Request action +Status Response Initiator ⇐ Target confirmation +Write Request Initiator ⇒ Target data to modify +Write Response Initiator ⇐ Target with errors or success from +Write Request action +``` +**8.7.1.2. Untimed Write Transaction** + +``` +Action Action Flow Description +Write Request Initiator ⇒ Target data to modify +Write Response Initiator ⇐ Target with errors or success from +Write Request action +``` +- If there is a preceding successful Timed Request action, the following Write Request action + SHALL be received before the end of the Timeout interval. +- If there is a preceding successful Timed Request action, the Timeout interval SHALL start when + the Status Response action acknowledging the Timed Request action with a success code is sent. +- If there is a preceding successful Timed Request action, the Write Request action SHALL be uni­ + cast. +- If there is not a preceding successful Timed Request action, the Write Request action MAY be + groupcast. +- A client MAY choose to use a Timed Write transaction even if the attribute does not have the + Timed Interaction quality. +- The server SHALL support a Timed Write transaction for all writeable attributes. + +**8.7.2. Write Request Action** + +This action is either the first action of the Write transaction or it follows a successful Timed Request +action. Please see Common Action Behavior for behavior common to all actions. The specific action +information for this action is shown below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 519 +``` + +**8.7.2.1. Write Request Action Information** + +``` +Action Field Type Conformance Description +SuppressResponse bool M do not send a response +to this action +TimedRequest bool M flag action as part of a +timed write transaction +WriteRequests list[AttributeDataIB] M a list of one or more +path and data tuples. +``` +**8.7.2.2. Outgoing Write Request Action** + +- This action SHALL be generated as the first action in a Write transaction, or following a Timed + Request action and successful Status Response action. +- If this action is part of a Timed Write transaction, TimedRequest SHALL be TRUE, else FALSE. +- If not part of a Timed Write transaction, this action MAY be groupcast. +- If this action is groupcast, SuppressResponse SHALL be TRUE. + +**8.7.2.3. Incoming Write Request Action** + +- If this action is not able to be executed because the maximum supported number of Write inter­ + actions is already in progress, then a Status Response action with the BUSY Status Code SHALL + be submitted to the message layer and this interaction SHALL terminate. +- If this action is part of a Timed Write transaction, and the Timeout has expired from the preced­ + ing Timed Request action, then a Status Response action with the TIMEOUT Status Code SHALL + be submitted to the message layer and this interaction SHALL terminate. + +``` +NOTE Devices certified prior to 1.4 MAY return UNSUPPORTED_ACCESS for this condition. +``` +- If this action is part of a Timed Write transaction, and this action has TimedRequest set to + FALSE, then a Status Response action with the TIMED_REQUEST_MISMATCH Status Code SHALL + be submitted to the message layer and this interaction SHALL terminate. + +``` +NOTE Devices certified prior to 1.4 MAY return UNSUPPORTED_ACCESS for this condition. +``` +- If this action is marked with TimedRequest as TRUE but this action is not part of a Timed Write + transaction (i.e. there was no corresponding Timed Request action prior to it matching the same + TransactionID), then a Status Response action with the TIMED_REQUEST_MISMATCH Status + Code SHALL be submitted to the message layer and this interaction SHALL terminate. + +``` +NOTE Devices certified prior to 1.4 MAY return UNSUPPORTED_ACCESS for this condition. +``` +See Outgoing Write Response Action for building a Write Response action and executing the Write +Request action. + +- If this action was unicast and SuppressResponse is FALSE, a Write Response action SHALL be + +``` +Page 520 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +generated and submitted to the message layer to send to the initiator, otherwise no Write +Response SHALL be sent. +``` +**8.7.3. Write Response Action** + +This action is a following action for a Write Request action. Please see Common Action Behavior for +behavior common to all actions. The specific action information for this action is shown below. + +**8.7.3.1. Write Response Action Information** + +``` +Action Field Type Conformance Description +WriteResponses list[AttributeStatusIB] O a list of zero or more +concrete paths indicat­ +ing errors or successes +``` +**8.7.3.2. Outgoing Write Response Action** + +- This action SHALL be unicast. +- Each request path in the WriteRequests field of a Write Request SHALL be processed as follows: + ◦ If the path does not conform to Valid Write Attribute Paths then: + ▪ a Status Response with the INVALID_ACTION Status Code SHALL be generated as defined + in Status Response Action, + ▪ a Write Response action SHALL NOT be generated, + ▪ and this interaction and process SHALL terminate. + ◦ Else if the path is a concrete path: + ▪ If the path indicates a specific node that is unsupported, an AttributeStatusIB SHALL be + generated with the UNSUPPORTED_NODE Status Code. + ▪ Else if writing to the attribute in the path requires a privilege that is not granted to + access the cluster in the path, an AttributeStatusIB SHALL be generated with the UNSUP­ + PORTED_ACCESS Status Code. + ▪ Else if the path indicates a specific attribute that is restricted (see ManagedDevice), an + AttributeStatusIB SHALL be generated with the ACCESS_RESTRICTED Status Code. + ▪ Else if the path indicates a specific endpoint that is unsupported, an AttributeStatusIB + SHALL be generated with the UNSUPPORTED_ENDPOINT Status Code. + ▪ Else if the path indicates a specific cluster that is unsupported, an AttributeStatusIB + SHALL be generated with the UNSUPPORTED_CLUSTER Status Code. + ▪ Else if the path indicates an attribute or attribute data field that is unsupported, an + AttributeStatusIB SHALL be generated with the UNSUPPORTED_ATTRIBUTE Status Code + with the Path field indicating only the path to the first unsupported data field (not the + entire attribute data path). + ▪ Else if the path indicates a specific attribute data that is not writable, an AttributeSta­ + tusIB SHALL be generated with the UNSUPPORTED_WRITE Status Code. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 521 +``` + +``` +▪ Else if the path indicates specific attribute data that requires a Timed Write transaction +to write and this action is not part of a Timed Write transaction, an AttributeStatusIB +SHALL be generated with the NEEDS_TIMED_INTERACTION Status Code. +▪ Else if the attribute in the path indicates a fabric-scoped list and there is no accessing +fabric, an AttributeStatusIB SHALL be generated with the UNSUPPORTED_ACCESS Status +Code, with the Path field indicating only the path to the attribute. +▪ Else if the DataVersion field of the AttributeDataIB is present and does not match the +data version of the indicated cluster instance, an AttributeStatusIB SHALL be generated +with the DATA_VERSION_MISMATCH Status Code. +▪ If the above processing generated an AttributeStatusIB, the path SHALL be discarded. +▪ Else perform Write Path Data Process +◦ Else perform Request Path Expansion and process each expanded existent path as follows: +▪ If the path indicates attribute data that is not writable, then the path SHALL be dis­ +carded. +▪ If writing to the attribute in the path requires a privilege that is not granted to access the +cluster in the path, or is restricted (see ManagedDevice), then the path SHALL be dis­ +carded. +▪ Else if the path indicates specific attribute data that requires a Timed Write transaction +to write and this action is not part of a Timed Write transaction, then the path SHALL be +discarded. +▪ Else perform Write Path Data Process +``` +**8.7.3.3. Write Path Data Process** + +- If the path indicates a fabric-scoped list or list entry, it SHALL be processed as a fabric-filtered + list of fabric-scoped structs. +- Each data field indicated by the path, SHALL be processed in the order conveyed as follows: + ◦ If a data field is not within the constraints defined by the cluster specification, an AttributeS­ + tatusIB SHALL be generated with the CONSTRAINT_ERROR Status Code, with the Path field + duplicating the path. + ◦ Otherwise perform the following: + ▪ The data field SHALL be changed to the data indicated with the path. + ▪ An AttributeStatusIB SHALL be generated with the SUCCESS Status Code, with the Path + field duplicating the path. + +**8.7.3.4. Write Response Generation** + +- Each AttributeStatusIB generated from processing the WriteRequests field of the Write Request + action, SHALL be added to the WriteResponses action field of the Write Response action. + +``` +NOTE An empty WriteResponses would occur if all paths were wildcard or group +paths that expand to non-accessible data. +``` +``` +Page 522 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.7.3.5. Incoming Write Response Action** + +Upon receipt of this action, the action information SHALL be submitted to the layer above. + +**8.7.4. Timed Request Action** + +This action is a first action of a transaction. The specific action information for this action is shown +below. + +This action informs the receiver that another action will be sent in the same direction, within the +same transaction, and within a specified Timeout interval. The Timeout interval SHALL start when +the Status Response action acknowledging the Timed Request action with a success code is sent. + +**8.7.4.1. Timed Request Action Information** + +``` +Action Field Type Conformance Description +Timeout uint16 M an interval, in millisec­ +onds, to expect a fol­ +lowing action +``` +**8.7.4.2. Outgoing Timed Request Action** + +- This action SHALL be generated as an optional first action in a Write or Invoke transaction. +- This action SHALL be unicast. + +**8.7.4.3. Incoming Timed Request Action** + +- Upon receipt of this action, this layer SHALL construct and send a Status Response action with + SUCCESS to the initiator. +- This layer SHALL expect a Write Request or Invoke Request action within Timeout milliseconds + of sending the Status Response action. + +**8.8. Invoke Interaction** + +This interaction is generated when a device wishes to invoke one or more cluster specific com­ +mands on one or more nodes. Cluster commands are defined as either client to server or server to +client. Invoke Request action SHALL support group paths and SHOULD support wildcard paths. +Invoke Response action does not support wildcard paths. + +**8.8.1. Invoke Transaction** + +- The Invoke interaction SHALL consist of one of the Invoke transactions shown below + +**8.8.1.1. Timed Invoke Transaction** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 523 +``` + +``` +Action Action Flow Description +Timed Request Initiator ⇒ Target time interval defined to send +Invoke Request action +Status Response Initiator ⇐ Target confirmation +Invoke Request Initiator ⇒ Target commands to invoke +Invoke Response Initiator ⇐ Target response(s) defined by the clus­ +ter specification +``` +**8.8.1.2. Untimed Invoke Transaction** + +``` +Action Action Flow Description +Invoke Request Initiator ⇒ Target commands to invoke +Invoke Response Initiator ⇐ Target response(s) defined by the clus­ +ter specification +``` +- A client MAY choose to use a Timed Invoke transaction even if the command does not have the + Timed Interaction quality. +- The server SHALL support a Timed Invoke transaction for all commands. + +**8.8.2. Invoke Request Action** + +- This action SHALL be generated as the first action in an Invoke transaction, or following a + Timed Request action and successful Status Response action. +- If there is a preceding successful Timed Request action, the following Invoke Request action + SHALL be received before the end of the Timeout interval. +- If there is a preceding successful Timed Request action, the Timeout interval SHALL start when + the Status Response action acknowledging the Timed Request action with a success code is sent. +- Each Invoke Request and Invoke Response action in a Timed Invoke transaction SHALL be uni­ + cast. +- If not part of a Timed Invoke transaction, this action MAY be groupcast. +- If a cluster command is defined to be invoked as the result of a groupcast, the command SHALL + be invoked with an Invoke Request action which SHALL start a new transaction. +- Each path in an Invoke Request or Invoke Response action SHALL indicate a server cluster. + +Invoke Request action is either the first action of the Invoke transaction or it follows a successful +Timed Request action. Please see Common Action Behavior for behavior common to all actions. The +specific action information for this action is shown below. + +**8.8.2.1. Invoke Request Action Information** + +``` +Page 524 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Action Field Type Constraint Conformance Description +SuppressRe­ +sponse +``` +``` +bool M do not send a +response to this +action +TimedRequest bool M flag action as part +of a timed invoke +transaction +InvokeRequests list[Command­ +DataIB] +``` +``` +desc M cluster com­ +mand(s) +``` +**8.8.2.2. Outgoing Invoke Request Action** + +- This action SHALL be generated as the first action in an Invoke transaction, or following a + Timed Request action and successful Status Response action. +- If this action is part of a Timed Invoke transaction, TimedRequest SHALL be TRUE, else FALSE. +- A valid CommandDataIB SHALL be one in the table Valid Command Paths. +- If InvokeRequests has 1 CommandDataIB, + ◦ the path indicated in that CommandDataIB MAY target a group or a wildcard. +- Else (InvokeRequests has more than 1 CommandDataIB), + ◦ each path indicated in InvokeRequests SHALL be a concrete (non-wildcard) path and SHALL + NOT target a group, and + ◦ each path indicated in InvokeRequests SHALL be unique. + ◦ The total number of CommandDataIB in InvokeRequests SHALL NOT exceed what the server + indicates it can handle (See MaxPathsPerInvoke). + ◦ Care must be taken to avoid issuing a set of commands with some data dependencies + between them, since there is no guarantee of "happens-after" in the ordering. + +### NOTE + +``` +For InteractionModelRevision <= 11, having more than one command in Invok­ +eRequests was marked as provisional. +``` +**8.8.2.3. Incoming Invoke Request Action** + +- If this action is part of a Timed Invoke transaction, and the Timeout has expired from the pre­ + ceding Timed Request action, then a Status Response action with the TIMEOUT Status Code + SHALL be submitted to the message layer and this interaction SHALL terminate. + +``` +NOTE Devices certified prior to 1.4 MAY return UNSUPPORTED_ACCESS for this condition. +``` +- If this action is part of a Timed Invoke transaction, and this action has TimedRequest set to + FALSE, then a Status Response action with the TIMED_REQUEST_MISMATCH Status Code SHALL + be submitted to the message layer and this interaction SHALL terminate. +- If this action is marked with TimedRequest as TRUE, but this action is not part of a Timed + Invoke transaction (i.e. there was no immediately previous Timed Invoke action), then a Status + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 525 +``` + +``` +Response action with the TIMED_REQUEST_MISMATCH Status Code SHALL be submitted to the +message layer and this interaction SHALL terminate. +``` +- If this action contains more CommandDataIB elements in the InvokeRequests list than are sup­ + ported by the device (see MaxPathsPerInvoke), then a Status Response action with the + INVALID_ACTION Status Code SHALL be submitted to the message layer and this interaction + SHALL terminate. +- Each request path in the InvokeRequests field SHALL be processed as follows: + ◦ If the path does not conform to Valid Command Paths then: + ▪ a Status Response with the INVALID_ACTION Status Code SHALL be generated as defined + in Status Response Action, + ▪ an Invoke Response action SHALL NOT be generated, + ▪ and this interaction and process SHALL terminate. + ◦ Else if the path is a concrete path: + ▪ If the path indicates a node that is unsupported, a CommandStatusIB SHALL be gener­ + ated with the UNSUPPORTED_NODE Status Code. + ▪ Else if invoking the command in the path requires a privilege that is not granted to + access the cluster in the path, a CommandStatusIB SHALL be generated with the UNSUP­ + PORTED_ACCESS Status Code. + ▪ Else if the path indicates a specific command that is restricted (see ManagedDevice), a + CommandStatusIB SHALL be generated with the ACCESS_RESTRICTED Status Code. + ▪ Else if the path indicates an endpoint that is unsupported, a CommandStatusIB SHALL be + generated with the UNSUPPORTED_ENDPOINT Status Code. + ▪ Else if the path indicates a cluster that is unsupported, a CommandStatusIB SHALL be + generated with the UNSUPPORTED_CLUSTER Status Code. + ▪ Else if the path indicates a command that is unsupported, a CommandStatusIB SHALL be + generated with the UNSUPPORTED_COMMAND Status Code. + ▪ Else if the command in the path is fabric-scoped and there is no accessing fabric, a Com­ + mandStatusIB SHALL be generated with the UNSUPPORTED_ACCESS Status Code. + ▪ Else if the command in the path requires a Timed Invoke transaction to invoke and this + action is not part of a Timed Invoke transaction, a CommandStatusIB SHALL be gener­ + ated with the NEEDS_TIMED_INTERACTION Status Code. + ▪ Each generated CommandStatusIB CommandPath field SHALL be a duplicate of the con­ + crete path processed, including the command ID of the original concrete path. + ◦ Else perform Request Path Expansion and process each expanded existent path as follows: + ▪ If invoking the command in the path requires a privilege that is not granted for the clus­ + ter in the path, or is restricted (see ManagedDevice), then the path SHALL be discarded. + ▪ Else if the command in the path is fabric-scoped and there is no accessing fabric, then + the path SHALL be discarded. + ▪ Else if the command in the path requires a Timed Invoke transaction to invoke and this + action is not part of a Timed Invoke transaction, then the path SHALL be discarded. + +Page 526 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +- Each command in the remaining and error-free concrete command paths SHALL be executed, + as defined in Invoke Execution. + +**Invoke Execution** + +- The command SHALL be executed as defined in the cluster specification, and the following + applies: + ◦ For each data field in CommandFields: + ▪ If a mandatory data field is missing, or incoming data cannot be mapped to the expected + data type for a field, a CommandStatusIB SHALL be generated with an error status of + INVALID_COMMAND, even if the cluster defines another type of response. + ▪ If a data field violates expected constraints, a CommandStatusIB SHOULD be generated + with an error status of CONSTRAINT_ERROR. + ◦ If the cluster specification defines a following command in response to the command, a + CommandDataIB SHALL be generated for the following command with these fields: + ▪ CommandFields defined for the following command + ▪ ClusterPath field of the CommandPath field that is a duplicate of the command path + processed, up to the cluster ID + ▪ Command field of the CommandPath field that is the command ID of the following com­ + mand + ◦ Else if the cluster specification defines a success or error status as a response (sometimes + specified as a Default Response), a CommandStatusIB SHALL be generated with these fields: + ▪ CommandPath that is a duplicate of the concrete command path processed + ▪ Status as defined in the cluster specification +- If the InvokeRequest contains more than 1 CommandDataIB: + ◦ If the InvokeRequest contains certain commands and endpoints for which the server has an + efficient way to process those commands: + ▪ The server MAY do so, even if this would deviate from the general concept of "execution + started in order" for the commands which are grouped. + ◦ Else: + ▪ The Invoke Execution SHALL be started for each command in the same order as con­ + veyed and expanded. + ◦ Actions MAY run concurrently, and the protocol offers no guarantees about completion of + one action preceding the start of another. + ◦ In case one or more of these CommandDataIB triggers an asynchronous action, any given + Invoke Execution may not complete in the same order as the corresponding Command­ + DataIB in the request. As a consequence, the order of generated CommandDataIB and/or + CommandStatusIB MAY be different from the order of the corresponding CommandDataIB + in the InvokeRequest. +- An Invoke Response Generation SHALL be performed on completion of all valid commands. A + partial Invoke Response Generation MAY be performed at any time when processing multiple + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 527 +``` + +``` +commands, provided it carries at least a single response. +``` +**8.8.3. Invoke Response Action** + +Invoke Response action is a following action for an Invoke Request action. Please see Common +Action Behavior for behavior common to all actions. The specific action information for this action +is shown below. + +**8.8.3.1. Invoke Response Action Information** + +``` +Action Field Type Conformance Description +SuppressResponse bool M Ignored by client +InvokeResponses list[InvokeResponseIB] M command response or +status +``` +The SuppressResponse field is mandatory to maintain backwards compatibility with older clients. +However, as Matter does not support responses to InvokeResponse actions, this field has no effect. + +**8.8.3.2. Outgoing Invoke Response Action** + +- This action SHALL be generated in response to an Invoke Request action, after all valid com­ + mands are executed. +- A valid InvokeResponseIB SHALL only indicate a concrete path. + +**Invoke Response Generation** + +- If the previous action in this transaction action is groupcast, this process and transaction termi­ + nate with no response. +- Else if SuppressResponse is FALSE, or a CommandDataIB was generated, an Invoke Response + action SHALL be generated as follows: + ◦ Each generated CommandStatusIB and CommandDataIB SHALL be included in an InvokeRe­ + sponseIB in the InvokeResponses action field. + ◦ An Invoke Response action SHALL be submitted to the message layer to send to the source of + the previous action. + +**8.8.3.3. Incoming Invoke Response Action** + +- Upon receipt of this action, each entry in InvokeResponses SHALL be processed, in order, as fol­ + lows: + ◦ If the entry is a CommandStatusIB, it SHALL be submitted to the layer above. + ◦ Else if the response is a CommandDataIB: + ▪ If the ClusterPath field of the CommandPath field does not duplicate or match a wildcard + of one of the paths in the previous action of the interaction, the entry SHALL be dis­ + carded. + ▪ Else if the command ID value of the Command field of the CommandPath field is not + +``` +Page 528 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +expected by the cluster instance, the entry SHALL be discarded. +▪ Else it SHALL be submitted to the layer above. +``` +- For each entry in the initial Invoke Request action that triggered this incoming Invoke Response + action, if there isn’t a corresponding entry in InvokeResponses, a CommandStatusIB with the + NO_COMMAND_RESPONSE status SHALL be submitted to the layer above. + +``` +NOTE: Sending the NO_COMMAND_RESPONSE should only be done after receiving all +encoded/transported messages, which indicates that the interaction is completed and +the response is missing for those requests. +``` +**8.9. Common Action Information Blocks and Paths** + +Shown below are common information blocks used to submit actions to, and receive actions from, +the message layer. + +**8.9.1. Path Information** + +- Logically for this specification, the Node or Group SHALL be present in all paths. +- When an outgoing path indicates the same Node or Group as the action target, the message + layer MAY optimize the path by removing Node or Group. +- When an incoming path does not indicate a Node or Group, the message layer SHALL add the + action target (Node or Group) to the path. + +See Path for more information. + +**8.9.1.1. ClusterPathIB** + +``` +Path Field Type Quality Conformance +Group group-id !Endpoint +Node node-id !Group +Endpoint endpoint-no A !Group +Cluster cluster-id A M +``` +**8.9.2. Attribute Information Blocks** + +**8.9.2.1. AttributePathIB** + +An attribute path supports nesting levels deeper than the attribute with the NestedPath field below. +The NestedPath indicates zero or more nesting levels to establish the nesting depth of the attribute +path. + +- An attribute path MAY indicate data at any nesting depth in the attribute data. +- If the Attribute is indicated as a wildcard then the path SHALL indicate all attributes of the clus­ + ter. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 529 +``` + +- If the Attribute is indicated as a wildcard, then NestedPath SHALL be empty. +- If the final nesting level in an attribute path indicates a collection data type, then the path + SHALL indicate all collection data, plus any deeper nested data as part of the collection. +- If the WildcardPathFlags field is absent, it SHALL be considered to be an empty map with all + flags unset. + +``` +Path Field Type Quality Conformance +Cluster ClusterPathIB M +Attribute attrib-id A M +NestedPath list[NestingLevelIB] Attribute != wildcard +WildcardPathFlags WildcardPathFlags­ +Bitmap +``` +### P, O + +**8.9.2.2. NestingLevelIB** + +This defines a deeper nesting level of an attribute path to collection data, such as a struct field, or +list entry. + +``` +Path Field Type Quality Conformance +FieldID field-id A O.a +ListIndex entry-idx A O.a +``` +**8.9.2.3. WildcardPathFlagsBitmap** + +The WildcardPathFlagsBitmap indicates flags that apply to the path, affecting wildcard expansion. + +The following flags are defined: + +``` +Bit Name Summary +0 WildcardSkipRootNode Skip the Root Node endpoint +(endpoint 0) during wildcard +expansion. +1 WildcardSkipGlobalAttributes Skip several large global attrib­ +utes during wildcard expan­ +sion. +2 WildcardSkipAttributeList Skip the AttributeList global +attribute during wildcard +expansion. +3 Reserved +4 WildcardSkipCommandLists Skip the AcceptedCommandList +and GeneratedCommandList +global attributes during wild­ +card expansion. +``` +``` +Page 530 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary +5 WildcardSkipCustomElements Skip any manufacturer-specific +clusters or attributes during +wildcard expansion. +6 WildcardSkipFixedAttributes Skip any Fixed (F) quality attrib­ +utes during wildcard expan­ +sion. +7 WildcardSkipChangesOmitte­ +dAttributes +``` +``` +Skip any Changes Omitted (C) +quality attributes during wild­ +card expansion. +8 WildcardSkipDiagnosticsClus­ +ters +``` +``` +Skip all clusters with the Diag­ +nostics (K) quality during wild­ +card expansion. +``` +**8.9.2.4. Valid Read Attribute Paths** + +This table is valid for AttributePathIB for a Read Request action or a Subscribe Request action. See +AttributePathIB for more conformance restrictions. + +The table defines valid attribute data path with wildcard and non-wildcard combinations. + +``` +Node Endpoint Cluster Attribute Attribute Data +Requested +Specific Wildcard Wildcard Wildcard all attribute data +from all clusters +on all endpoints +on a specific node +Specific Wildcard Wildcard Specific specific global +attribute data or +field for all clus­ +ters on all end­ +points on a spe­ +cific node (e.g. +ClusterRevision) +Specific Wildcard Specific Wildcard all attribute data +from a specific +cluster on all end­ +points on a spe­ +cific node (e.g. +Descriptor cluster) +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 531 +``` + +``` +Node Endpoint Cluster Attribute Attribute Data +Requested +Specific Wildcard Specific Specific a specific attribute +data or field from +a specific cluster +on all endpoints +on a specific node +(e.g. Descriptor +cluster) +Specific Specific Wildcard Wildcard all attribute data +from all clusters +on a specific end­ +point on a specific +node +Specific Specific Wildcard Specific a specific global +attribute data or +field for all clus­ +ters on a specific +endpoint on a spe­ +cific node (e.g. +ClusterRevision) +Specific Specific Specific Wildcard all attribute data +from a specific +cluster on a spe­ +cific endpoint a +specific node +Specific Specific Specific Specific a specific attribute +data or field from +a specific cluster +on a specific end­ +point on a specific +node +``` +**8.9.2.5. Valid Write Attribute Paths** + +This table is valid for Path field of a AttributeDataIB for a Write Request action. See AttributeDataIB +and AttributePathIB for more conformance restrictions. + +The table defines valid attribute data paths including combinations with wildcards, non-group +(node & endpoint), and group paths. A blank entry means the element does not exist in the path. + +``` +Page 532 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Node Endpoint Group Cluster Attribute Attribute Data +Provided +Specific Wildcard Specific Specific a specific +attribute data +or field from a +specific cluster +on all end­ +points on a spe­ +cific node +Specific Specific Specific Specific a specific +attribute data +or field from a +specific cluster +on a specific +endpoint on a +specific node +Specific Specific Specific a specific +attribute data +or field from a +specific cluster +on a specific +group of zero +or more end­ +points on each +node +``` +**8.9.2.6. AttributeDataIB** + +This is used in Write Request and Report Data actions. + +``` +Info Field Type Quality Conformance +DataVersion data-ver desc +Change enum8 desc +Path AttributePathIB M +Data desc M +``` +**DataVersion** + +- This field SHALL NOT be present for a group or wildcard path. +- This field MAY be present for a path in a Write Request action. +- This field SHALL be present for a path in a Report Data action. + +**Change** + +This field indicates a change to a list for a write interaction, or as reported for a read or subscribe + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 533 +``` + +interaction. + +- This field SHALL only be present if the data type is a list entry index or list data type. +- The list change SHALL be in the context of a fabric-filtered list, if fabric-filtering is enabled or + required. +- This field SHALL be one of the values defined in the table below. + +``` +Name Description +REPLACE This indicates the entire list changing to another +list. +ADD This adds one or more entries without imposing +a specific order. +``` +To delete or modify single entries in the list, the full list needs to be replaced. + +**REPLACE** + +- This Change value SHALL indicate replacing the entire list. +- This Change value SHALL only be used when the last nesting level of the Path field indicates a + list (Attribute or FieldID). +- The data type of the AttributeDataIB Data field SHALL be list. +- The Data field MAY be an empty list which effectively deletes all entries from the list. + +**ADD** + +- This Change value SHALL indicate adding one entry to the list. +- This Change value SHALL only be used when the last nesting level of the Path field indicates a + list (Attribute or FieldID). +- The data type of the AttributeDataIB Data field SHALL be the data type of the list’s entries. + +**Path** + +See AttributePathIB. + +**Data** + +- The data type of this field SHALL be the data type of the data indicated by the Path field. +- If the final nesting level indicated by the Path is an list entry index of null, the data type SHALL + be the data type of the list’s entries. + +**8.9.2.7. AttributeReportIB** + +``` +Info Field Type Quality Conformance +AttributeStatus AttributeStatusIB O.a +AttributeData AttributeDataIB O.a +``` +``` +Page 534 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Only one of the above two fields SHALL be present. + +**8.9.2.8. DataVersionFilterIB** + +``` +Info Field Type Quality Conformance +Path ClusterPathIB M +DataVersion data-ver M +``` +- The Path field SHALL indicate a concrete path. + +**8.9.3. Event Information Blocks and Paths** + +**8.9.3.1. EventFilterIB** + +``` +Info Field Type Quality Conformance +Node node-id M +EventMin event-no M +``` +**8.9.3.2. EventPathIB** + +``` +Path Field Type Quality Conformance +Path ClusterPathIB M +Event event-id O +IsUrgent bool O +``` +**8.9.3.3. Valid Event Paths** + +This table is valid for EventPathIB. The table defines valid event paths including combinations with +wildcards, but not group paths. + +``` +Node Endpoint Cluster Event Event(s) +Requested +Specific Wildcard Wildcard Wildcard all events from all +clusters on all end­ +points on a spe­ +cific node +Specific Wildcard Specific Wildcard all events from a +specific cluster on +all endpoints on a +specific node (e.g. +Descriptor cluster) +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 535 +``` + +``` +Node Endpoint Cluster Event Event(s) +Requested +Specific Wildcard Specific Specific a specific event +from a specific +cluster on all end­ +points on a spe­ +cific node (e.g. +Descriptor cluster) +Specific Specific Wildcard Wildcard all events from all +clusters on a spe­ +cific endpoint on a +specific node +Specific Specific Specific Wildcard all events from a +specific cluster on +a specific endpoint +on a specific node +Specific Specific Specific Specific a specific event +from a specific +cluster on a spe­ +cific endpoint on a +specific node +``` +**8.9.3.4. EventDataIB** + +``` +Info Field Type Quality Conformance +Path EventPathIB M +EventNumber event-no M +Priority priority M +EpochTimeStamp posix-ms O.a +SystemTimeStamp systime-ms O.a +Data variable M +``` +- The Path field SHALL indicate an existent path. +- The Path field SHALL NOT have an IsUrgent field present. + +**Data Field** + +The Data field SHALL contain the cluster-specific payload of the Event. + +**8.9.3.5. EventReportIB** + +``` +Info Field Type Quality Conformance +EventStatus EventStatusIB O.a +``` +``` +Page 536 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Info Field Type Quality Conformance +EventData EventDataIB O.a +``` +- Only one of the above fields SHALL be present. + +**8.9.4. Command Information Blocks and Paths** + +**8.9.4.1. CommandPathIB** + +``` +Path Field Type Quality Conformance +ClusterPath ClusterPathIB M +Command command-id M +``` +**8.9.4.2. Valid Command Paths** + +This table is valid for CommandPathIB. The table defines valid command paths including combina­ +tions with wildcards, non-group (node & endpoint), and group paths. A blank entry means the ele­ +ment does not exist in the path. + +``` +Node Endpoint Group Cluster Command Description Confor­ +mance +Specific Wildcard Specific Specific a specific +cluster com­ +mand to all +endpoints of +a node +``` +### P, M + +``` +Specific Specific Specific Specific a specific +cluster com­ +mand to a +specific end­ +point on a +node +``` +### M + +``` +Specific Specific Specific a specific +cluster com­ +mand to a +group of +endpoints +``` +### M + +``` +NOTE Support for commands paths involving wildcards is provisional. +``` +**8.9.4.3. CommandDataIB** + +``` +Info Field Type Quality Conformance +CommandPath CommandPathIB M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 537 +``` + +``` +Info Field Type Quality Conformance +CommandFields variable M +CommandRef uint16 O +``` +**CommandRef field** + +This field is used to provide a reference for a command. + +- When used in an Invoke Request Action: + ◦ This field MAY be omitted if InvokeRequests contains only a single CommandDataIB. + ◦ When InvokeRequests contains multiple CommandDataIBs, the CommandRef field SHALL + contain a value unique within InvokeRequests. + ▪ Implementations MAY choose to use the index of the CommandDataIB within the Invok­ + eRequests field as the value of this field. +- When used in an Invoke Response Action: + ◦ CommandRef MAY be omitted from the CommandDataIB in InvokeResponses if the Invok­ + eRequests being responded to contains only a single CommandDataIB, even if CommandRef + was included in that CommandDataIB. + ◦ CommandRef SHALL be included in the CommandDataIB in InvokeResponses if Invok­ + eRequests contained more than one CommandDataIB. + ◦ When a CommandDataIB in InvokeResponses has a CommandRef field, its value SHALL be + equal to the CommandRef field from the CommandDataIB (in the InvokeRequests) that gen­ + erated this CommandDataIB. + ▪ If InvokeRequests contained only a single CommandDataIB, and CommandRef was not + included in that CommandDataIB, then CommandRef for this CommandDataIB in Invok­ + eResponses SHALL NOT be included. + +**8.9.4.4. InvokeResponseIB** + +This is used in response to an invoked command. + +``` +Info Field Type Quality Conformance +Command CommandDataIB O.a +Status CommandStatusIB O.a +``` +- Only one of the above fields SHALL be present. +- The Path field in CommandDataIB and CommandStatusIB SHALL indicate a concrete path. + +**8.9.5. Status Information Blocks and Paths** + +**8.9.5.1. CommandStatusIB** + +This is used to indicate a command response that represents a status: an invalid command, an error +accessing the command, successful execution of a command without a following command, and so + +``` +Page 538 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +on. + +``` +Info Field Type Quality Conformance +CommandPath CommandPathIB M +Status StatusIB M +CommandRef uint16 O +``` +- The Path field SHALL indicate a concrete path. + +**CommandRef field** + +This field is used to provide a reference for a command. + +- CommandRef MAY be omitted from the CommandStatusIB if InvokeRequests contains only a + single CommandDataIB, even if CommandRef was included in that CommandDataIB. +- CommandRef SHALL be included in the CommandStatusIB in InvokeResponses if Invok­ + eRequests contained more than one CommandDataIB. +- When a CommandStatusIB in InvokeResponses has a CommandRef field, its value SHALL be + equal to the CommandRef field from the CommandDataIB (in InvokeRequests) that generated + this CommandStatusIB. + ◦ If InvokeRequests contained only a single CommandDataIB, and CommandRef was not + included in that CommandDataIB, then CommandRef for this CommandStatusIB in Invok­ + eResponses SHALL NOT be included. + +**8.9.5.2. EventStatusIB** + +This is used to indicate an invalid event, or an error accessing the event. + +``` +Info Field Type Quality Conformance +Path EventPathIB M +Status StatusIB M +``` +- The Path field SHALL indicate a concrete path. + +**8.9.5.3. AttributeStatusIB** + +This is used to indicate an invalid attribute data request path, or an error accessing the data, or suc­ +cess writing to an attribute path. + +``` +Info Field Type Quality Conformance +Path AttributePathIB M +Status StatusIB M +``` +- The Path field SHALL indicate a concrete path. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 539 +``` + +**8.9.5.4. StatusIB** + +This is used to respond with errors or success to actions. A success Status field is valid for every +layer. A non-success Status field is either defined in this layer, or generated and recognized by +another layer. ClusterStatus is defined in a cluster specification. + +Please see Status Codes for valid values for Status. + +``` +Info Field Type Quality Conformance +Status status M +ClusterStatus status O +``` +**Status Field** + +This is the one of the common status code values defined in Status Code Table. + +**ClusterStatus Field** + +ClusterStatus values are defined in a cluster specification. + +**8.10. Status Codes** + +The table below lists global status codes for the Interaction Model. These MAY be used by interac­ +tion model processing of actions and as common status codes for cluster specifications. All values +not defined here SHALL be reserved (per general conventions). Cluster specifications that wish to +communicate a status not defined in this table MAY use a cluster-specific status code as described in +Status Codes. + +**8.10.1. Status Code Table** + +``` +Status Code Value Summary +0x00 SUCCESS Operation was successful. +0x01 FAILURE Operation was not successful. +0x7D INVALID_SUBSCRIPTION Subscription ID is not active. +0x7E UNSUPPORTED_ACCESS +``` +``` +NOT_AUTHORIZED +``` +``` +The sender of the action or +command does not have autho­ +rization or access. +NOT_AUTHORIZED is an obso­ +lete name of this error code. +0x7F UNSUPPORTED_ENDPOINT The endpoint indicated is +unsupported on the node. +0x80 INVALID_ACTION The action is malformed, has +missing fields, or fields with +invalid values. Action not car­ +ried out. +``` +``` +Page 540 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Status Code Value Summary** + +0x81 **UNSUPPORTED_COMMAND** + +``` +UNSUP_COMMAND +``` +``` +The indicated command ID is +not supported on the cluster +instance. Command not carried +out. +UNSUP_COMMAND is an obso­ +lete name for this error code. +``` +0x82 _reserved_ Deprecated: use UNSUPPORT­ +ED_COMMAND + +0x83 _reserved_ Deprecated: use UNSUPPORT­ +ED_COMMAND + +0x84 _reserved_ Deprecated: use UNSUPPORT­ +ED_COMMAND + +0x85 **INVALID_COMMAND** + +``` +INVALID_FIELD +``` +``` +The cluster command is mal­ +formed, has missing fields, or +fields with invalid values. Com­ +mand not carried out. +INVALID_FIELD is an obsolete +name for this error code. +``` +0x86 **UNSUPPORTED_ATTRIBUTE** The indicated attribute ID, field +ID or list entry does not exist for +an attribute path. + +0x87 **CONSTRAINT_ERROR** + +``` +INVALID_VALUE +``` +``` +Out of range error or set to a +reserved value. Attribute keeps +its old value. Note that an +attribute value may be out of +range if an attribute is related +to another, e.g. with minimum +and maximum attributes. See +the individual attribute descrip­ +tions for specific details. +INVALID_VALUE is an obsolete +name for this error code. +``` +0x88 **UNSUPPORTED_WRITE** + +``` +READ_ONLY +``` +``` +Attempt to write a read-only +attribute. +READ_ONLY is an obsolete +name for this error code. +``` +0x89 **RESOURCE_EXHAUSTED** + +``` +INSUFFICIENT_SPACE +``` +``` +An action or operation failed +due to insufficient available +resources. +INSUFFICIENT_SPACE is an +obsolete name for this error +code. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 541 +``` + +``` +Status Code Value Summary +0x8A reserved Legacy cluster specification +error status code: use SUCCESS +0x8B NOT_FOUND The indicated data field or +entry could not be found. +0x8C UNREPORTABLE_ATTRIBUTE Reports cannot be issued for +this attribute. +0x8D INVALID_DATA_TYPE The data type indicated is unde­ +fined or invalid for the indi­ +cated data field. Command or +action not carried out. +0x8E reserved Legacy cluster specification +error status code: use UNSUP­ +PORTED_ATTRIBUTE. +0x8F UNSUPPORTED_READ Attempt to read a write-only +attribute. +0x90 reserved Deprecated: use FAILURE +0x91 reserved Deprecated: use FAILURE +0x92 DATA_VERSION_MISMATCH Cluster instance data version +did not match request path +0x93 reserved Legacy cluster specification +error status code: use FAILURE +0x94 TIMEOUT The transaction was aborted +due to time being exceeded. +0x95 reserved ZCL OTA Upgrade cluster spe­ +cific error status code +0x96 reserved ZCL OTA Upgrade cluster spe­ +cific error status code. +0x97 reserved ZCL OTA Upgrade cluster spe­ +cific error status code. +0x98 reserved ZCL OTA Upgrade cluster spe­ +cific error status code. +0x99 reserved ZCL OTA Upgrade cluster spe­ +cific error status code. +0x9A reserved ZCL OTA Upgrade cluster spe­ +cific error status code. +0x9B UNSUPPORTED_NODE The node ID indicated is not +supported on the node. +``` +Page 542 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Status Code Value Summary** + +0x9C **BUSY** The receiver is busy processing +another action that prevents +the execution of the incoming +action. + +0x9D **ACCESS_RESTRICTED** The access to the action or com­ +mand by the sender is permit­ +ted by the ACL but restricted by +the ARL. + +0xC0 _reserved_ Deprecated: use FAILURE + +0xC1 _reserved_ Deprecated: use FAILURE + +0xC2 _reserved_ Deprecated: use FAILURE + +0xC3 **UNSUPPORTED_CLUSTER** The cluster indicated is not sup­ +ported on the endpoint. + +0xC4 _reserved_ Deprecated: use SUCCESS + +0xC5 **NO_UPSTREAM_SUBSCRIP­ +TION** + +``` +Used by proxies to convey to +clients the lack of an upstream +subscription to a source. +``` +0xC6 **NEEDS_TIMED_INTERACTION** A Untimed Write or Untimed +Invoke interaction was used for +an attribute or command that +requires a Timed Write or +Timed Invoke. + +0xC7 **UNSUPPORTED_EVENT** The indicated event ID is not +supported on the cluster +instance. + +0xC8 **PATHS_EXHAUSTED** The receiver has insufficient +resources to support the speci­ +fied number of paths in the +request + +0xC9 **TIMED_REQUEST_MISMATCH** A request with TimedRequest +field set to TRUE was issued out­ +side a Timed transaction or a +request with TimedRequest set +to FALSE was issued inside a +Timed transaction. + +0xCA **FAILSAFE_REQUIRED** A request requiring a Fail-safe +context was invoked without +the Fail-Safe context. + +0xCB **INVALID_IN_STATE** The received request cannot be +handled due to the current +operational state of the device + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 543 +``` + +``` +Status Code Value Summary +0xCC NO_COMMAND_RESPONSE A CommandDataIB is missing a +response in the InvokeRe­ +sponses of an Invoke Response +action. +0xCD TERMS_AND_CONDITION­ +S_CHANGED +``` +``` +The node requires updated TC +acceptance. The user MAY be +directed to visit the Enhanced­ +SetupFlowMaintenanceUrl to +complete this. +0xCE MAINTENANCE_REQUIRED The node requires the user to +visit the EnhancedSetupFlow­ +MaintenanceUrl for instruc­ +tions on further action. +``` +Page 544 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 9. System Model Specification** + +**9.1. Practical Information** + +**9.1.1. Revision History** + +``` +Revision Description +1 Initial release of this specification +2 Added usage description for TagList +``` +**9.1.2. Scope and Purpose** + +This is part of a package of Data Model specifications that are agnostic to underlying layers (encod­ +ing, message, network, transport, etc.). Each specification below may be independently maintained. +This package, as a whole, SHALL be independently maintained as agnostic and decoupled from +lower layers. This package may be referenced by inclusion in a set of protocol stack specifications +for a complete vertical standard. + +``` +Data Model Defines first order elements and namespace for endpoints, clusters, +attributes, data types, etc. +``` +``` +Interaction Model Defines interactions, transactions and actions between nodes. +``` +``` +System Model Defines relationships that are managed between endpoints and clusters. +``` +``` +Cluster Library Reference library of cluster specifications. +``` +``` +Device Library Reference library of devices type definitions. +``` +**9.1.3. Origin Story** + +The origin of this section is the Dotdot Architecture Model and parts of Chapter 2 of the Zigbee Clus­ +ter Library specification that define the data model. + +The purpose is that this document will align with current cluster specifications in the ZCL and still +support cluster updates and evolution into a single set of data models. + +**9.1.4. Overview** + +This specification defines persistent relationships between local and remote instances of data +model elements, that support a system of operational communication between such instances. A +system is a set of nodes and persistent relationships that automate data flow and control based on +local or external stimulus. + +**9.2. Endpoint Composition** + +- Endpoint composition SHALL be indicated by these Descriptor cluster attributes: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 545 +``` + +``` +◦ DeviceTypeList SHALL list the device type(s) that the endpoint supports. +◦ PartsList SHALL indicate endpoints as required for each device type in the DeviceTypeList. +``` +- The population of the PartsList of the various endpoints allows for the indication of a hierarchy + (composition) for which the following terms are defined: + ◦ "Descendants" of an endpoint E are endpoints that are: + ▪ in the PartsList of E, or + ▪ descendants of an endpoint in the PartsList of E. + ◦ "Children" of an endpoint E are endpoints that are descendants of E but not descendants of + any endpoint in the PartsList of E. + ◦ "Sibling endpoints" are endpoints which are children of the same endpoint. + +``` +Example: in the figure below, endpoint 0 (Root Node, thus using full-family pattern) has a +PartsList containing endpoints 1 through 5. Endpoint 1 has a PartsList containing endpoints 2 +and 4, endpoint 2 has a PartsList containing endpoint 3, and endpoint 4 has a PartsList con­ +taining endpoint 5. Therefore, endpoints 2, 3, 4 and 5 are not children of endpoint 0 and thus +do not qualify as siblings of endpoint 1 (which is the only child of endpoint 0). +``` +``` +Endpoint 1 has a PartsList containing endpoints 2 and 4, and endpoints 2 and 4 do not occur +in any other PartsList of a descendant of endpoint 1, so endpoints 2 and 4 are children of end­ +point 1, and they are sibling endpoints. +``` +``` +Endpoint 2 has a PartsList containing only endpoint 3, so endpoint 3 is a single child and does +not have any siblings. +``` +``` +Endpoint 4 has a PartsList containing only endpoint 5, so endpoint 5 is a single child and does +not have any siblings. +``` +``` +Endpoints 3 and 5 are not appearing together in any other PartsList (except that of endpoint +0), so they are not siblings. +``` +- Each simple endpoint SHALL support exactly one Application device type with these exceptions: + ◦ The endpoint MAY support additional device types which are subsets of the Application + device type (the superset). See Superset Device Types for cluster requirements of superset + devices. + ◦ The endpoint MAY support additional device types (application, utility or node device types) + as defined by each additional device type. + +``` +For example: A Color Temperature Light device type may support device type IDs for both a +Dimmable Light and On/Off Light, because those are subsets of a Color Temperature Light +(the superset). +``` +``` +For example: A Room Temperature Sensor device type and a Room Humidity Sensor device +type must be on separate endpoints because they are both Simple device types and neither is +a subset of the other. +``` +Page 546 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +For example: The Bridged Node device type (a utility device type) may be added to an end­ +point, which means this endpoint represents a node behind a bridge, and requires one or +more extra clusters. +``` +- A leaf device type is not composed of other application device types (see above bullet on sub­ + sets). + +``` +For example: The Temperature Sensor device type mandates the Temperature Measurement +server cluster, and does not require additional device types or endpoints. +``` +- Most device types define leaf endpoints without the need for composition. + +``` +For example: A Dimmer Switch device type mandates these clusters: On/Off, Level Control, +Identify, and does not require additional device types or endpoints. +``` +- There can be situations where leaf endpoints have no application device types, and one or more + utility device types. + +``` +For example: a light with mains power and battery back-up. This needs two endpoints for the +two Power Source device types, each of which has a Power Source cluster, to describe both +power sources, and only one of those endpoints can host the lighting application device type. +The other endpoint will only have the Power Source cluster, and no application device type. +``` +- A composed device type is composed of one or more other device types, which have their own + endpoints which are listed in the PartsList of the endpoint of the composed device type. + +``` +For example: An endpoint supporting a Temperature Controlled Cabinet device type inside a +Refrigerator device type which has 2 temperature sensors (one for freezer temperature, and +one for ice tray temperature) would have a PartsList containing 2 temperature sensor leaf +endpoints (one for each of the sensors). Those leaf endpoints would indicate and conform to +the temperature sensor device type, and have unique TagList attributes to disambiguate +them. +``` +- Endpoint composition SHALL be defined in the device type specification. + +**9.2.1. Endpoint Composition Patterns** + +This specification defines two patterns for endpoint composition supported by a device type: + +- Tree pattern of endpoints directly below the composed endpoint. +- Full-family list of all descendant endpoints below the composed endpoint. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 547 +``` + +**9.2.1.1. Tree Pattern** + +The tree pattern supports a general tree of endpoints, each of which supports the pattern defined +by the endpoint’s device type. The tree pattern is commonly used for composed application device +types. The tree pattern is commonly used for device types that support physical device composition +(e.g. a Refrigerator). + +- The tree pattern of composition SHALL be defined in the device type specification, by a table of + device types, from which the specified device type is composed. + ◦ Each device type from the table that is included in an implementation SHALL be repre­ + sented by one or more endpoints in the PartsList attribute of the Descriptor cluster on the + endpoint of the parent device type. + ◦ An implementation MAY include other device types not listed in the table of device types in + its composition and each such additional device SHALL be represented by an endpoint in + the PartsList attribute of the Descriptor cluster on the endpoint of the parent device type. + +``` +For example: A Refrigerator/Freezer endpoint has a PartsList with the Refrigerator and +Freezer endpoint, but not the parts of the Refrigerator or Freezer. The Refrigerator and +Freezer endpoints each have a PartsList that includes temperature sensor and control end­ +points. +``` +**9.2.1.2. Full-Family Pattern** + +The full-family pattern is a list of all descendant endpoints, with no imposed hierarchy. + +- The full-family pattern of endpoint composition SHALL be defined in the device type specifica­ + tion by stating that the device type supports the full-family pattern. +- The PartsList attribute of the Descriptor cluster on the endpoint SHALL contain all descendant + endpoints. + +``` +Example: The Root Node and Aggregator device types use the full-family pattern, as defined +in their device type specification. +``` +**9.2.1.3. No Cycles** + +- An endpoint SHALL NOT include itself in its PartsList attribute. +- Cycles where an endpoint is a (direct or indirect) ancestor of itself SHALL NOT occur. + +**9.2.2. Root Node Endpoint** + +A root node device type is a category of device type that is specified to be supported by all nodes in +a fabric. Its main function is to describe the node and what endpoints the node supports. + +- A root node device type SHALL be a singleton on the root node endpoint. +- The PartsList of the Descriptor cluster on the root node endpoint SHALL list all endpoints on the + +``` +Page 548 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +node, except the root node endpoint. +``` +- The root node endpoint SHALL NOT exist in any other endpoint’s PartsList on the node. +- The root node endpoint requirements are defined by a node scoped device type. +- There SHALL be only one root node endpoint for the node. + +### NOTE + +``` +The root node endpoint is currently under-specified for nodes which are not com­ +missionable. As a result, the root node endpoint on non-commissionable nodes MAY +be absent or otherwise limited in functionality. This specification gap is expected to +be addressed in a future revision. +``` +**9.2.3. Disambiguation** + +Using the terms and composition patterns described above, some endpoints will have sibling end­ +points with an overlap in application device type(s). For this case, the **Duplicate** condition has been +defined (see the Base Device Type in the Device Library). + +- A device type definition MAY define a method for disambiguation when the Duplicate condition + applies to either the endpoint with that device type or to its children. +- If no disambiguation method is defined in the relevant device type definitions, an endpoint to + which the Duplicate condition applies SHALL have a TagList attribute in its Descriptor cluster + and its set of tags SHALL be distinct from the set of tags of any sibling endpoint with which it + has an overlap in application device type(s). When comparing sets of tags, ordering of the list + SHALL be ignored. +- The TagList feature and attribute MAY also be used in other cases to provide guidance to a client + and/or a user. +- When the Duplicate condition applies, clients SHOULD disambiguate the relevant sibling end­ + points in their user interfaces and client logic using the method defined in the device type or the + TagList attribute values if no other method is defined. + +``` +For example: If the Duplicate condition applies to child endpoints of an Aggregator endpoint +that represent multiple independent bridged devices, the endpoints make available metadata +to allow a client to disambiguate distinct bridged devices with an overlap in application +device types. Typically this is done using the NodeLabel attribute of the Bridged Device Basic +Information cluster - thus reusing the naming information which the bridge already has to +allow disambiguation to the user when using a direct user interface to the bridge. +``` +``` +For instance: The Aggregator in this example, exposes several Color Temperature Lights (end­ +points 13 and 22) which are disambiguated with their NodeLabel. Note that the composed +device at endpoints 24, 25 and 26 also uses a TagList since, for this case, the bridge knows the +lighting direction of both elements of the composed device. +``` +``` +Another example: The following diagram (copied from Chapter 10 of the Device Library) +shows a Video Player device containing 3 separate Content Apps on endpoints 21, 31 and 41 +which are disambiguated using the ApplicationName attribute of the Application Basic clus­ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 549 +``` + +``` +ter on these endpoints. +``` +``` +Figure 44. Endpoint Composition for Video Player Device +``` +Note that these requirements related to disambiguation hold for non-composed as well as com­ +posed device types, as illustrated in the examples below. + +``` +Example of using TagList for disambiguation for a non-composed device type: A switch device +with two buttons. +``` +- Endpoint 0 has device type Root Node with a PartsList with endpoints 11 and 12 (these are + sibling endpoints per the definition above) +- Endpoint 11 has device type Generic Switch and TagList containing two tags: Position.Left + and Number.One +- Endpoint 12 has device type Generic Switch and TagList containing two tags: Posi­ + tion.Right and Number.Two + +``` +Example of using TagList for disambiguation of a composed device type: a refrigerator with +two cabinets (fresh food and freezer), as illustrated in the figure below: +``` +- Endpoint 1 has the composed device type (Refrigerator) and the PartsList contains end­ + points 2 and 4 (but not 3 and 5). + +``` +Page 550 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Endpoints 2 and 4 are sibling endpoints which each have a device type Temperature Con­ + trolled Cabinet, with a TagList to disambiguate. +- Endpoint 2 has a PartsList with endpoint 3 to indicate that the temperature sensor on end­ + point 3 measures the temperature in the refrigerator (fresh food) compartment. Endpoint + 3 is a child of endpoint 2. +- Similarly, endpoint 4 has a PartsList with endpoint 5 to indicate that the temperature sen­ + sor on endpoint 5 measures the temperature in the freezer compartment. Endpoint 5 is a + child of endpoint 4. +- Endpoints 3 and 5 each use a TagList to indicate to the client details about the placement + of the temperature sensor inside the Temperature Controlled Cabinet of endpoint 2 and 4. + Note that these TagLists in this example are identical (in the product, both sensors are + located in the top left position of their respective compartment), which is allowed since + endpoints 3 and 5 are not siblings, hence the "Duplicate" condition does not apply. So + these endpoints are using a TagList to provide information rather than to disambiguate. + +``` +Figure 45. Disambiguation and information via semantic tags +``` +**9.2.4. Dynamic Endpoint Allocation** + +Some nodes MAY require a dynamic number of endpoints, since the functionality they expose can +change at run-time, e.g. + +- a Bridge on which Bridged Devices are added or deleted. +- a Casting Video Player in which Content App endpoints are added or deleted (see Device + Library, section 10). + +Such dynamic entities which need to be exposed with an endpoint, will be referred to as an +"exposed entity" in the following description. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 551 +``` + +For any node which changes its endpoint composition, the endpoint addresses SHALL be allocated +according to the following rules: + +- When such exposed entity is exposed for the first time, it SHALL be allocated a _new_ endpoint + address (or set of endpoint addresses), incrementing from the highest previously (ever) used + endpoint address. + ◦ For the situation where a node following these mechanisms has exhausted all available + remaining endpoint addresses for exposed entities, it MAY wrap around to the lowest + unused endpoint address, starting at 1, since the RootNode endpoint (endpoint 0) cannot be + used to host application device types and is therefore never free. +- For existing exposed entities, the endpoint addresses SHALL NOT be changed. + ◦ This persistency requirement also holds for the case of restart/reboot of the device. + +As a result of these mechanisms, endpoint addresses that were used for exposed entities that were +once exposed but now have been removed will _not_ be reused in the future (apart from the excep­ +tional wrap-around corner case mentioned above), in order to avoid the possibility of confusing +other nodes by re-assigning (reusing) an endpoint address for a _different_ exposed entity. Other +nodes using the exposed entities from this node SHOULD remove information related to exposed +entities no longer being exposed. + +Other nodes that wish to be notified of changes of the exposed entities SHOULD monitor changes of +the PartsList attribute in the Descriptor cluster on the root node endpoint. + +**9.2.5. Superset Device Types** + +A superset device type is a device type that is functionally similar to a subset device type and has an +overlap in its cluster requirements with a subset device type. If an endpoint lists both the superset +device type and the subset device type(s) in its DeviceTypeList list, a client that is capable of only +controlling the subset device type(s) would also be able to control the aspects of the superset device +type that are in common with the subset device type. + +A superset device type is subject to the following constraints: + +- All clusters in the subset device type with mandatory conformance SHALL be supported in the + superset device type with mandatory conformance. +- Any clusters in the subset device type with optional conformance MAY be supported in the + superset device type. +- Any clusters in the subset device type with optional conformance that are also supported in the + superset device type MAY have either optional or mandatory conformance in the superset + device type. +- Element requirements of overlapping clusters in the superset device type SHALL be the same as + in the subset device type. +- An endpoint implementing a superset device type MAY include the subset device type(s) in the + DeviceTypeList of the descriptor cluster of the endpoint. + +A composed device type SHALL indicate that superset device types are allowed in an implementa­ + +``` +Page 552 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +tion by adding a + sign after the ID and the name of the subset device type having a subset/superset +relationship in the device type requirements table of the composed device type. + +An endpoint SHALL NOT implement a subset of a device type listed in the device type requirements +table of a composed device type. + +For example, the following table indicates that an implementation may use a dimmable light or any +superset of a dimmable light (such as color temperature light and extended color light) in a com­ +posed device, but it may not use an on/off light as that is a subset of a dimmable light: + +``` +ID Name Constraint Conformance +0x0101+ Dimmable Light+ O +``` +**9.3. Interaction Model Relationships** + +This section define some of the system behaviors and their constraints as they apply to interactions +specified in the Interaction Model. + +**9.3.1. Subscription** + +**9.3.1.1. Persistency** + +A subscription is an ephemeral 'session' between a subscriber and a publisher. A subscription can +lose synchronization for a variety of reasons, including (but not limited to): + +- Inability to send reports due to network connectivity issues +- Factory-reset of the publisher +- Reboot of either the subscriber or publisher +- Decision by either publisher or subscriber to tear down the subscription to reclaim resources + +In all cases, the subscriber can eventually discover the loss of synchronization by not receiving a +sync report or data report in the agreed upon sync interval, or through some other failure to com­ +municate with the publisher. + +- When a subscriber discovers the loss of synchronization, it MAY then initiate a re-subscription + to resume the subscription. +- An implementation MAY choose to persist the details of a subscription across reboots, but it is + not necessary. + +In all cases, the publisher eventually discovers the loss of synchronization by not receiving a Status +Response to a Report Data message that expects a response, or by receiving an error Status +Response. + +**9.4. Binding Relationship** + +This relationship occurs because a simple client endpoint does not know which endpoints will be +the target for the client generated actions, on one or more remote nodes. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 553 +``` + +``` +For example: A light switch that controls one or more light bulbs, does not know the remote +node endpoints of the bulbs. +``` +``` +For example: A thermostat that subscribes to an occupancy sensor, does not know the remote +node endpoint of the sensor. +``` +In such cases, a binding is used to direct the local endpoint to the remote endpoint. The existence of +the Binding cluster on an endpoint, allows a director to create one or more binding entries (bind­ +ings) in the Binding cluster. A director is a remote client that is given access to create such bindings. + +Each binding indicates either a remote node’s endpoint or cluster on a remote node’s endpoint. +Multiple bindings are allowed, depending on the interaction. A binding is either a unicast binding, +where the binding target is a remote endpoint, or a groupcast binding, where the binding target is a +group of remote endpoints. + +Please see the Binding Cluster specification for more specification detail. + +**9.5. Descriptor Cluster** + +``` +NOTE The Descriptor cluster is meant to replace the support from the Zigbee Device +Object (ZDO) for describing a node, its endpoints and clusters. +``` +This cluster describes an endpoint instance on the node, independently from other endpoints, but +also allows composition of endpoints to conform to complex device type patterns. + +This cluster supports a list of one or more device type identifiers that represent conformance to +device type specifications. + +``` +For Example: An Extended Color Light device type may support device type IDs for both a +Dimmable Light and On/Off Light, because those are subsets of an Extended Color Light (the +superset). +``` +The cluster supports a PartsList attribute that is a list of zero or more endpoints to support a com­ +posed device type. + +``` +For Example: A Refrigerator/Freezer appliance device type may be defined as being com­ +posed of multiple Temperature Sensor endpoints, a Metering endpoint, and two Thermostat +endpoints. +``` +**9.5.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Page 554 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Revision Description +1 Initial revision +2 Semantic tag list; TagList feature +``` +**9.5.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Endpoint DESC +``` +**9.5.3. Cluster ID** + +``` +ID Name +0x001D Descriptor +``` +**9.5.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 TAGLIST TagList desc The TagList +attribute is +present +``` +**9.5.4.1. TagList Feature** + +See the Disambiguation section in the System Model spec for conformance requirements for this +feature and the corresponding attribute. + +**9.5.5. Data Types** + +**9.5.5.1. DeviceTypeStruct Type** + +The device type and revision define endpoint conformance to a release of a device type definition. +See the Data Model specification for more information. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Device­ +Type +``` +``` +devtype-id M +``` +``` +1 Revision uint16 min 1 M +``` +**DeviceType Field** + +This SHALL indicate the device type definition. The endpoint SHALL conform to the device type def­ +inition and cluster specifications required by the device type. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 555 +``` + +**Revision Field** + +This is the implemented revision of the device type definition. The endpoint SHALL conform to this +revision of the device type. + +**9.5.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Device­ +TypeList +``` +``` +list[Device­ +Type­ +Struct] +``` +``` +min 1 F desc R V M +``` +``` +0x0001 ServerList list[cluster- +id] +``` +``` +F empty R V M +``` +``` +0x0002 ClientList list[cluster- +id] +``` +``` +F empty R V M +``` +``` +0x0003 PartsList list[end­ +point-no] +``` +``` +empty R V M +``` +``` +0x0004 TagList list[Seman­ +tic­ +TagStruct] +``` +``` +1 to 6 F MS R V TAGLIST +``` +**9.5.6.1. DeviceTypeList Attribute** + +This is a list of device types and corresponding revisions declaring endpoint conformance (see +DeviceTypeStruct). At least one device type entry SHALL be present. + +An endpoint SHALL conform to all device types listed in the DeviceTypeList. A cluster instance that +is in common for more than one device type in the DeviceTypeList SHALL be supported as a shared +cluster instance on the endpoint. + +**9.5.6.2. ServerList Attribute** + +This attribute SHALL list each cluster ID for the server clusters present on the endpoint instance. + +**9.5.6.3. ClientList Attribute** + +This attribute SHALL list each cluster ID for the client clusters present on the endpoint instance. + +**9.5.6.4. PartsList Attribute** + +This attribute indicates composition of the device type instance. Device type instance composition +SHALL include the endpoints in this list. + +See Endpoint Composition for more information about which endpoints to include in this list. + +``` +Page 556 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.5.6.5. TagList Attribute** + +This attribute SHALL be used to disambiguate sibling endpoints in certain situations, as defined in +the Disambiguation section in the System Model specification. An example of such a situation might +be a device with two buttons, with this attribute being used to indicate which of the two endpoints +corresponds to the button on the left side. + +It MAY also be used to provide information about an endpoint (e.g. the relative location of a Tem­ +perature sensor in a Temperature Controlled Cabinet). + +- A client SHOULD use these tags to convey disambiguation information and other relevant infor­ + mation to the user (e.g. showing it in a user interface), as appropriate. +- A client SHOULD use these tags in its logic to make decisions, as appropriate. + +For example, a client MAY identify which endpoint maps to a certain function, orientation or label­ +ing. + +A client MAY use the Label field of each SemanticTagStruct, if present in each structure, to indicate +characteristics of an endpoint, or to augment what is provided in the TagID field of the same struc­ +ture. + +**9.6. Binding Cluster** + +### NOTE + +``` +This scope of this document is the Binding cluster as part of the Cluster Library. The +Binding cluster is meant to replace the support from the Zigbee Device Object (ZDO) +for supporting the binding table. +``` +A binding represents a persistent relationship between an endpoint and one or more other local or +remote endpoints. A binding does not require that the relationship exists. It is up to the node appli­ +cation to set up the relationship. + +A binding is used to inform a client endpoint of one or more targets for a potential interaction. For +example: a light switch that controls one or more light bulbs, needs to be told the nodes and end­ +points of the bulbs, or told a group in which the bulbs are members. For example: A client that +needs to subscribe to an occupancy sensor, needs to know the node and endpoint of the sensor. + +In such cases, a binding is used to direct a local endpoint to a target. The existence of the Binding +cluster on the client endpoint, allows the creation of one or more binding entries (bindings) in the +Binding cluster. + +Each binding indicates another endpoint or cluster on another endpoint. Multiple bindings are +allowed, depending on the interaction. + +A binding is either a unicast binding, where the target is a single endpoint on a single node, or a +groupcast binding, where the target is a group, which may indicate multiple endpoints on multiple +nodes. The binding may also target a single cluster on the target endpoint(s). + +When a client cluster requires a target for an interaction, the Binding cluster SHALL exist on the +same endpoint. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 557 +``` + +Once a binding entry is created on the Binding cluster, the client endpoint MAY initiate interactions +to the binding target. + +**9.6.1. Binding Mutation** + +If, during the creation of multiple bindings, there are no available resources to create an entry, or +to establish a binding relationship, the client SHALL respond with a status of RESOURCE_EX­ +HAUSTED, and the binding SHALL NOT be created. + +The number of bindings supported is left to the implementation. However, a device type definition +MAY prescribe the minimum number of bindings supported on an endpoint. In this case, the num­ +ber prescribed by the device type SHALL be supported for each fabric the node supports, unless the +device type specifies otherwise. The total number of bindings supported SHALL be the sum of the +requirements for each endpoint, unless the device types involved specify otherwise. + +- For example, if a node supports 6 fabrics and a device type specifies at least 3 bindings must be + supported, the node would need to support at least 18 bindings and ensure that at least 3 were + available to every fabric. + +A binding SHALL only be created with the Cluster field if the indicated client cluster exists on the +endpoint. + +When a binding is removed, the client endpoint SHALL end the binding relationship with the +removed binding target. + +**9.6.2. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**9.6.3. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Endpoint BIND +``` +**9.6.4. Cluster ID** + +``` +ID Name +0x001E Binding +``` +**9.6.5. Data Types** + +``` +Page 558 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.6.5.1. TargetStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 Node node-id all Endpoint +2 Group group-id min 1 !Endpoint +3 Endpoint endpoint- +no +``` +``` +all !Group +``` +``` +4 Cluster cluster-id all O +``` +**Node Field** + +This field is the remote target node ID. If the Endpoint field is present, this field SHALL be present. + +**Group Field** + +This field is the target group ID that represents remote endpoints. If the Endpoint field is present, +this field SHALL NOT be present. + +**Endpoint Field** + +This field is the remote endpoint that the local endpoint is bound to. If the Group field is present, +this field SHALL NOT be present. + +**Cluster Field** + +This field is the cluster ID (client & server) on the local and target endpoint(s). If this field is present, +the client cluster SHALL also exist on this endpoint (with this Binding cluster). If this field is +present, the target SHALL be this cluster on the target endpoint(s). + +**9.6.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Binding list[Target­ +Struct] +``` +``` +desc N [] RW VM F M +``` +**9.6.6.1. Binding Attribute** + +Each entry SHALL represent a binding. + +Here are some examples: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 559 +``` + +``` +Endpoint +Device Type +``` +``` +Node Group Cluster Endpoint Example +Description +Light Switch +Client +``` +``` +omit 1234 omit omit switch end­ +point sends +On/Off, Level & +Color Control +cluster com­ +mands to +group 1234 +Temp Sensor +Client +``` +``` +456789 omit 1026 3 temperature +sensor client +subscribes to +node 456789 +endpoint 3 +temperature +measurement +cluster +``` +**9.7. Label Cluster** + +This cluster provides a feature to tag an endpoint with zero or more labels. This is a base cluster +that requires a derived cluster to create an instance. + +**9.7.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**9.7.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Endpoint LABEL +``` +**9.7.3. Cluster ID** + +This is a base cluster with no cluster ID. Please see derived clusters for more information. + +``` +ID Name +n/a Label +``` +``` +Page 560 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.7.4. Data Types** + +**9.7.4.1. LabelStruct Type** + +This is a string tuple with strings that are user defined. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Label string max 16 empty M +1 Value string max 16 empty M +``` +**Label Field** + +The Label or Value semantic is not defined here. Label examples: "room", "zone", "group", "direc­ +tion". + +**Value Field** + +The Label or Value semantic is not defined here. The Value is a discriminator for a Label that may +have multiple instances. Label:Value examples: "room":"bedroom 2", "orientation":"North", +"floor":"2", "direction":"up" + +**9.7.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 LabelList list[Label­ +Struct] +``` +``` +derived derived empty derived M +``` +**9.7.5.1. LabelList Attribute** + +This is a list of string tuples. Each entry is a LabelStruct. + +**9.8. Fixed Label Cluster** + +This cluster is derived from the Label cluster and provides a feature for the device to tag an end­ +point with zero or more read-only labels. + +Examples: + +- A bridge can use this to indicate grouping of bridged devices. For example: All bridged devices + whose endpoints have an entry in their LabelList "room":"bedroom 2" are in the same + (bed)room. +- A manufacturer can use this to identify a characteristic of an endpoint. For example to identify + the endpoints of a luminaire, one pointing up, the other pointing down, one of the endpoints + would have a LabelList entry "orientation":"up" while the other would have "orienta­ + tion":"down". Using such indication, the user interface of a Node controlling this luminaire + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 561 +``` + +``` +knows which of the endpoints is which of the lights. +``` +Note that the TagList in the Descriptor cluster provides an alternative mechanism for such self- +description using standardized tags rather than manufacturer-selected strings, yielding a standard­ +ized mechanism for features defined in the various namespaces. The second example above can be +implemented using semantic tags Direction.Upward and Direction.Downward instead of (or in +addition to) the Fixed Label cluster. + +**9.8.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**9.8.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Label Utility Endpoint FLABEL +``` +**9.8.3. Cluster ID** + +``` +ID Name +0x0040 Fixed Label +``` +**9.8.4. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 LabelList list[Label­ +Struct] +``` +``` +N empty R V M +``` +**9.9. User Label Cluster** + +This cluster is derived from the Label cluster and provides a feature to tag an endpoint with zero or +more writable labels. + +**9.9.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +``` +Page 562 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.9.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Label Utility Endpoint ULABEL +``` +**9.9.3. Cluster ID** + +``` +ID Name +0x0041 User Label +``` +**9.9.4. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 LabelList list[Label­ +Struct] +``` +``` +min 4 per +node +``` +``` +N empty RW VM M +``` +**9.9.4.1. LabelList Attribute** + +An implementation SHALL support at least 4 list entries per node for all User Label cluster +instances on the node. + +**9.10. Access Control Cluster** + +The Access Control Cluster exposes a data model view of a Node’s Access Control List (ACL), which +codifies the rules used to manage and enforce Access Control for the Node’s endpoints and their +associated cluster instances. Access to this Access Control Cluster itself requires a special Adminis­ +ter privilege level, such that only Nodes granted such privilege (hereafter termed "Administrators") +can manage the Access Control Cluster. + +The Access Control Cluster SHALL be present on the root node endpoint of each Node, and SHALL +NOT be present on any other Endpoint of any Node. + +**9.10.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Added Managed Device feature, Extension fea­ +ture, fixed conformance +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 563 +``` + +**9.10.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node ACL +``` +**9.10.3. Cluster ID** + +``` +ID Name +0x001F AccessControl +``` +**9.10.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 EXTS Extension O Device provides +ACL Extension +attribute +1 MNGD ManagedDevice desc Device is managed +``` +**9.10.4.1. Extension Feature** + +This feature indicates the device supports ACL Extension attribute. + +**9.10.4.2. ManagedDevice Feature** + +This feature is for a device that is managed by a service associated with the device vendor and +which imposes default access restrictions upon each new fabric added to it. This could arise, for +example, if the device is managed by a service provider under contract to an end-user, in such a +way that the manager of the device does not unconditionally grant universal access to all of a +device’s functionality, even for fabric administrators. For example, many Home Routers are man­ +aged by an Internet Service Provider (a service), and these services often have a policy that requires +them to obtain user consent before certain administrative functions can be delegated to a third +party (e.g., a fabric Administrator). These restrictions are expressed using an Access Restriction List +(ARL). + +The purpose of this feature on the Access Control cluster is to indicate to a fabric Administrator that +access by it to specific attributes, commands and/or events for specific clusters is currently prohib­ +ited. Attempts to access these restricted data model elements SHALL result in an error of +ACCESS_RESTRICTED. + +A device that implements this feature SHALL have a mechanism to honor the ReviewFabricRestric­ +tions command, such as user interfaces or service interactions associated with a service provider or +the device manufacturer, which allows the owner (or subscriber) to manage access restrictions for +each fabric. The user interface design, which includes the way restrictions are organized and pre­ +sented to the user, is not specified, but SHOULD be usable by non-expert end-users from common +mobile devices, personal computers, or an on-device user interface. + +``` +Page 564 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Controllers and clients SHOULD incorporate generic handling of the ACCESS_RESTRICTED error +code, when it appears in allowed contexts, in order to gracefully handle situations where this fea­ +ture is encountered. Device vendors that adopt this feature SHOULD be judicious in its use given +the risk of unexpected behavior in controllers and clients. + +For certification testing, a device that implements this feature SHALL provide a way for all restric­ +tions to be removed. + +The ARL attribute provides the set of restrictions currently applied to this fabric. + +The ReviewFabricRestrictions command provides a way for the fabric Administrator to request that +the server triggers a review of the current fabric restrictions, by involving external entities such as +end-users, or other services associated with the manager of the device hosting the server. This +review process MAY involve communication between external services and the user, and MAY take +an unpredictable amount of time to complete since an end-user may need to visit some resources, +such as a mobile application or web site. A FabricRestrictionReviewUpdate event will be generated +by the device within a predictable time period of the ReviewFabricRestrictionsResponse (see +ReviewFabricRestrictions for specification of this time period), and this event can be correlated +with the ReviewFabricRestrictionsResponse using a token provided in both. The device MAY pro­ +vide instructions or a Redirect URL in the FabricRestrictionReviewUpdate event in order to help the +user access the features required for managing per-fabric restrictions. + +See Section 6.6.2, “Model” for a description of how access control is impacted by the ARL attribute. + +**Managed Device Feature Usage Restrictions** + +Use of this feature SHALL be limited to the mandatory clusters of endpoints having a device type +that explicitly permits its use in the Device Library Specification. As a reminder, the device types +associated with an endpoint are listed in the Descriptor cluster of the endpoint. + +In addition, use of this feature SHALL NOT restrict the following clusters on any endpoint: + +1. the Descriptor Cluster (0x001D) +2. the Binding Cluster (0x001E) +3. the Network Commissioning Cluster (0x0031) +4. the Identify Cluster (0x0003) +5. the Groups Cluster (0x0004) + +In addition, use of this feature SHALL NOT restrict the global attributes of any cluster. + +Because ARLs cannot be used to restrict root node access or access to any clusters required for com­ +missioning, administrators MAY determine the current restrictions of the ARL at any point, includ­ +ing during commissioning after joining the fabric. + +**9.10.5. Data Types** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 565 +``` + +**9.10.5.1. ChangeTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Changed Entry or extension was +changed +``` +### M + +``` +1 Added Entry or extension was +added +``` +### M + +``` +2 Removed Entry or extension was +removed +``` +### M + +**9.10.5.2. AccessControlEntryPrivilegeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +1 View Can read and observe +all (except Access Con­ +trol Cluster and as seen +by a non-Proxy) +``` +### M + +``` +2 Proxy View Can read and observe +all (as seen by a Proxy) +``` +### P, M + +``` +3 Operate View privileges, and +can perform the pri­ +mary function of this +Node (except Access +Control Cluster) +``` +### M + +``` +4 Manage Operate privileges, and +can modify persistent +configuration of this +Node (except Access +Control Cluster) +``` +### M + +``` +5 Administer Manage privileges, and +can observe and mod­ +ify the Access Control +Cluster +``` +### M + +**Proxy View Value** + +This value implicitly grants View privileges + +**Operate Value** + +This value implicitly grants View privileges + +``` +Page 566 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Manage Value** + +This value implicitly grants Operate & View privileges + +**Administer Value** + +This value implicitly grants Manage, Operate, Proxy View & View privileges + +**9.10.5.3. AccessRestrictionTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 AttributeAccessFor­ +bidden +``` +``` +Clients on this fabric +are currently forbidden +from reading and writ­ +ing an attribute +``` +### M + +``` +1 AttributeWriteForbid­ +den +``` +``` +Clients on this fabric +are currently forbidden +from writing an +attribute +``` +### M + +``` +2 CommandForbidden Clients on this fabric +are currently forbidden +from invoking a com­ +mand +``` +### M + +``` +3 EventForbidden Clients on this fabric +are currently forbidden +from reading an event +``` +### M + +**9.10.5.4. AccessControlEntryAuthModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +1 PASE Passcode authenticated +session +``` +### M + +``` +2 CASE Certificate authenti­ +cated session +``` +### M + +``` +3 Group Group authenticated +session +``` +### M + +**9.10.5.5. AccessControlTargetStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Cluster cluster-id all X M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 567 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +1 Endpoint endpoint- +no +``` +``` +all X M +``` +``` +2 Device­ +Type +``` +``` +devtype-id all X M +``` +**9.10.5.6. AccessControlEntryStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 Privilege AccessCon­ +trolEn­ +tryPrivi­ +legeEnum +``` +``` +all S M +``` +``` +2 AuthMode AccessCon­ +trolEn­ +tryAuth­ +Mod­ +eEnum +``` +``` +all S M +``` +``` +3 Subjects list[Subjec­ +tID] +``` +``` +max Sub­ +jectsPerAc­ +cessCon­ +trolEntry +``` +### X S M + +``` +4 Targets list[Access­ +Con­ +trolTarget­ +Struct] +``` +``` +max Tar­ +getsPerAc­ +cessCon­ +trolEntry +``` +### X S M + +**Privilege Field** + +The privilege field SHALL specify the level of privilege granted by this Access Control Entry. + +``` +NOTE The Proxy View privilege is provisional. +``` +Each privilege builds upon its predecessor, expanding the set of actions that can be performed +upon a Node. Administer is the highest privilege, and is special as it pertains to the administration +of privileges itself, via the Access Control Cluster. + +When a Node is granted a particular privilege, it is also implicitly granted all logically lower privi­ +lege levels as well. The following diagram illustrates how the higher privilege levels subsume the +lower privilege levels: + +``` +Page 568 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 46. Access Control Privilege Levels_ + +Individual clusters SHALL define whether attributes are readable, writable, or both readable and +writable. Clusters also SHALL define which privilege is minimally required to be able to perform a +particular read or write action on those attributes, or invoke particular commands. Device type +specifications MAY further restrict the privilege required. + +The Access Control Cluster SHALL require the Administer privilege to observe and modify the +Access Control Cluster itself. The Administer privilege SHALL NOT be used on Access Control +Entries which use the Group auth mode. + +``` +E.g. A Fan Control Cluster may require Operate privilege to write to a level attribute +(low/medium/high), and to configure each level’s RPM setting via a command. The Fan Con­ +trol Cluster may also expose a current RPM attribute, which requires only View privilege to +read. Clients granted Operate privilege will be able to both change the level, and configure +each level’s RPM. Clients granted View privilege will be able to read the current RPM, but will +not be granted sufficient privilege to change the level or configure each level’s RPM. +``` +``` +E.g. A Fan Control Cluster may be included in a more industrial device type. To ensure proper +operation, this device type may restrict configuration of fan level RPM settings to require +Manage privilege. Clients granted Manage privilege will have sufficient privilege to configure +each level’s RPM; clients granted Operate privilege will not be able to perform such configu­ +ration, but will still be able to change the level. This additional restriction would apply only to +the Fan Control Cluster as included in this particular device type; a client granted Operate +privilege may still be able to perform configuration in Fan Control Clusters included in other +device types on the same Node. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 569 +``` + +**AuthMode Field** + +The AuthMode field SHALL specify the authentication mode required by this Access Control Entry. + +**Subjects Field** + +The subjects field SHALL specify a list of Subject IDs, to which this Access Control Entry grants +access. + +Device types MAY impose additional constraints on the minimum number of subjects per Access +Control Entry. + +An attempt to create an entry with more subjects than the node can support SHALL result in a +RESOURCE_EXHAUSTED error and the entry SHALL NOT be created. + +Subject ID SHALL be of type uint64 with semantics depending on the entry’s AuthMode as follows: + +**Subject Semantics** + +``` +AuthMode Subject +PASE Lower 16-bits → Passcode ID +Upper 48-bits → all bits clear +CASE 64-bits → Node ID or CASE Authenticated Tag +Group Lower 16-bits → Group ID +Upper 48-bits → all bits clear +``` +An empty subjects list indicates a wildcard; that is, this entry SHALL grant access to any Node that +successfully authenticates via AuthMode. The subjects list SHALL NOT be empty if the entry’s Auth­ +Mode is PASE. + +The PASE AuthMode is reserved for future use (see Section 6.6.2.9, “Bootstrapping of the Access Con­ +trol Cluster”). An attempt to write an entry with AuthMode set to PASE SHALL fail with a status +code of CONSTRAINT_ERROR. + +For PASE authentication, the Passcode ID identifies the required passcode verifier, and SHALL be 0 +for the default commissioning passcode. + +For CASE authentication, the Subject ID is a distinguished name within the Operational Certificate +shared during CASE session establishment, the type of which is determined by its range to be one +of: + +- a Node ID, which identifies the required source node directly (by ID) +- a CASE Authenticated Tag, which identifies the required source node indirectly (by tag) + +``` +E.g. an ACL entry with CASE AuthMode that grants privileges to Subject IDs [ +0x0000_0000_1111_1111, 0x0000_0000_2222_2222, 0x0000_0000_3333_3333 ] (which are Node +IDs) will grant access to Nodes with Node ID 0x0000_0000_1111_1111, +0x0000_0000_2222_2222, or 0x0000_0000_3333_3333, but will not grant access to Nodes with +``` +``` +Page 570 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Node ID 0x0000_0000_4444_4444 or 0x0000_0000_5555_5555. +``` +``` +E.g. an ACL entry with CASE AuthMode that grants privileges to Subject IDs [ +0x0000_0000_6666_6666, 0xFFFF_FFFD_ABCD_0002 ] (which are a Node ID and a CASE +Authenticated Tag) will grant access to the Node with Node ID 0x0000_0000_6666_6666 and +any Nodes with CAT identifier value 0xABCD if the CAT’s version is 0x0002 or higher. It will +not grant access to Nodes with other CAT values such as 0x9999_9999. Any node with CAT +identifier value of 0xABCD but version less than 0x0002 (for example: 0xFFF­ +F_FFFD_ABCD_0001) will not be granted access. +``` +For Group authentication, the Group ID identifies the required group, as defined in the Group Key +Management Cluster. + +``` +E.g. an entry with Group AuthMode that grants privileges to Subject IDs [ +0x0000_0000_1111_1111, 0x0000_0000_2222_2222 ] (which are Group IDs) will grant access to +Nodes in Group 0x1111_1111 or 0x2222_2222, but will not grant access to Nodes in Group +0x3333_3333, even if they share Operational Group Keys. +``` +**Targets Field** + +The targets field SHALL specify a list of AccessControlTargetStruct, which define the clusters on this +Node to which this Access Control Entry grants access. + +Device types MAY impose additional constraints on the minimum number of targets per Access +Control Entry. + +An attempt to create an entry with more targets than the node can support SHALL result in a +RESOURCE_EXHAUSTED error and the entry SHALL NOT be created. + +A single target SHALL contain at least one field (Cluster, Endpoint, or DeviceType), and SHALL NOT +contain both an Endpoint field and a DeviceType field. + +A target grants access based on the presence of fields as follows: + +**Target Semantics** + +``` +Cluster Endpoint DeviceType Target +Invalid +D All clusters on any end­ +point with Descriptor +containing device type +D +E All clusters on only +endpoint E +E D Invalid +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 571 +``` + +``` +Cluster Endpoint DeviceType Target +C Only cluster C on all +endpoints +C D Only cluster C on any +endpoint with Descrip­ +tor containing device +type D +C E Only cluster C on only +endpoint E +C E D Invalid +``` +An empty targets list indicates a wildcard: that is, this entry SHALL grant access to all cluster +instances on all endpoints on this Node. + +``` +E.g. an entry that grants privileges to the Color Light Bulb Device Type will grant privileges to +any cluster on any endpoint that contains the Color Light Bulb device type (whether that clus­ +ter is in the Color Light Bulb device type or not), and will not grant privileges to any other +cluster on any other endpoint. +``` +``` +E.g. an entry that grants privileges to Endpoint 1 will grant privileges to any cluster on End­ +point 1, and will not grant privileges to any other cluster on any other endpoint. +``` +``` +E.g. an entry that grants privileges to the On/Off Cluster on any endpoint will not grant privi­ +leges to any other cluster on any endpoint. +``` +``` +E.g. an entry that grants privileges to the On/Off Cluster with Color Light Bulb Device Type +will grant privileges to just the On/Off Cluster on any endpoint that contains the Color Light +Bulb device type, and will not grant privileges to any other cluster on any other endpoint +(including other clusters in the Color Light Bulb device type, or the On/Off cluster on end­ +points that do not contain the Color Light Bulb device type). +``` +``` +E.g. an entry that grants privileges to the On/Off Cluster on Endpoint 1 will not grant privi­ +leges to any other cluster on Endpoint 1, or to any other cluster (including the On/Off cluster) +on any other endpoint. +``` +**9.10.5.7. AccessControlExtensionStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 Data octstr max 128 S M +``` +**Data Field** + +This field MAY be used by manufacturers to store arbitrary TLV-encoded data related to a fabric’s + +``` +Page 572 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Access Control Entries. + +The contents SHALL consist of a top-level anonymous list; each list element SHALL include a pro­ +file-specific tag encoded in fully-qualified form. + +Administrators MAY iterate over this list of elements, and interpret selected elements at their dis­ +cretion. The content of each element is not specified, but MAY be coordinated among manufactur­ +ers at their discretion. + +``` +E.g. a manufacturer could use this field to store structured data, including various metadata +and cryptographic signatures. The manufacturer could then verify a fabric’s Access Control +List by generating a canonical bytestream from the Access Control Entries for the fabric, then +verifying the signature against it. Such a canonical bytestream could be generated by encod­ +ing specific entry fields and sub-fields (such as lists) in specific order and specific format (e.g. +TLV). +``` +**9.10.5.8. AccessRestrictionStruct Type** + +This structure describes an access restriction that would be applied to a specific data model ele­ +ment on a given endpoint/cluster pair (see AccessRestrictionEntryStruct). + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Type AccessRe­ +striction­ +TypeEnum +``` +``` +all M +``` +``` +1 ID uint32 all X M +``` +**Type Field** + +This field SHALL indicate the type of restriction, for example, AttributeAccessForbidden. + +**ID Field** + +This field SHALL indicate the element Manufacturer Extensible Identifier (MEI) associated with the +element type subject to the access restriction, based upon the AccessRestrictionTypeEnum. When +the Type is AttributeAccessForbidden or AttributeWriteForbidden, this value SHALL be considered +of type attrib-id (i.e. an attribute identifier). When the Type is CommandForbidden, this value +SHALL be considered of type command-id (i.e. an attribute identifier). When the Type is EventFor­ +bidden, this value SHALL be considered of type event-id (i.e. an event identifier). + +A null value SHALL indicate the wildcard value for the given value of Type (i.e. all elements associ­ +ated with the Type under the associated endpoint and cluster for the containing AccessRestrictio­ +nEntryStruct). + +**9.10.5.9. AccessRestrictionEntryStruct Type** + +This structure describes a current access restriction on the fabric. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 573 +``` + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Endpoint endpoint- +no +``` +``` +all S M +``` +``` +1 Cluster cluster-id all S M +2 Restric­ +tions +``` +``` +list[Access­ +Restric­ +tionStruct] +``` +``` +min 1 desc S M +``` +**Endpoint Field** + +This field SHALL indicate the endpoint having associated access restrictions scoped to the associ­ +ated fabric of the list containing the entry. + +**Cluster Field** + +This field SHALL indicate the cluster having associated access restrictions under the entry’s End­ +point, scoped to the associated fabric of the list containing the entry. + +**Restrictions Field** + +This field SHALL indicate the set of restrictions applying to the Cluster under the given Endpoint, +scoped to the associated fabric of the list containing the entry. + +This list SHALL NOT be empty. + +**9.10.5.10. CommissioningAccessRestrictionEntryStruct Type** + +This structure describes a current access restriction when there is no accessing fabric. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Endpoint endpoint- +no +``` +``` +all M +``` +``` +1 Cluster cluster-id all M +2 Restric­ +tions +``` +``` +list[Access­ +Restric­ +tionStruct] +``` +``` +min 1 desc M +``` +**Endpoint Field** + +This field SHALL indicate the endpoint having associated access restrictions scoped to the associ­ +ated fabric of the list containing the entry. + +``` +Page 574 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Cluster Field** + +This field SHALL indicate the cluster having associated access restrictions under the entry’s End­ +point, scoped to the associated fabric of the list containing the entry. + +**Restrictions Field** + +This field SHALL indicate the set of restrictions applying to the Cluster under the given Endpoint, +scoped to the associated fabric of the list containing the entry. + +This list SHALL NOT be empty. + +**9.10.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 ACL list[Access­ +ControlEn­ +tryStruct] +``` +``` +desc desc RW A F M +``` +``` +0x0001 Extension list[Access­ +ControlEx­ +tension­ +Struct] +``` +``` +desc desc RW A F EXTS +``` +``` +0x0002 Sub­ +jectsPer­ +Access­ +Contro­ +lEntry +``` +``` +uint16 min 4 F 4 R V M +``` +``` +0x0003 Tar­ +getsPerAc­ +cessCon­ +trolEntry +``` +``` +uint16 min 3 F 3 R V M +``` +``` +0x0004 Access­ +Contro­ +lEntries­ +PerFabric +``` +``` +uint16 min 4 F 4 R V M +``` +``` +0x0005 Commis­ +sioningAR +L +``` +``` +list[Com­ +mis­ +sioningAc­ +cessRe­ +strictio­ +nEntryS­ +truct] +``` +``` +desc F [] R V MNGD +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 575 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0006 ARL list[Access­ +Restrictio­ +nEntryS­ +truct] +``` +``` +desc [] R V F MNGD +``` +**9.10.6.1. Default Value** + +The default values of the Access Control Cluster ACL and Extension attributes are empty; that is, +devoid of contents, with each list attribute containing zero elements. + +The Access Control List is able to have an initial entry added because the Access Control Privilege +Granting algorithm behaves as if, over a PASE commissioning channel during the commissioning +phase, the following implicit Access Control Entry were present on the Commissionee (but not on +the Commissioner): + +``` +Access Control Cluster: { +ACL: [ +0: { // implicit entry only; does not explicitly exist! +FabricIndex: 0, // not fabric-specific +Privilege: Administer, +AuthMode: PASE, +Subjects: [], +Targets: [] // entire node +} +], +Extension: [] +} +``` +When the ManagedDevice feature is present, the value of the Access Control Cluster Commis­ +sioningARL attribute contains the set of access restrictions applied during commissioning, before a +fabric has been assigned. Upon allocation of a new FabricIndex during commissioning (see Node +Operational Credentials Cluster AddNOC command), one or more ARL entries with the new +FabricIndex SHALL be added to the ARL attribute. + +In the following example of the CommissioningARL and ARL attributes, the restrictions applied +during commissioning consist of a single entry with 3 limitations on Cluster 0x0453 of Endpoint 1: +writing to attribute 0x0000, all commands, all events. In contrast, the example also includes a +restriction on the fabric with index 1 which consists of 1 limitation on Cluster 0x0453 of Endpoint 1: +writing to attribute 0x0000. + +``` +Access Control Cluster: { +CommissioningARL: [ +0: { +``` +``` +Page 576 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Endpoint: 1, // application endpoint 1 +Cluster: 0x0453, // application cluster 0x0453 +Restrictions: [ +0: { +Type: AttributeWriteForbidden, // write limitation for attribute +Id: 0x0000 // attribute 0x0000 +}, +1: { +Type: CommandForbidden, // command limitation +Id: NULL // all commands +}, +2: { +Type: EventForbidden, // event limitation +Id: NULL // all events +} +] +} +] +ARL: [ +0: { +FabricIndex: 1, // ARL is fabric-scoped +Endpoint: 1, // application endpoint 1 +Cluster: 0x0453, // application cluster 0x0453 +Restrictions: [ +0: { +Type: AttributeWriteForbidden, // write limitation for attribute +Id: 0x0000 // attribute 0x0000 +} +] +} +} +``` +**9.10.6.2. Administration Guidelines** + +The Access Control Cluster is passive in nature and is only responsible for maintaining entries in +the Access Control List. It is the responsibility of Administrators to create and maintain Access Con­ +trol policy by managing the list and its entries. The Access Control Cluster SHALL NOT change or +remove Access Control Entries of its own volition. A device that needs to impose access restrictions +upon a fabric MAY do so by adding Access Restriction Entries to the CommissioningARL and ARL +attributes. + +Administrators SHOULD strive to minimize resource usage by combining entries where appropri­ +ate. For example, if an Administrator is responsible for an entry that grants privilege to subject +Node A, and wishes to grant the same privilege to Node B under the same conditions, then that + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 577 +``` + +Administrator SHOULD update the existing entry to apply to subject Node B as well as Node A, +instead of creating a new entry. If a set of Nodes is commonly used in entries, then an Administra­ +tor MAY consider using CASE Authenticated Tags (CATs) for those entries, especially if membership +in the set of Nodes changes over time. + +Administrators SHOULD carefully consider the effect of Access Control Entries they manage, partic­ +ularly when targeting entire Endpoints (either directly, or indirectly by Device Type), to ensure that +granted privileges are appropriate for the set of Clusters that may entail. Administrators SHOULD +be mindful that targeting by Device Type grants privileges to all Clusters on all Endpoints with +Descriptor containing that Device Type (thereby including Clusters not part of that specified Device +Type), now and in the future. Administrators SHOULD consider whether targeting specific End­ +points, or Clusters, or both, might be a more appropriate policy for the given Subjects; studying the +Descriptor Cluster for affected Endpoints may help in this determination. + +Administrators SHOULD be careful to avoid inadvertently removing their own administrative +access. For example, an Administrator SHOULD change its own administrative access entry by +updating the existing entry or by creating a new entry before removing the old entry, and SHOULD +NOT remove the old entry before creating any new entry. + +**9.10.6.3. ACL Attribute** + +An attempt to add an Access Control Entry when no more entries are available SHALL result in a +RESOURCE_EXHAUSTED error being reported and the ACL attribute SHALL NOT have the entry +added to it. See access control limits. + +See the AccessControlEntriesPerFabric attribute for the actual value of the number of entries per +fabric supported by the server. + +Each Access Control Entry codifies a single grant of privilege on this Node, and is used by the Access +Control Privilege Granting algorithm to determine if a subject has privilege to interact with targets +on the Node. + +**9.10.6.4. Extension Attribute** + +If present, the Access Control Extensions MAY be used by Administrators to store arbitrary data +related to fabric’s Access Control Entries. + +The Access Control Extension list SHALL support a single extension entry per supported fabric. + +**9.10.6.5. SubjectsPerAccessControlEntry Attribute** + +This attribute SHALL provide the minimum number of Subjects per entry that are supported by this +server. + +Since reducing this value over time may invalidate ACL entries already written, this value SHALL +NOT decrease across time as software updates occur that could impact this value. If this is a con­ +cern for a given implementation, it is recommended to only use the minimum value required and +avoid reporting a higher value than the required minimum. + +``` +Page 578 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.10.6.6. TargetsPerAccessControlEntry Attribute** + +This attribute SHALL provide the minimum number of Targets per entry that are supported by this +server. + +Since reducing this value over time may invalidate ACL entries already written, this value SHALL +NOT decrease across time as software updates occur that could impact this value. If this is a con­ +cern for a given implementation, it is recommended to only use the minimum value required and +avoid reporting a higher value than the required minimum. + +**9.10.6.7. AccessControlEntriesPerFabric Attribute** + +This attribute SHALL provide the minimum number of ACL Entries per fabric that are supported by +this server. + +Since reducing this value over time may invalidate ACL entries already written, this value SHALL +NOT decrease across time as software updates occur that could impact this value. If this is a con­ +cern for a given implementation, it is recommended to only use the minimum value required and +avoid reporting a higher value than the required minimum. + +**9.10.6.8. CommissioningARL Attribute** + +This attribute SHALL provide the set of CommissioningAccessRestrictionEntryStruct applied during +commissioning on a managed device. + +When present, the CommissioningARL attribute SHALL indicate the access restrictions applying +during commissioning. + +Attempts to access data model elements described by an entry in the CommissioningARL attribute +during commissioning SHALL result in an error of ACCESS_RESTRICTED. See Access Control Model +for more information about the features related to controlling access to a Node’s Endpoint Clusters +("Targets" hereafter) from other Nodes. + +See Section 9.10.4.2.1, “Managed Device Feature Usage Restrictions” for limitations on the use of +access restrictions. + +**9.10.6.9. ARL Attribute** + +This attribute SHALL provide the set of AccessRestrictionEntryStruct applied to the associated fab­ +ric on a managed device. + +When present, the ARL attribute SHALL indicate the access restrictions applying to the accessing +fabric. In contrast, the CommissioningARL attribute indicates the accessing restrictions that apply +when there is no accessing fabric, such as during commissioning. + +The access restrictions are externally added/removed based on the particular relationship the +device hosting this server has with external entities such as its owner, external service provider, or +end-user. + +Attempts to access data model elements described by an entry in the ARL attribute for the accessing +fabric SHALL result in an error of ACCESS_RESTRICTED. See Access Control Model for more infor­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 579 +``` + +mation about the features related to controlling access to a Node’s Endpoint Clusters ("Targets" +hereafter) from other Nodes. + +See Section 9.10.4.2.1, “Managed Device Feature Usage Restrictions” for limitations on the use of +access restrictions. + +**9.10.7. Error handling** + +Administrators SHALL use regular actions to administer the Access Control Cluster (by reading and +writing entries in the list). Administrators SHOULD take care to use DataVersion conditional writes +when administering the list or its contents. + +The Access Control Cluster SHALL fail to write, and return an appropriate error, if an attempt is +made to create or update an Access Control Entry or Access Control Extension such that it would +have invalid contents. + +For example, the following Access Control Entry conditions will result in an error of CONSTRAIN­ +T_ERROR: + +- Privilege enum value invalid +- AuthMode enum value invalid +- AuthMode is PASE (reserved for future use) +- Subjects element invalid + ◦ e.g. illegal CAT with CASE AuthMode +- Targets element invalid + ◦ e.g. no field present + ◦ e.g. both Endpoint and DeviceType fields present +- Field combinations invalid + ◦ e.g. Administer Privilege with Group AuthMode + +For example, the following Access Control Extension conditions will result in an error of CON­ +STRAINT_ERROR: + +- There is an attempt to add more than 1 entry associated with the given accessing fabric index in + the extension list +- Data value exceeds max length +- Data value not valid TLV-encoded data + +The Access Control Cluster MAY fail to write, and return a RESOURCE_EXHAUSTED error, if an +attempt is made to create or update an entry or extension such that storage is exhausted. + +**9.10.8. Commands** + +``` +Page 580 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Direction Response Access Conformance +0x00 ReviewFabri­ +cRestrictions +``` +``` +client ⇒ server ReviewFabri­ +cRestriction­ +sResponse +``` +### A F MNGD + +``` +0x01 ReviewFabri­ +cRestriction­ +sResponse +``` +``` +client ⇐ server N MNGD +``` +**9.10.8.1. ReviewFabricRestrictions Command** + +This command signals to the service associated with the device vendor that the fabric administrator +would like a review of the current restrictions on the accessing fabric. This command includes an +optional list of ARL entries that the fabric administrator would like removed. + +In response, a ReviewFabricRestrictionsResponse is sent which contains a token that can be used to +correlate a review request with a FabricRestrictionReviewUpdate event. + +Within 1 hour of the ReviewFabricRestrictionsResponse, the FabricRestrictionReviewUpdate event +SHALL be generated, in order to indicate completion of the review and any additional steps +required by the user for the review. + +A review MAY include obtaining consent from the user, which can take time. For example, the user +may need to respond to an email or a push notification. + +The ARL attribute may change at any time due to actions taken by the user, or the service associ­ +ated with the device vendor. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ARL list[Commis­ +sioningAc­ +cessRestric­ +tionEntryS­ +truct] +``` +``` +desc desc M +``` +**ARL Field** + +When the ARL field is provided, it indicates the specific restrictions that are requested for review. +An empty list represents a generic request for review of all restrictions. + +**9.10.8.2. ReviewFabricRestrictionsResponse Command** + +Returns the review token for the request, which can be used to correlate with a FabricRestriction­ +ReviewUpdate event. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 581 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Token uint64 all M +``` +**Token Field** + +This field SHALL specify a Token that can be used to correlate a ReviewFabricRestrictionsResponse +with a FabricRestrictionReviewUpdate event. + +**9.10.9. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 AccessContro­ +lEn­ +tryChanged +``` +### INFO A S M + +``` +0x01 AccessCon­ +trolExtension­ +Changed +``` +### INFO A S EXTS + +``` +0x02 FabricRestric­ +tionReviewUp­ +date +``` +### INFO A S MNGD + +**9.10.9.1. AccessControlEntryChanged Event** + +The cluster SHALL generate AccessControlEntryChanged events whenever its ACL attribute data is +changed by an Administrator. + +- Each added entry SHALL generate an event with ChangeType Added. +- Each changed entry SHALL generate an event with ChangeType Changed. +- Each removed entry SHALL generate an event with ChangeType Removed. + +``` +Access Quality: Fabric-Sensitive +ID Name Type Constraint Quality Default Confor­ +mance +1 AdminN­ +odeID +``` +``` +node-id desc X M +``` +``` +2 AdminPass­ +codeID +``` +``` +uint16 desc X M +``` +``` +3 ChangeType ChangeType­ +Enum +``` +``` +all M +``` +``` +4 LatestValue AccessCon­ +trolEntryS­ +truct +``` +``` +all X M +``` +``` +Page 582 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**AdminNodeID Field** + +The Node ID of the Administrator that made the change, if the change occurred via a CASE session. + +Exactly one of AdminNodeID and AdminPasscodeID SHALL be set, depending on whether the +change occurred via a CASE or PASE session; the other SHALL be null. + +**AdminPasscodeID Field** + +The Passcode ID of the Administrator that made the change, if the change occurred via a PASE ses­ +sion. Non-zero values are reserved for future use (see PasscodeId generation in PBKDFParamRe­ +quest). + +Exactly one of AdminNodeID and AdminPasscodeID SHALL be set, depending on whether the +change occurred via a CASE or PASE session; the other SHALL be null. + +**ChangeType Field** + +The type of change as appropriate. + +**LatestValue Field** + +The latest value of the changed entry. + +This field SHOULD be set if resources are adequate for it; otherwise it SHALL be set to NULL if +resources are scarce. + +**9.10.9.2. AccessControlExtensionChanged Event** + +The cluster SHALL generate AccessControlExtensionChanged events whenever its extension +attribute data is changed by an Administrator. + +- Each added extension SHALL generate an event with ChangeType Added. +- Each changed extension SHALL generate an event with ChangeType Changed. +- Each removed extension SHALL generate an event with ChangeType Removed. + +``` +Access Quality: Fabric-Sensitive +ID Name Type Constraint Quality Default Confor­ +mance +1 AdminN­ +odeID +``` +``` +node-id desc X M +``` +``` +2 AdminPass­ +codeID +``` +``` +uint16 desc X M +``` +``` +3 ChangeType ChangeType­ +Enum +``` +``` +all M +``` +``` +4 LatestValue AccessCon­ +trolExten­ +sionStruct +``` +``` +all X M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 583 +``` + +**AdminNodeID Field** + +The Node ID of the Administrator that made the change, if the change occurred via a CASE session. + +Exactly one of AdminNodeID and AdminPasscodeID SHALL be set, depending on whether the +change occurred via a CASE or PASE session; the other SHALL be null. + +**AdminPasscodeID Field** + +The Passcode ID of the Administrator that made the change, if the change occurred via a PASE ses­ +sion. Non-zero values are reserved for future use (see PasscodeId generation in PBKDFParamRe­ +quest). + +Exactly one of AdminNodeID and AdminPasscodeID SHALL be set, depending on whether the +change occurred via a CASE or PASE session; the other SHALL be null. + +**ChangeType Field** + +The type of change as appropriate. + +**LatestValue Field** + +The latest value of the changed extension. + +This field SHOULD be set if resources are adequate for it; otherwise it SHALL be set to NULL if +resources are scarce. + +**9.10.9.3. FabricRestrictionReviewUpdate Event** + +The cluster SHALL generate a FabricRestrictionReviewUpdate event to indicate completion of a fab­ +ric restriction review. Due to the requirement to generate this event within a bound time frame of +successful receipt of the ReviewFabricRestrictions command, this event MAY include additional +steps that the client MAY present to the user in order to help the user locate the user interface for +the Managed Device feature. + +``` +Access Quality: Fabric-Sensitive +ID Name Type Constraint Quality Default Confor­ +mance +0 Token uint64 all M +1 Instruction string max 512 O +2 ARLRe­ +quest­ +FlowUrl +``` +``` +string max 256 O +``` +**Token Field** + +This field SHALL indicate the Token that can be used to correlate a ReviewFabricRestrictionsRe­ +sponse with a FabricRestrictionReviewUpdate event. + +``` +Page 584 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Instruction Field** + +This field SHALL provide human readable text that MAY be displayed to the user to help them +locate the user interface for managing access restrictions for each fabric. + +A device SHOULD implement the Localization Configuration Cluster when it has no other means to +determine the locale to use for this text. + +Examples include "Please try again and immediately access device display for further instructions." +or "Please check email associated with your Acme account." + +**ARLRequestFlowUrl Field** + +This field SHALL indicate the URL for the service associated with the device maker which the user +can visit to manage fabric limitations. The syntax of this field SHALL follow the syntax as specified +in RFC 1738 and SHALL use the https scheme for internet-hosted URLs. + +- The URL MAY embed the token, fabric index, fabric vendor, or other information transparently + in order to pass context about the originating ReviewFabricRestrictions command to the service + associated with the URL. The service associated with the device vendor MAY perform vendor ID + verification on the fabric from which the ReviewFabricRestrictions command originated. +- If the device grants the request, the ARL attribute in the Access Control Cluster SHALL be + updated to reflect the new access rights and a successful response SHALL be returned to the + device making the request using the MTaer field of the callbackUrl. If the request is denied, the + ARL attribute SHALL remain unchanged and a failure response SHALL be returned to the + device making the request using the MTaer field of the callbackUrl. +- The device using this mechanism SHALL provide a service at the URL that can accept requests + for additional access and return responses indicating whether the requests were granted or + denied. +- This URL will typically lead to a server which (e.g. by looking at the User-Agent) redirects the + user to allow viewing, downloading, installing or using a manufacturer-provided means for + guiding the user through the process to review and approve or deny the request. The device + manufacturer MAY choose to use a constructed URL which is valid in a HTTP GET request (i.e. + dedicated for the product) such as, for example, https://domain.example/arl-app?vid=FFF1& + pid=1234. If a client follows or launches the ARLRequestFlowUrl, it SHALL expand it as described + in Section 9.10.9.3.4, “ARLRequestFlowUrl format”. +- A manufacturer contemplating using this flow should realize that + ◦ This flow typically requires internet access to access the URL, and access extension may fail + when internet connectivity is not available. + ◦ If the flow prefers to redirect the user to an app which is available on popular platforms, it + SHOULD also provide a fallback option such as a web browser interface to ensure users can + complete access extension. + +**ARLRequestFlowUrl format** + +The ARLRequestFlowUrl SHALL contain a query component (see RFC 3986 section 3.4) composed of +one or more key-value pairs: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 585 +``` + +- The query SHALL use the & delimiter between key/value pairs. +- The key-value pairs SHALL in the format name= where name is the key name, and + is the contents of the value encoded with proper URL-encoded escaping. +- If key MTcu is present, it SHALL have a value of "_" (i.e. MTcu=_). This is the "callback URL (Call­ + backUrl) placeholder". +- Any key whose name begins with MT not mentioned in the previous bullets SHALL be reserved + for future use by this specification. Manufacturers SHALL NOT include query keys starting with + MT in the ARLRequestFlowUrl unless they are referenced by a version of this specification. + +Any other element in the ARLRequestFlowUrl query field not covered by the above rules, as well as +the fragment field (if present), SHALL remain including the order of query key/value pairs present. + +**Expansion of ARLRequestFlowUrl by client** + +Once the URL is obtained, it SHALL be expanded to form a final URL (ExpandedARLRequestFlowUrl) by +proceeding with the following substitution algorithm on the original ARLRequestFlowUrl: + +1. If key MTcu is present, compute the CallbackUrl desired (see Section 9.10.9.3.5, “CallbackUrl for­ + mat for ARL Request Flow response”), and substitute the placeholder value "_" (i.e. in MTcu=_) in + the ARLRequestFlowUrl with the desired contents, encoded with proper URL-encoded escaping + (see RFC 3986 section 2). + +The final URL after expansion (ExpandedARLRequestFlowUrl) SHALL be the one to follow, rather than +the original value obtained from the FabricRestrictionReviewUpdate event. + +**CallbackUrl format for ARL Request Flow response** + +If a CallbackUrl field (i.e. MTcu=) query field placeholder is present in the ARLRequestFlowUrl, the +client MAY replace the placeholder value "_" in the ExpandedARLRequestFlowUrl with a URL that the +manufacturer flow can use to make a smooth return to the client when the ARL flow has termi­ +nated. + +This URL field MAY contain a query component (see RFC 3986 section 3.4). + +If a query is present, it SHALL be composed of one or more key-value pairs: + +- The query SHALL use the & delimiter between key/value pairs. +- The key-value pairs SHALL follow the format name= where name is the key name, and + is the contents of the value encoded with proper URL-encoded escaping. +- If key MTaer is present, it SHALL have a value of "_" (i.e. MTaer=_). This is the placeholder for a + "access extension response" provided by the manufacturer flow to the client. The manufacturer + flow SHALL replace this placeholder with the final status of the access extension request, which + SHALL be formatted following Expansion of CallbackUrl by the manufacturer custom flow and + encoded with proper URL-encoded escaping. +- Any key whose name begins with MT not mentioned in the previous bullets SHALL be reserved + for future use by this specification. + +Any other element in the CallbackUrl query field not covered by the above rules, as well as the frag­ + +``` +Page 586 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +ment field (if present), SHALL remain as provided by the client through embedding within the +ExpandedARLRequestFlowUrl, including the order of query key/value pairs present. + +**Expansion of CallbackUrl by the manufacturer custom flow** + +Once the CallbackUrl is obtained by the manufacturer flow, it MAY be expanded to form a final +ExpandedARLRequestCallbackUrl URL to be used by proceeding with the following substitution algo­ +rithm on the provided CallbackUrl: + +- If key MTaer is present, the manufacturer custom flow having received the initial query contain­ + ing the CallbackUrl SHALL substitute the placeholder value "_" (i.e. in MTaer=_) in the CallbackUrl + with the final status of the access extension request flow which SHALL be one of the following. + Any value returned in the MTaer field not listed above SHALL be considered an error and SHALL + be treated as GeneralFailure. + ◦ Success - The flow completed successfully and the ARL attribute was updated. The client + MAY now read the ARL attribute to determine the new access restrictions. + ◦ NoChange - The ARL attribute was already listing minimum restrictions for the requesting + fabric. + ◦ GeneralFailure - The flow failed for an unspecified reason. + ◦ FlowAuthFailure - The user failed to authenticate to the flow. + ◦ NotFound - Access extension failed because the target fabric was not found. + +A manufacturer custom flow having received an ExpandedARLRequestFlowUrl SHOULD attempt to +open the ExpandedARLRequestCallbackUrl, on completion of the request, if an ExpandedARLRequest­ +CallbackUrl was computed from the CallbackUrl and opening such a URL is supported. + +**Examples of ARLRequestFlowUrl URLs** + +Below are some examples of valid ExpandedARLRequestFlowUrl for several valid values of ARLRequest­ +FlowUrl, as well as some examples of invalid values of ARLRequestFlowUrl: + +- Invalid URL with no query string: http scheme is not allowed: + ◦ [http://company.domain.example/matter/arl/vFFF1p1234](http://company.domain.example/matter/arl/vFFF1p1234) +- Valid URL : + ◦ https://company.domain.example/matter/arl/vFFF1p1234 +- Valid URL, CallbackUrl requested: + ◦ Before expansion: + +``` +https://company.domain.example/matter/arl?vid=FFF1&pid=1234&MTcu=_ +``` +``` +◦ After expansion: +``` +``` +https://company.domain.example/matter/arl?vid=FFF1&pid=1234&MTcu=https%3A%2F%2Fc +lient.domain.example%2Fcb%3Ftoken%3DmAsJ6_vqbr-vjDiG_w%253D%253D%26MTaer%3D_ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 587 +``` + +``` +◦ The ExpandedARLRequestFlowUrl URL contains: +▪ A CallbackUrl with a client-provided arbitrary token= key/value pair and the MTaer= +key/value pair place-holder to indicate support for a return access extension completion +status: https://client.domain.example/cb?token=mAsJ6_vqbr-vjDiG_w%3D%3D&MTaer=_ +▪ After expansion of the CallbackUrl (MTcu key) into an ExpandedCallbackUrl, with an exam­ +ple return access extension completion status of Success, the ExpandedARLRequestCall­ +backUrl would be: +``` +``` +https://client.domain.example/cb?token=mAsJ6_vqbr- +vjDiG_w%3D%3D&MTaer=Success +``` +``` +Note that the MTcu key/value pair was initially provided URL-encoded within the +ExpandedARLRequestFlowUrl URL and the MTaer=_ key/value pair placeholder now contains +a substituted returned completion status. +``` +- Invalid URL, due to MTza=79 key/value pair in reserved MT-prefixed keys reserved for future use: + ◦ https://company.domain.example/matter/arl?vid=FFF1&pid=1234&MTop=_&MTza=79 + +**9.11. Group Relationship** + +A group is a collection of one or more endpoints on one or more nodes. A group is identified by a +unique group ID. If the network supports fabrics, each group, its group ID, and nodes that are mem­ +bers of the group, are all scoped to a single fabric. + +Conceptually, there is a Group Table on each node that represents endpoint group membership. +Each Group Table entry maps a group ID to one or more endpoints on that node, and any endpoint +on a node MAY be assigned to one or more groups. + +A group relationship, that is contained in the Group Table, is managed through the endpoints using +the Groups cluster. + +The Interaction Model allows a group identifier to be used as the destination of a message or action. +If a message received by a node has a group destination, the Group Table is checked to see which +endpoints on the node are members of the group. Then, the message will be delivered to those end­ +points. + +Note that there is a risk that multiple clients allocate the same group identifier for their own pur­ +pose. This likely leads to undesired behavior. For this reason, a client SHOULD discover the unique­ +ness of their 'candidate' group ID. + +Also note that groupcast relies on its support by the underlying network layer. Depending on this +network layer, groupcast may not work to "sleepy" devices that have their radio turned off when +idle to preserve battery lifetime. + +``` +Page 588 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.12. Bridge for non-Matter devices** + +**9.12.1. Introduction** + +A Bridge serves to allow the use of non-Matter IoT devices (e.g. devices on a Zigbee or Z-Wave net­ +work, or any other non-Matter connectivity technology) in a Matter Fabric, with the goal to enable +the consumer to keep using these non-Matter devices together with their Matter devices. + +This is illustrated in the figure below: the non-Matter devices are exposed as Bridged Devices to +Nodes on the Fabric. The Matter Nodes can communicate with both the (native) Matter devices as +well as the Bridged Devices (by virtue of the Bridge which performs the translation between Matter +and the other protocol). + +``` +Bridged +Device 1 +Bridged +Device 2 +Bridged +Device 3 +``` +``` +Bridge +Assumes responsibility +for securing +and certifying the communi- +cation link to each Bridged +Device +``` +``` +Acts as an interpreter +for Bridged Devices +and +presents +them as Matter +Devices to +the various +Matter apps +``` +``` +Presents +a interface Matter +to the +Matter +apps +Matter App 3 +``` +``` +Matter App 2 +``` +``` +Matter App 1 +``` +``` +See and control all +ofthe Bridged +Devices and Matter +Devices using +Matter protocol +``` +``` +Non-Matter +Transport Layer (e.g. +Zigbee; Z-Wave; +proprietary; etc.) +``` +``` +Manufacturer +App +Manufacturer- +defined +interface +``` +``` +Matter Device 1 +``` +``` +Matter +Fabric +``` +``` +Matter Device 2 +Matter Device 3 +Matter Device 4 +``` +_Figure 47. principle of bridging_ + +### NOTE + +``` +The bridging-concept described here is NOT intended to be used to expose Matter +Nodes (which are not on the Fabric) to a Fabric, since direct connection of those +Matter Nodes to the Fabric would provide a better experience. +``` +This section will describe how the Data Model concepts can be used by a Bridge to expose the +Bridged Devices in such a way that they can be discovered and used by Nodes on the Matter Fabric. + +**9.12.2. Exposing functionality and metadata of Bridged Devices** + +After Commissioning, the Bridge SHALL expose (at least) one Node to the Fabric. The device imple­ +menting the Bridge MAY have more than one Node. This, however, is orthogonal to the bridging +concept and will not be discussed further here. + +- On this Node, the Bridge SHALL expose a set of endpoints representing the various Bridged + Devices on the non-Matter side of the Bridge. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 589 +``` + +- Additionally, it SHALL expose an endpoint with the device type Aggregator which has a Descrip­ + tor cluster with a PartsList attribute containing all the endpoints representing those Bridged + Devices. +- Each Bridged Device is represented by one or more endpoints listed in this PartsList (see Infor­ + mation about Bridged Devices and examples below). The Descriptor cluster on the correspond­ + ing endpoint provides information about the particular Bridged Device, such as its device + type(s). + +``` +Descriptor cluster:DeviceTypeList: Extended Color Light, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "kitchen" +``` +``` +Descriptor cluster:DeviceTypeList: Extended Color Light, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "dining table" +``` +``` +Descriptor cluster:DeviceTypeList: Dimmable Light, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "hallway" +``` +``` +Descriptor cluster:DeviceTypeList: Temperature Sensor, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "outdoor temperature" +``` +``` +Descriptor cluster:DeviceTypeList: Generic Switch, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "living room entrance" +``` +``` +Descriptor cluster:DeviceTypeList: Generic Switch, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "kitchen entrance" +``` +``` +The PartsList on endpoint 1 lists all endpoints for bridged +devices; each endpoint 11.. 16 represents one device at +the non-Matter side of the bridge. +``` +``` +Descriptor cluster:DeviceTypeList: Root Node +Basic Information cluster:PartsList: EP 1, 11,12,13,14,15,16 +.. +``` +``` +EP 0 +``` +``` +EP 11 +``` +``` +EP 12 +``` +``` +EP 13 +``` +``` +EP 14 +``` +``` +EP 15 +``` +``` +EP 16 +``` +``` +Descriptor cluster:DeviceTypeList: Aggregator +PartsList: EP 11,12,13,14,15,16 +``` +``` +EP 1 +``` +_Figure 48. example of endpoints representing Bridged Devices_ + +In case the Bridge is bridging to/from multiple technologies (or has some other logical distinction +between groups of bridged devices), it MAY expose such groups as two or more such hierarchical +trees each with their Aggregator device type (e.g. one for each technology, see figure below); it MAY +also combine all bridged devices in one hierarchical tree (see figure above). Both figures have the +same set of bridged devices - the difference is in how the bridge manufacturer decides to expose +them as one or multiple sets. + +``` +Descriptor cluster:DeviceTypeList: Aggregator +TagListPartsList: EP 14,15,16: Tag=(MfgCode=0xFFF1, Namespace=0x11, +TagID=0x05), Label=“Z-Wavebridge” +``` +``` +Descriptor cluster:DeviceTypeList: Extended Color Light,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "kitchen" +``` +``` +Descriptor cluster:DeviceTypeList: Extended Color Light,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "dining table" +``` +``` +Descriptor cluster:DeviceTypeList: Dimmable Light,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "hallway" +``` +``` +Descriptor cluster:DeviceTypeList: Generic Switch,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "living room entrance" +``` +``` +This implementation chooses to expose two instances of the Aggregator device type, each with +their own hierarchy of devices, to be able to expose which bridged device is on which technology. +``` +``` +Descriptor cluster:DeviceTypeList: Root Node +Basic Information cluster:PartsList: EP 1,2, 11,12,13,14,15,16 +.. +``` +``` +EP 0 +``` +``` +EP 11 +``` +``` +EP 12 +``` +``` +EP 13 +``` +``` +EP 14 +``` +``` +Descriptor cluster:DeviceTypeList: Aggregator +PartsList: EP 11,12,13TagList: Tag=(MfgCode=0xFFF1, Namespace=0x11, +TagID=0x03), Label=“Zigbee bridge” +``` +``` +EP 1 EP 2 +``` +``` +Zigbee devices Z-Wave devices +``` +``` +Descriptor cluster:DeviceTypeList: Temperature Sensor,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "outdoor temperature" +``` +``` +Descriptor cluster:DeviceTypeList: Generic Switch,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "kitchen entrance" +``` +``` +EP 15 +``` +``` +EP 16 +``` +_Figure 49. example of endpoints representing Bridged Devices from two technologies_ + +``` +Page 590 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.12.2.1. Topology or logical grouping** + +A Bridge typically has information on topology or logical grouping of the Bridged Devices, which +can be of use to Nodes on the Matter Fabric. + +- For example, consider a Bridge with 50 lights. If this exposure of grouping, and their naming, + would not be present, the user would just see a list of 50 lights on their controller and would not + know which of those physical lights would be in which location/group. + +If a Bridge has such information on topology or logical grouping, it SHOULD expose such informa­ +tion in the EndpointLists attribute of an Actions cluster (the ActionLists of which MAY be empty if +no actions are exposed). A Bridge MAY make it possible (e.g., through a Bridge Manufacturer’s app) +for its users to restrict whether all or some of such information is exposed to the Fabric. The Node +on the Fabric using the Bridged Devices which is interested in using such topology or logical group­ +ing (e.g. to show the grouping of lights per room in an overview to the user), SHOULD derive such +grouping (and associated naming) from this EndpointLists attribute. + +In the example below, the devices are split over two rooms, as exposed in the EndpointLists +attribute. This example also illustrates a composed endpoint for a composed Bridged Device, in this +case a lighting device (Bridged Device at EP 24,25,26) which has an up- and downlighter which can +be controlled separately, and which have their own set of lighting-related clusters on an individual +endpoint (EP 25,26). Note that the Bridged Device Basic Information cluster is at the top of the hier­ +archy for this composed device (EP 24), while the application device types and application clusters +are at the leaf endpoints (EP 25,26). +Since EP 25,26 are listed in the PartsList of EP 24, they 'inherit' the Bridged Node device type and +information in the Bridged Device Basic Information cluster of EP 24. + +``` +Descriptor cluster:DeviceTypeList: Extended Color Light +TagList:Direction.Downward +``` +``` +Descriptor cluster:DeviceTypeList: Extended Color Light,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "dining table" +``` +``` +Descriptor cluster:DeviceTypeList: Color Temperature Light,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "ceiling light" +``` +``` +Descriptor cluster:DeviceTypeList: Color Temperature Light,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "kitchen light" +``` +``` +Descriptor cluster:DeviceTypeList: Temperature Sensor,Bridged Node, +Bridge Device Basic Information cluster:Power Source +Power Source cluster: (features=BAT,REPLC)NodeLabel: "bedroom temperature" +BatChargeLevel: WarningBatReplacementDescription: "AAA batteries" +BatQuantity: 2EndpointList: 23 +``` +``` +Descriptor cluster:DeviceTypeList: Generic Switch,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "living room entrance" +``` +``` +In this example, the Actions cluster is used to indicate +grouping,i.e.which devices are in which room. The bedroom +has 3 bridged devices, and one of them (endpoint 24,25,26) +is a composed device - it uses theTagListin the Descriptor +cluster to expose information on the user-relevant +components of the composed device (endpoint 25,26). +``` +``` +living room bedroom +``` +``` +Descriptor cluster:DeviceTypeList: Extended Color Light +TagList:Direction.Upward +``` +``` +composed device +Descriptor cluster:DeviceTypeList:Bridged Node +Bridge Device Basic Information cluster:PartsList: 25,26 +NodeLabel: "bedroom light" +``` +``` +EP 12 +``` +``` +EP 13 +``` +``` +EP 14 +``` +``` +EP 24 +``` +``` +EP 25 +``` +``` +EP 26 +``` +``` +EP 22 +``` +``` +EP 23 +``` +``` +Descriptor cluster:DeviceTypeList: Root Node +Basic Information cluster:PartsList: EP 1, 12,13,14,22,23,24,25,26 +.. +``` +``` +EP 0 +Descriptor cluster:DeviceTypeList: Aggregator +Actions cluster:PartsList: EP 12,13,14,22,23,24,25,26 +ActionListEndpointLists: [ ]: [ +[0xE001, "living room", room, [12,13,14] ],[0xE002, "bedroom", room, [22,23,24,25,26] ] +] +``` +``` +EP 1 +``` +_Figure 50. example of endpoints representing Bridged Devices using grouping_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 591 +``` + +``` +living roomdining table +kitchen light +living room entrance +``` +``` +bedroom temperature +``` +``` +bedroomceiling light +bedroom lightbedroom light up +bedroom light down +``` +_Figure 51. impression of app UI indicating information for the Bridged Devices_ + +**9.12.2.2. Native Matter functionality in Bridge** + +The Bridge MAY also contain native Matter functionality, i.e. non-bridged functionality, such as in +the example below, which shows a smart speaker device having, in addition to a Wi-Fi connection, +also a Zigbee connection towards a number of Zigbee lights. The speaker functionality (EP 31) is +native Matter functionality (and could have a Controller role to allow sending Matter commands +upon receiving voice commands), while the remainder of the non-zero endpoints represent the +Bridged Devices. + +``` +Descriptor cluster:DeviceTypeList: Generic Switch, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "bedside switch" +``` +``` +In this example, the EndPointListsattribute of the Actions +cluster is used to indicate grouping (e.g.all devices in one +room -irrespective whether they are bridged or not). +EP31 is a component of the device itself which is not bridged, +i.e.native Matter; it is in the bedroom along with some +bridged devices. +``` +``` +Descriptor cluster:DeviceTypeList: Speaker +``` +``` +bedroom +``` +``` +Descriptor cluster:DeviceTypeList: Extended Color Light, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "dining table" +Descriptor cluster:DeviceTypeList: Color Temperature Light, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "kitchen light" +Descriptor cluster:DeviceTypeList: Generic Switch, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "living room entrance" +living room +``` +``` +Descriptor cluster:DeviceTypeList: Color Temperature Light, Bridged Node +Bridge NodeLabelDevice Basic Information cluster:: "ceiling light" +``` +``` +EP 12 +``` +``` +EP 13 +``` +``` +EP 14 +``` +``` +EP 31 +``` +``` +EP 22 +``` +``` +EP 24 +``` +``` +Descriptor cluster:DeviceTypeList: Root Node +Basic PartsList: EP Information cluster:1, 12,13,14,22,24,31 +.. +``` +``` +EP 0 +Descriptor cluster:DeviceTypeList: Aggregator +Actions cluster:PartsList: EP 12,13,14,22,24 +ActionListEndpointLists: [ ]: [ +[0xE001, "living room", room, [12,13,14] ],[0xE002, "bedroom", room, [22,24,31] ] +] +``` +``` +EP 1 +``` +_Figure 52. example of Bridge with native Matter functionality_ + +**9.12.2.3. Information about Bridged Devices** + +For each Bridged Device, the Bridge SHALL include a Bridged Device Basic Information cluster on +the endpoint which represents this Bridged Device. In case a Bridged Device is represented by mul­ +tiple endpoints, the Bridged Device Basic Information cluster SHALL only be present on the end­ +point which is the top level of the hierarchy representing this Bridged Device (example: endpoint 24 +in Figure 50, “example of endpoints representing Bridged Devices using grouping”). +On this endpoint with the Bridged Device Basic Information cluster, the Bridge SHALL also include +a Descriptor cluster with + +``` +Page 592 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- a DeviceTypeList attribute containing device type Bridged Node plus the device type(s) of the + Bridged Device, and +- a PartsList attribute listing any other endpoints which jointly expose the functionality of this + Bridged Device. + +**Information about power sources for Bridged Devices** + +In case the Bridged Device contains a power source such as battery or mains power feed, _and_ infor­ +mation about the state of that power source is available to the Bridge, the Bridge SHALL also +include one or more Power Source cluster(s), where their EndpointList attribute SHALL contain the +endpoint(s) of the Bridged Device that are powered by this power source. Each endpoint with a +Power Source cluster SHALL have the related Power Source device type in its DeviceTypeList. + +For Bridged Devices which are represented by a single endpoint: + +- The Power Source cluster SHALL be included on that single endpoint. An example of this is + shown for the battery-powered temperature sensor on endpoint 23 in Figure 50, “example of + endpoints representing Bridged Devices using grouping”. + +For Bridged Devices which are represented by multiple endpoints: + +- If the Bridged Device contains only one power source, the Power Source cluster SHALL be + present on an endpoint which corresponds to the part of the Bridged Device being powered by + the power source. + ◦ In case this power source provides power to the entire Bridged Device, the power source + cluster SHALL be on the endpoint where the Bridged Node device type is located, and con­ + tain an EndpointList attribute containing all the endpoints constituting the Bridged Device. + +In case a Bridged Device does not contain a power source such as battery or mains power feed, _or_ +information about the state of that power source is not available to the Bridge, the Bridge SHALL +NOT include a Power Source cluster on the endpoint(s) representing the Bridged Device. + +**9.12.2.4. Clusters for Bridged Device functionality (device types)** + +For each Bridged Device, the Bridge SHALL expose the clusters required for a device of the indi­ +cated Matter device type(s). +This allows the Matter Nodes to recognize the device type of the Bridged Device and interact with +its clusters in the same manner as with a native Matter Node of that device type. + +**9.12.2.5. Identify for Bridge and Bridged Devices** + +If the bridge has a mechanism to identify itself to the user (e.g. blinking LED on the bridge itself ), +the associated Identify cluster SHOULD be used on the endpoint with the Aggregator device type. + +For the identification function of individual bridged devices, the conformance for the associated +Identify cluster is determined by the application device types on the endpoint(s) representing the +bridged device. For example, in the composed lighting device in Figure 50, “example of endpoints +representing Bridged Devices using grouping”, each of the endpoints 25 and 26 would have an iden­ +tify cluster to allow individual identification of each of those lights. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 593 +``` + +**9.12.3. Discovery of Bridged Devices** + +A Node which discovers another Node with device type Aggregator on one of its endpoints SHOULD +walk the entire tree of endpoints via the PartsList attributes and endpoints to discover the list of +Bridged Devices, including their device types and other attributes, as well as any native Matter +functionality potentially present on the Node. +Each endpoint found containing a Bridged Node device type represents a Bridged Device of the +device type(s) specified at this endpoint, or one of the endpoints found via its PartsList. If the dis­ +covering Node supports this device type, it MAY add this Bridged Device to the list of devices which +it could interact with, or could set up configuration for. + +This discovering Node SHALL use the acquired information on the available Bridged Devices to set +up (configure) (likely with input from the user) how the Bridged Devices can be used with the Mat­ +ter Nodes (e.g. which switch controls which light, or how to control a light from an app on the +user’s phone). +Since the Bridge may expose a large number of Bridged Devices, the discovering Node SHALL use +the NodeLabel attribute in the Bridged Device Basic Information cluster of each of the Bridged +Devices to allow the user to easily identify and recognize the various Bridged Devices, and expedite +the setup/configuration process, rather than present the user with an unannotated list of, for exam­ +ple, 20 lights, 3 sensors and 4 switches. These labels have likely been populated by the user when +interacting previously with the Bridge e.g. through means provided by the Bridge Manufacturer, +such as a Bridge Manufacturer app. +If power source-related information regarding the Bridged Device is provided in the Power Source +cluster on the associated endpoint, the discovering Node SHOULD use this information in a similar +manner as power source-related information acquired from a Matter Node’s Power Source cluster. +Such information can then be used to inform the user about the state of the power source (e.g. +warn about low batteries) in a Bridged Device in a similar manner as done for Matter Nodes. + +**9.12.4. Configuration of Bridged Devices** + +For configuration of the discovered Bridged Devices, two basic archetypes are described in the fol­ +lowing sections: one for actuators and one for sensors/switches. +Since a Bridged Device of a certain device type has the same set of application clusters as a native +Matter device of the same device type, this process is similar to configuring a native Matter device +of that device type. + +**9.12.4.1. Sending commands from a Matter controller to a Bridged Device** + +For Bridged Devices that are actuators and hence have a Controlee role, a Controller Node on the +Fabric MAY send commands to the associated clusters on one or more endpoints on the Bridge’s +Node, such as an On command to the On/Off cluster of a Bridged Device. The Bridge SHALL forward +this command to the relevant Bridged Device after conversion between the Matter protocol and the +non-Matter device’s native protocol. + +Example: + +A Controller creates a Group containing some Matter lights as well as some non-Matter lights, by +sending an Add Group command to the instances of the Group cluster on both the endpoints of the +Matter lights as well as on the Bridge’s Node endpoints representing the targeted bridged lights. + +``` +Page 594 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Similarly, the Controller creates one or more Scenes using the instances of the Scenes Management +cluster on these endpoints. +The Controller then sends a (single) On command (On/Off cluster) to this group to switch on all these +lights in a single operation. This (single) multicast message will be received (and interpreted) by the +Matter lights which are part of this group as well as by the Bridge, which will forward it (after +appropriate protocol conversion) to the relevant bridged lights. +Similarly, the Controller sends a (single) Move to Level (Level Control cluster) or sends a (single) +Recall Scene (Scenes Management cluster) to this group, to set the brightness resp. recall a scene con­ +tents on all these lights in a single operation. + +``` +Zigbee +network +``` +``` +Matter +network +``` +``` +Matter controllers & apps +``` +``` +lights +``` +``` +bridge +Matter +<=> +Zigbee +``` +``` +Matter light control Zigbee light control +``` +``` +Matter +lights +``` +``` +Bridge Manufacturer app +``` +``` +Living roomUplighter +DownlighterReading +light +``` +``` +Living roomUplighter +DownlighterReading light +KitchenCeiling +Cooking island +``` +``` +bridged lights +``` +_Figure 53. example of bridging lights_ + +**9.12.4.2. Receiving status/events/commands from a Bridged Device** + +For Bridged Devices like sensors and switches, the Bridge will receive value updates (e.g. Zigbee +attribute reports), events and/or commands from those devices, and SHALL (after conversion from +the native protocol of the non-Matter devices towards Matter protocol) represent those as attrib­ +utes, events and/or commands in the appropriate clusters on the associated endpoints of the Bridge. +Interactions with those attributes/events/commands on the Matter side (e.g., towards a Controller +using the sensor/switch data) SHOULD be identical to interactions with corresponding attrib­ +utes/events/commands in native Matter sensors and switches (e.g., attribute readout and subscrip­ +tion, proxying and eventing). + +Examples: + +- A temperature sensor sends a status report to the Bridge over a non-Matter interface. The logic + in the Bridge processes this as an update to the Measured Value attribute of the Temperature Mea­ + surement cluster on the endpoint associated with this bridged sensor. + Nodes on the Fabric which have an interest in this value can read the updated attribute value, + and can configure a subscription on this attribute. This is identical to reading an attribute value + or setting up an attribute subscription on a native-Matter temperature sensor Node. +- A user presses a button on a (push-button) switch device. The switch device sends a message to + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 595 +``` + +``` +the Bridge over a non-Matter interface. The logic in the Bridge processes this to generate an Ini­ +tialPress event (Switch cluster) on the endpoint representing the switch. +Nodes on the Fabric which have an interest in the switch operation can setup eventing from this +cluster. +``` +``` +bridge +Matter +<=> +Zigbee Zigbee +network +``` +``` +Matter +network +``` +``` +Matter controllers & apps Bridge Manufacturer app +``` +``` +Living roomUplighter +DownlighterReading light +``` +``` +Living roomUplighter +DownlighterReading light +KitchenCeilingCooking island +``` +``` +sensors & switches +``` +``` +Matter switch/sensor state Zigbee switch/sensor state +``` +``` +bridged switches/sensors +``` +``` +lights +``` +``` +Matter +lights +``` +``` +Switch 1 ONSwitch 2 OFF +Temp: 20 °C +``` +``` +Switch 1 ONSwitch 2 OFF +Temp: 20 °C +``` +_Figure 54. example of bridging switches and sensors_ + +**9.12.5. New features for Bridged Devices** + +Bridged Devices can have their software updated independently of the Bridge, through Bridge Man­ +ufacturer-specific means. These updates MAY result in one or more changes to their capabilities, +such as supported clusters and/or attributes, for an endpoint. Like every Matter Node, every end­ +point on the Bridge’s Node contains a Descriptor cluster that contains attributes for the device types +(DeviceTypeList), endpoints (PartsList) and supported clusters (ServerList and ClientList). Nodes +that wish to be notified of such changes SHOULD monitor changes of these attributes. + +**9.12.6. Changes to the set of Bridged Devices** + +Bridged Devices can be added to or removed from the Bridge through Bridge-specific means. For +example, the user can use a Manufacturer-provided app to add/remove Zigbee devices to/from their +Matter-Zigbee Bridge. +When an update to the set of Bridged Devices (which are exposed according to the Section 9.12.11, +“Best practices for Bridge Manufacturers”) occurs, the Bridge SHALL + +- on the Descriptor clusters of the root node endpoint and of the endpoint which holds the Aggre­ + gator device type: update the PartsList attribute (add/remove entries from this list) +- update the exposed endpoints and their descriptors according to the new set of Bridged Devices + +Nodes that wish to be notified of added/removed devices SHOULD monitor changes of the PartsList +attribute in the Descriptor cluster on the root node endpoint and the endpoint which holds the +Aggregator device type. + +``` +Page 596 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Allocation of endpoints for Bridged Devices SHALL be performed as described in Dynamic End­ +point allocation. + +**9.12.7. Changes to device names and grouping of Bridged Devices** + +Typically, the user has some means (e.g. a Manufacturer-provided app) to assign names to the +Bridged Devices, or names could be assigned automatically by the Bridge. The Bridge SHALL expose +such names in the NodeLabel attribute of the Bridged Device Basic Information cluster on the +applicable endpoint. +Similarly, the user typically has some means to group the Bridged Devices (e.g. via a room/zone-con­ +cept) and provide names to such groups, or grouping could be applied automatically by the Bridge. +The Bridge SHOULD expose such grouping using the EndpointLists attribute of the Actions cluster +as described above. +For such exposed information, when there is a change in naming/grouping (e.g. the user makes +changes via a Manufacturer-provided app), the Bridge SHALL update the appropriate attributes. +Nodes that wish to be notified of a change in such a name or grouping SHOULD monitor changes of +this attribute or cluster. + +**9.12.8. Setup flow for a Bridge (plus Bridged Devices)** + +As described above, the Bridge together with its Bridged Devices is exposed as a single Node with a +list of endpoints. Consequently, a single Node ID and a single Operational Certificate is assigned +during Commissioning and a single pass through the commissioning flow is required to bring the +Bridge (along with its Bridged Devices) onto a Fabric. This provides for a simple user experience, +since the user only needs to go through the commissioning flow for the Bridge, and not separately +for each of the Bridged Devices. + +**9.12.9. Access Control** + +The Bridge is a Matter node, therefore it has a single Access Control Cluster for the entire Node, like +every other Matter Node. This cluster contains all Access Control Entries for each of its endpoints, +including for all Bridged Devices and other native Matter functionality exposed by the Bridge Node. +A typical setup of Access Control would reflect which privilege level a Matter Controller needs to +have for one or more Bridged Devices. This overall access set may be a subset of all the Bridged +Devices on the Bridge, rather than all endpoints on a Bridge. This can be accomplished by setting an +Access Control Entry containing as targets a list of those endpoints representing a Bridged Device or +a set of Bridged Devices. As defined in the ACL model, it is also possible to specify access towards +specific Targets, for example all Bridged Devices of device type Extended Color Light. + +**9.12.10. Software update (OTA)** + +The Bridge is a Matter device and its Matter-related functionality MAY be updated using the mecha­ +nism described in Section 11.20, “Over-the-Air (OTA) Software Update”. +The Bridged Devices, on the other hand, are not native Matter devices, do not have a Product ID, +and are not listed in the Distributed Compliance Ledger. They are typically updated using a mecha­ +nism defined and deployed by the Bridge Manufacturer. That same mechanism is typically used to +update the parts of the Bridge which are not related to Matter, which is particularly relevant to +allow synchronization of updates to the non-Matter part of the Bridge with updates to the Bridged + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 597 +``` + +Devices. Obviously, such mechanism MAY also be employed to update the entire Bridge firmware, +including the Matter-related functionality. + +**9.12.11. Best practices for Bridge Manufacturers** + +This section summarizes (in order of priority) the process to determine which non-Matter devices +the Bridge exposes to the Fabric. + +1. Choice of supported device types + ◦ A Manufacturer MAY choose which of the Matter device types they can or want to support in + the Bridge. After implementation of support for bridging of those device types, they SHALL + certify the Bridge for those device types. + ◦ By default, a Bridge SHOULD expose to the Fabric all its connected non-Matter devices which + can be mapped to a Matter device type for which that Bridge is certified. + E.g., if a Bridge is certified for Matter light bulbs, it SHOULD NOT hide any light bulb on the + non-Matter side from the Fabric by default (some situations where the Bridge MAY deviate + from this recommendation are in the following text). + ◦ Given the wide variety of device types on a wide variety of standards, there may be device + types on the non-Matter side that do not have a corresponding Matter device type. Such + devices cannot be bridged to a Matter device type. The Manufacturer MAY choose to not + expose such devices with the Bridge or MAY expose them with a manufacturer-specific + device type and/or manufacturer-specific clusters. +2. Compatibility issues + ◦ For the device types for which a Bridge is certified, a Bridge Manufacturer MAY decide to + not expose certain devices based on any reason, including compatibility and interoperabil­ + ity reasons, or to expose them in a 'best-effort' manner as needed. + ▪ The Bridge Manufacturer may choose to not expose a device that does not support cer­ + tain functions or features which are mandatory for a Matter device type, but which are + defined as optional, or not defined at all, in the specification for the corresponding + device type on the non-Matter side of the bridge. Such a Bridge would expose to the Fab­ + ric only Bridged Devices of device types which support those particular control functions + or features which are required. + ▪ The Bridge Manufacturer may also choose to map or emulate such features which are + not available in the Bridged Device; example: for a bridged colored light connected via a + protocol which does not support scenes, the Bridge could emulate the scene function by + storing the scenes in the Bridge and sending corresponding brightness and color com­ + mands to the light when a Scene Recall command is received from a Matter Node. +3. User choice + ◦ A Bridge MAY make it possible (e.g., through a Bridge Manufacturer’s app) for its users to + further restrict which devices are exposed to the Fabric. + For example, a user may decide to prevent exposure to the Fabric of certain Devices Types, + such as all occupancy sensors, or of only certain devices of a certain device type, such as + only their bedroom occupancy sensor. + +``` +Page 598 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.12.12. Best practices for Administrators** + +An Administrator MAY indicate to users which devices are native Matter and which ones are +Bridged Devices, as determined using the presence of a Bridged Node device type on the endpoint, in +order to ensure the user does not make assumptions about the Bridged Devices having the same +security requirements as native Matter devices. + +**9.13. Bridged Device Basic Information Cluster** + +This cluster is a derived cluster of the Basic Information cluster and serves two purposes towards a +Node communicating with a Bridge: + +- Indicate that the functionality on the Endpoint where it is placed (and its Parts) is bridged, and +- Provide a centralized collection of attributes that the Node MAY collect to aid in conveying + information regarding the Bridged Device to a user, such as the vendor name, the model name, + or user-assigned name. + +This cluster SHALL be exposed by a Bridge on the Endpoint representing each Bridged Device. +When the functionality of a Bridged Device is represented using a set of Endpoints, this cluster +SHALL only be exposed on the Endpoint which is at the top of the hierarchy for the functionality of +that Bridged Device. + +This cluster SHALL NOT be used on an endpoint that is not in the Descriptor cluster PartsList of an +endpoint with an Aggregator device type. + +This cluster has been derived from the Basic Information Cluster, and provides generic information +about the Bridged Device. Not all of the attributes in the Basic Information Cluster are relevant for +a Bridged Device (e.g. ProductID since it is not a Matter device). For other attributes, the informa­ +tion which is listed as Mandatory for the Basic Information Cluster, may not be available when the +Bridged Device does not provide it to the Bridge, and the Bridge has no other means to determine it. +For such cases where the information for a particular attribute is not available, the Bridge SHOULD +NOT include the attribute in the cluster for this Bridged Device. See below for Conformance details. + +**9.13.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Added ProductAppearance attribute +3 Added SpecificationVersion and MaxPathsPerIn­ +voke attributes +4 Updated conformance for UniqueID to manda­ +tory, ProductID to optional when bridging Mat­ +ter devices, add the BridgedICDSupport feature. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 599 +``` + +**9.13.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Basic Information Utility Endpoint BRBINFO +``` +**9.13.3. Cluster ID** + +``` +ID Name +0x0039 Bridged Device Basic Information +``` +**9.13.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +20 BIS BridgedICDSup­ +port +``` +``` +O Support bridged +ICDs. +``` +**9.13.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 DataMod­ +elRevision +``` +### X + +``` +0x0001 Vendor­ +Name +``` +### O + +``` +0x0002 VendorID O +0x0003 Product­ +Name +``` +### O + +``` +0x0004 ProductID desc +0x0005 NodeLabel O +0x0006 Location X +0x0007 Hardware­ +Version +``` +### O + +``` +0x0008 Hardware­ +Version­ +String +``` +### O + +``` +0x0009 Software­ +Version +``` +### O + +``` +Page 600 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x000A Software­ +Version­ +String +``` +### O + +``` +0x000B Manufac­ +turing­ +Date +``` +### O + +``` +0x000C PartNum­ +ber +``` +### O + +``` +0x000D Produc­ +tURL +``` +### O + +``` +0x000E Product­ +Label +``` +### O + +``` +0x000F Serial­ +Number +``` +### O + +``` +0x0010 LocalCon­ +figDis­ +abled +``` +### X + +``` +0x0011 Reachable M +0x0012 UniqueID M +0x0013 Capabili­ +tyMinima +``` +### X + +``` +0x0014 Produc­ +tAppear­ +ance +``` +### O + +``` +0x0015 Specifica­ +tionVer­ +sion +``` +### X + +``` +0x0016 Max­ +PathsPer­ +Invoke +``` +### X + +Since this cluster has been derived from the Basic Information Cluster, the identifiers of the attrib­ +utes, their range, quality and default characteristics and their descriptions correspond to those in +that Cluster and those descriptions are not repeated here. Several attributes from the Basic Infor­ +mation Cluster which are _not_ relevant or applicable for a Bridged Device have been marked with X +in column Conformance and SHALL NOT be used in the Bridged Device Basic Information Cluster. +The Conformance characteristics of several attributes in this cluster have changed from M to O +compared to their Conformance in the Basic Information Cluster, and SHALL be used according to +the table above. + +The Bridge SHOULD fill these attributes with the available information, which could e.g. come from + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 601 +``` + +the Bridged Device provided to the Bridge over the non-Matter interface (e.g. VendorName and Ven­ +dorID) or could have been provided by the user (e.g. assigned name of a device for NodeLabel). +If the manufacturer of a Bridged Device is known to the Bridge, the Bridge SHALL provide this +name (in attribute VendorName), otherwise it SHALL NOT include this attribute. +If the manufacturer of a Bridged Device and the associated Alliance-assigned Vendor ID are known +to the Bridge (e.g. by copying the Manufacturer Code from the Node Descriptor of a Zigbee device or +the Basic Information cluster of a Matter device), the Bridge SHALL provide this identifier (in +attribute VendorID), otherwise it SHALL NOT include this attribute. If the associated Product ID of a +bridged Matter device is known to the Bridge (e.g. from the Basic Information cluster of the bridged +Matter device), the Bridge SHALL provide this identifier (in attribute ProductID), otherwise it +SHALL NOT include this attribute. For bridged non-Matter devices, the ProductID attribute SHALL +NOT be included. + +**9.13.5.1. Reachable Attribute** + +This attribute SHALL be used to indicate whether the bridged device is reachable by the bridge, so a +Matter Node which wants to communicate with a bridged device can get an indication that this +might fail (when the attribute is False). Determination of reachability might not be perfect (e.g. +depending on technology employed), so the Matter Node SHOULD be aware of the risk of false posi­ +tives and negatives on reachability determination. For example, a bridged device MAY be marked +as unreachable while it could actually be reached, and vice-versa. Also, detection (and indication) +that a bridged device is not longer reachable may be delayed due to the technique employed (e.g. +detecting that a number of expected messages from the bridged device did not arrive). Also see +event ReachableChanged below. + +**9.13.5.2. UniqueID Attribute** + +This attribute SHALL, for a Bridged Device, be updated when the Bridge is factory reset. If the +bridged device does not provide some unique id (e.g. in the case of bridging from non-Matter +devices, or in case of bridging Matter devices from an earlier revision which were not required to +provide a UniqueID attribute), the bridge SHALL generate a unique id on behalf of the bridged +device. + +``` +NOTE The UniqueID attribute was optional in cluster revisions prior to revision 4. +``` +**9.13.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x80 KeepActive client ⇒ server Y O BIS +``` +**9.13.6.1. KeepActive Command** + +Upon receipt, the server SHALL attempt to keep the bridged device active for the duration specified +by the command, when the device is next active. + +The implementation of this is best-effort since it may interact with non-native protocols. However, +several specific protocol requirements are: + +``` +Page 602 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- If the bridged device is a Matter Intermittently Connected Device, then the server SHALL send a + StayActiveRequest command with the StayActiveDuration field set to value of the StayActiveDu­ + ration field in the received command to the bridged device when the bridged device next sends + a checks-in message or subscription report. See Intermittently Connected Devices Behavior for + details on ICD state management. + +When the bridge detects that the bridged device goes into an active state, an ActiveChanged event +SHALL be generated. + +In order to avoid unnecessary power consumption in the bridged device: + +- The server SHALL enter a "pending active" state for the associated device when the KeepActive + command is received. The server "pending active" state SHALL expire after the amount of time + defined by the TimeoutMs field, in milliseconds, if no subsequent KeepActive command is + received. When a KeepActive command is received, the "pending active" state is set, the StayAc­ + tiveDuration is updated to the greater of the new value and the previously stored value, and the + TimeoutMs is updated to the greater of the new value and the remaining time until the prior + "pending active" state expires. +- The server SHALL only keep the bridged device active once for a request. (The server SHALL + only consider the operation performed if an associated ActiveChanged event was generated.) + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StayActive­ +Duration +``` +``` +uint32 all M +``` +``` +1 TimeoutMs uint32 30000 to +3600000 +``` +### M + +**StayActiveDuration Field** + +This field SHALL indicate the duration, in milliseconds, that the device is requested to remain +active, once the device becomes active again. + +The value of this field MAY be longer than the value supported by the bridged device and would, +typically, be used by the client to request the server of the bridged device to stay active and respon­ +sive for this period to allow a sequence of message exchanges during that period. + +The client MAY slightly overestimate the duration it wants the bridged device to be active for, in +order to account for network delays. + +**TimeoutMs Field** + +This field SHALL indicate the period, in milliseconds, that the server will wait before the "pending +active" state expires. See the KeepActive Command description for details. + +``` +NOTE TimeoutMs is a timeout for the request, NOT the time the device will be awake for. +The server will wait for up to TimeoutMs for the device. If after TimeoutMs the ICD +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 603 +``` + +``` +device does NOT check-in, the server will not perform any actions. +``` +**9.13.7. Events** + +This cluster SHALL support these events: + +``` +ID Name Priority Quality Access Conformance +0x00 StartUp O +0x01 ShutDown O +0x02 Leave O +0x03 Reach­ +ableChanged +``` +### M + +``` +0x80 ActiveChange +d +``` +### INFO V BIS + +**9.13.7.1. Leave Event** + +The Leave event SHOULD be generated by the bridge when it detects that the associated device has +left the non-Matter network. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 FabricIndex X +``` +### NOTE + +``` +The FabricIndex field has the X conformance, indicating it SHALL NOT be present. +This event, in the context of Bridged Device Basic Information cluster, has no usable +fields, but the original Basic Information cluster’s field definition is kept for com­ +pleteness. +``` +**9.13.7.2. ReachableChanged Event** + +This event SHALL be generated when there is a change in the Reachable attribute. Its purpose is to +provide an indication towards interested parties that the reachability of a bridged device has +changed over its native connectivity technology, so they MAY take appropriate action. +After (re)start of a bridge this event MAY be generated. + +**9.13.7.3. ActiveChanged Event** + +This event (when supported) SHALL be generated the next time a bridged device becomes active +after a KeepActive command is received. +See KeepActive for more details. + +The data of this event SHALL contain the following information: + +``` +Page 604 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PromisedAc +tiveDura­ +tion +``` +``` +uint32 desc M +``` +**PromisedActiveDuration Field** + +This field SHALL indicate the minimum duration, in milliseconds, that the bridged device will +remain active after receiving the initial request from the KeepActive processing steps. + +If the bridged device is a Matter Intermittently Connected Device, PromisedActiveDuration SHALL +be set to the PromisedActiveDuration value returned in the StayActiveResponse command. + +If the bridged device is not a Matter Intermittently Connected Device, the implementation of this is +best-effort since it may interact with non-native protocol. + +**9.14. Actions Cluster** + +This cluster provides a standardized way for a Node (typically a Bridge, but could be any Node) to +expose + +- Information about logical grouping of endpoints on the Node (example: lights in a room) +- Information about named actions that can be performed on such a group of endpoints (exam­ + ple: recall a scene for a group of lights by its name) +- Commands to trigger such actions +- Events to receive feedback on the state of such actions. + +The information on grouping and available actions is typically provided by the user or Bridge man­ +ufacturer via some means not defined in Matter, and therefore provided as read-only to Nodes. For +example: a manufacturer-provided app allows a user to set up logical grouping and create/assign +scene for such groups. + +Using this cluster, a Node can learn about such logical grouping, provided actions, and trigger such +actions. + +While the origin of this cluster stems from use cases with a Bridge, its server side may also be +implemented on any Node which can expose certain grouping, actions or automations to other +users. + +After defining the attributes, commands and events for this cluster, and the associated data types, +several examples are provided to illustrate the capabilities of this cluster. + +Actions can be defined in a flexible manner to suit the needs of the various nodes implementing +this cluster. For each action, the commands available for that particular action are defined. + +This cluster can be used to expose only the grouping of endpoints without any actions defined by +populating the EndpointList attribute accordingly and providing an empty list for ActionList. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 605 +``` + +The term 'action' in the description of this cluster should not be confused with the term 'action' as +used in the Interaction Model. + +**9.14.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**9.14.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Node ACT +``` +**9.14.3. Cluster ID** + +``` +ID Name +0x0025 Actions +``` +**9.14.4. Data Types** + +**9.14.4.1. CommandBits Type** + +This data type is derived from map16. + +``` +Bit Name Summary +0 InstantAction Indicate support for InstantAc­ +tion command +1 InstantActionWithTransition Indicate support for InstantAc­ +tionWithTransition command +2 StartAction Indicate support for StartAction +command +3 StartActionWithDuration Indicate support for StartAc­ +tionWithDuration command +4 StopAction Indicate support for StopAction +command +5 PauseAction Indicate support for PauseAc­ +tion command +6 PauseActionWithDuration Indicate support for PauseAc­ +tionWithDuration command +``` +``` +Page 606 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary +7 ResumeAction Indicate support for ResumeAc­ +tion command +8 EnableAction Indicate support for EnableAc­ +tion command +9 EnableActionWithDuration Indicate support for EnableAc­ +tionWithDuration command +10 DisableAction Indicate support for DisableAc­ +tion command +11 DisableActionWithDuration Indicate support for DisableAc­ +tionWithDuration command +``` +Note - The bit allocation of this bitmap SHALL follow the ID’s of the Commands of this cluster. + +**9.14.4.2. ActionTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Other Use this only when +none of the other val­ +ues applies +``` +### M + +``` +1 Scene Bring the endpoints +into a certain state +``` +### M + +``` +2 Sequence A sequence of states +with a certain time pat­ +tern +``` +### M + +``` +3 Automation Control an automation +(e.g. motion sensor con­ +trolling lights) +``` +### M + +``` +4 Exception Sequence that will run +when something +doesn’t happen +``` +### M + +``` +5 Notification Use the endpoints to +send a message to user +``` +### M + +``` +6 Alarm Higher priority notifi­ +cation +``` +### M + +**Scene Value** + +Can be used to set a static state of the associated endpoints (typically using InstantAction or Instan­ +tActionWithTransition), or to bring these endpoints into a more dynamic state (typically using Star­ +tAction), where the endpoints would e.g. gradually cycle through certain colors for a pleasing effect. +A voice controller could use "set" (to map to InstantAction) or "play" (to map to StartAction) to trig­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 607 +``` + +ger such actions. +Example: see examples 1 and 2. + +**Sequence Value** + +Indicates an action which involves a sequence of events/states of the associated endpoints, such as +a wake-up experience. +Example: see example 4. + +**Automation Value** + +Indications an automation (e.g. a motion sensor controlling lights, an alarm system) which can be +e.g. started, stopped, paused, resumed. +Example: see example 3. + +**Exception Value** + +Indicates some action which the server will execute when a certain condition (which normally does +not happen) is not met. +Example: lock the doors when the server’s system has detected no one is at home while the doors +are in the 'unlocked' state. + +**Notification Value** + +Indicates an action that can be triggered (e.g. by InstantAction) to notify the user. +Example: play a pattern on the lights in the living room if there is someone in the garden in the +evening. + +**Alarm Value** + +Similar to Notification but with a higher priority (and might override other endpoint states which +Type=Notification would _not_ override). +Example: flash all lights in the house when CO sensor triggers. + +**9.14.4.3. ActionStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Inactive The action is not active M +1 Active The action is active M +2 Paused The action has been +paused +``` +### M + +``` +3 Disabled The action has been +disabled +``` +### M + +Note that some of these states are applicable only for certain actions, as determined by their Sup­ +portedCommands. + +``` +Page 608 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.14.4.4. ActionErrorEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown Other reason not listed +in the row(s) below +``` +### M + +``` +1 Interrupted The action was inter­ +rupted by another com­ +mand or interaction +``` +### M + +**9.14.4.5. EndpointListTypeEnum Type** + +This data type is derived from enum8 and has its values listed below. + +``` +Value Name Summary Conformance +0 Other Another group of end­ +points +``` +### M + +``` +1 Room User-configured group +of endpoints where an +endpoint can be in only +one room +``` +### M + +``` +2 Zone User-configured group +of endpoints where an +endpoint can be in any +number of zones +``` +### M + +The Room and Zone values are provided for the cases where a user (or the system on behalf of the +user) has created logical grouping of the endpoints (e.g. bridged devices) based on location. + +**Other Value** + +This value is provided for the case of an endpoint list which is tied specifically to this action i.e. not +independently created by the user. For Type=Other the Name MAY be empty. A Matter controller +would typically not use this for anything else than just to know which endpoints would be affected +by the action. + +**Room Value** + +Is used for the situation where an endpoint can only be part of one such rooms (e.g. physical map­ +ping). Using these exposed logical groups, a Matter controller who has a similar grouping concept +can use it to place each endpoint (bridged device) in the right room automatically, without user +having to redo that setup for each device in each system - both at first contact and upon later +updates to the endpoints (e.g. user adds a bridged device or creates a new room). + +**Zone Value** + +Is a more general concept where an endpoint can be part of multiple zones, e.g. a light in the living + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 609 +``` + +room can be part of the "reading corner" zone (subset of the lights in the living room) but also part +of the "downstairs" zone which contains all the lights on a floor, e.g. combining living room, kitchen +and hallway. This indicates that a user has defined this list of endpoints as something they logically +would like to control as a group, so Matter controllers could provide the user with a way to do as +such. + +**9.14.4.6. ActionStruct Type** + +This data type holds the details of a single action, and contains the data fields below. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ActionID uint16 all M +1 Name string max +128{32} +``` +### M + +``` +2 Type Action­ +TypeEnum +``` +``` +all M +``` +``` +3 End­ +pointLis­ +tID +``` +``` +uint16 all M +``` +``` +4 Support­ +edCom­ +mands +``` +``` +Command­ +Bits +``` +``` +0 to +0x0FFF +``` +### M + +``` +5 State ActionSta­ +teEnum +``` +``` +all M +``` +**ActionID Field** + +This field SHALL provide an unique identifier used to identify an action. + +**Name Field** + +This field SHALL indicate the name (as assigned by the user or automatically by the server) associ­ +ated with this action. This can be used for identifying the action to the user by the client. Example: +"my colorful scene". + +**Type Field** + +This field SHALL indicate the type of action. The value of Type of an action, along with its Support­ +edCommands can be used by the client in its UX or logic to determine how to present or use such +action. See ActionTypeEnum for details and examples. + +**EndPointListID Field** + +This field SHALL provide a reference to the associated endpoint list, which specifies the endpoints +on this Node which will be impacted by this ActionID. + +``` +Page 610 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**SupportedCommands Field** + +This field is a bitmap which SHALL be used to indicate which of the cluster’s commands are sup­ +ported for this particular action, with a bit set to 1 for each supported command according to the ta­ +ble below. Other bits SHALL be set to 0. + +**State Field** + +This field SHALL indicate the current state of this action. + +**9.14.4.7. EndpointListStruct Type** + +This data type holds the details of a single endpoint list, which relates to a set of endpoints that +have some logical relation, and contains the data fields below. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 End­ +pointLis­ +tID +``` +``` +uint16 all R M +``` +``` +1 Name string max +128{32} +``` +### R M + +``` +2 Type End­ +pointList­ +TypeEnum +``` +``` +all R M +``` +``` +3 Endpoints list[end­ +point-no] +``` +``` +max 256 R M +``` +**EndPointListID Field** + +This field SHALL provide an unique identifier used to identify the endpoint list. + +**Name Field** + +This field SHALL indicate the name (as assigned by the user or automatically by the server) associ­ +ated with the set of endpoints in this list. This can be used for identifying the action to the user by +the client. Example: "living room". + +**Type Field** + +This field SHALL indicate the type of endpoint list, see EndpointListTypeEnum. + +**EndPoints Field** + +This field SHALL provide a list of endpoint numbers. + +**9.14.5. Attributes** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 611 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 ActionList list[Action­ +Struct] +``` +``` +max 256 empty R V M +``` +``` +0x0001 End­ +pointLists +``` +``` +list[End­ +pointList­ +Struct] +``` +``` +max 256 empty R V M +``` +``` +0x0002 SetupURL string max 512 empty R V O +``` +**9.14.5.1. ActionList Attribute** + +The ActionList attribute holds the list of actions. Each entry SHALL have an unique ActionID, and its +EndpointListID SHALL exist in the EndpointLists attribute. + +**9.14.5.2. EndpointLists Attribute** + +The EndpointLists attribute holds the list of endpoint lists. Each entry SHALL have an unique End­ +pointListID. + +**9.14.5.3. SetupURL Attribute** + +The SetupURL attribute (when provided) SHALL indicate a URL; its syntax SHALL follow the syntax +as specified in RFC 1738, max. 512 ASCII characters and SHALL use the https scheme. The location +referenced by this URL SHALL provide additional information for the actions provided: + +- When used without suffix, it SHALL provide information about the various actions which the + cluster provides. + ◦ Example: SetupURL could take the value of example://Actions or https://domain.example/ + Matter/bridgev1/Actions for this generic case (access generic info how to use actions pro­ + vided by this cluster). +- When used with a suffix of "/?a=" and the decimal value of ActionID for one of the actions, it + MAY provide information about that particular action. This could be a deeplink to manufac­ + turer-app/website (associated somehow to the server node) with the information/edit-screen for + this action so that the user can view and update details of the action, e.g. edit the scene, or + change the wake-up experience time period. + ◦ Example of SetupURL with suffix added: example://Actions/?a=12345 or + https://domain.example/Matter/bridgev1/Actions/?a=12345 for linking to specific info/editing + of the action with ActionID 0x3039. + +**9.14.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 InstantAction client ⇒ server Y O desc +``` +``` +Page 612 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Direction Response Access Conformance +0x01 InstantAction­ +WithTransi­ +tion +``` +``` +client ⇒ server Y O desc +``` +``` +0x02 StartAction client ⇒ server Y O desc +0x03 StartAction­ +WithDuration +``` +``` +client ⇒ server Y O desc +``` +``` +0x04 StopAction client ⇒ server Y O desc +0x05 PauseAction client ⇒ server Y O desc +0x06 PauseAction­ +WithDuration +``` +``` +client ⇒ server Y O desc +``` +``` +0x07 ResumeAction client ⇒ server Y O desc +0x08 EnableAction client ⇒ server Y O desc +0x09 EnableAction­ +WithDuration +``` +``` +client ⇒ server Y O desc +``` +``` +0x0A DisableAction client ⇒ server Y O desc +0x0B DisableAction­ +WithDuration +``` +``` +client ⇒ server Y O desc +``` +Conformance: a server SHALL support a command when it is listed in the SupportedCommands +data field of one or more actions listed in the ActionList provided by the server. + +Some general requirements and data fields for all the commands: + +- The ActionID data field SHALL indicate the action identifier. If there is no entry the in ActionList + holding the same action identifier, a response SHALL be generated with the StatusCode NOT_­ + FOUND. +- The InvokeID data field MAY be provided by the client when invoking a command. When this + value is provided, the server SHALL generate a StateChanged event when the action changes to + a new state or an ActionFailed event when execution of the action fails; in the data of such + events, the value of the InvokeID data field from the invoke will be provided, so that the client + can relate the event back to the corresponding command. It is up to the client to determine + which value is provided in InvokeID. When sending multiple commands for the same action, + with different InvokeID, the server SHALL provide in the event the InvokeID value from the + most recent command for a particular ActionID. +- If the command refers to an action which currently is not in a state where the command + applies, a response SHALL be generated with the StatusCode INVALID_COMMAND. +- Actions are typically mapped to state changes of the involved endpoints. Those endpoints can + also be controlled with commands from other clusters, controlled by other nodes and impacted + by non-Matter interactions (e.g. local controls). Such other interactions can cause the state of the + endpoints to differ from the results of the command which triggered the action. A client inter­ + ested in such changes can use the InvokeID data field (see above) to receive events State­ + Changed and ActionFailed for feedback for such cases. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 613 +``` + +**9.14.6.1. InstantAction Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +``` +This command triggers an action (state change) on the involved endpoints, in a "fire and forget" +manner. Afterwards, the action’s state SHALL be Inactive. + +Example: recall a scene on a number of lights. + +**9.14.6.2. InstantActionWithTransition Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +2 Transition­ +Time +``` +``` +uint16 all MS M +``` +It is recommended that, where possible (e.g., it is not possible for attributes with Boolean data type), +a gradual transition SHOULD take place from the old to the new state over this time period. How­ +ever, the exact transition is manufacturer dependent. + +This command triggers an action (state change) on the involved endpoints, with a specified time to +transition from the current state to the new state. During the transition, the action’s state SHALL be +Active. Afterwards, the action’s state SHALL be Inactive. + +Example: recall a scene on a number of lights, with a specified transition time. + +**TransitionTime Field** + +This field SHALL indicate the transition time in 1/10th of seconds. + +**9.14.6.3. StartAction Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +``` +``` +Page 614 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +This command triggers the commencement of an action on the involved endpoints. Afterwards, the +action’s state SHALL be Active. + +Example: start a dynamic lighting pattern (such as gradually rotating the colors around the set­ +points of the scene) on a set of lights. + +Example: start a sequence of events such as a wake-up experience involving lights moving through +several brightness/color combinations and the window covering gradually opening. + +**9.14.6.4. StartActionWithDuration Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +2 Duration uint32 all MS M +``` +This command triggers the commencement of an action on the involved endpoints, and SHALL +change the action’s state to Active. After the specified Duration, the action will stop, and the action’s +state SHALL change to Inactive. + +Example: start a dynamic lighting pattern (such as gradually rotating the colors around the set­ +points of the scene) on a set of lights for 1 hour (Duration=3600). + +**Duration Field** + +This field SHALL indicate the requested duration in seconds. + +**9.14.6.5. StopAction Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +``` +This command stops the ongoing action on the involved endpoints. Afterwards, the action’s state +SHALL be Inactive. + +Example: stop a dynamic lighting pattern which was previously started with StartAction. + +**9.14.6.6. PauseAction Command** + +This command SHALL have the following data fields: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 615 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +``` +This command pauses an ongoing action, and SHALL change the action’s state to Paused. + +Example: pause a dynamic lighting effect (the lights stay at their current color) which was previ­ +ously started with StartAction. + +**9.14.6.7. PauseActionWithDuration Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +2 Duration uint32 all MS M +``` +This command pauses an ongoing action, and SHALL change the action’s state to Paused. After the +specified Duration, the ongoing action will be automatically resumed. which SHALL change the +action’s state to Active. + +Example: pause a dynamic lighting effect (the lights stay at their current color) for 10 minutes +(Duration=600). + +The difference between Pause/Resume and Disable/Enable is on the one hand semantic (the former +is more of a transitionary nature while the latter is more permanent) and on the other hand these +can be implemented slightly differently in the implementation of the action (e.g. a Pause would be +automatically resumed after some hours or during a nightly reset, while an Disable would remain +in effect until explicitly enabled again). + +**Duration Field** + +This field SHALL indicate the requested duration in seconds. + +**9.14.6.8. ResumeAction Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +``` +This command resumes a previously paused action, and SHALL change the action’s state to Active. + +``` +Page 616 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The difference between ResumeAction and StartAction is that ResumeAction will continue the +action from the state where it was paused, while StartAction will start the action from the begin­ +ning. + +Example: resume a dynamic lighting effect (the lights' colors will change gradually, continuing from +the point they were paused). + +**9.14.6.9. EnableAction Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +``` +This command enables a certain action or automation. Afterwards, the action’s state SHALL be +Active. + +Example: enable a motion sensor to control the lights in an area. + +**9.14.6.10. EnableActionWithDuration Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +2 Duration uint32 all MS M +``` +This command enables a certain action or automation, and SHALL change the action’s state to be +Active. After the specified Duration, the action or automation will stop, and the action’s state SHALL +change to Disabled. + +Example: enable a "presence mimicking" behavior for the lights in your home during a vacation; +the Duration field is used to indicated the length of your absence from home. After that period, the +presence mimicking behavior will no longer control these lights. + +**Duration Field** + +This field SHALL indicate the requested duration in seconds. + +**9.14.6.11. DisableAction Command** + +This command SHALL have the following data fields: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 617 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +``` +This command disables a certain action or automation, and SHALL change the action’s state to Inac­ +tive. + +Example: disable a motion sensor to no longer control the lights in an area. + +**9.14.6.12. DisableActionWithDuration Command** + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 all M +1 InvokeID uint32 all O +2 Duration uint32 all MS M +``` +This command disables a certain action or automation, and SHALL change the action’s state to Dis­ +abled. After the specified Duration, the action or automation will re-start, and the action’s state +SHALL change to either Inactive or Active, depending on the actions (see examples 4 and 6). + +Example: disable a "wakeup" experience for a period of 1 week when going on holiday (to prevent +them from turning on in the morning while you’re not at home). After this period, the wakeup +experience will control the lights as before. + +**Duration Field** + +This field SHALL indicate the requested duration in seconds. + +**9.14.7. Events** + +This cluster SHALL support these events: + +``` +ID Name Priority Access Conformance +0x00 StateChanged INFO V M +0x01 ActionFailed INFO V M +``` +**9.14.7.1. StateChanged Event** + +This event SHALL be generated when there is a change in the State of an ActionID during the execu­ +tion of an action _and_ the most recent command using that ActionID used an InvokeID data field. + +It provides feedback to the client about the progress of the action. + +``` +Page 618 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Example_ : When InstantActionWithTransition is invoked (with an InvokeID data field), two State­ +Changed events will be generated: + +- one when the transition starts (NewState=Active) +- one when the transition completed (NewState=Inactive) + +This event SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 M +1 InvokeID uint32 M +2 NewState ActionSta­ +teEnum +``` +### M + +**ActionID Field** + +This field SHALL be set to the ActionID of the action which has changed state. + +**InvokeID Field** + +This field SHALL be set to the InvokeID which was provided to the most recent command referenc­ +ing this ActionID. + +**NewState Field** + +This field SHALL be set to state that the action has changed to. + +**9.14.7.2. ActionFailed Event** + +This event SHALL be generated when there is some error which prevents the action from its nor­ +mal planned execution _and_ the most recent command using that ActionID used an InvokeID data +field. + +It provides feedback to the client about the non-successful progress of the action. + +_Example_ : When InstantActionWithTransition is invoked (with an InvokeID data field), and another +controller changes the state of one or more of the involved endpoints during the transition, thus +interrupting the transition triggered by the action, two events would be generated: + +- StateChanged when the transition starts (NewState=Active) +- ActionFailed when the interrupting command occurs (NewState=Inactive, Error=interrupted) + +_Example_ : When InstantActionWithTransition is invoked (with an InvokeID data field = 1), and the +same client invokes an InstantAction with (the same or another ActionId and) InvokeID = 2, and this +second command interrupts the transition triggered by the first command, these events would be +generated: + +- StateChanged (InvokeID=1, NewState=Active) when the transition starts + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 619 +``` + +- ActionFailed (InvokeID=2, NewState=Inactive, Error=interrupted) when the second command + interrupts the transition +- StateChanged (InvokeID=2, NewState=Inactive) upon the execution of the action for the second + command + +This event SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ActionID uint16 M +1 InvokeID uint32 M +2 NewState ActionSta­ +teEnum +``` +### M + +``` +3 Error Action­ +ErrorEnum +``` +### M + +**ActionID Field** + +This field SHALL be set to the ActionID of the action which encountered an error. + +**InvokeID Field** + +This field SHALL be set to the InvokeID which was provided to the most recent command referenc­ +ing this ActionID. + +**NewState Field** + +This field SHALL be set to state that the action is in at the time of generating the event. + +**Error Field** + +This field SHALL be set to indicate the reason for non-successful progress of the action. + +**9.14.8. Examples** + +This section provides some examples how the attributes and commands in this cluster can be used +in practical situations. Details of the behavior typically depend on the details of the logic built into +the server. + +**9.14.8.1. Example 1: Scene recall** + +User has defined a scene on a number of lights. The corresponding action would have these data +fields describing it: + +- Name="sunset" +- Type=Scene +- EndpointListID references a struct referencing the set of involved endpoints + +``` +Page 620 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +◦ Name="living room" +◦ Type=Room +◦ Endpoints=list of the endpoints of the lights in this room +``` +- SupportedCommands: InstantAction, InstantActionWithTransition + +The InstantAction command (e.g. triggered by a voice command "set sunset in living room") will +trigger the server to activate that scene on those lights. + +When a slow fade-in is preferred, the InstantActionWithTransition can be used, with a Transition­ +Time parameter of e.g. 50 (denoting 5 s). + +_Figure 55. State diagram for example 'scene recall'_ + +**9.14.8.2. Example 2: Set dynamic light effect** + +User has defined a scene on a number of lights. The corresponding action would have these data +fields describing it: + +- Name="sunset" +- Type=Scene +- EndpointListID references a struct referencing the set of involved endpoints (same as in Exam­ + ple 1) +- SupportedCommands: StartAction, StartActionWithDuration, StopAction + +The StartActionWithDuration command (e.g. triggered by a voice command "play sunset in living +room for 1 hour") will trigger the server to activate a dynamic pattern with colors inspired by sun­ +set on the associated lights. At any time, the StopAction can be used to stop the effect. + +Please note that the most of the data fields in the ActionStruct for this example are identical to +those in example 1 - except for the SupportedCommands. The different sets of supported commands +indicate whether it is an instant scene recall (example 1) vs. a long-term dynamic effort (example +2). A server could expose this action also as a single action with the combined set of supported com­ +mands. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 621 +``` + +_Figure 56. State diagram for example 'dynamic light effect'_ + +**9.14.8.3. Example 3: Pause sensor automation** + +User has defined an automation: a motion sensor controls the lights in a certain room. Sometimes, +they want to override that automatic behavior, e.g. when having a party. + +The action for this example would refer to such automation, which is typically active, but can be +paused (=temporarily disabled). + +The corresponding action would have these data fields describing it: + +- Name="motion sensor" +- Type=Automation +- EndpointListID references a struct referencing the set of involved endpoints (same as in Exam­ + ple 1) +- SupportedCommands: EnableAction, DisableAction, PauseAction, PauseActionWithDuration, + ResumeAction + +Typically, the action has been started when the user defines the motion sensor behavior, so without +a Matter command the action’s state would be 'Active'. The PauseActionWithDuration command +(e.g. triggered by a voice command "disable the motion sensor in living room for 2 hours") will trig­ +ger the server to disable the behavior associated with the motion sensor for the specified time. A +ResumeAction command would make this behavior active again. The automation could also have +internal logic to abort the disabling after several hours or during the night-time reset, to accommo­ +date for the case the user 'paused' and forgot to 'resume'. + +``` +Page 622 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 57. State diagram for example 'pause sensor automation'_ + +**9.14.8.4. Example 4: Wake-up routine** + +User has defined a wake-up routine: the lights in the bedroom will gradually become brighter and +change in color temperature to simulate a sunrise. The sequence lasts for e.g. 30 minutes. Near the +end of the sequence, the window coverings would be (partially) opened as well. + +The corresponding action would have these data fields describing it: + +- Name="wakeup" +- Type=Sequence +- EndpointListID references a struct referencing the set of involved endpoints (lights and window + coverings in the bedroom) +- SupportedCommands: EnableAction, DisableAction, DisableActionWithDuration, PauseAction, + PauseActionWithDuration + +When the user wants to snooze some more, he can use a voice command to trigger the PauseAction +command (which could automatically timeout after e.g. 10 minutes). The StopAction command +could similarly be used to cancel the remainder of the whole sequence. The DisableActionWithDu­ +ration (with parameter 172,800 =2*24*60*60 s) can be used on Friday evening to disable the +sequence for the weekend. + +When such action has been defined, a Matter node which is aware of the user’s calendar for the +day, can use the StartAction command to trigger this sequence of events. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 623 +``` + +_Figure 58. State diagram for example 'wake-up experience'_ + +**9.14.8.5. Example 5: Scheduled scene recall** + +User has setup a scene to be recalled at a certain time of day (e.g. colorful garden lighting to switch +on around sunset) and switching off those lights (e.g. at midnight). The server’s automation system +takes care of this. On certain occasions (e.g. garden party), the user wants to override this behavior +(i.e. the scene should not be recalled at sunset because another scene has been set for the party). + +The corresponding action would have these data fields describing it: + +- Name="colorful evening garden" +- Type=Automation +- EndpointListID references a struct referencing the set of involved endpoints (lights in the gar­ + den) +- SupportedCommands: EnableAction, DisableAction, DisableActionWithDuration + +After installation, this action is in Inactive state. At the scheduled "on" time, the colorful garden +lighting scene is activated and the action’s state changes to the Active state. At the scheduled "off " +time, the lights are switched off, and the action’s state changes to the Inactive state. Using the Dis­ +ableAction, the user can prevent these automated steps to occur - the action’s state changes to the +Disabled state. Using the DisableActionWithDuration, the user can do similarly, but also indicate an +automatic re-enabling after the specified time period. Using the EnableAction, the user can re- +enable the automation. + +``` +Page 624 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 59. State diagram for example 'scheduled scene recall'_ + +**9.14.8.6. Example 6: Alarm system** + +User has an alarm system which exposes this cluster, with an action that allows to arm/disarm the +system by voice commands from a Matter node which is a client to this cluster. + +The corresponding action would have these data fields describing it: + +- Name="alarm system" +- Type=Automation +- EndpointListID references a struct referencing the set of involved endpoints (elements of the + alarm system) +- SupportedCommands: EnableAction, DisableAction, DisableActionWithDuration + +After installation, this action could be in Inactive state (assume user is at home installing so system +is not armed). Using the EnableAction, the alarm system would be armed. Using the DisableAction, +the alarm system would be disarmed (or disarmed for a period with DisableWithDuration). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 625 +``` + +_Figure 60. State diagram for example 'alarm system'_ + +**9.15. Proxy Architecture** + +``` +NOTE Proxy Architecture, Proxy clusters, and Proxy support, are provisional. +``` +**9.15.1. Motivation** + +Constrained devices might not support more than a handful of subscriptions. This is usually attrib­ +utable to a limited memory or battery. However, there might be a large number of clients who +desire to subscribe to that device. + +**9.15.2. Subscription Proxy: Overview** + +A subscription proxy is a type of Node that is capable of multiplexing subscriptions from multiple +subscribers onto a single subscription to a given publisher. + +The term 'proxy' is a convenient shorthand that refers to this type of Node. + +The term 'source' SHALL refer to a node that serves as the original source of truth for a set of data. +The source acts as a publisher of that data. + +The term 'client' SHALL refer to a node that wants to subscribe to some source. + +A proxy subscribing to a source SHALL surface an identical 'mirror' of the source’s data to down­ +stream clients without the clients having to alter their interaction regardless of whether they are +interacting with a proxy or the source itself. + +The proxy SHALL be identified by the Subscription Proxy Device Type. + +``` +Page 626 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 61. Digital twin acting as a proxy re-publishing clusters_ + +This multiplexing of subscriptions allows the source to delegate all subscriptions to its proxy, only +needing to support a single subscription from that proxy. This reduces the demands placed on +energy and memory resources. Consequently, that single subscription will encompass the union of +all client interest sets. If the combined set of attribute/event paths becomes fairly large, proxies can +leverage the use of wildcards to merge multiple localized paths into a single, broader path with +wildcards. + +_Figure 62. Proxy multiplexing interest sets from 3 distinct clients_ + +A proxy SHALL only proxy subscribe interactions. It SHALL NOT proxy any other type of interac­ +tion. + +**9.15.3. Composition & Paths** + +A client subscribing to a proxy SHALL specify the Node ID of the source it wishes to subscribe to in +the Path. This SHALL be different from the logical destination Node ID of the message, which + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 627 +``` + +SHALL be the Node ID of the proxy. + +_Figure 63. Sample paths when subscribing to a proxy vs the source_ + +**9.15.4. Proxy Subscriptions** + +**9.15.4.1. Overview** + +A proxy only attempts to subscribe to a source when there is a current, valid subscription from a +client to the proxy for that source’s data. + +The term 'upstream subscription' refers to the subscription from the proxy either directly to the +source, or indirectly to another proxy for that source’s data. + +The term 'downstream subscription' refers to the subscription from either a client or another proxy +to the proxy in question. + +Consequently, when that 'downstream' subscription disappears, the 'upstream' subscription will +either be torn down (if there are no other clients interested in that source) or be amended. + +This does not require a priori knowledge of a client’s interest set. + +**9.15.4.2. Upstream/Downstream Subscription Mechanics** + +Upstream and downstream subscriptions have the following properties: + +- Both subscriptions are independent, but weakly linked. + ◦ Data is received on the client side, stored on the server side, and used to generate a different + set of reports to downstream client(s). +- It is data that is being proxied, not the actual subscription messages themselves. +- The termination of a downstream subscription will automatically result in an amendment of + the upstream subscription to remove the relevant paths that were in the downstream, with a + +``` +Page 628 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +complete termination of the upstream subscription if there was only 1 downstream subscriber +present. +``` +- The disappearance of an upstream subscription will not automatically cancel the downstream + subscription. + ◦ Upstream subscriptions MAY disappear due to network connectivity issues. If an upstream + sync report is not received, the proxy SHALL attempt once to re-subscribe to the upstream + source; if that re-subscription attempt fails, the proxy SHALL terminate any associated + downstream subscriptions. + ◦ If an upstream subscription is positively terminated by the source as a whole, that will + result in a similar termination of the downstream subscription. +- In addition to forwarding status codes embedded in the ReportData from the source, the proxy + will convey a special 'NO_UPSTREAM_SUBSCRIPTION' IM status code to the downstream client if + it has not established a subscription to the source. + +The diagram below gives a sample sequence show-casing the two subscriptions: + +_Figure 64. Upstream/Downstream subscription sequences_ + +**9.15.4.3. Sync/Liveness** + +Since subscriptions provide a 'sync' message to infer health of the subscription on both sides, it +allows a client to monitor the health of its source peer. + +Conveyance of this is preserved in downstream subscription through the 'NO_UPSTREAM_SUB­ +SCRIPTION' status code. This conveys effectively the same information as the sync message would +had the client directly subscribed to the source. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 629 +``` + +**9.15.4.4. Upstream Subscription Parameter Derivation** + +Since the proxy multiplexes all downstream subscriptions onto a single upstream subscription, it +has to have logic to harmonize the various parameters from each client subscription. + +The following logic table describes what the proxy SHOULD do: + +``` +Parameter Suggested Logic +Attribute/EventPaths UNION of all paths. Proxy MAY use wildcards if +needed to simplify this logic. +DataVersionList MIN +EventNumberList MIN +MinimumSyncInterval MIN +MaximumSyncInterval MAX +MinimumReportingIntervalList MIN +ReportableChangeList MIN +``` +Since each client’s interest is different from the final multiplexed subscription, the proxy has to +appropriately filter the data being received from the source before sending it to a given client. + +**9.15.5. Schemas and Data Serialization/Deserialization** + +Unlike clients that need to semantically interpret data in addition to deserializing/serializing +to/from its internal data stores, a proxy only needs to do the latter. + +As a result, proxies MAY achieve proxy functionality with a single firmware image built to handle +any client, any cluster, any type of device. + +**9.15.6. Indirect Proxies** + +A proxy MAY subscribe to another proxy instead of subscribing directly to the source. This creates +proxy chains that allow a single source to be proxied by multiple proxies, allowing better use of +available proxy capacity. + +**9.15.7. Proxy Discovery & Assignment Flow** + +The following flow describes the process by which a client: + +- Discovers that a source needs a proxy +- Finds an appropriate proxy on the network that is able to handle its request +- Sets up the proxy to subscribe to the source + +**9.15.7.1. Step 0: Proxy Setup** + +A device indicates its ability to act as a certified proxy through stating support for the Subscription +Proxy device type. + +``` +Page 630 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +When such a device is commissioned, the commissioner SHALL recognize this ability and MAY +write the NodeIds of all the sources that need proxying into the Proxy Configuration Cluster on the +proxy device. Alternatively, it MAY configure the proxy to wildcard proxy all devices, removing the +need to specify a particular set of NodeIds. + +Additionally, the commissioner MAY write the Node ID of the newly added proxy to the Valid Prox­ +ies Cluster on source devices that needs proxying. This cluster stores the static list of candidate +proxies for a given device. Only devices that support the cluster would need to have this configura­ +tion written. + +**9.15.7.2. Step 1: Rejection** + +There unfortunately isn’t any a priori heuristic that MAY be applied to deduce if a source needs +proxying. This is usually a function of the number of clients subscribed to a source, the number of +paths in those subscriptions, as well as the sync intervals. + +When a source cannot handle any more incremental subscriptions, that is when proxying is +needed. This is discovered when a client tries to subscribe to the source and is sent back a StatusRe­ +sponse containing a RESOURCE_EXHAUSTED IM status code, indicating the source’s inability to handle +further subscriptions: + +_Figure 65. Rejection_ + +In the diagram above, the constraints of the source have been simplified down to having 3 available +subscription slots that get filled up. + +Upon receipt of the RESOURCE_EXHAUSTED error, the client SHALL invoke the Get Valid Proxies Request +command on the source Node. In response, it SHALL receive a Get Valid Proxies Response message +containing the NodeIds of valid, candidate proxies. + +**9.15.7.3. Step 2: Proxy Discovery** + +After the client has received the list of possible valid proxies, the client MAY attempt to discover a +valid proxy that is able to proxy its request. + +To do so, the client sends out a Proxy Discover Request Command as a groupcast message to the All + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 631 +``` + +Proxies universal group. Before it transmits this message, the client SHALL momentarily subscribe +to the IPv6 address that maps to the All Proxies universal group to appropriately receive all +responses. + +_Figure 66. Discovery Request_ + +**9.15.7.4. Step 3: Proxy Response** + +Proxies respond to the request with a Proxy Discover Response Command sent as a groupcast message +to the All Proxies universal group. A proxy SHALL only send this message when it can handle the +subscription request, regardless of whether it is currently subscribed to the source. The response +will contain metadata about its ability to handle the subscription. + +The Proxy Discover Response Command SHALL be sent as a completely separate, un-related transac­ +tion to the original request. The client SHALL correlate the two using the SourceNodeId present in +both messages. + +Proxies SHALL stagger their responses by waiting for a random interval between 0 and _PROXY_S­ +CAN_RESPONSE_JITTER_ before sending the Proxy Discover Response Command to prevent overwhelm­ +ing the network or the client, which can be constrained and can have limited buffers. + +``` +Page 632 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 67. Proxies send back responses_ + +**9.15.7.5. Step 4: Proxy Selection** + +Client SHALL wait for _PROXY_SCAN_PERIOD_ to aggregate all responses and SHALL filter the set of +responses received. Specifically, the client SHALL discard: + +- Responses containing a Source Node ID for other unintended sources +- Responses containing a Source Node ID in the message that does not match any in the Valid­ + ProxyList. + +It SHALL then select a proxy from this filtered set based on implementation-chosen policies. One +suggested approach would involve selecting the proxy with the least number of hops to the source, +followed by largest available capacity. + +Clients MAY unsubscribe from the IPv6 multicast group that maps to the All Proxies universal +group after aggregating the responses. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 633 +``` + +_Figure 68. Selecting a Proxy_ + +**9.15.7.6. Step 5: Proxy Subscription** + +The client then subscribes to the proxy it has selected. + +The proxy will do one of two things: + +**Option 1:** If there isn’t another proxy already subscribed to the source, the proxy subscribes to the +source directly: + +``` +Page 634 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 69. Primary proxy subscription_ + +**Option 2:** If there is already another proxy subscribed to that source, the selected proxy subscribes +to that proxy instead. + +_Figure 70. Primary proxy subscription_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 635 +``` + +It doesn’t attempt to subscribe directly to the source since it does not know if the source has any +free slots available to support the subscription, risking a potential subscription failure if it did so. + +Proxies MAY select between the two options by 'sniffing' the `Proxy Discover Response Command mes­ +sages that were emitted by other proxies. This allows the candidate proxy to determine whether +there is another proxy already subscribed to the source. + +A proxy SHALL have only one subscription to a given source regardless of the number of subscrip­ +tion requests from clients for that source. This is necessary to ensure timely ACL enforcement in the +case where a client no longer has access to the source, and subsequent state changes will not be +made available to that client (see ACL Enforcement for more details). + +**9.15.7.7. Step 6: Eviction** + +At this point, the source might not be able to handle another subscription. If so, it SHALL evict non- +proxy subscriptions to make space for the proxy subscription. This is acceptable since those clients +that got evicted MAY eventually subscribe to a proxy as well. + +To make this possible, proxies have to express the type of subscription (proxy or not proxy) in the +SubscribeRequest itself. + +_Figure 71. C3 gets evicted_ + +**9.15.7.8. Step 7: Re-Assignment** + +The evicted clients undergo the same proxy discovery/selection process, and eventually settle on a +set of proxies. + +``` +Page 636 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 72. C3 gets reassigned to P1_ + +**9.15.7.9. Notable Characteristics** + +This algorithm has the following notable characteristics: + +- The system 'auto-balances' based on the needs of clients and the capabilities of the source +- No persistent state or a priori configuration is needed on any node +- No a priori heuristics are needed to figure out if a node _should_ be proxied. +- Robust to proxy failure by leveraging the liveness construct of subscriptions to accelerate dis­ + covery +- No centralized proxy management/assignment service is needed. + ◦ There is no single point of failure. No need for an election, state backup, or fail-over. +- Low complexity on server (which are usually the more constrained device), slightly more on the + client + +**9.15.8. Constraints** + +**9.15.8.1. Eviction Rules** + +A source SHALL NOT evict an existing proxy already subscribed to it to make way for a new sub­ +scription regardless of whether that new subscription emanates from a proxy or not. This prevents +instability in the system since it might result in ping-ponging proxies subscribing to that source. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 637 +``` + +**9.15.8.2. Number of Direct Proxies** + +There SHOULD only be one proxy node directly subscribed to a source in a single-fabric setting. +This is not enforced by the source but rather, by proxies themselves. + +**9.15.8.3. Multi-Fabric** + +In a multi-fabric setting, a source node MAY be subscribed to by clients commissioned into different +fabrics. It is highly desirable that a single proxy interacting with a source support clients from mul­ +tiple fabrics. To make this possible, a proxy SHOULD when possible, be commissioned into all fab­ +rics that contain sources that need proxying. + +If a proxy is not commissioned into all fabrics, it might not see another proxy’s Proxy Discover +Response Command messages, nor will it be capable of directly subscribing to that proxy even if it did, +since it doesn’t have credentials to do so. This MAY result in multiple proxies attempting to sub­ +scribe directly to the source, resulting in potential rejection by the source and consequently, an +inability for a client’s subscription to be served indirectly through that chosen proxy. This might be +unpredictable depending on which proxy was able to subscribe first to that source. + +**9.15.9. Certification** + +To ensure a consistent expectation of behavior from a proxy device, the proxy SHOULD be certified +by the Connectivity Standards Alliance against the expectations of a proxy. Once certified, it MAY +claim compatibility against the Subscription Proxy device type. + +**9.15.10. Security & Privacy** + +**9.15.10.1. Authentication** + +To prevent malicious or unattested devices from acting as proxies to clients, the Valid Proxies Clus­ +ter provides a scheme for admins to specify the NodeIds of valid, attested proxies to the source +itself, which is in turn conveyed to clients. This allows for filtering of the ensuing Proxy Discover +Response Command messages to only select valid, trusted proxies. + +**9.15.10.2. Multicast Messages** + +The proxy discovery commands SHALL be encrypted with a fabric-provided group key. An Admin­ +istrator that wishes to enable proxy functionality on a set of clients SHALL bind the All Proxies +group to a specific group key in the Group Key Management cluster. + +Consequently, a Proxy Discover Request Command message SHALL be sent for every All Proxies +GroupID instance specified in the Group Keys Management cluster. + +**9.15.10.3. ACL Enforcement** + +Administrators SHOULD configure source nodes to grant the 'Proxy View' privilege to proxy clients. +If this privilege is not granted for at least the Access Control cluster, the proxy will not function. +This privilege SHOULD be granted for the entire source node for a proxy to be most effective, since +neither the proxy nor the Administrator can predict which source clusters may be subscribed by +other clients. + +``` +Page 638 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The proxy SHALL subscribe to the Access Control Cluster on the source and SHALL enforce the +source’s ACLs _on behalf of_ the source when serving its downstream client subscriptions. + +The proxy MAY enforce the source’s ACLs eagerly (i.e. at first ACL change), lazily (i.e. at next data +report), or by some combination of these approaches. The key guarantee is that the proxy SHALL +apply the latest source ACLs from its upstream subscription at the time it generates associated +downstream subscription reports. + +The proxy SHALL enforce the source’s ACLs on a path by path basis, in a similar manner to how the +Access Control Privilege Granting algorithm enforces access. Downstream subscription paths that +are not granted access by the proxy SHALL cause the proxy to generate an UNSUPPORTED_ACCESS error +for that subscription path. + +If all report data paths in a downstream subscription result in UNSUPPORTED_ACCESS error, the proxy +SHALL tear down that downstream subscription. + +If the proxy is not able to view the source’s Access Control Cluster due to insufficient privileges, it +SHALL NOT generate any downstream subscription data reports for that source. Instead, the proxy +SHALL generate a report containing UNSUPPORTED_ACCESS errors for each path in the downstream +subscription and tear down the downstream subscription. + +**9.15.11. Parameters and Constants** + +Table 86, “Glossary of constants” is a glossary of constants used in this section, along with a brief +description and example default for each constant. + +_Table 86. Glossary of constants_ + +``` +Constant Name Description Default Value +PROXY_SCAN_RESPONSE_JITTER The maximum amount of time to ran­ +domly wait before sending a Proxy Dis­ +cover Response Command message. +``` +``` +1000 millisec­ +onds +``` +``` +PROXY_SCAN_PERIOD The maximum amount of time initiator of +proxy discovery will wait to collect Proxy +Discover Response Command messages after +sending a Proxy Discover Request Command +message. +``` +``` +1100 millisec­ +onds +``` +**9.15.12. Proxy Discovery Cluster** + +This cluster contains commands needed to do proxy discovery as defined in the Section 9.15.7.3, +“Step 2: Proxy Discovery” and Section 9.15.7.4, “Step 3: Proxy Response” steps of the overall Section +9.15.7, “Proxy Discovery & Assignment Flow”. + +**9.15.12.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 639 +``` + +``` +Revision Description +1 Initial revision +``` +**9.15.12.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node PXDSC +``` +**9.15.12.3. Cluster ID** + +``` +ID Name Conformance +0x0043 ProxyDiscovery P +``` +**9.15.12.4. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 ProxyDiscov­ +erRequest +``` +``` +client ⇒ server N O M +``` +``` +0x01 ProxyDiscov­ +erResponse +``` +``` +client ⇐ server N M +``` +**9.15.12.4.1. ProxyDiscoverRequest Command** + +This command is used during proxy discovery, as specified in Section 9.15.7, “Proxy Discovery & +Assignment Flow”. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SourceNode +Id +``` +``` +node-id all M +``` +``` +1 NumAttrib­ +utePaths +``` +``` +uint16 desc M +``` +``` +2 NumEvent­ +Paths +``` +``` +uint16 desc M +``` +**SourceNodeId Field** + +This is the Node ID of the source for which a client seeks to find a Proxy. + +**NumAttributePaths Field** + +The number of attribute paths the client will have in the subscription request. This is a heuris­ +tic/hint to allow a Proxy to better ascertain whether it can support the ensuing subscription. + +``` +Page 640 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**NumEventPaths Field** + +The number of event paths the client will have in the subscription request. This is a heuristic/hint to +allow a Proxy to better ascertain whether it can support the ensuing subscription. + +**9.15.12.4.2. ProxyDiscoverResponse Command** + +This command is used during proxy discovery, as specified in Section 9.15.7, “Proxy Discovery & +Assignment Flow”. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SourceNode +Id +``` +``` +node-id all M +``` +``` +1 NumHop­ +sToSource +``` +``` +uint16 desc M +``` +``` +2 Available­ +Capacity +``` +``` +uint16 desc M +``` +**SourceNodeId Field** + +This is the Node ID of the source the proxy can proxy for. This SHALL match the node id in the cor­ +responding Proxy Discover Request Command message. + +**NumHopsToSource Field** + +If the proxy currently subscribes to the source (either directly or indirectly), this indicates the num­ +ber of hops to the source. Sensible values start at 1, with 1 being used for a proxy that subscribes +directly to the source. If the proxy is not subscribed directly to the source, this value SHALL be one +greater than the NumHopsToSource for the given Node ID of the proxy it is subscribed to. + +0 indicates that the proxy currently does not have a subscription to the source. + +**AvailableCapacity Field** + +A number indicating the number of Cluster Attribute Paths the proxy has space for support. This +allows for an absolute comparison of different memory capacities of candidate proxies by the client +in selecting the best possible candidate. + +**9.15.13. Proxy Configuration Cluster** + +This cluster provides a means for a proxy-capable device to be told the set of Nodes it SHALL proxy. + +**9.15.13.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 641 +``` + +``` +Revision Description +1 Initial revision +``` +**9.15.13.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node PXCFG +``` +**9.15.13.3. Cluster ID** + +``` +ID Name Conformance +0x0042 ProxyConfiguration P +``` +**9.15.13.4. Data Types** + +**9.15.13.4.1. ConfigurationStruct Type** + +``` +Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 Prox­ +yAllNodes +``` +``` +bool desc false RW M +``` +``` +2 SourceList list[node- +id] +``` +``` +desc empty RW M +``` +**ProxyAllNodes Field** + +This field SHALL be set to true to indicate to the proxy that it SHALL proxy all nodes. When true, +the SourceList attribute is ignored. + +**SourceList Field** + +When ProxyAllNodes is false, this list contains the set of Node IDs of sources that this proxy SHALL +specifically proxy. + +**9.15.13.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Configura­ +tionList +``` +``` +list[Config­ +ura­ +tionStruct] +``` +``` +all N empty R W M +``` +**9.15.13.5.1. ConfigurationList Attribute** + +List of proxy configurations. There SHALL NOT be multiple entries in this list for the same fabric. + +``` +Page 642 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.15.14. Valid Proxies Cluster** + +This cluster provides a means for a device to be told of the valid set of _possible_ proxies that can +proxy subscriptions on its behalf as per Section 9.15.7, “Proxy Discovery & Assignment Flow”. + +**9.15.14.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**9.15.14.2. Classification** + +``` +Hierarchy Role Context PICS Code +Base Utility Node PXVALID +``` +**9.15.14.3. Cluster ID** + +``` +ID Name Conformance +0x0044 ValidProxies P +``` +**9.15.14.4. Data Types** + +**9.15.14.4.1. ValidProxyStruct Type** + +Encapsulates the Node ID of a Valid Proxy. + +``` +Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 NodeID node-id all R W M +``` +**9.15.14.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 ValidProx­ +yList +``` +``` +list[Valid­ +ProxyS­ +truct] +``` +``` +N/A N F empty R W M +``` +**9.15.14.5.1. ValidProxyList Attribute** + +List of valid proxies that can proxy this Node. Each entry in this list is fabric-scoped. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 643 +``` + +**9.15.14.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 GetValidProx­ +iesRequest +``` +``` +client ⇒ server GetValidProx­ +iesResponse +``` +### O M + +``` +0x01 GetValidProx­ +iesResponse +``` +``` +client ⇐ server N M +``` +**9.15.14.6.1. GetValidProxiesRequest Command** + +This command is used during proxy discovery, as specified in Section 9.15.7, “Proxy Discovery & +Assignment Flow”. + +**9.15.14.6.2. GetValidProxiesResponse Command** + +This command is used during proxy discovery, as specified in Section 9.15.7, “Proxy Discovery & +Assignment Flow”. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ProxyN­ +odeIdList +``` +``` +list[node-id] M +``` +**ProxyNodeList Field** + +This contains the list of node ids stored in the ValidProxyList whose associated fabric matches the +accessing fabric. + +**9.16. Intermittently Connected Devices Behavior** + +**9.16.1. ICD Server Behavior** + +**9.16.1.1. Operational States** + +**9.16.1.1.1. Idle Mode** + +**Idle Mode** defines the operational state of an ICD where the node is unreachable due to it not being +able to receive messages for a certain period of time. The ICD will remain in Idle Mode for a maxi­ +mum of one Idle Mode Duration as defined in the ICD Management cluster. + +**Slow Polling** + +When in **Idle Mode** , the ICD SHALL configure its network interface in _Slow Polling_. _Slow Polling_ +defines the fastest frequency at which the device will typically receive messages in Idle Mode. The +_Slow Polling_ interval MAY be the same as the Idle Mode Duration. + +``` +Page 644 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.16.1.1.2. Active Mode** + +**Active Mode** defines the operational state of an ICD where it is reachable on the network and will +answer in a timely manner. The minimum amount of time a device will typically remain in Active +Mode is Active Mode Duration as defined in the ICD Management cluster. + +**Fast Polling** + +When in **Active Mode** , the ICD SHALL configure its network interface in _Fast Polling_. _Fast Polling_ +defines the fastest frequency at which the device can receive messages in Active Mode. + +**9.16.1.1.3. Operational State Switch** + +Some of the reasons why an ICD can switch Operational states from Idle Mode to Active Mode are: + +- The ICD has remained in Idle Mode for a full Idle Mode Duration. +- An attribute change needs to be reported to a subscriber. +- When the maximum reporting interval has been reached for an active subscription. +- A generated event needs to be reported to a subscriber. + +When an ICD switches from Idle Mode to Active Mode, it MAY send all pending messages. These +messages could be: + +- Sending subscription reports and events. +- Sending Check-In messages. +- Sending Interaction Messages. + +A node typically determines whether it is in Active or Idle mode based on whether it has any out­ +standing Exchanges in the Message Layer. While there are Exchanges active, a node typically will +remain in Active mode. Once all Exchanges are closed and the node has no other outstanding rea­ +sons for staying active, a node SHOULD transition into Idle mode. An ICD node MAY use additional +modes and logic for switching between them. + +**9.16.1.2. ICD Session Configurations** + +Due to the ICD operating modes, there may be an additional delay before the ICD receives a mes­ +sage. This causes the travel time of a message to be affected by the ICD’s configuration and current +operating mode. + +When in Idle Mode, the device will typically not receive messages at a faster frequency than the +Slow Polling Interval. As such, a client SHOULD NOT try to send the same message at a frequency +higher than the Slow Polling Interval when the ICD is in Idle Mode. The ICD SHALL set its SES­ +SION_IDLE_INTERVAL to a value greater than or equal to the Slow Polling Interval. + +When in Active Mode, the device will typically not receive messages at a faster frequency than the +Fast Polling Interval. As such, a client SHOULD NOT try to send the same message at a frequency +higher than the Fast Polling Interval when the ICD is in Active Mode. The ICD SHALL set its SES­ +SION_ACTIVE_INTERVAL to a value greater than or equal to the Fast Polling Interval. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 645 +``` + +The ICD SHALL set its SESSION_ACTIVE_THRESHOLD to the Active Mode Threshold stored in the +ICD Management cluster. + +**9.16.1.3. Check-In Protocol Support** + +This section describes the Check-In Protocol use case used by Intermittently Connected Devices +(ICDs) to maintain a known relationship in case subscriptions with clients are lost. This includes +how a client shares a Check-In token (symmetric key) with the ICD, when Check-In messages are +sent and how the Check-In Protocol requirements are respected. + +The Check-In Protocol is a fail-safe mechanism which allows an Intermittently Connected Device +(ICD) to notify a registered client that it is available for communication when all subscriptions +between the client and ICD are lost. A subscription can be lost for several reasons, such as: + +- The ICD might not have full RAM retention when it is in an idle state. +- When the ICD is powered off to change the battery. +- Power or network outage causing the connection between the client and the ICD to be inter­ + rupted. +- The client is unavailable for any reason (e.g. during a software update or hosted on a mobile + device that is sometimes out-of-home). + +The Check-In message is sessionless and relies on a shared secret that has been given to the ICD +during the registration of the client using the ICD Management cluster. + +**9.16.1.3.1. Use Case Requirements** + +The ICD Check-In Protocol representation of the Check-In Counter SHALL be the ICD Counter. It +SHALL follow all the requirements of the Check-In Counter. + +The ICD Check-In Protocol representation of the Check-In Protocol persistent data store SHALL be +the RegisteredClients attribute in the ICD Management cluster. The attribute SHALL store all the +client registration information. + +The Application Data for the ICD Check-In Protocol use case SHALL be the Active Mode Threshold +attribute in the ICD Management cluster. Before being used in the encryption process, the Active +Mode Threshold SHALL be converted into a 2-byte little-endian value. + +**9.16.1.3.2. Protocol State Machine** + +The state machine diagram represents the states an ICD can be in. The diagram represents the state +of the ICD for one client or MonitoredSubject. The ICD can be in a different state for each client +simultaneously. + +``` +Page 646 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 73. ICD State Machine_ + +**Uncommissioned State** + +An ICD is in the _Uncommissioned_ state when it has not been provided with any credentials to join a +fabric. In this state, the ICD is passively waiting for incoming messages during the open commis­ +sioning window. + +**Unregistered State** + +An ICD is in the _Unregistered_ state with a given MonitoredSubject when no established relationship +with the client exists, meaning the ICD has neither a registration entry in the ICD Management clus­ +ter nor an active subscription associated with the client. In this state, the ICD is passively waiting +for incoming messages during its Active Mode Duration. + +**Check-in State** + +An ICD is in the _Check-in_ state when a registration entry is present for the client in the ICD Manage­ +ment cluster, but no active subscription exists for that client. In this state, the ICD sends Check-In +messages instead of subscription reports/events. The Check-In message notifies the client that the +ICD is available for communication. + +When in the Check-in state, each time an ICD transitions from Idle Mode to Active Mode, the ICD +SHALL attempt to send a Check-In message to each registered (MonitoredSubject) client that are +resident clients without an active subscription, effectively attempting to send a Check-In message +every Idle Mode Duration. The ICD SHOULD NOT attempt to send Check-In messages to clients that +have been registered as ephemeral clients. + +The ICD MAY back-off (i.e. skip some of these Check-In messages) when it does not experience inter­ +actions from the registered client (e.g. if that client has left the home network) after several consec­ +utive Check-In messages. The time between Check-In messages SHALL NOT be larger than the dura­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 647 +``` + +tion (in seconds) specified in MaximumCheckInBackoff. The number of consecutive missed Check- +In messages required to start backing-off is manufacturer specific. The missed Check-In message +counters SHALL be reset to 0 for all registered clients when a user active mode trigger is executed. + +**Subscribed State** + +An ICD is in the _Subscribed_ state with a given MonitoredSubject when it has at least one active sub­ +scription with the client. It is not necessary to have an entry in the ICD Management cluster to be in +the subscribed state. The ICD MAY be in the subscribed state most of its operating time. In this state, +the ICD’s goal is to notify the client when it is available for communication with subscription +reports. + +**9.16.1.3.3. Message Format** + +All Check-In messages SHALL be structured as specified in Message Format. + +All Check-In messages are unsecured at the message layer: + +- The Session ID field SHALL be set to 0. +- The Session Type bits of the Security Flags SHALL be set to 0. +- The S Flag field of the Message Flags SHALL be set to 0. +- The Message Counter value SHALL be the current value of the global unencrypted message + counter. +- The DSIZ field of the Message Flags SHALL be set to 0. + +**Protocol Header Field** + +The Check-In message will have the following values for the protocol header field : + +- The Initiator flag field SHALL be set to 1. +- The Reliability flag field SHALL be set to 0. +- The SX flag field SHALL be set to 0. +- The Vendor Flag field SHALL be set to 0. + +**Protocol Id and Opcode** + +The ICD Check-In message SHALL have secure channel protocol ID. The ICD Check-In message +SHALL have the ICD Check-In message protocol opcode. + +**9.16.1.3.4. Sending Check-In Message Steps** + +When sending an ICD Check-In message, the server SHALL respect the following requirements: + +1. The server SHALL NOT send more than one Check-In message with a given ICD counter value to + the same RegisteredClient CheckInNodeID. +2. The server SHALL follow the encryption process of the Check-In Protocol. +3. The server SHALL configure the Matter header as defined in message format section. + +``` +Page 648 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The server MAY try to resolve the IP address and the port of the CheckInNodeID each time the +server needs to send a Check-In message to a RegisteredClient CheckInNodeID. + +**9.16.1.4. User Active Mode Trigger** + +Since ICDs are not immediately responsive, they require a means to render them available for com­ +munication for user initiated use cases. Some of the user initiated use cases are: + +- Opening a new commissioning window to add another administrator. +- Reconfiguration of an existing fabric (e.g. IPKs, NOC rotation, ACL changes). +- Reconfiguration of cluster functionality (e.g. ICD Management, Bindings, Groups, Scenes). +- Removal of a device from a fabric. +- Changes to the device’s settings. + +An ICD that requires user initiated use cases SHALL provide an Active Mode Trigger as a way for a +user to put the device into active mode and make it responsive to controller communication. The +UserActiveModeTrigger feature in the ICD Management cluster indicates whether a particular +device implements an active mode trigger. + +**9.16.1.5. Short Idle Time (SIT) ICD** + +ICDs with Slow Polling Interval shorter than or equal to 15 seconds SHOULD be configured as a +Short Idle Time ICD. For example, this is a typical scenario for door locks and window coverings, +where commands need to be sent to the ICD with a use case imposed latency requirement. Typi­ +cally, devices that are Short Idle Time ICDs are not initiators in the communication flow. + +**9.16.1.5.1. Requirements** + +A SIT ICD SHALL advertise its SESSION_IDLE_INTERVAL per SII. It SHALL also advertise its SES­ +SION_ACTIVE_INTERVAL per SAI. The device MAY have a user action that triggers the ICD to transi­ +tion to Active mode. + +Having a long ActiveModeThreshold makes the ICD more responsive for subsequent messages at the +expense of increased power consumption. The ICD stays in Active Mode for the entire duration of +the ActiveModeThreshold. + +On the other hand, having an ActiveModeThreshold of 0 means that the device might enter Idle Mode +immediately after the last active exchange is closed. One good example is if a client reads five +attributes in a row from an ICD and the ActiveModeThreshold is 0 then it MAY have to wait up to one +Idle Mode Duration after each attribute read. + +In order to get the benefits of the ActiveModeThreshold attributes while keeping the power consump­ +tion low, the ICD MAY ignore the Active Mode Threshold and immediately return to IdleMode upon +the completion of an exchange if the ICD was the Initiator of the exchange being closed and there +are no other reasons keeping it in active mode. + +**9.16.1.6. Long Idle Time (LIT) ICD** + +ICDs with a Slow Polling Interval longer than 15 seconds SHOULD be configured as Long Idle Time + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 649 +``` + +ICDs. For example, this is a typical scenario for sensors and light switches, where data reports are +initiated by the ICD for an updated sensed value or a switch event. Typically, devices that are Long +Idle Time ICDs are initiators in the communication flow. + +**9.16.1.6.1. Overview** + +The high-level steady state behavior of a LIT ICD is to alternate between long IDLE mode periods +and short ACTIVE mode periods, where the ACTIVE mode period begins with a transmission to reg­ +istered clients. A graphical depiction of ICD steady state behavior is shown in Figure 74, “ICD Steady +State Behavior Diagram”. + +_Figure 74. ICD Steady State Behavior Diagram_ + +The ICD stays active a minimum amount of time each active mode period, and that time can be +extended based on received network activity from registered clients. A graphical depiction of ICD +behavior when in ACTIVE mode is shown in Figure 75, “ICD Active Mode Behavior Diagram”. The +ActiveModeDuration starts immediately upon transitioning out of IDLE mode into ACTIVE mode. The +ActiveModeThreshold starts immediately upon sending the Check-In message or any other transmis­ +sion. The Exchange Context ends upon receipt of a response acknowledgement or timeout. Receipt +of a response acknowledgement starts a new ActiveModeThreshold and keeps the ICD ACTIVE for +longer. If further messages are received during the ActiveModeThreshold, a new Exchange can be +created to keep the ICD ACTIVE for even longer. + +_Figure 75. ICD Active Mode Behavior Diagram_ + +**9.16.1.6.2. Requirements** + +The device SHALL indicate it is a LIT ICD by setting the LongIdleTime feature to 1 in the ICD Man­ +agement cluster. When the device is operating as a LIT ICD, it SHALL advertise 1 with the ICD dis­ +covery TXT key. This informs clients that they SHOULD wait for a notification from the LIT ICD +before sending any messages to the device. When the device is operating as a SIT ICD, it SHALL + +``` +Page 650 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +advertise 0 with the ICD discovery TXT key. This informs clients that they SHOULD NOT wait for a +notification from the LIT ICD before sending any messages to the device. It SHALL also advertise its +SESSION_ACTIVE_INTERVAL per SAI. A LIT ICD SHOULD NOT advertise its SESSION_IDLE_INTER­ +VAL with SII. The device SHALL support the ICD Check-In use case requirements. The device SHALL +have a user action that triggers the ICD to transition to Active mode. The _Fast Polling_ interval +SHALL be smaller than the Active Mode Duration. The ActiveModeThreshold SHALL NOT be +smaller than 5 seconds. + +**9.16.1.6.3. Client Registration Requirement** + +For LIT ICDs to be fully functional, they require clients to support the ICD client behavior. The main +client requirements are the client registration process with the ICD Management cluster, and the +processing of incoming Check-In messages received from the ICD. A LIT ICD SHALL operate as a SIT +ICD if it doesn’t have at least one registration with any client on any fabric in the ICD Management +cluster. A LIT ICD MAY operate as a LIT ICD when at least one client has successfully registered. + +When operating as a SIT ICD, a LIT ICD: + +1. SHALL NOT set its Slow Polling Interval to a value higher than the Short Idle Time ICD maxi­ + mum. +2. SHALL advertise its SESSION_IDLE_INTERVAL using the SII discovery TXT key. +3. SHALL advertise 0 with the ICD discovery TXT key to inform clients that it can be reached asyn­ + chronously. +4. MAY ignore the Active Mode Threshold as described in the SIT ICD Requirements section. + +After a client has successfully registered with ICD Management cluster, a LIT ICD MAY operate as +one. When an ICD transitions from operating as a SIT to a LIT ICD, the LIT ICD SHALL respect all the +LIT requirements. + +**9.16.1.6.4. Runtime Operating Mode Switching** + +Due to the registration requirement, LIT ICDs SHALL have the capacity to switch between LIT and +SIT operating modes. This ability can be leveraged by devices that have a use case where the device +MAY want to remain in the SIT operating mode even if a client has registered. A good example is a +Smoke & CO alarm device. While the device is line-powered, it can be very responsive to clients and +remain in the SIT operating mode. If it loses line-power, it can transition to LIT operating mode if it +has at least one registration and leverage all the LIT ICD features and power efficiency. If the device +supports switching between the SIT and LIT operation modes even with a registered client, it +SHALL set the DynamicSitLitSupport feature in the ICD Management cluster. + +Each time a LIT ICD switches between operating modes, both the mDNS ICD key and Operating­ +Mode attribute of the ICDM cluster must be updated: + +- ICD=0 and OperatingMode=SIT if "Long Idle Time ICD is operating as a Short Idle Time ICD", +- ICD=1 and OperatingMode=LIT if "Long Idle Time ICD is operating as a Long Idle Time ICD". + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 651 +``` + +**9.16.1.6.5. Runtime Polling Interval Changes** + +In addition to being able to dynamically switch between LIT and SIT operating modes, an ICD can +also dynamically change its Fast Polling Interval, Slow Polling Interval and its Active Mode Thresh­ +old. A change in Active Mode Threshold value SHALL trigger a DNS-SD update of the SAT TXT key. +Changes of the SESSION_ACTIVE_INTERVAL or SESSION_IDLE_INTERVAL SHALL also trigger a DNS-SD +update of the corresponding SAI or SII TXT keys. Note that an update of the polling intervals MAY +NOT trigger an update of the SAI or SII TXT keys if the new polling intervals are still compliant with +the rules from ICD Session Configurations section. + +**9.16.2. ICD Client Behavior** + +This section provides a description of the client requirements to support Long Idle Time ICDs. A +client does not require a specific feature-set to support Short Idle Time ICDs. + +**9.16.2.1. Check-In Protocol Support** + +A client that supports Long Idle Time ICDs SHALL implement the Check-In Protocol client require­ +ments. + +**9.16.2.2. Registration Processes** + +In order to maximize the reliability of communications with Long Idle Time ICDs, which can be +unreachable for extended periods of time, the ICD Management cluster provides a mechanism for +clients to register themselves or other monitoring nodes to receive Check-In messages from an ICD. +A client that needs to be able to interact with a Long Idle Time ICDs SHALL invoke the Register­ +Client command against it, typically during commissioning, or have the commissioner or some +other existing client send the RegisterClient command on its behalf. + +The RegisterClient command supplies three parameters to the server: + +1. A symmetric Key which is used to encrypt the Check-In messages sent by the server. +2. A node identifier which specifies the node that will receive the Check-In messages. +3. A subject-id used to determine if a particular client has an active subscription. +4. The type of the client registering, permanent or ephemeral (e.g. mobile). + +When a client registers with multiple servers, it SHALL use unique keys since the key is used to +identify which server sent the Check-In message. Check-In messages do not have an originator +address. Therefore, successfully decrypting a Check-In message with a key and having that key cor­ +respond to a specific server is the only way to identify which server sent the Check-In message. + +If the commissioner is ephemeral and a separate stationary controller exists in the network, the +commissioner SHOULD register the stationary controller in the ICD Management cluster. Because +an ICD is only required to provide one guaranteed client slot per fabric, clients SHOULD self-limit +commissioning time registration. + +**9.16.2.2.1. Commissioner Self-Registration** + +A commissioner that is also a controller can register itself with the ICD during the device configura­ + +``` +Page 652 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +tion portion of the commissioning process. This is the simplest client registration scenario, where a +commissioner registers itself during commissioning. At the end of the commissioning process, the +commissioner and ICD are coupled. + +This diagram shows one possible process a commissioner can use to register itself with an ICD. +Other processes are also possible such as a Commissioner which registers itself right after the Add +NOC step and before the Operational Discovery step. + +_Figure 76. Commissioner Self-Registration to ICD_ + +**9.16.2.2.2. External Controller Registration** + +A commissioner can also register an external controller at the time of commissioning. This requires +that the commissioner knows the node ID of the controller and that commissioner and controller +share a symmetric key used for the client registration by some out-of-band means. + +This diagram shows one possible process a commissioner can use to register the controller with an +ICD. Other processes are also possible such as a Commissioner which registers the controller right +after the Add NOC step and before the Operational Discovery step. The same is true for when the +Symmetric Key is shared between devices. Other processes may choose to share the key at a differ­ +ent moment in the process. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 653 +``` + +_Figure 77. External Controller Registration_ + +**9.16.2.2.3. Delegated Controller Registration** + +A commissioner can also delegate client registration to some other assisting device or controller. In +such a scenario, the commissioner does not register the controller, but instead completes the com­ +missioning process and then hands control to the delegated controller to register itself or other +clients with the ICD. + +When doing so, a commissioner would need to send a command to keep the ICD awake for some +amount of time, in order to ensure that an external controller can reach it. + +Alternatively, the infrastructure could also be notified of the newly-commissioned ICD before +invoking CommissioningComplete, as this would keep the device awake and available for interactions. + +This diagram shows one possible process a commissioner can use to register the controller with an +ICD. + +``` +Page 654 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 78. Delegated Controller Registration_ + +**9.16.2.2.4. Assisted On Demand Registration** + +If a new controller is added to a fabric with existing ICDs, it may be necessary that some existing +controller in the infrastructure assist with client registration by providing notification to a new con­ +troller when an ICD is active and thus available. + +In this scenario, an out-of-band method can be used for the existing controller to detect or be +informed of the addition of the new controller and signal to it when present ICDs are active. It +should be noted that it is also feasible for a node identity to be instantiated on different hardware +to suit the needs of the user. This could allow controllers to be replaced in a system, or have con­ +troller identities roam to different hardware without the need to re-register in the client. + +This diagram shows one possible process a commissioner can use to register the controller with an +ICD. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 655 +``` + +_Figure 79. Infrastructure Assisted On-Demand Registration_ + +**9.16.2.2.5. Assisted Proxy Registration** + +Alternatively, instead of the new controller receiving notification when an ICD wakes up, an exist­ +ing controller could be requested to register the new controller when an ICD checks-in. In this way, +the existing controller acts as a proxy to register on behalf of the new controller. This requires a +queuing or caching mechanism in the existing controller. + +_Figure 80. Infrastructure Assisted Proxy Registration_ + +**9.16.2.3. Unregistration Process** + +When a commissioner or client wants to unregister itself, it can send an UnregisterClient command +to the ICD. When a registered client is about to permanently leave the network, it SHOULD send an +UnregisterClient command to free its slot for another client. + +``` +Page 656 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +When an ICD receives the RemoveFabric command, all registrations associated with the fabric +SHALL be removed during the fabric removal process. + +**9.16.2.4. Post-Commissioning Process** + +In addition to registering a client with the ICD, the commissioner or client SHOULD ensure that +some node that matches the registered SubjectID establishes and maintains a subscription with the +ICD. A client is not required to establish and maintain a subscription with the ICD. In such case, it +can rely on Check-In messages as a heartbeat to provide an indication when it can communicate +with an ICD. + +**9.16.2.5. Client and ICD Relationship** + +This section describes how a client and a LIT ICD arrange to communicate with each other. Because +SIT ICDs are reachable on the network without special action by clients, clients need not register +with SIT ICDs. + +**9.16.2.5.1. Communication with an ICD** + +LIT ICDs have two operating modes. They can either be operating as LIT or as SIT ICD. If the ICD is +operating as a SIT ICD, it SHALL advertise this by setting the ICD discovery TXT key to 0. When the +LIT ICD is operating as a SIT ICD, clients can send their message to the ICD without prior notifica­ +tion. If the ICD is operating as a LIT ICD, it SHALL advertise this by setting the ICD discovery TXT +key to 1. If the ICD is operating as a LIT ICD, it will be unreachable for extended of periods of time. +Permanent clients need to wait for prior notification before sending a message to the ICD. Prior +notification typically arrives with these two types of messages : + +- Report transaction from the ICD on an ongoing Subscription. +- Check-In message from the ICD. + +Ephemeral clients SHOULD leverage asynchronous interactions since they might not be present in +the network when the ICD notifies it is available for communication. + +After sending either of these messages, an ICD will remain available for a period of time to allow +clients to send their messages. Clients that support LIT ICDs SHOULD sequentially send any +buffered interactions for a peer ICD immediately after receipt of a notification from that LIT ICD. + +Upon receipt of a Check-In message from an ICD, a client that has lost its previous subscription or +intends to establish a new subscription with that ICD SHOULD initiate an attempt to subscribe to +the ICD. If the client initiates a session establishment with the ICD in response to a Check-In mes­ +sage, then the client SHOULD assume the ICD to be active and use the SESSION_ACTIVE_INTERVAL +for its MRP retry intervals. If the client chooses not to establish a subscription, it MAY utilize the +Check-In message as a means of tracking a regular heartbeat from the given ICD. If the client no +longer intends to interact with the ICD, the uninterested client SHOULD unregister itself from the +ICD. + +When a client wants the ICD to stay in active mode for a longer duration (typically greater than the +duration of ActiveModeThreshold), it can send a StayActiveRequest command to the ICD server. The +StayActiveRequest command SHALL contain a requested time duration (in milliseconds) that the +client wants the ICD to stay active for. In response, the ICD SHALL reply with the duration that the + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 657 +``` + +ICD SHALL be active for. + +**9.16.2.5.2. Asynchronous Interactions** + +Consider a sensor LIT ICD, which primarily exposes telemetry data via read-only attributes and +allows a few commands to be executed from its application clusters. Such devices must still be +administered, and that can only be carried out when the ICD is reachable. + +Likely targets for administration are: + +- Opening a new commissioning window to add another administrator. +- Reconfiguration of an existing fabric (e.g. IPKs, NOC rotation, ACL changes). +- Reconfiguration of cluster functionality (e.g. ICD Management cluster, Binding cluster, Groups + cluster, Scenes Management cluster). +- Removal of a device from a fabric. +- Changes to the device’s settings. + +To enable these user initiated use cases, LIT ICDs expose to clients instructions on how they can be +forced into Active Mode. Clients SHOULD read these instructions from the ICD during the registra­ +tion process and persist them. Clients SHOULD expose these instructions to users to permit users to +trigger Active Mode as needed. + +**9.17. ICD Management Cluster** + +ICD Management Cluster enables configuration of the ICD’s behavior and ensuring that listed +clients can be notified when an intermittently connected device, ICD, is available for communica­ +tion. + +The cluster implements the requirements of the Check-In Protocol that enables the ICD Check-In +use case. + +**9.17.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Addition of LIT ICD support, UserActiveMode­ +Trigger, ActiveModeDuration, StayActiveRe­ +sponse; removal of field Key in MonitoringRegis­ +trationStruct +3 Addition of the ClientType attribute; addition of +the ICD Check-In Backoff support; addition of +the DynamicSitLitSupport feature +``` +``` +Page 658 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.17.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node ICDM +``` +**9.17.3. Cluster ID** + +``` +ID Name +0x0046 ICDManagement +``` +**9.17.4. Features** + +This cluster SHALL support the FeatureMap global attribute. + +``` +Bit Code Feature Conformance Summary +0 CIP CheckInProtocol­ +Support +``` +``` +LITS, O Device supports +attributes and +commands for the +Check-In Protocol +support. +1 UAT UserActiveMode­ +Trigger +``` +``` +LITS, O Device supports +the user active +mode trigger fea­ +ture. +2 LITS LongIdleTimeSup­ +port +``` +``` +O Device supports +operating as a +Long Idle Time +ICD. +3 DSLS DynamicSitLitSup­ +port +``` +``` +[LITS] Device supports +dynamic switching +from SIT to LIT +operating modes. +``` +**9.17.4.1. CheckInProtocolSupport Feature** + +When this feature is supported, the device SHALL support all the associated commands and attrib­ +utes to properly support the Check-In Protocol. + +**9.17.4.2. UserActiveModeTrigger Feature** + +This feature is supported if and only if the device has a user active mode trigger. + +**9.17.4.3. LongIdleTimeSupport Feature** + +This feature is supported if and only the device is a Long Idle Time ICD. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 659 +``` + +**9.17.4.4. DynamicSitLitSupport Feature** + +This feature is supported if and only if the device can switch between SIT and LIT operating modes +even if it has a valid registered client. See the dynamic SIT / LIT operating mode switching for more +details. + +**9.17.5. Data Types** + +**9.17.5.1. UserActiveModeTriggerBitmap Type** + +This data type is derived from map32. See the UserActiveModeTriggerHint table for requirements +associated to each bit. + +``` +Bit Name Summary Conformance +0 PowerCycle Power Cycle to transi­ +tion the device to +ActiveMode +``` +### M + +``` +1 SettingsMenu Settings menu on the +device informs how to +transition the device to +ActiveMode +``` +### M + +``` +2 CustomInstruction Custom Instruction on +how to transition the +device to ActiveMode +``` +### M + +``` +3 DeviceManual Device Manual informs +how to transition the +device to ActiveMode +``` +### M + +``` +4 ActuateSensor Actuate Sensor to tran­ +sition the device to +ActiveMode +``` +### M + +``` +5 ActuateSensorSec­ +onds +``` +``` +Actuate Sensor for N +seconds to transition +the device to Active­ +Mode +``` +### M + +``` +6 ActuateSensorTimes Actuate Sensor N times +to transition the device +to ActiveMode +``` +### M + +``` +7 ActuateSensorLights­ +Blink +``` +``` +Actuate Sensor until +light blinks to transi­ +tion the device to +ActiveMode +``` +### M + +``` +8 ResetButton Press Reset Button to +transition the device to +ActiveMode +``` +### M + +``` +Page 660 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary Conformance +9 ResetButtonLights­ +Blink +``` +``` +Press Reset Button until +light blinks to transi­ +tion the device to +ActiveMode +``` +### M + +``` +10 ResetButtonSeconds Press Reset Button for +N seconds to transition +the device to Active­ +Mode +``` +### M + +``` +11 ResetButtonTimes Press Reset Button N +times to transition the +device to ActiveMode +``` +### M + +``` +12 SetupButton Press Setup Button to +transition the device to +ActiveMode +``` +### M + +``` +13 SetupButtonSeconds Press Setup Button for +N seconds to transition +the device to Active­ +Mode +``` +### M + +``` +14 SetupButtonLights­ +Blink +``` +``` +Press Setup Button +until light blinks to +transition the device to +ActiveMode +``` +### M + +``` +15 SetupButtonTimes Press Setup Button N +times to transition the +device to ActiveMode +``` +### M + +``` +16 AppDefinedButton Press the N Button to +transition the device to +ActiveMode +``` +### M + +**9.17.5.1.1. ClientTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Permanent The client is typically +resident, always-on, +fixed infrastructure in +the home. +``` +### M + +``` +1 Ephemeral The client is mobile or +non-resident or not +always-on and may not +always be available in +the home. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 661 +``` + +**9.17.5.2. OperatingModeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 SIT ICD is operating as a +Short Idle Time ICD. +``` +### M + +``` +1 LIT ICD is operating as a +Long Idle Time ICD. +``` +### M + +**9.17.5.3. MonitoringRegistrationStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 CheckInN­ +odeID +``` +``` +node-id all N S M +``` +``` +2 Moni­ +toredSub­ +ject +``` +``` +subject-id all N S M +``` +``` +3 Key D +4 ClientType ClientType­ +Enum +``` +``` +all N 0 S M +``` +**9.17.5.3.1. CheckInNodeID Field** + +This field SHALL indicate the NodeID of the Node to which Check-In messages will be sent when the +MonitoredSubject is not subscribed. + +**9.17.5.3.2. MonitoredSubject Field** + +This field SHALL indicate the monitored Subject ID. This field SHALL be used to determine if a par­ +ticular client has an active subscription for the given entry. The MonitoredSubject, when it is a +NodeID, MAY be the same as the CheckInNodeID. The MonitoredSubject gives the registering client +the flexibility of having a different CheckInNodeID from the MonitoredSubject. A subscription +SHALL count as an active subscription for this entry if: + +- It is on the associated fabric of this entry, and +- The subject of this entry matches the ISD of the SubscriptionRequest message that created the + subscription. Matching SHALL be determined using the subject_matches function defined in the + Access Control Privilege Granting Algorithm. + +For example, if the MonitoredSubject is Node ID 0x1111_2222_3333_AAAA, and one of the sub­ +scribers to the server on the entry’s associated fabric bears that Node ID, then the entry matches. + +Another example is if the MonitoredSubject has the value 0xFFFF_FFFD_AA12_0002, and one of the + +``` +Page 662 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +subscribers to the server on the entry’s associated fabric bears the CASE Authenticated TAG value +0xAA12 and the version 0x0002 or higher within its NOC, then the entry matches. + +**9.17.5.4. ClientType Field** + +This field SHALL indicate the client’s type to inform the ICD of the availability for communication +of the client. + +**9.17.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 IdleMode­ +Duration +``` +``` +uint32 1 to 64800 F 1 R V M +``` +``` +0x0001 Active­ +ModeDu­ +ration +``` +``` +uint32 all F 300 R V M +``` +``` +0x0002 Active­ +Mode­ +Threshold +``` +``` +uint16 all F 300 R V M +``` +``` +0x0003 Regis­ +tered­ +Clients +``` +``` +list[Moni­ +toringReg­ +istra­ +tionStruct] +``` +``` +desc N [] R A F CIP +``` +``` +0x0004 ICD­ +Counter +``` +``` +uint32 all NC 0 R A CIP +``` +``` +0x0005 ClientsSup +portedPer­ +Fabric +``` +``` +uint16 min 1 F 1 R V CIP +``` +``` +0x0006 UserAc­ +tiveMode­ +Trigger­ +Hint +``` +``` +UserActive­ +ModeTrig­ +gerBitmap +``` +``` +desc F 0 R V UAT +``` +``` +0x0007 UserAc­ +tiveMode­ +TriggerIn­ +struction +``` +``` +string max 128 F "" R V desc +``` +``` +0x0008 Operating­ +Mode +``` +``` +Operating­ +Mod­ +eEnum +``` +``` +all R V LITS +``` +``` +0x0009 Maxi­ +mum­ +CheckIn­ +Backoff +``` +``` +uint32 IdleMode­ +Duration to +64800 +``` +### F 1 R V CIP + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 663 +``` + +**9.17.6.1. IdleModeDuration Attribute** + +This attribute SHALL indicate the maximum interval in seconds the server can stay in idle mode. +The IdleModeDuration SHALL NOT be smaller than the ActiveModeDuration. + +**9.17.6.2. ActiveModeDuration Attribute** + +This attribute SHALL indicate the minimum interval in milliseconds the server typically will stay in +active mode after initial transition out of idle mode. The ActiveModeDuration does not include the +ActiveModeThreshold. + +**9.17.6.3. ActiveModeThreshold Attribute** + +This attribute SHALL indicate the minimum amount of time in milliseconds the server typically will +stay active after network activity when in active mode. + +**9.17.6.4. RegisteredClients Attribute** + +This attribute SHALL contain all clients registered to receive notification if their subscription is lost. +The maximum number of entries that can be in the list SHALL be ClientsSupportedPerFabric for +each fabric supported on the server, as indicated by the value of the SupportedFabrics attribute in +the Operational Credentials cluster. + +**9.17.6.5. ICDCounter Attribute** + +This attribute returns the value of the ICD Counter. + +**9.17.6.6. ClientsSupportedPerFabric Attribute** + +This attribute SHALL indicate the maximum number of entries that the server is able to store for +each fabric in the RegisteredClients attribute. + +**9.17.6.7. UserActiveModeTriggerHint Attribute** + +This attribute SHALL indicate which user action(s) will trigger the ICD to switch to Active mode. If +the attribute indicates support for a trigger that is dependent on the UserActiveModeTriggerIn­ +struction in the UserActiveModeTriggerHint table, the UserActiveModeTriggerInstruction attribute +SHALL be implemented and SHALL provide the required information, unless specified otherwise in +the requirement column of the UserActiveModeTriggerHint table. + +ActuateSensorLightsBlink, ResetButtonLightsBlink and SetupButtonLightsBlink (i.e. bits 7, 9 and 14) +have a dependency on the UserActiveModeTriggerInstruction attribute but do not require the +attribute to be present. + +``` +Page 664 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Bit index Name Requirement UserActiveModeTrig­ +gerInstruction Depen­ +dency** + +0 PowerCycle The Device will auto­ +matically enter Active +Mode upon power cycle +(e.g. remove/re-insert +batteries). + +``` +False +``` +1 SettingsMenu The settings menu on +the Device provides +instructions to put it +into Active Mode. + +``` +False +``` +2 CustomInstruction The UserActiveMode­ +TriggerInstruction +key/value pair +describes a custom way +to put the Device into +Active Mode. This Cus­ +tom Instruction option +is NOT recommended +for use by a Device that +does not have knowl­ +edge of the user’s lan­ +guage preference. + +``` +True +``` +3 DeviceManual The Device Manual pro­ +vides special instruc­ +tions to put the Device +into Active Mode (see +Section 11.23.6.15, +“UserManualUrl”). This +is a catch-all option to +capture user interac­ +tions that are not codi­ +fied by other options in +this table. + +``` +False +``` +4 ActuateSensor The Device will enter +Active Mode when the +sensor is actuated, e.g. +for a door sensor, +open/close the door. + +``` +False +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 665 +``` + +``` +Bit index Name Requirement UserActiveModeTrig­ +gerInstruction Depen­ +dency +5 ActuateSensorSeconds The Device will enter +Active Mode when the +sensor is actuated for N +seconds. The exact +value of N SHALL be +made available via the +UserActiveModeTrig­ +gerInstruction +attribute. +``` +``` +True +``` +``` +6 ActuateSensorTimes The Device will enter +Active Mode when +reset button is pressed. +The exact value of N +SHALL be made avail­ +able via the UserActive­ +ModeTriggerInstruc­ +tion attribute. +``` +``` +True +``` +``` +7 ActuateSensorLights­ +Blink +``` +``` +The Device will enter +Active Mode when the +sensor is actuated until +associated light blinks. +Information on color of +light MAY be made +available via the User­ +ActiveModeTriggerIn­ +struction attribute. +``` +``` +True +``` +``` +8 ResetButton The Device will enter +Active Mode when +reset button is pressed. +``` +``` +False +``` +``` +9 ResetButtonLightsBlink The Device will enter +Active Mode when +reset button is pressed +until associated light +blinks. Information on +color of light MAY be +made available via the +UserActiveModeTrig­ +gerInstruction +attribute. +``` +``` +True +``` +Page 666 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Bit index Name Requirement UserActiveModeTrig­ +gerInstruction Depen­ +dency** + +10 ResetButtonSeconds The Device will enter +Active Mode when +reset button is pressed +for N seconds. The +exact value of N SHALL +be made available via +the UserActiveMode­ +TriggerInstruction +attribute. + +``` +True +``` +11 ResetButtonTimes The Device will enter +Active Mode when +reset button is pressed +N times with maximum +1 second between each +press. The exact value +of N SHALL be made +available via UserAc­ +tiveModeTriggerIn­ +struction attribute. + +``` +True +``` +12 SetupButton The Device will enter +Active Mode when +setup button is pressed. + +``` +False +``` +13 SetupButtonSeconds The Device will enter +Active Mode when +setup button is pressed +for N seconds. The +exact value of N SHALL +be made available via +the UserActiveMode­ +TriggerInstruction +attribute. + +``` +True +``` +14 SetupButtonLightsBlinkThe Device will enter +Active Mode when +setup button is pressed +until associated light +blinks. Information on +color of light MAY be +made available via the +UserActiveModeTrig­ +gerInstruction +attribute. + +``` +True +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 667 +``` + +``` +Bit index Name Requirement UserActiveModeTrig­ +gerInstruction Depen­ +dency +15 SetupButtonTimes The Device will enter +Active Mode when +setup button is pressed +N times with maximum +1 second between each +press. The exact value +of N SHALL be made +available via the User­ +ActiveModeTriggerIn­ +struction attribute. +``` +``` +True +``` +``` +16 AppDefinedButton The Device will enter +Active Mode when N +button is pressed +where N identifies +which button to press. +The value of N SHALL +be made available via +the UserActiveMode­ +TriggerInstruction +attribute +``` +``` +True +``` +An ICD can indicate multiple ways of being put into Active Mode by setting multiple bits in the +bitmap at the same time. However, a device SHALL NOT set more than one bit which has a depen­ +dency on the UserActiveModeTriggerInstruction attribute. + +**9.17.6.8. UserActiveModeTriggerInstruction Attribute** + +The meaning of the attribute is dependent upon the UserActiveModeTriggerHint attribute value, +and the conformance is in indicated in the "dependency" column in UserActiveModeTriggerHint ta­ +ble. The UserActiveModeTriggerInstruction attribute MAY give additional information on how to +transition the device to Active Mode. If the attribute is present, the value SHALL be encoded as a +valid UTF-8 string with a maximum length of 128 bytes. If the UserActiveModeTriggerHint has the +ActuateSensorSeconds, ActuateSensorTimes, ResetButtonSeconds, ResetButtonTimes, SetupButton­ +Seconds or SetupButtonTimes set, the string SHALL consist solely of an encoding of N as a decimal +unsigned integer using the ASCII digits 0-9, and without leading zeros. + +For example, given UserActiveModeTriggerHint="2048", ResetButtonTimes is set which indicates +"Press Reset Button for N seconds". Therefore, a value of UserActiveModeTriggerInstruction="10" +would indicate that N is 10 in that context. + +When CustomInstruction is set by the UserActiveModeTriggerHint attribute, indicating presence of a +custom string, the ICD SHOULD perform localization (translation to user’s preferred language, as +indicated in the Device’s currently configured locale). The Custom Instruction option SHOULD NOT +be used by an ICD that does not have knowledge of the user’s language preference. + +``` +Page 668 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +When the UserActiveModeTriggerHint key indicates a light to blink (ActuateSensorLightsBlink, Reset­ +ButtonLightsBlink or SetupButtonLightsBlink), information on color of light MAY be made available +via the UserActiveModeTriggerInstruction attribute. When using such color indication in the UserAc­ +tiveModeTriggerInstruction attribute, the string SHALL consist of exactly 6 hexadecimal digits using +the ASCII characters 0-F and encoding the RGB color value as used in HTML encodings. + +**9.17.6.9. OperatingMode Attribute** + +This attribute SHALL indicate the operating mode of the ICD as specified in the OperatingMod­ +eEnum. + +- If the ICD is operating as a LIT ICD, OperatingMode SHALL be LIT. +- If the ICD is operating as a SIT ICD, OperatingMode SHALL be SIT. + +**9.17.6.10. MaximumCheckInBackoff Attribute** + +This attribute SHALL indicate the maximum time in seconds between two Check-In messages when +back-off is active. The MaximumCheckInBackoff SHALL NOT be smaller than the IdleModeDura­ +tion. + +If the MaximumCheckInBackoff is equal to the IdleModeDuration, it means the ICD does notback- +off. + +**9.17.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 RegisterClient client ⇒ server RegisterClien­ +tResponse +``` +### M F CIP + +``` +0x01 RegisterClien­ +tResponse +``` +``` +client ⇐ server N CIP +``` +``` +0x02 Unregister­ +Client +``` +``` +client ⇒ server Y M F CIP +``` +``` +0x03 StayAc­ +tiveRequest +``` +``` +client ⇒ server StayActiveRe­ +sponse +``` +### O LITS, O + +``` +0x04 StayActiveRe­ +sponse +``` +``` +client ⇐ server N LITS, O +``` +**9.17.7.1. RegisterClient Command** + +This command allows a client to register itself with the ICD to be notified when the device is avail­ +able for communication. + +This command SHALL have the following data fields: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 669 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 CheckInN­ +odeID +``` +``` +node-id all M +``` +``` +1 Monitored­ +Subject +``` +``` +subject-id all M +``` +``` +2 Key octstr 16 M +3 Verification­ +Key +``` +``` +octstr 16 O +``` +``` +4 ClientType ClientType­ +Enum +``` +``` +all M +``` +**9.17.7.1.1. CheckInNodeID Field** + +This field SHALL provide the node ID to which a Check-In message will be sent if there are no active +subscriptions matching MonitoredSubject. + +**9.17.7.1.2. MonitoredSubject Field** + +This field SHALL provide the monitored subject ID. + +**9.17.7.1.3. Key Field** + +This field SHALL provide the shared secret between the client and the ICD to encrypt the Check-In +message. + +**9.17.7.1.4. VerificationKey Field** + +This field SHALL provide the verification key. The verification key represents the key already +stored on the server. The verification key provided in this field SHALL be used by the server to +guarantee that a client with manage permissions can only modify entries that contain a Key equal +to the verification key. The verification key SHALL be provided for clients with manage permis­ +sions. The verification key SHOULD NOT be provided by clients with administrator permissions for +the server cluster. The verification key SHALL be ignored by the server if it is provided by a client +with administrator permissions for the server cluster. + +**9.17.7.1.5. ClientType Field** + +This field SHALL provide the client type of the client registering. + +**9.17.7.1.6. Effect on Receipt** + +On receipt of the RegisterClient command, the server SHALL perform the following procedure: + +1. The server verifies that an entry for the fabric is available in the server’s list of registered + clients. + a.If one of the entries in storage for the fabric has the same CheckInNodeID as the received + CheckInNodeID, the server SHALL continue from step 2. + +``` +Page 670 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +b. If there is an available entry for the fabric, an entry is created for the fabric and the +received CheckInNodeID, MonitoredSubject, Key and ClientType are stored. The server +SHALL continue from step 5. +c. If there are no available entries for the fabric, the status SHALL be RESOURCE_EXHAUSTED +and the server SHALL continue from step 6. +``` +2. The server SHALL verify the privileges of the command’s ISD. + a. If the ISD of the command has administrator privileges for the server cluster, the server + SHALL continue from step 4. + b. If the ISD of the command does not have administrator privileges for the server cluster, the + server SHALL continue from step 3. +3. The server SHALL verify that the received verification key is equal to the key previously stored + in the list of registered clients with the matching CheckInNodeID. + a. If the verification key does not have a valid value, the status SHALL be FAILURE. the server + SHALL continue from step 6. + b. If the verification key is not equal to the Key value stored in the entry, the status SHALL be + FAILURE. The server SHALL continue from step 6. +c. If the verification key is equal to the Key value stored in the entry, the server SHALL con­ +tinue from step 4. +4. The entry SHALL be updated with the received CheckInNodeID, MonitoredSubject, Key and + ClientType. + a. If the update fails, the status SHALL be FAILURE. The server SHALL continue from step 6. + b. If the update succeeds, the server SHALL continue from step 5. +5. The server SHALL persist the client information. + a. If the persistence fails, the status SHALL be FAILURE and the server SHALL continue from + step 6. + b. If the persistence succeeds, the status SHALL be SUCCESS and the server SHALL continue + from step 6. +6. The server SHALL generate a response. + a. If the status is SUCCESS, the server SHALL generate a RegisterClientResponse command. + b. If the status is not SUCCESS, the server SHALL generate a default response with the Status + field set to the evaluated error status. + +**9.17.7.2. RegisterClientResponse Command** + +This command SHALL be sent by the ICD Management Cluster server in response to a successful +RegisterClient command. + +This command SHALL have the following data fields: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 671 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ICDCounter uint32 all M +``` +**9.17.7.2.1. When Generated** + +This command SHALL be generated in response to a successful RegisterClient command. The ICD­ +Counter field SHALL be set to the ICDCounter attribute of the server. + +**9.17.7.3. UnregisterClient Command** + +This command allows a client to unregister itself with the ICD. Example: a client that is leaving the +network (e.g. running on a phone which is leaving the home) can (and should) remove its subscrip­ +tions and send this UnregisterClient command before leaving to prevent the burden on the ICD of +an absent client. + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 CheckInN­ +odeID +``` +``` +node-id all M +``` +``` +1 Verification­ +Key +``` +``` +octstr 16 O +``` +**9.17.7.3.1. CheckInNodeID Field** + +This field SHALL provide the registered client node ID to remove from storage. + +**9.17.7.3.2. VerificationKey Field** + +This field SHALL provide the verification key associated with the CheckInNodeID to remove from +storage. The verification key represents the key already stored on the server. The verification key +provided in this field SHALL be used by the server to guarantee that a client with manage permis­ +sions can only remove entries that contain a Key equal to the stored key. The verification key +SHALL be provided for clients with manage permissions. The verification key SHOULD NOT be pro­ +vided by clients with administrator permissions for the server cluster. The verification key SHALL +be ignored by the server if it is provided by a client with administrator permissions for the server +cluster. + +**9.17.7.3.3. Effect on Receipt** + +On receipt of the UnregisterClient command, the server SHALL perform the following procedure: + +1. The server SHALL check whether there is a entry stored on the device for the fabric with the + same CheckInNodeID. + a.If there are no entries stored for the fabric, the status SHALL be NOT_FOUND. The server + SHALL continue from step 6. + +``` +Page 672 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +b. If there is an error when reading from storage, the status SHALL be FAILURE. The server +SHALL continue from step 6. +c. If there is at least one entry stored on the server for the fabric, the server SHALL continue +from step 2. +``` +2. The server SHALL verify if one of the entries for the fabric has the corresponding CheckInN­ + odeID received in the command. + a. If no entries have the corresponding CheckInNodeID, the status SHALL be NOT_FOUND. The + server SHALL continue from step 6. + b. If an entry has the corresponding CheckInNodeID, the server SHALL continue to step 3. +3. The server SHALL check whether the ISD of the command has administrator permissions for + the server cluster. + a. If the ISD of the command has administrator privileges for the server cluster, the server + SHALL continue from step 5. + b. If the ISD of the command does not have administrator privileges for the server cluster, the + server SHALL continue from step 4. +4. The server SHALL verify that the received verification key is equal to the key previously stored + in the list of registered clients with the matching CheckInNodeID. + a. If the verification key does not have a valid value, the status SHALL be FAILURE. the server + SHALL continue from step 6. + b. If the verification key is not equal to the Key value stored in the entry, the status SHALL be + FAILURE. The server SHALL continue from step 6. +c. If the verification key is equal to the Key value stored in the entry, the server SHALL con­ +tinue from step 5. +5. The server SHALL delete the entry with the matching CheckInNodeID from storage and will per­ + sist the change. + a. If the removal of the entry fails, the status SHALL be FAILURE. The server SHALL continue + from step 6. + b. If the removal succeeds, the status SHALL be SUCCESS and the server SHALL continue to + step 6. +6. The server SHALL generate a response with the Status field set to the evaluated status. + +**9.17.7.4. StayActiveRequest Command** + +This command allows a client to request that the server stays in active mode for at least a given +time duration (in milliseconds) from when this command is received. + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StayActive­ +Duration +``` +``` +uint32 all M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 673 +``` + +This StayActiveDuration MAY be longer than the ActiveModeThreshold value and would, typically, be +used by the client to request the server to stay active and responsive for this period to allow a +sequence of message exchanges during that period. The client MAY slightly overestimate the dura­ +tion it wants the ICD to be active for, in order to account for network delays. + +**9.17.7.4.1. Effect on Receipt** + +When receiving a StayActiveRequest command, the server SHALL calculate the maximum +PromisedActiveDuration it can remain active as the greater of the following two values: + +- StayActiveDuration`: Specified in the received command by the client. +- Remaining Active Time: The server’s planned remaining active time based on the ActiveMode­ + Threshold and its internal resources and power budget. + +A server MAY replace StayActiveDuration with Minimum Active Duration in the above calculation. + +PromisedActiveDuration represents the guaranteed minimum time the server will remain active, +taking into account both the requested duration and the server’s capabilities. + +The ICD SHALL report the calculated PromisedActiveDuration in a StayActiveResponse message back +to the client. + +**9.17.7.5. StayActiveResponse Command** + +This message SHALL be sent by the ICD in response to the StayActiveRequest command and SHALL +contain the computed duration (in milliseconds) that the ICD intends to stay active for. + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PromisedAc +tiveDura­ +tion +``` +``` +uint32 desc M +``` +**9.17.7.5.1. PromisedActiveDuration Field** + +This field SHALL provide the actual duration that the ICD server can stay active from the time it +receives the StayActiveRequest command. + +**Minimum Value for PromisedActiveDuration** + +The minimum value of the PromisedActiveDuration field SHALL be equal to either 30000 millisec­ +onds or StayActiveDuration (from the received StayActiveRequest command), whichever is smaller. + +``` +Example scenarios: +``` +- A Client requests an ICD to stay awake for 20000 milliseconds in its StayActiveDuration + field. The ICD responds with 20000 in its PromisedActiveDuration if it can stay active for + +``` +Page 674 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +that duration. +``` +- A Client requests an ICD to stay awake for 35000 milliseconds in its StayActiveDuration + field. The ICD responds with 30000 in its PromisedActiveDuration since it can only stay + active for that minimal amount. +- A Client requests an ICD to stay awake for 10000 milliseconds in its StayActiveDuration + field, but the ICD’s remaining active time is 20000 milliseconds. The ICD responds with + 20000 milliseconds in its PromisedActiveDuration field since it intends to stay active that + long. + +**9.18. Ecosystem Information Cluster** + +The Ecosystem Information Cluster provides extended device information for all the logical devices +represented by a Bridged Node. The Ecosystem Information Cluster presents the view of device +name and location metadata for presentation by a client of the cluster to a user. This cluster is +intended to support Fabric Synchronization and be present on an endpoint with the BridgedNode +device type listed in the DeviceTypeList of the endpoint’s Descriptor cluster. + +This augments the Bridged Device Basic Information Cluster in the following ways: + +- The Ecosystem Information Cluster adds support for providing a name and location for individ­ + ual endpoints. (The endpoints do not need to be present on the Bridge for their name and loca­ + tion information to be present.) +- The Ecosystem Information Cluster adds metadata to support conflict resolution between multi­ + ple sources of the name and location data. +- The Ecosystem Information Cluster supports user control for the presence of the name and loca­ + tion information by specifying more restricted access. + +A client SHOULD use the information provided by the Ecosystem Information Cluster to help the +user organize and interact with their devices. Some examples may include: + +- Directly organizing and labeling the devices in a client’s user interface. +- Providing hints in the user interface, which can assist the user in organizing and labeling their + devices. + +For the purposes of the Ecosystem Information Cluster section, an instance of the Ecosystem Infor­ +mation Cluster will be referred to as an "instance". + +**9.18.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 675 +``` + +**9.18.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Endpoint ECOINFO +``` +**9.18.3. Cluster ID** + +``` +ID Name +0x0750 Ecosystem Information +``` +**9.18.4. Data Types** + +**9.18.4.1. EcosystemDeviceStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Device­ +Name +``` +``` +string max 64 empty S O +``` +``` +1 Device­ +Name­ +LastEdit +``` +``` +epoch-us all 0 S desc +``` +``` +2 Bridge­ +dEndpoint +``` +``` +endpoint- +no +``` +``` +desc S desc +``` +``` +3 Original­ +Endpoint +``` +``` +endpoint- +no +``` +``` +desc S desc +``` +``` +4 Device­ +Types +``` +``` +list[Device­ +Type­ +Struct] +``` +``` +desc S M +``` +``` +5 UniqueLo­ +cationIDs +``` +``` +list[string] max 64 +[max 64] +``` +### S M + +``` +6 UniqueLo­ +cationID­ +sLastEdit +``` +``` +epoch-us all 0 S M +``` +**9.18.4.1.1. DeviceName Field** + +This field SHALL indicate the device’s name, which is provided externally if the user consents. (For +example, provided by the user in an ecosystem specific interface.) + +**9.18.4.1.2. DeviceNameLastEdit Field** + +This field SHALL be present and set if the DeviceName field is present. + +``` +Page 676 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +This field SHALL indicate the timestamp of when the DeviceName was last modified. + +**9.18.4.1.3. BridgedEndpoint Field** + +This field SHALL indicate the endpoint this EcosystemDeviceStruct is associated with on this Bridge. + +This field SHALL be present and set to a valid endpoint if the device is accessible through the +bridge. + +**9.18.4.1.4. OriginalEndpoint Field** + +This field SHALL indicate the endpoint this EcosystemDeviceStruct is associated with on the origi­ +nal device represented by this bridge’s Bridged Node. If this bridge is receiving the device from +another bridge, then the OriginalEndpoint field value would be the same on both bridges. This field +SHALL be present and set to a valid endpoint on the original device if that device is a Matter device. + +**9.18.4.1.5. DeviceTypes Field** + +This field SHALL indicate all of the DeviceTypes within the DeviceTypeList in the Descriptor Cluster +associated with this EcosystemDeviceStruct entry. + +This field SHALL contain a list of valid device type ids. + +**9.18.4.1.6. UniqueLocationIDs Field** + +This field SHALL specify the EcosystemLocationStruct entries in the LocationDirectory attribute +associated with this EcosystemDeviceStruct. + +**9.18.4.1.7. UniqueLocationIDsLastEdit Field** + +This field SHALL indicate the timestamp of when the UniqueLocationIDs was last modified. + +### NOTE + +``` +If multiple server instances update the UniqueLocationIDs field at the same time, it +is possible one of the updates will be missed. This is considered an acceptable limi­ +tation to reduce the complexity of the design. Since this is meant to be provided +from user input, it is unlikely these signals would be happening at one time. +``` +**9.18.4.2. EcosystemLocationStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 UniqueLo­ +cationID +``` +``` +string max 64 S M +``` +``` +1 Location­ +Descriptor +``` +``` +location­ +desc +``` +### S M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 677 +``` + +``` +Access Quality: Fabric Scoped +2 Location­ +Descrip­ +torLastE­ +dit +``` +``` +epoch-us 0 S M +``` +**9.18.4.2.1. UniqueLocationID Field** + +This field SHALL indicate a unique identifier for a specific Ecosystem Information Cluster server +instance representing the location independent of its LocationDescriptor field. + +UniqueLocationID can be used by the client to determine if the change is a relocation of the device +or just a renaming of the location. + +No guarantees are given for consistency of the ID between server instances. The same location may +be represented by different IDs on different Ecosystem Information Cluster server instances, so +only the history from a single server instance should be considered when evaluating a change. + +UniqueLocationID SHALL be changed when the LocationDescriptor changes from one existing loca­ +tion to another location as a result of an external interaction. (For example, the user changes the +location assignment.) + +UniqueLocationID SHALL NOT be changed when the LocationDescriptor changes name, but still +represents the same location. (For example, the user renames a room.) + +UniqueLocationID SHALL be changed when LocationDescriptor changes as a result of another +Ecosystem Information Cluster server instance changing and the UniqueLocationID on the remote +server instance also changes. + +UniqueLocationID SHALL NOT be changed when LocationDescriptor changes as a result of another +Ecosystem Information Cluster server instance changing and the UniqueLocationID on the remote +server instance does not change. + +**9.18.4.2.2. LocationDescriptor Field** + +This field SHALL indicate the location (e.g. living room, driveway) and associated metadata that is +provided externally if the user consents. (For example, provided by the user in an ecosystem spe­ +cific interface.) + +"Location" in this context is typically used by the user’s grouping into rooms, areas or other logical +groupings of how devices are used. So a device might be part of multiple such "Locations"s. + +**9.18.4.2.3. LocationDescriptorLastEdit Field** + +This field SHALL indicate the timestamp of when the LocationDescriptor was last modified. + +**9.18.5. Attributes** + +``` +Page 678 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 DeviceDi­ +rectory +``` +``` +list[Ecosys­ +temDe­ +viceStruct] +``` +### N R M F M + +``` +0x0001 Loca­ +tionDirec­ +tory +``` +``` +list[Ecosys­ +temLoca­ +tionStruct] +``` +### N R M F M + +### NOTE + +``` +The DeviceDirectory and LocationDirectory attributes are Fabric Scoped with Fabric +Sensitive fields. The user may direct an ecosystem to disable sharing of user gener­ +ated data with specific fabrics in the DeviceDirectory and LocationDirectory attrib­ +utes. This can result in a client ecosystem receiving a list of entries scoped only to +other fabrics (with only the fabric index visible since all other fields are fabric sen­ +sitive) if the user has disabled sharing of user generated data with specific fabrics. +``` +**9.18.5.1. DeviceDirectory Attribute** + +This attribute SHALL contain the list of logical devices represented by a Bridged Node. Most of the +time this will contain a single entry, but may grow with more complex device compositions (e.g. +another bridge.) + +An empty list indicates that the information is not available. + +**9.18.5.2. LocationDirectory Attribute** + +This attribute SHALL contain the list of rooms, areas and groups associated with the DeviceDirec­ +tory entries, and SHALL NOT contain locations which are dynamically generated and removed by +an ecosystem. (E.g. a location that is generated and removed based on the user being home is not +permitted. However, an initially generated location name that does not quickly change is accept­ +able.) + +An empty list indicates that the information is not available. + +LocationDirectory entries SHALL be removed if there is no DeviceDirectory that references it. + +**9.18.6. Examples** + +**9.18.6.1. Bridged Node with One Device and Two Locations** + +In the example below, there is a single ecosystem representation of a device for the Bridged Node. +The user has configured the name "Dimmable Light" for that device and configured it into two loca­ +tions in the ecosystem (the "Living Room" is on the "First Floor" so the device can be in two loca­ +tions). + +This example demonstrates the relationship between DeviceDirectory and LocationDirectory, syn­ +chronization data is omitted for clarity. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 679 +``` + +_Figure 81. Ecosystem Information Cluster Examples - One Device, Two Locations_ + +**9.18.6.2. Bridged Node with Two DeviceName and Two Locations** + +In the example below, there are ecosystem representations of two devices for the Bridged Node. +The user has configured them named "Outlet 1" and "Outlet 2". The devices are each configured by +the user to be in a single location in the ecosystem. + +This example demonstrates the relationship between DeviceDirectory and LocationDirectory, syn­ +chronization data is omitted for clarity. + +_Figure 82. Ecosystem Information Cluster Examples - Two Devices, Two Locations_ + +``` +Page 680 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 10. Interaction Model Encoding** + +**Specification** + +**10.1. Overview** + +This specification details the encoding of the Interaction Model (IM) in the Matter TLV format. + +Specifically, it details the encoding of the application payload for Matter messages that map to the +Interaction Model. The details of the message header are described in Section 4.4, “Message Frame +Format” and out of scope of this document. + +**10.2. Messages** + +**10.2.1. IM Protocol Messages** + +Each Action in the IM specification SHALL be mapped to a message with a unique Protocol Opcode, +namespaced under the PROTOCOL_ID_INTERACTION_MODEL Protocol ID. + +- Vendor ID = 0x0000 (Matter Common) +- Protocol ID = PROTOCOL_ID_INTERACTION_MODEL + +``` +Protocol Opcode Action Message +0x01 Status Response StatusResponseMessage +0x02 Read Request ReadRequestMessage +0x03 Subscribe Request SubscribeRequestMessage +0x04 Subscribe Response SubscribeResponseMessage +0x05 Report Data ReportDataMessage +0x06 Write Request WriteRequestMessage +0x07 Write Response WriteResponseMessage +0x08 Invoke Request InvokeRequestMessage +0x09 Invoke Response InvokeResponseMessage +0x0A Timed Request TimedRequestMessage +``` +**10.2.2. Common Action Information Encoding** + +Every action SHALL encode the fields specified in Section 8.2.5.1, “Common Action Information”. +The methods for encoding Common Action Information fields are: + +- As a field in the message header +- As a context tagged field in the action payload + +For every field appearing in TLV-encoded data described by the schemas of the following sections, + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 681 +``` + +and where a context-specific tag is used, any context-specific tag not listed in a given schema +SHALL be reserved for future use and SHALL be silently ignored by clients and servers if seen in a +payload. + +**10.2.2.1. Message Header Encoded Action Information** + +The following Common Action Information fields are encoded into the message header: + +``` +Header Field Type Description +Message Exchange ID 16-bit integer Used to convey the Transaction +ID +Source Node ID 64-bit integer Node ID of the source that gen­ +erated the transaction +Destination ID 64-bit integer Either a Node ID or Group ID is +encoded in here depending on +what the IM indicates +Protocol ID 32 bits The protocol to which this mes­ +sage belongs; all messages in +this spec SHALL use the PROTO­ +COL_ID_INTERACTION_MODEL Proto­ +col ID +Protocol OpCode 8 bits The specific message type +``` +**10.2.2.2. Context Tag Encoded Action Information** + +The following Common Action Information fields are encoded as context tagged fields in the action +message payload. All action messages defined in Section 10.7, “Message Definitions” SHALL include +these tagged fields: + +``` +Common Action Field Context Tag +InteractionModelRevision 0xFF +``` +**10.2.3. Chunking** + +Chunking is the act of splitting an Action that contains attribute/event data, specifically ReportData +and WriteRequest actions, into multiple messages at logical boundaries due to the size limitations +imposed by IPv6 for UDP packets (see Section 4.4.4, “Message Size Requirements” for more details). + +Since attribute/event data within Actions are already organized into a series of AttributeDataIBs +(for attributes) and EventDataIBs for event records, chunking entails maximally packing these +information blocks (IBs) into a series of 'data' messages. + +To ensure in-order delivery of a chunked set of IBs, each data message requires a response before +the next data message can be sent. For ReportDataMessage and WriteRequestMessage, a StatusRe­ +sponseMessage and WriteResponseMessage are the respective response messages. + +A MoreChunkedMessages flag SHALL be set on every data message except the last to convey to the + +``` +Page 682 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +receiver possible delivery of more chunked messages within a given Action. This is specified in the +WriteRequestMessage and ReportDataMessage. + +While most data types can be easily encoded in this scheme to fit within a message, the fact that +lists can be of variable, and arbitrary, length can lead to complications. Specific strategies to encode +lists that are chunking friendly are provided in Section 10.6.4.3.1, “Lists”. + +**10.2.4. Transaction Flows** + +**10.2.4.1. Read (Success)** + +_Figure 83. Read message flow_ + +**10.2.4.2. Read (Server Error)** + +_Figure 84. Read message with server-side error flow_ + +**10.2.4.3. Read (Client Error)** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 683 +``` + +_Figure 85. Read message with client-side error flow_ + +**10.2.4.4. Write (Success)** + +_Figure 86. Write message flow_ + +**10.2.4.5. Write (Server Error)** + +_Figure 87. Write message with server-side error flow_ + +**10.2.4.6. Subscribe (Success)** + +``` +Page 684 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 88. Subscription flow_ + +**10.2.4.7. Subscribe (Server Error)** + +_Figure 89. Subscription with server-side error flow_ + +**10.2.4.8. Subscribe (Client Error)** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 685 +``` + +_Figure 90. Subscription with client-side error flow_ + +**10.3. Data Types** + +The IM specification defines a number of schema data types that are usable in a given cluster +schema definition. + +This section will outline their encoding onto TLV wire types, and their specific representations. + +``` +Class Schema Data Type TLV Type +Analog uint8, uint16, uint24, uint32, +uint40, uint48, uint56, uint64 +``` +``` +Unsigned Integer (width is +selected automatically depend­ +ing on data value) +int8, int16, int24, int32, int40, +int48, int56, int64 +``` +``` +Signed Integer (width is +selected automatically depend­ +ing on data value) +float32 Floating Point Number, 4-byte +value +float64 Floating Point Number, 8-byte +value +``` +``` +Page 686 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Class Schema Data Type TLV Type +Discrete enum8, enum16 Unsigned Integer (width is +selected automatically depend­ +ing on data value) +data8, data16, data32, data64 Unsigned Integer (width is +selected automatically depend­ +ing on data value) +map8, map16, map32, map64 Unsigned Integer (width is +selected automatically depend­ +ing on data value) +boolean Boolean +Composite string UTF-8 string (length is selected +automatically depending on +data value) +octstr TLV octet string +Collection list TLV array +struct TLV structure +``` +**10.3.1. Analog - Integer** + +All signed integer schema types SHALL be encoded using the TLV signed integer type. The specific +TLV element type (1-byte, 2-byte, 4-byte and 8-byte signed integer types) SHALL be selected auto­ +matically at runtime depending on the actual value. + +In this regard, the actual width of the over-the-wire type can be narrower than the width specified +in schema. + +E.g. a 32-bit value defined in schema will be encoded to a 1-byte TLV signed integer type if the value +doesn’t exceed (-128 to +127). + +Similarly, all unsigned integer schema types SHALL be encoded using the TLV unsigned integer +type. + +**10.3.2. Analog - Floating Point** + +Both single and double precision floating point analog schema types SHALL be encoded using +equivalent TLV floating point types as well. + +**10.3.3. Discrete - Enumeration** + +Enumerations SHALL be encoded using the TLV unsigned integer type, with the width selected +automatically at runtime based on the actual value. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 687 +``` + +**10.3.4. Discrete - Bitmap** + +Bitmaps SHALL be encoded using the TLV unsigned integer type, with the width selected automati­ +cally at runtime based on the actual value. + +**10.3.5. Composite - String** + +While strings are a derived data type, they SHALL be encoded using the TLV UTF-8 string type. + +**10.3.6. Composite - Octet String** + +Octet strings SHALL be encoded using TLV Byte Strings. + +**10.3.7. Collection - Struct** + +Structure types in schema SHALL be encoded using the TLV structure type. + +**10.3.8. Collection - List** + +The entirety of a list SHALL be encoded as a TLV array. + +A list index SHALL start at 0. + +Lists SHALL have a maximum size of 65535 elements (2^16 -1). + +**10.3.9. Derived Types** + +All derived types (with the exception of strings) SHALL be encoded according to their base type. + +**10.3.10. Field IDs** + +Field IDs SHALL be encoded as: + +- A context tag when the MEI prefix encodes a standard/scoped source. +- A fully-qualified profile-specific tag when the MEI prefix encodes a manufacturer code. The + Vendor ID SHALL be set to the manufacturer code, the profile number set to 0 and the tag num­ + ber set to the MEI suffix. + +``` +NOTE Support for encoding Field IDs with an MC source is provisional. +``` +**10.4. Sample Clusters** + +This section defines sample clusters (with attributes, events, and commands) for illustrative pur­ +poses; they SHALL NOT be interpreted as real clusters. + +**10.4.1. Disco Ball Cluster** + +This example cluster controls an imaginary mirrored disco ball, for the express purpose of disco + +``` +Page 688 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +dancing. + +**10.4.1.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Deprecated Off enum value in Rotate attribute +3 Added pattern list feature +4 Added Name attribute +5 Added Reverse feature +6 Updated columns from Data & Interaction Model +specs +7 Deprecated Party feature +8 Added WobbleSupport and WobbleSetting +9 Made Pattern attribute non-volatile +``` +**10.4.1.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint DISCO +``` +**10.4.1.3. Cluster ID** + +``` +ID Name +0x3456 Disco Ball +``` +**10.4.1.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 PTY Party D Deprecated fea­ +ture +1 AX Axis O Allows the disco +ball rotational axis +to change +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 689 +``` + +``` +Bit Code Feature Conformance Summary +2 WBL Wobble O Allows the disco +ball to wobble on +its axis as speed +(dependent on +Axis) +3 PAT Pattern O Supports a list of +patterns to cycle +through automati­ +cally +4 STA Statistics O Supports a request +to statistics +5 REV Reverse P, O Supports a +Reverse command +and counterclock­ +wise rotation +``` +``` +Spec Writer Note +Describe features each in a separate section (if needed). +``` +**10.4.1.4.1. Statistics Feature** + +This feature indicates the ability to collect and read out statistics regarding the usage of the Disco +Ball. + +**10.4.1.5. Data Types** + +**10.4.1.5.1. WobbleBitmap Type** + +This data type is derived from map8. + +``` +Bit Name Summary Conformance +0 Perpendicular Indicate wobble per­ +pendicular to axis +``` +### O + +``` +1 AlongAxis Indicate wobble along +Axis +``` +### O + +``` +2 Around Indicate wobble +around +``` +### O + +**10.4.1.5.2. RotateEnum Type** + +This data type is derived from enum8. + +``` +Page 690 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0 Off Deprecated D* +1 Clockwise Rotation is currently +clockwise +``` +### M + +``` +2 CounterClockwise Rotation is currently +counterclockwise +``` +### REV + +``` +*Spec Writer Note +"D" means deprecated. +``` +**Clockwise Value** + +This value SHALL indicate that the disco ball is rotating in the clockwise direction + +**CounterClockwise Value** + +This value SHALL indicate that the disco ball is rotating in the counterclockwise direction + +``` +Spec Writer Note +Description sections are optional and should only be present, if additional details are needed +for a given enum value +``` +**10.4.1.5.3. PatternStruct Type** + +This indicates a pattern of operation for a running disco ball. + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Duration uint16 all 0 M +1 Rotate Rota­ +teEnum +``` +``` +desc X* null* M +``` +``` +2 Speed uint8 max 200 X null M +3 Axis uint8 max 90 X null AX | WBL +4 Wobble­ +Speed +``` +``` +uint8 max 200 X null WBL**, O +``` +``` +5 Passcode string max 6 X null S M +``` +``` +*Spec Writer Note +Nullable data ("X") means that in some cases, the data can be null. Null data meaning must +be defined (as it is below). +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 691 +``` + +``` +**Conformance +"WBL, O" means mandatory for WBL feature, otherwise optional. +``` +**Duration Field** + +This field SHALL indicate the time in seconds for the disco ball to perform the pattern. + +**Rotate Field** + +This field SHALL indicate the rotation direction or null to not change the direction. + +**Speed Field** + +This field SHALL indicate the speed of the rotation, or null to not change the speed. + +**Axis Field** + +This field SHALL indicate the angle of the axis of rotation, or null to not change the angle. + +**WobbleSpeed Field** + +This field SHALL indicate the speed of the axis wobble, or null to not change the speed. + +**Passcode Field** + +An optionally specified passcode that if present, needs to always be provided in the Pattern Request +command to successfully invoke this pattern. + +**10.4.1.6. Status Codes** + +**10.4.1.6.1. StatusCodeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary +0x02* UNSUPPORTED_PATTERN The movement pattern is +unsupported on the device even +though all values are within +constraints +``` +``` +*Spec Writer Note +The list contains cluster specific status codes only indicated for a particular instance of this +cluster. +``` +``` +The list SHALL start at 2, after the global error status values of 0 for SUCCESS and 1 for +FAILURE. +``` +``` +Page 692 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.4.1.7. Attributes** + +``` +Spec Writer Note +Attributes are supported by the server cluster only. +``` +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Run bool all* 0 R V M +0x0001 Rotate Rota­ +teEnum +``` +``` +all 0 R V M +``` +``` +0x0002 Speed uint8 0 to 200* 0 R V M +0x0003 Axis uint8 0 to 90 0 RW VO AX | WBL +0x0004 Wobble­ +Speed +``` +``` +uint8 0 to 200 0 RW VO WBL +``` +``` +0x0005 Patterns list[Pat­ +ternStruct] +``` +``` +max 16* N* 0 RW VM T* PAT +``` +``` +0x0006 Name string max 16 N 0 RW VM P, O +0x0007 Wobble­ +Support +``` +``` +Wob­ +bleBitmap +``` +``` +desc R V WobbleSet­ +ting +0x0008 Wobble­ +Setting +``` +``` +Wob­ +bleBitmap +``` +``` +desc RW VM [WBL] +``` +``` +*Spec Writer Note +Constraint +``` +- "all" _means all possible values._ +- "desc" _means see attribute description for constraints on attribute._ +- _"X_ to _Y" means a value range from X=minimum to Y=maximum value._ +- "max _X" means range or maximum number of entries for a list or bytes for a string type_ + _derived from octstr._ +**Quality** +- "N" _indicates the read only, write only or read & write value is non-volatile across +restarts._ +- "F" _indicates that the read-only value is static (fixed) and will not change in the future +(like the ClusterRevision attribute)._ +- _If there is no_ "N" _or_ "F" _then the value is volatile such that the value of the attribute may +change at some point in the future._ +**Access** +- _Access column indicates R=Read Only, RW=Read Write, R*W=Read [Write], T=Timed +Write, View=Read, Operate=Write, Manage=Write, Administer=Write for ACL processing_. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 693 +``` + +``` +Conformance +``` +- _Any attribute that is "M" is part of the base mandatory feature set. "O" is purely optional._ +- _To support the Axis feature any attribute with "AX" conformance must be supported (see_ + _Data Model)._ +- _To support the Wobble feature any attribute with WBL conformance must be supported_ + _(see Data Model)._ +- _"AX | WBL" means either feature mandates this attribute. If neither are true, then the_ + _attribute is not allowed._ +- _"AX & WBL" would require both features supported to mandate._ +- _"[PAT]" means optional for Pattern feature._ +- _"P, O" means provisional otherwise optional (after it’s no longer provisional)._ +- _The name of another attribute in the conformance column means the attribute is manda­_ + _tory if the other attribute is supported. Conformance based on the presence of another_ + _attribute can be made optional by using [ ]. Conformance MAY be set using any element in_ + _the same table._ + +**10.4.1.7.1. Run Attribute** + +This attribute SHALL indicate if the disco ball is operating. If the Run attribute is 0, then the Speed, +Rotate and WobbleSpeed attributes SHALL be 0. + +**10.4.1.7.2. Rotate Attribute** + +This attribute SHALL indicate the direction of rotation either clockwise or counterclockwise. + +**10.4.1.7.3. Speed Attribute** + +This attribute SHALL indicate the speed of the disco ball in revolutions per minute. + +**10.4.1.7.4. Axis Attribute** + +This attribute SHALL indicate the tilt of the axis of the disco ball, in degrees. + +**10.4.1.7.5. WobbleSpeed Attribute** + +This attribute SHALL indicate the speed of the wobble rotation in revolutions per minute. + +**10.4.1.7.6. Pattern Attribute** + +This attribute SHALL contain an ordered list of pattern entries. This list of patterns SHALL be used +to operate the disco ball when the Pattern Request command is invoked. + +**10.4.1.7.7. Name Attribute** + +This attribute SHALL indicate a display name. + +``` +Page 694 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.4.1.7.8. WobbleSupport Attribute** + +This attribute SHALL indicate the bits of the WobbleBitmap supported by the device. + +**10.4.1.7.9. WobbleSetting Attribute** + +This attribute SHALL indicate the selected type of wobble. This attribute is constrained to, in case of +a write interaction, only accept the bits indicated in the WobbleSupport attribute. + +**10.4.1.8. Commands** + +``` +Spec Writer Note +Commands are supported by the client & server, but always initiated by the client. +``` +``` +ID Name Direction Response** Access Quality Confor­ +mance +0x00 StartRe­ +quest +``` +``` +client ⇒ +server +``` +### Y O M + +``` +0x01 StopRequest client ⇒ +server +``` +### Y O M + +``` +0x02 ReverseReq +uest +``` +``` +client ⇒ +server +``` +### Y O REV + +``` +0x03 Wob­ +bleRequest +``` +``` +client ⇒ +server +``` +### Y O WBL + +``` +0x04 PatternRe­ +quest +``` +``` +client ⇒ +server +``` +### Y M T* PAT + +``` +0x05 StatsRe­ +quest +``` +``` +client ⇒ +server +``` +``` +StatsRe­ +sponse** +``` +### O STA + +``` +0x06 StatsRe­ +sponse +``` +``` +client ⇐ +server +``` +### N O STA + +``` +*Spec Writer Note +Commands are operable (O) with Invoke. Commands are operable with Timed (T) Invoke +only. +``` +``` +**Spec Writer Note +"StatsRequest" command has a "StatsResponse" command. "Y" means that the command +requires just a status in the Invoke Response. "N" means no response required (most +response commands do not need a response). +``` +**10.4.1.8.1. StartRequest Command** + +Upon receipt, this SHALL start the disco ball rotating using the data as follows: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 695 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Speed uint8 max 200 MS* M +1 Rotate RotateEnum all Clockwise O +``` +``` +*Spec Writer Note +"MS" means Manufacturer Specific. +``` +**Speed Field** + +This field SHALL indicate the rotation speed. + +**Rotate Field** + +This field SHALL indicate the rotation direction. + +**10.4.1.8.2. StopRequest Command** + +Upon receipt, this SHALL stop the disco ball rotating, and SHALL set the Run, Speed and Rotate +attributes to 0. + +**10.4.1.8.3. ReverseRequest Command** + +Upon receipt, this SHALL reverse the direction of the disco ball rotation. This command MAY gener­ +ate an error response of UNSUPPORTED_PATTERN. + +**10.4.1.8.4. WobbleRequest Command** + +Upon receipt, this SHALL wobble the disco ball on its axis at the speed in the WobbleSpeed +attribute. This command MAY generate an error response of UNSUPPORTED_PATTERN. + +**10.4.1.8.5. PatternRequest Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Passcode string max 6 empty M +``` +**Passcode Field** + +If the passcode field is an empty string, this SHALL start the disco ball rotating using unprotected +(i.e patterns that have no passcode) pattern list entries in sequence to control the disco ball. When +the final entry in the list is processed the sequence SHALL restart at the first entry. + +If the passcode field is not an empty string, only the patterns that correspond to the provided pass­ +code SHALL be invoked. + +``` +Page 696 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.4.1.8.6. StatsRequest Command** + +Upon receipt, this SHALL generate a StatsResponse command. + +**10.4.1.8.7. StatsResponse Command** + +This command SHALL be generated in response to a StatsRequest command. The data for this com­ +mand SHALL be as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 LastRun uint32 all 0 M +1 NumPat­ +tern­ +sChanged +``` +``` +uint32 all 0 [PAT] * +``` +``` +*Spec Writer Note +Patterns field is an optional only for the PAT feature. +``` +**LastRun Field** + +This field SHALL indicate the duration in seconds for the last time the disco ball was run. + +**NumPatternsChanged Field** + +This field SHALL indicate the number of pattern changes from the Patterns attribute within the last +run time. + +**10.4.1.9. Events** + +``` +Spec Writer Note +Events are supported by the server cluster only. +``` +``` +ID Name Priority Access Conformance +0x00 Started INFO V* M +0x01 Stopped INFO V M +0x02 PatternChange INFO V [PAT] +``` +``` +*Spec Writer Note +All events are viewable (V). +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 697 +``` + +**10.4.1.9.1. Started Event** + +This event SHALL be generated, when the Run attribute changes from false to true. + +**10.4.1.9.2. Stopped Event** + +This event SHALL be generated, when the Run attribute changes from true to false. + +**10.4.1.9.3. PatternChange Event** + +This event SHALL be generated when the Rotate, Speed, or WobbleSpeed attributes are written or +changed locally as the result of processing the Pattern attribute. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 PrevPattern Pattern­ +Struct +``` +``` +X null M +``` +``` +1 CurPattern Pattern­ +Struct +``` +### M + +``` +2 NextPattern Pattern­ +Struct +``` +``` +X null M +``` +``` +3 Label string max 32 X null O +``` +**PrevPattern Field** + +This field SHALL be the previous pattern run. If there is no previous pattern, then PrevPattern +SHALL be null. + +**CurPattern Field** + +This field SHALL be the current pattern being run. + +**NextPattern Field** + +This field SHALL be the next in the pattern list. If there is no next pattern, the NextPattern event +field SHALL be null. + +**Label Field** + +This field SHALL indicate additional readable text that describes the reason for the pattern change. + +**10.4.2. Super Disco Ball Cluster** + +This is derived* from the Disco Ball cluster, with overrides for qualities and conformance. + +``` +*Spec Writer Note +This is an example of a derived cluster, where only stricter conformance overrides, and +the Name attribute gets a longer allowed length. If both the Disco Ball and Super Disco Ball +``` +``` +Page 698 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +server clusters are on the same endpoint, they would represent a singleton instance of a +cluster. This allows legacy clients implemented before the Super Disco Ball was specified +to still interoperate. Blank column entries define no change to the qualities. +``` +**10.4.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**10.4.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Disco Ball Application Endpoint SUPDISC +``` +**10.4.2.3. Cluster ID** + +``` +ID Name +0xBBCC Super Disco Ball +``` +**10.4.2.4. Features** + +``` +Bit Code Feature Conformance Summary +0 PTY Party D Deprecated fea­ +ture +1 AX Axis M Allows the disco +ball rotational axis +to change +2 WBL Wobble M Allows the disco +ball to wobble on +its axis as speed +(dependent on +Axis) +3 PAT Pattern M Supports a list of +patterns to cycle +through automati­ +cally +4 STA Statistics M Supports a request +to statistics +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 699 +``` + +``` +Bit Code Feature Conformance Summary +5 REV Reverse P, M Supports a +Reverse command +and counterclock­ +wise rotation +``` +**10.4.2.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Run M +0x0001 Rotate M +0x0002 Speed M +0x0003 Axis AX | WBL +0x0004 Wobble­ +Speed +``` +### WBL + +``` +0x0005 Pattern PAT +0x0006 Name max 32 P, M +0x0007 Wobble­ +Support +``` +### [WBL] + +``` +0x0008 Wobble­ +Setting +``` +### [WBL] + +**10.4.2.6. Events** + +``` +ID Name Priority Access Conformance +0x00 Started M +0x01 Stopped M +0x02 PatternChange PAT +``` +**10.5. Sample Device Types** + +This section defines sample device types based on the Section 10.4, “Sample Clusters” for illustrative +purposes; they SHALL NOT be interpreted as real device types. + +**10.5.1. Disco Ball Device Type** + +This defines conformance to the example Disco Ball device type. + +**10.5.1.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is + +``` +Page 700 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Attribute Name access changed to Administer +3 Initial Matter release +``` +**10.5.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x5678 Disco Ball Simple Endpoint +``` +**10.5.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**10.5.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +0x3456 Disco Ball Server M +``` +**10.5.1.4.1. Identify Cluster** + +This is used to identify the endpoint. + +``` +Spec Writer Note +Describe each cluster use with normative requirements in a separate section (like this if +needed). +``` +**10.5.1.4.2. Disco Ball Cluster** + +This is what controls the disco ball. + +**10.5.1.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 701 +``` + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x3456 Disco Ball Feature Pattern Ethernet | +Wi-Fi +0x3456 Disco Ball Feature Statistics Ethernet | +Wi-Fi +0x3456 Disco Ball Attribute Name max 10 VA Matter +0x3456 Disco Ball Event Field Pattern­ +Change.Labe +l +``` +### M + +**10.5.2. Super Disco Ball Device Type** + +This defines conformance to the example Super Disco Ball device type. + +**10.5.2.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**10.5.2.2. Classification** + +``` +ID Device Name Superset Class +0x3457 Super Disco Ball Disco Ball Simple +``` +**10.5.2.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**10.5.2.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +0x3456 Super Disco Ball Server M +``` +**10.5.2.4.1. Identify Cluster** + +This is used to identify the endpoint. + +``` +Page 702 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.5.2.4.2. Super Disco Ball Cluster** + +This is what controls the super disco ball. + +**10.5.2.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x3456 Disco Ball Feature Pattern Ethernet | +Wi-Fi +0x3456 Disco Ball Feature Statistics Ethernet | +Wi-Fi +0x3456 Disco Ball Attribute Name max 10 VA Matter +0x3456 Disco Ball Event Field Pattern­ +Change.Labe +l +``` +### M + +**10.5.3. Disco Spot Device Type** + +This defines a spot light that shines on a disco ball to create a disco dancing experience. + +**10.5.3.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**10.5.3.2. Classification** + +``` +*Spec Writer Note +When new device types are being created, the ID SHALL be set to ID-TBD until an ID can +be assigned to the new device type. +``` +``` +ID Device Name Superset Class Scope +N/A Disco Spot Simple Endpoint +``` +``` +Spec Writer Note +When adding new device types or clusters (non-sample) that do not have an allocated ID, +please use ID-TBD in the ID column and contact the Matter data model tiger team chair for +instructions on how to allocate new IDs. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 703 +``` + +**10.5.3.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**10.5.3.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +*Spec Writer Note +When new clusters are being created, the ID SHALL be set to ID-TBD until an ID can be +assigned to the new cluster. +``` +``` +ID Name Client/Server Quality Conformance +N/A Light Movement Server M +0x010D Extended Color +Light +``` +``` +Server M +``` +**10.5.3.5. Element Requirements** + +``` +*Spec Writer Note +If there are no element overrides, then this section SHALL be omitted. +``` +**10.5.4. Disco Dance System Device Type** + +This defines the components needed for a complete disco dancing system. + +**10.5.4.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**10.5.4.2. Classification** + +``` +ID Device Name Superset Class Scope +N/A Disco Dance Sys­ +tem +``` +``` +Simple Endpoint +``` +**10.5.4.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +``` +Page 704 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.5.4.4. Device Type Requirements*** + +``` +*Spec Writer Note +This is the section to define that a device type is composed of other endpoints (device types). +``` +Each endpoint supporting this device type SHALL include endpoints with these device types based +on the conformance defined below. + +``` +ID Name Constraint Conformance +N/A Disco Ball 1 * M +N/A Disco Spot min 1* M +``` +``` +*Spec Writer Note +Constraints are limitations on how many endpoints (parts) for this device type. In this exam­ +ple, there may be multiple (possibly many) spot lights for a single disco ball. +``` +**10.5.4.5. Cluster Requirements** + +``` +*Spec Writer Note +If there are no cluster requirements, then this section SHALL be omitted. +``` +**10.5.4.6. Element Requirements** + +``` +*Spec Writer Note +If there are no element overrides, then this section SHALL be omitted. +``` +**10.5.5. Weather Station Device Type** + +This defines the components needed for a weather station. + +**10.5.5.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**10.5.5.2. Classification** + +``` +ID Device Name Superset Class Scope +N/A Weather Station Simple Endpoint +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 705 +``` + +**10.5.5.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**10.5.5.4. Device Type Requirements** + +Each endpoint supporting this device type SHALL include endpoints with these device types based +on the conformance defined below. + +``` +ID Name Constraint Namespace Conformance +0x0302 Temperature Sen­ +sor +``` +``` +min 1 Building M +``` +``` +0x0307 Humidity Sensor min 1 O +N/A Wind Speed Sen­ +sor +``` +``` +min 1 O +``` +``` +N/A Wind Direction +Sensor +``` +``` +min 1 O +``` +``` +0x0044 Rain Sensor min 1 O +``` +**10.5.5.5. Cluster Requirements** + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +``` +**10.5.5.6. Element Requirements** + +``` +*Spec Writer Note +If there are no element overrides, then this section SHALL be omitted. +``` +**10.6. Information Blocks** + +These are elements that may apply to multiple message types, and are defined in a common way to +permit re-use as a definition. Unless stated otherwise, these correspond to their identically named +counterparts in the Interaction Model Specification. + +**10.6.1. Tag Rules** + +Unless otherwise noted, all context tags SHALL be emitted in the order as defined in the appropri­ +ate specification. This is done to reduce receiver side complexity in having to deal with arbitrary +order tags. + +**10.6.2. AttributePathIB** + +``` +Page 706 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +TLV Type: List +Tag Comments Tag Type Tag Number TLV Type Range +EnableTagCom­ +pression +``` +``` +Context Tag 0 bool - +``` +``` +Node Context Tag 1 Unsigned Int 64 bits +Endpoint Context Tag 2 Unsigned Int 16 bits +Cluster Context Tag 3 Unsigned Int 32 bits +Attribute Context Tag 4 Unsigned Int 32 bits +ListIndex Context Tag 5 Unsigned Int 16 bits, nul­ +lable +WildcardPath­ +Flags +``` +``` +Context Tag 6 Unsigned Int 32 bits +``` +- The contents of ClusterPathIB in the Interaction Model specification have been expanded here + for encoding efficiency. +- The ClusterPathIB Group field is omitted here (see Node field description). +- Maximum nesting is restricted to referencing a list element in an attribute. Consequently, the + NestedPath field is removed and replaced with a single ListIndex field. + +**10.6.2.1. EnableTagCompression** + +This tag is used to select between two different interpretations on the receiver when the Node, End­ +point, Cluster, Attribute tags are omitted: + +- When false or not present, omission of any of the tags in question (with the exception of Node) + indicates wildcard semantics. +- When true, indicates the use of a tag compression scheme. In this case the value for any omitted + tag SHALL be set to the value for that tag in the last AttributePathIB that had EnableTagCompres­ + sion not present or set to false and was seen in a message that is part of the same interaction + model Action as the current message. + ◦ The AttributePathIB the values end up coming from MAY appear in the same message (but + earlier in it) as the current AttributePathIB. + ◦ The values that come from the previous AttributePathIB MAY still be missing. In that case, + with the exception of Node, they indicate wildcard semantics. + +``` +NOTE Support for encoding using the EnableTagCompression tag is provisional. +``` +**10.6.2.2. Node** + +- If the Group field is present in the IM representation, the Group ID is encoded in the DST field in + the message header and elided from the encoding here. +- The Node tag MAY be omitted if the target node of the path matches the NodeID of the server + involved in the interaction. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 707 +``` + +**10.6.2.3. Endpoint, Cluster** + +- Each of these tags can be omitted. The semantics of such omission depend on the value of + EnableTagCompression. + +**10.6.2.4. Attribute, ListIndex** + +- When EnableTagCompression is false or not present, they have the following semantics: + +``` +Attribute ListIndex Description +Omitted Omitted Selects all attributes within the +specified Node, Endpoint, Clus­ +ter +Present Omitted Selects a specific attribute +within the specified Node, End­ +point, Cluster. +Present Present Selects a specific list item +within a top-level attribute of +type list. +``` +This does not allow expressing all possible paths defined in the interaction model. Only paths that +can be expressed MAY be used. + +- The ListIndex tag is nullable. The null value SHALL only be used when this AttributePathIB is + used in an AttributeDataIB and indicates a list append operation. See Section 10.6.4.3.1, “Lists” + for more details. + +**10.6.2.5. WildcardPathFlags** + +- The meaning of the flags present in this tag is defined in WildcardPathFlagsBitmap. +- The absence of the WildcardPathFlags tag SHALL indicate that all flags are false. +- If the WildcardPathFlags value is zero, is SHOULD be omitted by clients. +- The effect of WildcardPathFlags on AttributePathIB processing is described in Section 8.2.1.7.1, + “Attribute Wildcard Path Flags”. + +**10.6.2.6. Examples** + +_Select all attributes on a given cluster and endpoint:_ + +``` +AttributePath = [[ Endpoint = 10, Cluster = Disco Ball ]] +``` +_Select all attributes in all clusters on a given endpoint:_ + +``` +Path = [[ Endpoint = 10 ]] +``` +``` +Page 708 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Select all attributes in all clusters on the node:_ + +``` +Path = [[ ]] +``` +_Select a specific attribute:_ + +``` +Path = [[ Endpoint = 10, Cluster = Disco Ball, Attribute = Axis ]] +``` +_Select a specific item in a top-level list:_ + +``` +Path = [[ Endpoint = 10, Cluster = Disco Ball, Attribute = Pattern, ListIndex = 4 ]] +``` +_Select all attributes in all clusters on a given endpoint on a proxied node:_ + +``` +Path = [[ Node = 0x18B430003020203, Endpoint = 10 ]] +``` +_Tag Compression Example #1:_ + +``` +Path1 = [[ Node = 0x18B430003020203, Endpoint = 10, Cluster = Disco Ball, Attribute = +Pattern, ListIndex = 3 ]] // Start tracking path elements. +Path2 = [[ EnableTagCompression = true, ListIndex = 4 ]] // Node, Endpoint, Cluster, +Attribute are re-used from Path1 +Path3 = [[ EnableTagCompression = true, ListIndex = 5 ]] // Node, Endpoint, Cluster, +Attribute are re-used from Path1 +Path4 = [[ EnableTagCompression = true, Attribute = Axis ]] // Endpoint, Cluster are +re-used from Path1 +``` +_Tag Compression Example #2:_ + +``` +Path1 = [[ Node = 0x18B430003020203, Cluster = Disco Ball, Attribute = Pattern, +ListIndex = 3 ]] // Endpoint is wildcard, start tracking path elements. +Path2 = [[ EnableTagCompression = true, ListIndex = 4 ]] // Node, Endpoint (including +wildcard), Cluster, Attribute are re-used from Path1 +Path3 = [[ EnableTagCompression = true, ListIndex = 5 ]] // Node, Endpoint (including +wildcard), Cluster, Attribute are re-used from Path1 +``` +_Tag Compression Example #3:_ + +``` +Path1 = [[ Node = 0x18B430003020203, Endpoint = 10, Cluster = Disco Ball, Attribute = +Pattern, ListIndex = 3 ]] // Start tracking path elements. +Path2 = [[ EnableTagCompression = true, ListIndex = 4 ]] // Node, Endpoint, Cluster, +Attribute are re-used from Path1 +Path3 = [[ EnableTagCompression = true, ListIndex = 5 ]] // Node, Endpoint, Cluster, +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 709 +``` + +``` +Attribute are re-used from Path1 +Path4 = [[ Node = 0x18B430003020203, Endpoint = 20, Cluster = Disco Ball, Attribute = +Axis ]] // Reset tracker variables +Path5 = [[ EnableTagCompression = true, Attribute = Pattern, ListIndex = 5]] // Node, +Endpoint, Cluster are re-used from Path4. +``` +**10.6.3. DataVersionFilterIB** + +``` +TLV Type: Structure +Element Comments Tag Type Tag Number Type Range +Path Context Tag 0 ClusterPathIB - +DataVersion Context Tag 1 Unsigned Int 32 bits +``` +**10.6.4. AttributeDataIB** + +``` +TLV Type: Structure +Element Comments Tag Type Tag Number Type Range +DataVersion Context Tag 0 Unsigned Int 32 bits +Path Context Tag 1 Attribut­ +ePathIB +``` +### - + +``` +Data Context Tag 2 Variable (see +below) +``` +### - + +- The Change field in the Interaction Model specification is not encoded directly. Instead, it is + encoded through the use of special values in the Path and Data fields (see Lists below). + +**10.6.4.1. DataVersion** + +This tag can be omitted if the value of EnableTagCompression in the Path field is true. In this case, the +value for the omitted tag SHALL be set to the value for that tag (if present) in the last Attribute­ +DataIB that had tag compression disabled (i.e EnableTagCompression not present or set to false) and +was seen in a message that is part of the same interaction model Action as the current message. If +this tag was not present and tag compression was disabled, it SHALL be interpreted as though a +data version was not specified in that, or subsequent AttributeDataIBs. + +``` +NOTE Support for encoding using the EnableTagCompression tag is provisional. +``` +**10.6.4.2. Path** + +In addition to the rules specified for AttributePathIB, the Attribute and 'Cluster' fields within that +element SHALL always be present. + +**10.6.4.3. Data** + +Upon path expansion of the value in Path, the hierarchy and structure of the encoded data for each + +``` +Page 710 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +concrete Path SHALL be based on the schema description of the specified attribute within the speci­ +fied cluster. The TLV encoding of each element in the data SHALL follow the rules of encoding as +provided in Data Types. + +**10.6.4.3.1. Lists** + +The various values in the Change enumeration are realized as follows: + +``` +Change Type Realization +REPLACE Path SHALL refer to a list with ListIndex omitted +and Data SHALL contain new values that will +replace the existing contents of the list. +ADD Path SHALL refer to a list with ListIndex contain­ +ing a value of null and Data containing the new +value of the list item that will be added to the +list. +``` +### NOTE + +``` +ListIndex is currently only allowed to be omitted or null. Any other value SHALL be +interpreted as an error. +``` +The below bullets detail the suggested patterns for mutating a list, depending on the encoding of the +list. + +- A single AttributeDataIB containing a path to the list itself and Data that contains all items in the + list encoded as a TLV array. This option SHOULD be selected if it is possible to encode the + entirety of the list in a single AttributeDataIB that fits in a single message. +- A series of AttributeDataIBs, with the first containing a path to the list itself and Data that is an + empty array, which signals clearing the list, and subsequent AttributeDataIBs each containing a + path to each list item with ListIndex being null, in order, and Data that contains the value of the + list item. This option SHOULD be selected when it is not possible to encode the entirety of the list + in a single AttributeDataIB that fits in a single message. + +**10.6.4.4. Examples** + +**10.6.4.4.1. Simple Types** + +_Update a top-level attribute:_ + +``` +AttributeDataIB = { +DataVersion = 1, +Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Axis ]], +Data = 90 +} +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 711 +``` + +**10.6.4.5. Collection Types (List)** + +_Add an item to a list:_ + +``` +AttributeDataIB = { +DataVersion = 1, +Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern, ListIndex = +null]], +Data = { +Duration = 100, +Rotate = Counterclockwise, // On the wire enum value (2) is used +Speed = 12, +Axis = 90, +// WobbleSpeed omitted; this cluster instance does not support Wobble +Passcode = "9876" +} +} +``` +_Replace a list (Single IB):_ + +``` +AttributeDataIB = { +DataVersion = 1, +Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern]], +Data = [[ +{ +Duration = 900, +Rotate = Clockwise, // On the wire enum value (1) is used +Speed = 12, +Axis = 0, +// WobbleSpeed omitted; this cluster instance does not support Wobble +Passcode = "1234" +} +{ +Duration = 100, +Rotate = Counterclockwise, // On the wire enum value (2) is used +Speed = 12, +Axis = 90, +// WobbleSpeed omitted; this cluster instance does not support Wobble +Passcode = "9876" +}, +]] +} +``` +``` +Page 712 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Replace a list (Multiple IBs):_ + +``` +AttributeDataIB1 = { +DataVersion = 1, +Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern ]], +Data = [ +] +} +``` +``` +AttributeDataIB2 = { +DataVersion = 1, +Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern, ListIndex = +null]], +Data = { +Duration = 900, +Rotate = Clockwise, // On the wire enum value (1) is used +Speed = 12, +Axis = 0, +// WobbleSpeed omitted; this cluster instance does not support Wobble +Passcode = "1234" +} +} +``` +``` +AttributeDataIB3 = { +DataVersion = 1, +Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern, ListIndex = +null]], +Data = { +Duration = 100, +Rotate = Counterclockwise, // On the wire enum value (2) is used +Speed = 12, +Axis = 90, +// WobbleSpeed omitted; this cluster instance does not support Wobble +Passcode = "9876" +} +} +``` +Modifying or deleting single list items SHALL be done by completely replacing the list with the +options provided above. + +**10.6.5. AttributeReportIB** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 713 +``` + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number TLV Type Range +AttributeSta­ +tus +``` +``` +Context Tag 0 AttributeSta­ +tusIB +``` +### - + +``` +AttributeData Context Tag 1 Attribute­ +DataIB +``` +### - + +**10.6.6. EventFilterIB** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number TLV Type Range +Node Context Tag 0 Unsigned Int 64 bits +EventMin Context Tag 1 Unsigned Int 64 bits +``` +- The Node tag MAY be omitted if the target node of the path matches the NodeID of the server + involved in the interaction. + +**10.6.7. ClusterPathIB** + +``` +TLV Type: List +Element Comments Tag Type Tag Number TLV Type Range +Node Context Tag 0 Unsigned Int 64 bits +Endpoint Context Tag 1 Unsigned Int 16 bits +Cluster Context Tag 2 Unsigned Int 32 bits +``` +- The Node tag MAY be omitted if the target node of the path matches the NodeID of the server + involved in the interaction. +- If the Group field is present, the Group ID is encoded in the DST field in the message header and + elided from the encoding here. + +**10.6.8. EventPathIB** + +``` +TLV Type: List +Element Comments Tag Type Tag Number TLV Type Range +Node Context Tag 0 Unsigned Int 64 bits +Endpoint Context Tag 1 Unsigned Int 16 bits +Cluster Context Tag 2 Unsigned Int 32 bits +Event Context Tag 3 Unsigned Int 32 bits +'IsUrgent' Context Tag 4 Boolean - +``` +- The contents of ClusterPathIB have been expanded here to increase encoding efficiency. + +``` +Page 714 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- The Node tag MAY be omitted if the target node of the path matches the NodeID of the server + involved in the interaction. +- Omission of the Endpoint, Cluster and Event tags SHALL have different interpretations depend­ + ing on where the EventPathIB is used. See Section 10.7.2.2, “EventRequests”, Section 10.7.4.1, + “EventRequests”, and Section 10.7.3.1, “EventReports” for the different contexts. + +**10.6.8.1. Examples** + +_Select a particular event type:_ + +``` +Path = [[ Endpoint = 10, Cluster = Disco Ball, Event = Pattern Change ]] +``` +_Select all events on a given cluster (used in Read/Subscribe requests):_ + +``` +Path = [[ Endpoint = 10, Cluster = Disco Ball ]] +``` +_Select all events on a given cluster with urgency (used in Read/Subscribe requests):_ + +``` +Path = [[ Endpoint = 10, Cluster = Disco Ball, IsUrgent = true ]] +``` +**10.6.9. EventDataIB** + +``` +TLV Type: Structure +Element Comments Tag Type Tag Number Type Range +Path Context Tag 0 EventPathIB - +EventNumber Context Tag 1 Unsigned Int 64 bits +Priority Context Tag 2 Unsigned Int 8 bits +one-of { +→ EpochTime­ +stamp +``` +``` +Context Tag 3 Unsigned Int 64 bits +``` +``` +→ SystemTime­ +stamp +``` +``` +Context Tag 4 Unsigned Int 64 bits +``` +``` +→ DeltaE­ +pochTimestamp +``` +``` +Optional Context Tag 5 Unsigned Int 64 bits +``` +``` +→ DeltaSystem­ +Timestamp +``` +``` +Optional Context Tag 6 Unsigned Int 64 bits +``` +``` +} +Data Context Tag 7 Variable (see +below) +``` +### - + +**10.6.9.1. DeltaEpochTimestamp** + +This tag is present when delta encoding the UTC timestamp relative to a prior event in a given + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 715 +``` + +stream of events. + +When this tag is present, all other timestamp tags SHALL be omitted. + +This SHALL have the same units as EpochTimestamp. + +**10.6.9.2. DeltaSystemTimestamp** + +This tag is present when delta encoding the System timestamp relative to a prior event in a given +stream of events. + +When this tag is present, all other timestamp tags SHALL be omitted. + +This SHALL have the same units as SystemTimestamp. + +**10.6.9.3. Data** + +This contains the cluster-specific payload of the Event. + +The entirety of the Event is represented as a TLV Structure type. + +The TLV encoding of each field in the event SHALL follow the rules of encoding as provided in Data +Types. + +If the cluster does not define any payload for the given event instance, this Data field SHALL be +encoded as a struct with no member elements. + +**10.6.9.4. Examples** + +_Single event:_ + +``` +EventDataElement = { +Path = [[ Endpoint = 10, Cluster = Disco Ball, EventID = Started ]], +EventNumber = 1001, +Priority = INFO, +EpochTimestamp = 102340234293, +Data = { +// Started event contains no data +} +} +``` +**10.6.10. EventReportIB** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number TLV Type Range +EventStatus Context Tag 0 EventStatusIB - +EventData Context Tag 1 EventDataIB - +``` +``` +Page 716 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.6.11. CommandPathIB** + +``` +TLV Type: List +Element Comments Tag Type Tag Number TLV Type Range +Endpoint Context Tag 0 Unsigned Int 16 bits +Cluster Context Tag 1 Unsigned Int 32 bits +Command Context Tag 2 Unsigned Int 32 bits +``` +- The contents of ClusterPathIB have been expanded into the CommandPathIB here to increase + encoding efficiency. +- Wildcarding is achieved by omission of the respective tag. +- The Node field in the IM representation is the NodeID of the server involved in the interaction. + This is omitted in the encoding here since it is retrievable from the message layer for the mes­ + sage containing this element. +- The Group field in the IM representation is encoded in the DST field in the message header. + +**10.6.11.1. Examples** + +_Select a particular command:_ + +``` +Path = [[ Endpoint = 10, Cluster = Disco Ball, Command = Stop Request ]] +``` +_Select a particular command (addressed to a group):_ + +``` +Path = [[ Cluster = Disco Ball, Command = Stop Request ]] +``` +**10.6.12. CommandDataIB** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +CommandPath Context Tag 0 Command­ +PathIB +``` +### - + +``` +CommandFields Optional Context Tag 1 variable - +CommandRef Optional Context Tag 2 Unsigned Int 16 bits +``` +**10.6.12.1. CommandFields** + +This field SHALL contain the full set of arguments as specified in the description of the command +request/response. The arguments SHALL follow the rules of encoding as provided in Data Types. + +The entirety of the arguments SHALL be encapsulated in a TLV structure, with each argument +encoded appropriately using its field id as the context tag number. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 717 +``` + +If there are no arguments in the Request or Response, this tag MAY be omitted entirely. + +**10.6.12.2. CommandRef** + +This field SHALL contain an unsigned integer used to correlate responses to commands with the +requests that led to those responses. + +**10.6.12.3. Examples** + +_Request + Response:_ + +``` +RequestCommandElement = { +CommandPath = [[ Endpoint = 10, Cluster = Disco Ball, Command = Stats Request ]], +CommandFields = {} // Empty CommandFields MAY be encoded as an empty container +CommandRef = 17 +} +``` +``` +ResponseCommandElement = { +CommandPath = [[ Endpoint = 10, Cluster = Disco Ball, Command = Stats Response ]], +CommandFields = { +LastRun = 100, +Patterns = 1 +} +CommandRef = 17 // the same number as in the request +} +``` +_Empty request:_ + +``` +RequestCommandElement = { +CommandPath = [[ Endpoint = 10, Cluster = Disco Ball, Command = Stop Request ]] +// Empty CommandFields MAY also be omitted entirely +// CommandRef MAY be omitted when the request contains only a single CommandDataIB +``` +### } + +``` +// No cluster specific response is returned; a status is passed via Invoke Response at +the Interaction layer +``` +**10.6.13. InvokeResponseIB** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +``` +``` +Page 718 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +TLV Type: Structure (Anonymous) +Command Context Tag 0 Command­ +DataIB +``` +### - + +``` +Status Context Tag 1 CommandSta­ +tusIB +``` +### - + +**10.6.14. CommandStatusIB** + +``` +TLV Type: Structure +Element Comments Tag Type Tag Number Type Range +CommandPath Context Tag 0 Command­ +PathIB +``` +### - + +``` +Status Context Tag 1 StatusIB - +CommandRef Optional Context Tag 2 Unsigned Int 16 bits +``` +**10.6.14.1. CommandRef** + +This field SHALL contain an unsigned integer used to correlate responses to commands with the +requests that led to those responses. + +**10.6.15. EventStatusIB** + +``` +TLV Type: Structure +Element Comments Tag Type Tag Number Type Range +Path Context Tag 0 EventPathIB - +Status Context Tag 1 StatusIB - +``` +**10.6.16. AttributeStatusIB** + +``` +TLV Type: Structure +Element Comments Tag Type Tag Number Type Range +Path Context Tag 0 Attribut­ +ePathIB +``` +### - + +``` +Status Context Tag 1 StatusIB - +``` +**10.6.17. StatusIB** + +``` +TLV Type: Structure +Element Comments Tag Type Tag Number Type Range +Status Context Tag 0 Unsigned Int 8 bits +ClusterStatus Context Tag 1 Unsigned Int 8 bits +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 719 +``` + +**10.7. Message Definitions** + +This section contains message definitions that correspond to their equivalent actions in the Interac­ +tion Model Specification. Unless specifically indicated, all fields in the ensuing definitions SHALL +match their equivalents in the appropriate Actions defined in the Interaction Model Specification. + +**10.7.1. StatusResponseMessage** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +Status Context Tag 0 Unsigned Int 8-bits +``` +**10.7.2. ReadRequestMessage** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +Attribut­ +eRequests +``` +``` +Optional Context Tag 0 Array of Attrib­ +utePathIB +``` +### - + +``` +EventRequests Optional Context Tag 1 Array of Event­ +PathIB +``` +### - + +``` +EventFilters Optional Context Tag 2 Array of Event­ +FilterIB +``` +### - + +``` +FabricFiltered Context Tag 3 boolean - +DataVersion­ +Filters +``` +``` +Optional Context Tag 4 Array of +DataVersionFil­ +terIB +``` +### - + +**10.7.2.1. AttributeRequests** + +- If not present SHALL be treated as an empty list. + +**10.7.2.2. EventRequests** + +- If not present SHALL be treated as an empty list. +- Omission of any of the Endpoint, Cluster, Event tags indicates wildcard semantics. + +**10.7.2.3. EventFilters** + +- If not present SHALL be treated as an empty list. +- MAY be ignored (i.e. not decoded) if EventRequests is empty. + +**10.7.2.4. DataVersionFilters** + +- If not present SHALL be treated as an empty list. + +``` +Page 720 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- MAY be ignored (i.e. not decoded) if AttributeRequests is empty. + +**10.7.3. ReportDataMessage** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +SubscriptionID Optional Context Tag 0 Unsigned Inte­ +ger +``` +``` +32 bits +``` +``` +AttributeRe­ +ports +``` +``` +Optional Context Tag 1 Array of Attrib­ +uteReportIB +EventReports Optional Context Tag 2 Array of Even­ +tReportIB +MoreChun­ +kedMessages +``` +``` +Can be omitted +if false. +``` +``` +Context Tag 3 Boolean - +``` +``` +SuppressRe­ +sponse +``` +``` +Omit if 'false' Context Tag 4 Boolean - +``` +- Multiple ReportDataMessages SHALL be sent if a Report Data action does not fit into a single + message. In this case all the ReportDataMessages except the last one SHALL have MoreChun­ + kedMessages set to true. +- For each ReportDataMessage received, a successful StatusResponse message SHALL be sent + back to the sender unless SuppressResponse is true. +- If MoreChunkedMessages is true, SuppressResponse SHALL be false. +- If MoreChunkedMessages is false, SuppressResponse SHALL be set to the SuppressResponse value in + the Report Data action being encoded. + +**10.7.3.1. EventReports** + +A list of EventReportIB encoded as a TLV array that have certain compression schemes applied to +them to reduce redundant data. + +For each EventReportIB in the list: + +- The Path tag SHALL utilize the same tag compression scheme as that utilized by the tags in + AttributePathIB. Specifically: + ◦ The tag compression scheme SHALL only apply to the Node, Endpoint, Cluster and Event tags + within the EventPathIB element. + ◦ The first element within the list SHALL specify all the necessary tags and hence serve as the + anchor on which subsequent items MAY rely for compression. +- The EventNumber MAY be omitted if it is exactly one greater than the EventNumber of the pre­ + vious Event. +- The 'Delta' tags SHALL be used to encode timestamps as deltas from the prior event to improve + compression of large timestamps. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 721 +``` + +``` +NOTE Support for using the tag compression scheme for the Path is provisional. +``` +**10.7.3.1.1. Examples** + +_Event list (highlighting compressions):_ + +``` +EventReports = [ +{ +Path = [[ Endpoint = 10, Cluster = Disco Ball, EventID = Started ]], +ImportanceLevel = INFO, +Number = 1001, +UTCTimestamp = 102340234293, +Data = { +} +}, +{ +Path = [[ EventID = PatternChange]], // same endpoint and cluster but different +event type +DeltaUTCTimestamp = 1000, +Data = { +PrevPattern = null, +CurPattern = { +Duration = 900, +Rotate = Clockwise, // On the wire enum value (1) is used +Speed = 12, +Axis = 0, +// WobbleSpeed omitted; this cluster instance does not support Wobble +Passcode = "1234" +}, +NextPattern = { +Duration = 100, +Rotate = Counterclockwise, // On the wire enum value (2) is used +Speed = 12, +Axis = 90, +// WobbleSpeed omitted; this cluster instance does not support Wobble +Passcode = "9876" +} +} +} +{ +Path = [[ ]], // same path as the previous path +DeltaUTCTimestamp = 900000000, +Data = { +``` +``` +Page 722 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +PrevPattern = { +Duration = 900, +Rotate = Clockwise, +Speed = 12, +Axis = 0, +Passcode = "1234" +}, +CurPattern = { +Duration = 100, +Rotate = Counterclockwise, +Speed = 12, +Axis = 90, +Passcode = "9876" +}, +NextPattern = null +} +} +] +``` +**10.7.3.2. MoreChunkedMessages** + +This flag is set to ‘true’ when there are more chunked messages in a transaction. + +**10.7.4. SubscribeRequestMessage** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +KeepSubscrip­ +tions +``` +``` +Context Tag 0 Boolean +``` +``` +MinInter­ +valFloor +``` +``` +Context Tag 1 Unsigned Int 16 bits +``` +``` +MaxInterval­ +Ceiling +``` +``` +Context Tag 2 Unsigned Int 16 bits +``` +``` +Attribut­ +eRequests +``` +``` +Optional Context Tag 3 Array of Attrib­ +utePathIB +``` +### - + +``` +EventRequests Optional Context Tag 4 Array of Event­ +PathIB +``` +### - + +``` +EventFilters Optional. Only +present if +EventRequests +is present. +``` +``` +Context Tag 5 Array of Event­ +FilterIB +``` +### - + +``` +FabricFiltered Context Tag 7 boolean - +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 723 +``` + +``` +TLV Type: Structure (Anonymous) +DataVersion­ +Filters +``` +``` +Optional. Only +present if +Attribut­ +eRequests is +present. +``` +``` +Context Tag 8 Array of +DataVersionFil­ +terIB +``` +### - + +**10.7.4.1. EventRequests** + +- Omission of any of Endpoint, Cluster, Event tags indicates wildcard semantics. + +**10.7.5. SubscribeResponseMessage** + +This is sent after all Reports have been sent back to the client. The sole purpose of this is to convey +the final set of parameters for the subscription back to the client. + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +SubscriptionID Context Tag 0 Unsigned Int 32 bits +MaxInterval Context Tag 2 Unsigned Int 16 bits +``` +**10.7.6. WriteRequestMessage** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +SuppressRe­ +sponse +``` +``` +Omit if ‘false' Context Tag 0 Boolean - +``` +``` +TimedRequest Context Tag 1 Boolean - +WriteRequests Context Tag 2 Array of Attrib­ +uteDataIB +MoreChun­ +kedMessages +``` +``` +Can be omitted +if false +``` +``` +Context Tag 3 Boolean - +``` +**10.7.6.1. SuppressResponse** + +- If MoreChunkedMessages is true, SuppressResponse SHALL be false. +- If MoreChunkedMessages is false, SuppressResponse SHALL be set to the SuppressResponse value in + the Write Request action being encoded. + +**10.7.6.2. MoreChunkedMessages** + +- Multiple WriteRequestMessages SHALL be sent in a single transaction if the set of Attribute­ + DataIBs have to be sent across multiple packets. All but the last message SHALL have the + MoreChunkedMessages flag set to true to indicate this situation. Before sending the next + WriteRequestMessage, the sender SHALL await the WriteResponseMessage associated with the + +``` +Page 724 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +previous WriteRequestMessage. +``` +- A Write Request action that is part of a Timed Write Interaction SHALL NOT be chunked. + +**10.7.7. WriteResponseMessage** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +WriteResponses Context Tag 0 Array of Attrib­ +uteStatusIB +``` +### - + +**10.7.8. TimedRequestMessage** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +Timeout Context Tag 0 Unsigned Int 16 bits +``` +**10.7.9. InvokeRequestMessage** + +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +SuppressRe­ +sponse +``` +``` +Context Tag 0 Boolean - +``` +``` +TimedRequest Context Tag 1 Boolean - +InvokeRequests Context Tag 2 Array of Com­ +mandDataIB +``` +### - + +### NOTE + +``` +In this version of the specification, InvokeRequestMessage contains no provisions +for spanning multiple messages (see Section 4.4.4, “Message Size Requirements”). +``` +**10.7.10. InvokeResponseMessage** + +### NOTE + +``` +The interaction model is written at the abstract level of actions, and as such, it does +not address fragmentation. The interaction model describes a complete response to +the invoke interaction as a unit, the chunking protocol described here maintains +that illusion as much as possible. The status response messages (Status = SUCCESS) +are used for flow control. Status response messages with any other Status indicate +the sender of any further chunked InvokeResponseMessages must exit early. In exit­ +ing early, the sender MAY send an InvalidAction StatusResponse. +``` +``` +TLV Type: Structure (Anonymous) +Element Comments Tag Type Tag Number Type Range +SuppressRe­ +sponse +``` +``` +Context Tag 0 Boolean - +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 725 +``` + +``` +TLV Type: Structure (Anonymous) +InvokeRe­ +sponses +``` +``` +Context Tag 1 Array of Invok­ +eResponseIB +``` +### - + +``` +MoreChun­ +kedMessages +``` +``` +Context Tag 2 Boolean - +``` +**10.7.10.1. SuppressResponse** + +- If MoreChunkedMessages is true, SuppressResponse SHALL be false. +- If MoreChunkedMessages is false, SuppressResponse SHALL be set to the SuppressResponse value in + the Invoke Response action being encoded. + +**10.7.10.2. InvokeResponses** + +If the InvokeResponseMessage is being generated in response to an InvokeRequestMessage contain­ +ing InvokeRequests of length 1, it SHALL contain an InvokeResponses element, and it SHALL NOT +contain MoreChunkedMessages. + +**10.7.10.3. MoreChunkedMessages** + +Multiple InvokeResponseMessages MAY be sent in a single transaction when multiple Command­ +DataIBs were present in the Invoke Request action. All but the last message SHALL have the +MoreChunkedMessages flag set to true to indicate this situation, and the last message SHALL have the +MoreChunkedMessages flag set to false. + +Implementations MAY choose to send the InvokeResponseMessage at any granularity, such as: + +- Responding with one InvokeResponseMessage to each CommandDataIB in the corresponding + InvokeRequestMessage; +- Waiting to batch the responses until a message full boundary is reached; +- Accumulating all responses to all CommandDataIBs from the InvokeRequestMessage, followed + by sending as many messages as needed to fit all the responses. + +These different InvokeMessageResponse buffering strategies all have different buffering costs to +the server, different latency for the client, and different latency for command execution. + +Upon reception of any InvokeResponseMessage with MoreChunkedResponses set to true, the receiver +SHALL respond with StatusResponseMessage. Before sending the next InvokeResponseMessage, the +sender SHALL await the StatusResponseMessage associated with the previous InvokeResponseMes­ +sage. If the Status field in the StatusResponseMessage is set to SUCCESS, that indicates the receiver +is ready to process the next InvokeResponseMessage in the chunked series, and in that case the +sender SHALL send the next chunk as soon as possible. Any other value of the Status field other +than SUCCESS in the StatusResponseMessage SHALL cause the sender of the InvokeResponseMes­ +sage to terminate further transmission of InvokeResponseMessages, close the exchange, and con­ +sider the Invoke Interaction completed. + +``` +Page 726 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 11. Service and Device Management** + +**11.1. Basic Information Cluster** + +This cluster provides attributes and events for determining basic information about Nodes, which +supports both Commissioning and operational determination of Node characteristics, such as Ven­ +dor ID, Product ID and serial number, which apply to the whole Node. + +**11.1.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Added ProductAppearance attribute +3 Added SpecificationVersion and MaxPathsPerIn­ +voke attributes +4 Updated conformance for UniqueID to manda­ +tory. +``` +**11.1.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node BINFO +``` +**11.1.3. Cluster ID** + +``` +ID Name +0x0028 Basic Information +``` +**11.1.4. Data Types** + +**11.1.4.1. ProductFinishEnum Type** + +The data type of ProductFinishEnum is derived from enum8. + +``` +Value Name Summary Conformance +0 Other Product has some other +finish not listed below. +``` +### M + +``` +1 Matte Product has a matte fin­ +ish. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 727 +``` + +``` +Value Name Summary Conformance +2 Satin Product has a satin fin­ +ish. +``` +### M + +``` +3 Polished Product has a polished +or shiny finish. +``` +### M + +``` +4 Rugged Product has a rugged +finish. +``` +### M + +``` +5 Fabric Product has a fabric +finish. +``` +### M + +**11.1.4.2. ColorEnum Type** + +The data type of ColorEnum is derived from enum8. + +``` +Value Name Summary Conformance +0 Black Approximately RGB +#000000. +``` +### M + +``` +1 Navy Approximately RGB +#000080. +``` +### M + +``` +2 Green Approximately RGB +#008000. +``` +### M + +``` +3 Teal Approximately RGB +#008080. +``` +### M + +``` +4 Maroon Approximately RGB +#800080. +``` +### M + +``` +5 Purple Approximately RGB +#800080. +``` +### M + +``` +6 Olive Approximately RGB +#808000. +``` +### M + +``` +7 Gray Approximately RGB +#808080. +``` +### M + +``` +8 Blue Approximately RGB +#0000FF. +``` +### M + +``` +9 Lime Approximately RGB +#00FF00. +``` +### M + +``` +10 Aqua Approximately RGB +#00FFFF. +``` +### M + +``` +11 Red Approximately RGB +#FF0000. +``` +### M + +``` +12 Fuchsia Approximately RGB +#FF00FF. +``` +### M + +``` +Page 728 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +13 Yellow Approximately RGB +#FFFF00. +``` +### M + +``` +14 White Approximately RGB +#FFFFFF. +``` +### M + +``` +15 Nickel Typical hardware +"Nickel" color. +``` +### M + +``` +16 Chrome Typical hardware +"Chrome" color. +``` +### M + +``` +17 Brass Typical hardware +"Brass" color. +``` +### M + +``` +18 Copper Typical hardware "Cop­ +per" color. +``` +### M + +``` +19 Silver Typical hardware "Sil­ +ver" color. +``` +### M + +``` +20 Gold Typical hardware +"Gold" color. +``` +### M + +**11.1.4.3. ProductAppearanceStruct Type** + +This structure provides a description of the product’s appearance. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Finish Pro­ +ductFin­ +ishEnum +``` +``` +all M +``` +``` +1 Primary­ +Color +``` +``` +ColorEnumall X M +``` +**Finish Field** + +This field SHALL indicate the visible finish of the product. + +**PrimaryColor Field** + +This field indicates the representative color of the visible parts of the product. If the product has no +representative color, the field SHALL be null. + +**11.1.4.4. CapabilityMinimaStruct Type** + +This structure provides constant values related to overall global capabilities of this Node, that are +not cluster-specific. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 729 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 CaseSes­ +sionsPer­ +Fabric +``` +``` +uint16 min 3 3 M +``` +``` +1 Subscrip­ +tionsPer­ +Fabric +``` +``` +uint16 min 3 3 M +``` +**CaseSessionsPerFabric Field** + +This field SHALL indicate the actual minimum number of concurrent CASE sessions that are sup­ +ported per fabric. + +This value SHALL NOT be smaller than the required minimum indicated in Section 4.14.2.8, “Mini­ +mal Number of CASE Sessions”. + +**SubscriptionsPerFabric Field** + +This field SHALL indicate the actual minimum number of concurrent subscriptions supported per +fabric. + +This value SHALL NOT be smaller than the required minimum indicated in Section 8.5.1, “Subscribe +Transaction”. + +**11.1.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 DataMod­ +elRevision +``` +``` +uint16 desc F MS R V M +``` +``` +0x0001 Vendor­ +Name +``` +``` +string max 32 F MS R V M +``` +``` +0x0002 VendorID vendor-id all F MS R V M +0x0003 Product­ +Name +``` +``` +string max 32 F MS R V M +``` +``` +0x0004 ProductID uint16 all F MS R V M +0x0005 NodeLabel string max 32 N "" RW VM M +0x0006 Location string 2 N "XX" RW VA M +0x0007 Hardware­ +Version +``` +``` +uint16 all F 0 R V M +``` +``` +0x0008 Hardware­ +Version­ +String +``` +``` +string 1 to 64 F MS R V M +``` +``` +Page 730 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0009 Software­ +Version +``` +``` +uint32 desc F 0 R V M +``` +``` +0x000A Software­ +Version­ +String +``` +``` +string 1 to 64 F MS R V M +``` +``` +0x000B Manufac­ +turing­ +Date +``` +``` +string 8 to 16 F MS R V O +``` +``` +0x000C PartNum­ +ber +``` +``` +string max 32 F MS R V O +``` +``` +0x000D Produc­ +tURL +``` +``` +string max 256 F MS R V O +``` +``` +0x000E Product­ +Label +``` +``` +string max 64 F MS R V O +``` +``` +0x000F Serial­ +Number +``` +``` +string max 32 F MS R V O +``` +``` +0x0010 LocalCon­ +figDis­ +abled +``` +``` +bool all N False RW VM O +``` +``` +0x0011 Reachable bool all True R V O +0x0012 UniqueID string max 32 F MS R V M +0x0013 Capabili­ +tyMinima +``` +``` +Capabili­ +tyMini­ +maStruct +``` +``` +all F MS R V M +``` +``` +0x0014 Produc­ +tAppear­ +ance +``` +``` +ProductAp­ +pearanceS­ +truct +``` +``` +all F MS R V O +``` +``` +0x0015 Specifica­ +tionVer­ +sion +``` +``` +uint32 desc F 0 R V M +``` +``` +0x0016 Max­ +PathsPer­ +Invoke +``` +``` +uint16 min 1 F 1 R V M +``` +**11.1.5.1. DataModelRevision Attribute** + +This attribute SHALL be set to the revision number of the Data Model against which the Node is cer­ +tified. The value of this attribute SHALL be one of the valid values listed in Section 7.1.1, “Revision +History”. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 731 +``` + +**11.1.5.2. VendorName Attribute** + +This attribute SHALL specify a human readable (displayable) name of the vendor for the Node. + +**11.1.5.3. VendorID Attribute** + +This attribute SHALL specify the Vendor ID. + +**11.1.5.4. ProductName Attribute** + +This attribute SHALL specify a human readable (displayable) name of the model for the Node such +as the model number (or other identifier) assigned by the vendor. + +**11.1.5.5. ProductID Attribute** + +This attribute SHALL specify the Product ID assigned by the vendor that is unique to the specific +product of the Node. + +**11.1.5.6. NodeLabel Attribute** + +This attribute SHALL represent a user defined name for the Node. This attribute SHOULD be set +during initial commissioning and MAY be updated by further reconfigurations. + +**11.1.5.7. Location Attribute** + +This attribute SHALL be an ISO 3166-1 alpha-2 code to represent the country, dependent territory, +or special area of geographic interest in which the Node is located at the time of the attribute being +set. This attribute SHALL be set during initial commissioning (unless already set) and MAY be +updated by further reconfigurations. This attribute MAY affect some regulatory aspects of the +Node’s operation, such as radio transmission power levels in given spectrum allocation bands if +technologies where this is applicable are used. The Location’s region code SHALL be interpreted in +a case-insensitive manner. If the Node cannot understand the location code with which it was con­ +figured, or the location code has not yet been configured, it SHALL configure itself in a region- +agnostic manner as determined by the vendor, avoiding region-specific assumptions as much as is +practical. The special value XX SHALL indicate that region-agnostic mode is used. + +**11.1.5.8. HardwareVersion Attribute** + +This attribute SHALL specify the version number of the hardware of the Node. The meaning of its +value, and the versioning scheme, are vendor defined. + +**11.1.5.9. HardwareVersionString Attribute** + +This attribute SHALL specify the version number of the hardware of the Node. The meaning of its +value, and the versioning scheme, are vendor defined. The HardwareVersionString attribute SHALL +be used to provide a more user-friendly value than that represented by the HardwareVersion +attribute. + +**11.1.5.10. SoftwareVersion Attribute** + +This attribute SHALL contain the current version number for the software running on this Node. + +``` +Page 732 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The version number can be compared using a total ordering to determine if a version is logically +newer than another one. A larger value of SoftwareVersion is newer than a lower value, from the +perspective of software updates (see Section 11.20.3.3, “Availability of Software Images”). Nodes +MAY query this field to determine the currently running version of software on another given +Node. + +**11.1.5.11. SoftwareVersionString Attribute** + +This attribute SHALL contain a current human-readable representation for the software running +on the Node. This version information MAY be conveyed to users. The maximum length of the Soft­ +wareVersionString attribute is 64 bytes of UTF-8 characters. The contents SHOULD only use simple +7-bit ASCII alphanumeric and punctuation characters, so as to simplify the conveyance of the value +to a variety of cultures. + +Examples of version strings include "1.0", "1.2.3456", "1.2-2", "1.0b123", "1.2_3". + +**11.1.5.12. ManufacturingDate Attribute** + +This attribute SHALL specify the date that the Node was manufactured. The first 8 characters +SHALL specify the date of manufacture of the Node in international date notation according to ISO +8601, i.e., YYYYMMDD, e.g., 20060814. The final 8 characters MAY include country, factory, line, shift +or other related information at the option of the vendor. The format of this information is vendor +defined. + +**11.1.5.13. PartNumber Attribute** + +This attribute SHALL specify a human-readable (displayable) vendor assigned part number for the +Node whose meaning and numbering scheme is vendor defined. +Multiple products (and hence PartNumbers) can share a ProductID. For instance, there may be dif­ +ferent packaging (with different PartNumbers) for different regions; also different colors of a prod­ +uct might share the ProductID but may have a different PartNumber. + +**11.1.5.14. ProductURL Attribute** + +This attribute SHALL specify a link to a product specific web page. The specified URL SHOULD +resolve to a maintained web page available for the lifetime of the product. The syntax of this +attribute SHALL follow the syntax as specified in RFC 1738 and SHALL use the https scheme. The +maximum length of this attribute is 256 ASCII characters. + +**11.1.5.15. ProductLabel Attribute** + +This attribute SHALL specify a vendor specific human readable (displayable) product label. The +ProductLabel attribute MAY be used to provide a more user-friendly value than that represented by +the ProductName attribute. The ProductLabel attribute SHOULD NOT include the name of the ven­ +dor as defined within the VendorName attribute. + +**11.1.5.16. SerialNumber Attribute** + +This attribute SHALL specify a human readable (displayable) serial number. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 733 +``` + +**11.1.5.17. LocalConfigDisabled Attribute** + +This attribute SHALL allow a local Node configuration to be disabled. When this attribute is set to +True the Node SHALL disable the ability to configure the Node through an on-Node user interface. +The value of the LocalConfigDisabled attribute SHALL NOT in any way modify, disable, or otherwise +affect the user’s ability to trigger a factory reset on the Node. + +**11.1.5.18. Reachable Attribute** + +This attribute (when used) SHALL indicate whether the Node can be reached. For a native Node this +is implicitly True (and its use is optional). +Its main use case is in the derived Bridged Device Basic Information cluster where it is used to indi­ +cate whether the bridged device is reachable by the bridge over the non-native network. + +**11.1.5.19. UniqueID Attribute** + +This attribute SHALL indicate a unique identifier for the device, which is constructed in a manufac­ +turer specific manner. +It MAY be constructed using a permanent device identifier (such as device MAC address) as basis. +In order to prevent tracking, + +- it SHOULD NOT be identical to (or easily derived from) such permanent device identifier +- it SHALL be updated when the device is factory reset +- it SHALL NOT be identical to the SerialNumber attribute +- it SHALL NOT be printed on the product or delivered with the product + +The value does not need to be human readable, since it is intended for machine to machine (M2M) +communication. + +### NOTE + +``` +The conformance of the UniqueID attribute was optional in cluster revisions prior +to revision 4. +``` +``` +NOTE This UniqueID attribute SHALL NOT be the same as the Persistent Unique ID which +is used in the Rotating Device Identifier mechanism. +``` +**11.1.5.20. CapabilityMinima Attribute** + +This attribute SHALL provide the minimum guaranteed value for some system-wide resource capa­ +bilities that are not otherwise cluster-specific and do not appear elsewhere. This attribute MAY be +used by clients to optimize communication with Nodes by allowing them to use more than the strict +minimum values required by this specification, wherever available. + +The values supported by the server in reality MAY be larger than the values provided in this +attribute, such as if a server is not resource-constrained at all. However, clients SHOULD only rely +on the amounts provided in this attribute. + +Note that since the fixed values within this attribute MAY change over time, both increasing and +decreasing, as software versions change for a given Node, clients SHOULD take care not to assume + +``` +Page 734 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +forever unchanging values and SHOULD NOT cache this value permanently at Commissioning time. + +**11.1.5.21. ProductAppearance Attribute** + +This attribute SHALL provide information about the appearance of the product, which could be +useful to a user trying to locate or identify the node. + +**11.1.5.22. SpecificationVersion Attribute** + +This attribute SHALL contain the current version number for the specification version this Node +was certified against. The version number can be compared using a total ordering to determine if a +version is logically newer than another one. A larger value of SpecificationVersion is newer than a +lower value. + +Nodes MAY query this field to determine the currently supported version of the specification on +another given Node. + +The format of this number is segmented as its four component bytes. + +Bit positions for the fields are as follows: + +``` +Bits Name Summary +31 .. 24 Major Major version of specification. +23 .. 16 Minor Minor version of specification. +15 .. 8 Patch Patch version of the specifica­ +tion. +7 .. 0 Reserved1 Future reserved version field 1, +set to 0 until defined. +``` +For example, a SpecificationVersion value of 0x0102AA00 is composed of 4 version components, +representing a version 1.2.170.0. + +In the example above: + +- Major version is the uppermost byte (0x01). +- Minor version is the following byte (0x02). +- Patch version is 170/0xAA. +- Reserved1 value is 0. + +The initial revision (1.0) of this specification (1.0) was 0x01000000. Matter Spring 2024 release (1.3) +was 0x01030000. + +If the SpecificationVersion is absent or zero, such as in Basic Information cluster revisions prior to +Revision 3, the specification version cannot be properly inferred unless other heuristics are +employed. + +Comparison of SpecificationVersion SHALL always include the total value over 32 bits, without +masking reserved parts. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 735 +``` + +**11.1.5.23. MaxPathsPerInvoke Attribute** + +This attribute SHALL indicate the maximum number of elements in a single InvokeRequests list +(see Section 8.8.2, “Invoke Request Action”) that the Node is able to process. Note that since this +attribute MAY change over time, both increasing and decreasing, as software versions change for a +given Node, clients SHOULD take care not to assume forever unchanging values and SHOULD NOT +cache this value permanently at Commissioning time. + +If the MaxPathsPerInvoke attribute is absent or zero, such as in Basic Information cluster revisions +prior to Revision 3, clients SHALL assume a value of 1. + +**11.1.6. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 StartUp CRITICAL V M +0x01 ShutDown CRITICAL V O +0x02 Leave INFO V O +0x03 Reach­ +ableChanged +``` +``` +INFO V desc +``` +**11.1.6.1. StartUp Event** + +The StartUp event SHALL be generated by a Node as soon as reasonable after completing a boot or +reboot process. The StartUp event SHOULD be the first Data Model event recorded by the Node after +it completes a boot or reboot process. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Software­ +Version +``` +``` +uint32 M +``` +**SoftwareVersion Field** + +This field SHALL be set to the same value as the one available in the SoftwareVersion attribute. + +**11.1.6.2. ShutDown Event** + +The ShutDown event SHOULD be generated by a Node prior to any orderly shutdown sequence on a +best-effort basis. When a ShutDown event is generated, it SHOULD be the last Data Model event +recorded by the Node. This event SHOULD be delivered urgently to current subscribers on a best- +effort basis. Any subsequent incoming interactions to the Node MAY be dropped until the comple­ +tion of a future boot or reboot process. + +``` +Page 736 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.1.6.3. Leave Event** + +The Leave event SHOULD be generated by a Node prior to permanently leaving a given Fabric, such +as when the RemoveFabric command is invoked for a given fabric, or triggered by factory reset or +some other manufacturer specific action to disable or reset the operational data in the Node. When +a Leave event is generated, it SHOULD be assumed that the fabric recorded in the event is no longer +usable, and subsequent interactions targeting that fabric will most likely fail. + +Upon receipt of Leave Event on a subscription, the receiving Node MAY update other nodes in the +fabric by removing related bindings, access control list entries and other data referencing the leav­ +ing Node. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 FabricIndex fabric-idx 1 to 254 M +``` +**FabricIndex Field** + +This field SHALL contain the local Fabric Index of the fabric which the node is about to leave. + +**11.1.6.4. ReachableChanged Event** + +This event SHALL be supported if and only if the Reachable attribute is supported. +This event (when supported) SHALL be generated when there is a change in the Reachable +attribute. +Its main use case is in the derived Bridged Device Basic Information cluster. +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Reachable­ +NewValue +``` +``` +bool M +``` +**ReachableNewValue Field** + +This field SHALL indicate the value of the Reachable attribute after it was changed. + +**11.2. Group Key Management Cluster** + +The Group Key Management cluster manages group keys for the node. The cluster is scoped to the +node and is a singleton for the node. This cluster maintains a list of groups supported by the node. +Each group list entry supports a single group, with a single group ID and single group key. Duplicate +groups are not allowed in the list. Additions or removal of a group entry are performed via modifi­ +cations of the list. Such modifications require Administer privilege. + +Each group entry includes a membership list of zero of more endpoints that are members of the +group on the node. Modification of this membership list is done via the Groups cluster, which is + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 737 +``` + +scoped to an endpoint. Please see the System Model specification for more information on groups. + +**11.2.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Clarify KeySetWrite validation and behavior on +invalid epoch key lengths +``` +**11.2.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node GRPKEY +``` +**11.2.3. Cluster ID** + +``` +ID Name +0x003F GroupKeyManagement +``` +**11.2.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 CS CacheAndSync P The ability to sup­ +port Cache­ +AndSync security +policy and MCSP. +``` +**11.2.5. Data Types** + +**11.2.5.1. GroupKeySecurityPolicyEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 TrustFirst Message counter syn­ +chronization using +trust-first +``` +### M + +``` +Page 738 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +1 CacheAndSync Message counter syn­ +chronization using +cache-and-sync +``` +### CS + +**11.2.5.2. GroupKeyMulticastPolicyEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 PerGroupID Indicates filtering of +multicast messages for +a specific Group ID +``` +### M + +``` +1 AllNodes Indicates not filtering +of multicast messages +``` +### M + +**PerGroupID Value** + +The 16-bit Group Identifier of the Multicast Address SHALL be the Group ID of the group. + +**AllNodes Value** + +The 16-bit Group Identifier of the Multicast Address SHALL be 0xFFFF. + +**11.2.5.3. GroupKeyMapStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 GroupId group-id all M +2 GroupKey­ +SetID +``` +``` +uint16 1 to 65535 M +``` +**GroupId Field** + +This field uniquely identifies the group within the scope of the given Fabric. + +**GroupKeySetID Field** + +This field references the set of group keys that generate operational group keys for use with this +group, as specified in Section 4.17.3.5.1, “Group Key Set ID”. + +A GroupKeyMapStruct SHALL NOT accept GroupKeySetID of 0, which is reserved for the IPK. + +**11.2.5.4. GroupKeySetStruct Type** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 739 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 GroupKey­ +SetID +``` +``` +uint16 all M +``` +``` +1 GroupKey­ +Security­ +Policy +``` +``` +GroupKey­ +Security­ +Poli­ +cyEnum +``` +``` +all S M +``` +``` +2 EpochKey +0 +``` +``` +octstr 16 X S M +``` +``` +3 EpochStar +tTime0 +``` +``` +epoch-us all X S M +``` +``` +4 EpochKey +1 +``` +``` +octstr 16 X S M +``` +``` +5 EpochStar +tTime1 +``` +``` +epoch-us all X S M +``` +``` +6 EpochKey +2 +``` +``` +octstr 16 X S M +``` +``` +7 EpochStar +tTime2 +``` +``` +epoch-us all X S M +``` +``` +8 GroupKey­ +Multicast­ +Policy +``` +``` +GroupKey­ +Multicast­ +Poli­ +cyEnum +``` +``` +all S P, M +``` +**GroupKeySetID Field** + +This field SHALL provide the fabric-unique index for the associated group key set, as specified in +Section 4.17.3.5.1, “Group Key Set ID”. + +**GroupKeySecurityPolicy Field** + +This field SHALL provide the security policy for an operational group key set. + +When CacheAndSync is not supported in the FeatureMap of this cluster, any action attempting to +set CacheAndSync in the GroupKeySecurityPolicy field SHALL fail with an INVALID_COMMAND +error. + +**EpochKey0 Field** + +This field, if not null, SHALL be the root credential used in the derivation of an operational group +key for epoch slot 0 of the given group key set. If EpochKey0 is not null, EpochStartTime0 SHALL +NOT be null. + +``` +Page 740 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**EpochStartTime0 Field** + +This field, if not null, SHALL define when EpochKey0 becomes valid as specified by Section 4.17.3, +“Epoch Keys”. Units are absolute UTC time in microseconds encoded using the epoch-us representa­ +tion. + +**EpochKey1 Field** + +This field, if not null, SHALL be the root credential used in the derivation of an operational group +key for epoch slot 1 of the given group key set. If EpochKey1 is not null, EpochStartTime1 SHALL +NOT be null. + +**EpochStartTime1 Field** + +This field, if not null, SHALL define when EpochKey1 becomes valid as specified by Section 4.17.3, +“Epoch Keys”. Units are absolute UTC time in microseconds encoded using the epoch-us representa­ +tion. + +**EpochKey2 Field** + +This field, if not null, SHALL be the root credential used in the derivation of an operational group +key for epoch slot 2 of the given group key set. If EpochKey2 is not null, EpochStartTime2 SHALL +NOT be null. + +**EpochStartTime2 Field** + +This field, if not null, SHALL define when EpochKey2 becomes valid as specified by Section 4.17.3, +“Epoch Keys”. Units are absolute UTC time in microseconds encoded using the epoch-us representa­ +tion. + +**GroupKeyMulticastPolicy Field** + +This field specifies how the IPv6 Multicast Address SHALL be formed for groups using this opera­ +tional group key set. + +The PerGroupID method maximizes filtering of multicast messages, so that receiving nodes receive +only multicast messages for groups to which they are subscribed. + +The AllNodes method minimizes the number of multicast addresses to which a receiver node needs +to subscribe. + +### NOTE + +``` +Support for GroupKeyMulticastPolicy is provisional. Correct default behavior is that +implied by value PerGroupID. +``` +**11.2.5.5. GroupInfoMapStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 GroupId group-id all M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 741 +``` + +``` +Access Quality: Fabric Scoped +2 Endpoints list[end­ +point-no] +``` +``` +min 1 M +``` +``` +3 Group­ +Name +``` +``` +string max 16 O +``` +**GroupId Field** + +This field uniquely identifies the group within the scope of the given Fabric. + +**Endpoints Field** + +This field provides the list of Endpoint IDs on the Node to which messages to this group SHALL be +forwarded. + +**GroupName Field** + +This field provides a name for the group. This field SHALL contain the last GroupName written for +a given GroupId on any Endpoint via the Groups cluster. + +**11.2.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Group­ +KeyMap +``` +``` +list[Group­ +KeyMap­ +Struct] +``` +``` +desc N empty RW VM F M +``` +``` +0x0001 GroupT­ +able +``` +``` +list[GroupI +nfoMap­ +Struct] +``` +``` +desc empty R V F M +``` +``` +0x0002 Max­ +GroupsPer +Fabric +``` +``` +uint16 all F 0 R V M +``` +``` +0x0003 Max­ +Group­ +KeysPer­ +Fabric +``` +``` +uint16 1 to 65535 F 1 R V M +``` +**11.2.6.1. GroupKeyMap Attribute** + +This attribute is a list of GroupKeyMapStruct entries. Each entry associates a logical Group Id with a +particular group key set. + +**11.2.6.2. GroupTable Attribute** + +This attribute is a list of GroupInfoMapStruct entries. Each entry provides read-only information +about how a given logical Group ID maps to a particular set of endpoints, and a name for the group. + +``` +Page 742 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The content of this attribute reflects data managed via the Groups cluster (see AppClusters), and is +in general terms referred to as the 'node-wide Group Table'. + +The GroupTable SHALL NOT contain any entry whose GroupInfoMapStruct has an empty Endpoints +list. If a RemoveGroup or RemoveAllGroups command causes the removal of a group mapping from +its last mapped endpoint, the entire GroupTable entry for that given GroupId SHALL be removed. + +**11.2.6.3. MaxGroupsPerFabric Attribute** + +This attribute SHALL indicate the maximum number of groups that this node supports per fabric. +The value of this attribute SHALL be set to be no less than the required minimum supported groups +as specified in Group Limits. The length of the GroupKeyMap and GroupTable list attributes SHALL +NOT exceed the value of the MaxGroupsPerFabric attribute multiplied by the number of supported +fabrics. + +**11.2.6.4. MaxGroupKeysPerFabric Attribute** + +This attribute SHALL indicate the maximum number of group key sets this node supports per fab­ +ric. The value of this attribute SHALL be set according to the minimum number of group key sets to +support as specified in Group Limits. + +**11.2.7. Commands** + +All commands in this cluster SHALL be scoped to the accessing fabric. + +``` +ID Name Direction Response Access Conformance +0x00 KeySetWrite client ⇒ server Y A F M +0x01 KeySetRead client ⇒ server KeySetRead­ +Response +``` +### A F M + +``` +0x02 KeySetRead­ +Response +``` +``` +client ⇐ server N M +``` +``` +0x03 KeySe­ +tRemove +``` +``` +client ⇒ server Y A F M +``` +``` +0x04 KeySe­ +tReadAllIndic +es +``` +``` +client ⇒ server KeySe­ +tReadAllIndice +sResponse +``` +### A F M + +``` +0x05 KeySe­ +tReadAllIndic +esResponse +``` +``` +client ⇐ server N M +``` +**11.2.7.1. KeySetWrite Command** + +This command is used by Administrators to set the state of a given Group Key Set, including atomi­ +cally updating the state of all epoch keys. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 743 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupKey­ +Set +``` +``` +GroupKey­ +SetStruct +``` +### M + +**Effect on Receipt** + +The following validations SHALL be done against the content of the GroupKeySet field: + +- If the EpochKey0 field is null or its associated EpochStartTime0 field is null, then this command + SHALL fail with an INVALID_COMMAND status code responded to the client. +- If the EpochKey0 field’s length is not exactly 16 bytes, then this command SHALL fail with a + CONSTRAINT_ERROR status code responded to the client. +- If the EpochStartTime0 is set to 0, then this command SHALL fail with an INVALID_COMMAND + status code responded to the client. Note that internally, a GroupKeySetStruct’s EpochStartTime0 + MAY be set to zero, due to the behavior of the AddNOC command which synthesizes a Group­ + KeySetStruct (see IPKValue). However, the value 0 is illegal in the GroupKeySet field sent by a + client. +- If the EpochKey1 field is not null, then the EpochKey0 field SHALL NOT be null. Otherwise this + command SHALL fail with an INVALID_COMMAND status code responded to the client. +- If the EpochKey1 field is not null, and the field’s length is not exactly 16 bytes, then this com­ + mand SHALL fail with a CONSTRAINT_ERROR status code responded to the client. +- If the EpochKey1 field is not null, its associated EpochStartTime1 field SHALL NOT be null and + SHALL contain a later epoch start time than the epoch start time found in the EpochStartTime0 + field. Otherwise this command SHALL fail with an INVALID_COMMAND status code responded + to the client. +- If exactly one of the EpochKey1 or EpochStartTime1 is null, rather than both being null, or nei­ + ther being null, then this command SHALL fail with an INVALID_COMMAND status code + responded to the client. +- If the EpochKey2 field is not null, then the EpochKey1 and EpochKey0 fields SHALL NOT be null. + Otherwise this command SHALL fail with an INVALID_COMMAND status code responded to the + client. +- If the EpochKey2 field is not null, and the field’s length is not exactly 16 bytes, then this com­ + mand SHALL fail with a CONSTRAINT_ERROR status code responded to the client. +- If the EpochKey2 field is not null, its associated EpochStartTime2 field SHALL NOT be null and + SHALL contain a later epoch start time than the epoch start time found in the EpochStartTime1 + field. Otherwise this command SHALL fail with an INVALID_COMMAND status code responded + to the client. +- If exactly one of the EpochKey2 or EpochStartTime2 is null, rather than both being null, or nei­ + ther being null, then this command SHALL fail with an INVALID_COMMAND status code + responded to the client. + +If there exists a Group Key Set associated with the accessing fabric which has the same GroupKey­ +SetID as that provided in the GroupKeySet field, then the contents of that group key set SHALL be + +``` +Page 744 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +replaced. A replacement SHALL be done by executing the equivalent of entirely removing the pre­ +vious Group Key Set with the given GroupKeySetID, followed by an addition of a Group Key Set with +the provided configuration. Otherwise, if the GroupKeySetID did not match an existing entry, a new +Group Key Set associated with the accessing fabric SHALL be created with the provided data. The +Group Key Set SHALL be written to non-volatile storage. + +Upon completion, this command SHALL send a status code back to the initiator: + +- If the Group Key Set was properly installed or updated on the Node, the status code SHALL be + set to SUCCESS. +- If there are insufficient resources on the receiver to store an additional Group Key Set, the sta­ + tus code SHALL be set to RESOURCE_EXHAUSTED (see group key limits); +- Otherwise, this status code SHALL be set to FAILURE. + +**11.2.7.2. KeySetRead Command** + +This command is used by Administrators to read the state of a given Group Key Set. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupKey­ +SetID +``` +``` +uint16 all M +``` +**Effect on Receipt** + +If there exists a Group Key Set associated with the accessing fabric which has the same GroupKey­ +SetID as that provided in the GroupKeySetID field, then the contents of that Group Key Set SHALL +be sent in a KeySetReadResponse command, but with the EpochKey0, EpochKey1 and EpochKey2 +fields replaced by null. + +Otherwise, if the GroupKeySetID does not refer to a Group Key Set associated with the accessing +fabric, then this command SHALL fail with a NOT_FOUND status code. + +**11.2.7.3. KeySetReadResponse Command** + +This command SHALL be generated in response to the KeySetRead command, if a valid Group Key +Set was found. It SHALL contain the configuration of the requested Group Key Set, with the +EpochKey0, EpochKey1 and EpochKey2 key contents replaced by null. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupKey­ +Set +``` +``` +GroupKey­ +SetStruct +``` +### M + +**11.2.7.4. KeySetRemove Command** + +This command is used by Administrators to remove all state of a given Group Key Set. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 745 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupKey­ +SetID +``` +``` +uint16 all M +``` +**Effect on Receipt** + +If there exists a Group Key Set associated with the accessing fabric which has the same GroupKey­ +SetID as that provided in the GroupKeySetID field, then the contents of that Group Key Set SHALL +be removed, including all epoch keys it contains. + +If there exist any entries for the accessing fabric within the GroupKeyMap attribute that refer to the +GroupKeySetID just removed, then these entries SHALL be removed from that list. + +This command SHALL fail with an INVALID_COMMAND status code back to the initiator if the +GroupKeySetID being removed is 0, which is the Key Set associated with the Identity Protection Key +(IPK). The only method to remove the IPK is usage of the RemoveFabric command or any operation +which causes the equivalent of a RemoveFabric to occur by side-effect. + +This command SHALL send a SUCCESS status code back to the initiator on success, or NOT_FOUND +if the GroupKeySetID requested did not exist. + +**11.2.7.5. KeySetReadAllIndices Command** + +This command is used by Administrators to query a list of all Group Key Sets associated with the +accessing fabric. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 DoNotUse X +``` +**Effect on Receipt** + +Upon receipt, this command SHALL iterate all stored GroupKeySetStruct associated with the access­ +ing fabric and generate a KeySetReadAllIndicesResponse command containing the list of GroupKey­ +SetID values from those structs. + +**11.2.7.6. KeySetReadAllIndicesResponse Command** + +This command SHALL be generated in response to KeySetReadAllIndices and it SHALL contain the +list of _GroupKeySetID_ for all Group Key Sets associated with the scoped Fabric. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupKey­ +SetIDs +``` +``` +list[uint16] M +``` +``` +Page 746 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**GroupKeySetIDs Field** + +This field references the set of group keys that generate operational group keys for use with the +accessing fabric. + +Each entry in GroupKeySetIDs is a GroupKeySetID field. + +**11.3. Localization Configuration Cluster** + +Nodes should be expected to be deployed to any and all regions of the world. These global regions +may have differing common languages, units of measurements, and numerical formatting stan­ +dards. As such, Nodes that visually or audibly convey information need a mechanism by which they +can be configured to use a user’s preferred language, units, etc. + +This cluster supports an interface to a Node. It provides attributes for determining and configuring +localization information that a Node SHALL utilize when conveying values to a user. + +**11.3.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.3.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node LCFG +``` +**11.3.3. Cluster ID** + +``` +ID Name +0x002B Localization Configuration +``` +**11.3.4. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 ActiveLo­ +cale +``` +``` +string max 35 N MS RW VM M +``` +``` +0x0001 Support­ +edLocales +``` +``` +list[string] max +32[max 35] +``` +### F MS R V M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 747 +``` + +**11.3.4.1. ActiveLocale Attribute** + +The ActiveLocale attribute SHALL represent the locale that the Node is currently configured to use +when conveying information. The ActiveLocale attribute SHALL be a Language Tag as defined by +BCP47. The ActiveLocale attribute SHALL have a default value assigned by the Vendor and SHALL +be a value contained within the SupportedLocales attribute. + +An attempt to write a value to ActiveLocale that is not present in SupportedLocales SHALL result in +a CONSTRAINT_ERROR error. + +**11.3.4.2. SupportedLocales Attribute** + +The SupportedLocales attribute SHALL represent a list of locale strings that are valid values for the +ActiveLocale attribute. The list SHALL NOT contain any duplicate entries. The ordering of items +within the list SHOULD NOT express any meaning. + +**11.4. Time Format Localization Cluster** + +Nodes should be expected to be deployed to any and all regions of the world. These global regions +may have differing preferences for how dates and times are conveyed. As such, Nodes that visually +or audibly convey time information need a mechanism by which they can be configured to use a +user’s preferred format. + +This cluster supports an interface to a Node. It provides attributes for determining and configuring +time and date formatting information that a Node SHALL utilize when conveying values to a user. + +**11.4.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.4.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node LTIME +``` +**11.4.3. Cluster ID** + +``` +ID Name +0x002C Time Format Localization +``` +**11.4.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Page 748 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Summary +0 CALFMT CalendarFormat The Node can be con­ +figured to use different +calendar formats when +conveying values to a +user. +``` +**11.4.5. Data Types** + +**11.4.5.1. HourFormatEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 12hr Time conveyed with a +12-hour clock +``` +### M + +``` +1 24hr Time conveyed with a +24-hour clock +``` +### M + +``` +255 UseActiveLocale Use active locale clock M +``` +**11.4.5.2. CalendarTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Buddhist Dates conveyed using +the Buddhist calendar +``` +``` +O.a+ +``` +``` +1 Chinese Dates conveyed using +the Chinese calendar +``` +``` +O.a+ +``` +``` +2 Coptic Dates conveyed using +the Coptic calendar +``` +``` +O.a+ +``` +``` +3 Ethiopian Dates conveyed using +the Ethiopian calendar +``` +``` +O.a+ +``` +``` +4 Gregorian Dates conveyed using +the Gregorian calendar +``` +``` +O.a+ +``` +``` +5 Hebrew Dates conveyed using +the Hebrew calendar +``` +``` +O.a+ +``` +``` +6 Indian Dates conveyed using +the Indian calendar +``` +``` +O.a+ +``` +``` +7 Islamic Dates conveyed using +the Islamic calendar +``` +``` +O.a+ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 749 +``` + +``` +Value Name Summary Conformance +8 Japanese Dates conveyed using +the Japanese calendar +``` +``` +O.a+ +``` +``` +9 Korean Dates conveyed using +the Korean calendar +``` +``` +O.a+ +``` +``` +10 Persian Dates conveyed using +the Persian calendar +``` +``` +O.a+ +``` +``` +11 Taiwanese Dates conveyed using +the Taiwanese calendar +``` +``` +O.a+ +``` +``` +255 UseActiveLocale calendar implied from +active locale +``` +``` +O.a+ +``` +**11.4.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 HourFor­ +mat +``` +``` +HourFor­ +matEnum +``` +``` +all N RW VM M +``` +``` +0x0001 ActiveCal­ +endarType +``` +``` +Calendar­ +TypeEnum +``` +``` +all N RW VM CALFMT +``` +``` +0x0002 Support­ +edCalen­ +darTypes +``` +``` +list[Calen­ +darType­ +Enum] +``` +``` +desc F N/A R V CALFMT +``` +**11.4.6.1. HourFormat Attribute** + +This attribute SHALL represent the format that the Node is currently configured to use when con­ +veying the hour unit of time. + +If not UseActiveLocale, this value SHALL take priority over any unit implied through the ActiveLo­ +cale attribute. +If UseActiveLocale, any unit implied through the ActiveLocale attribute is used as the hour format, +and if ActiveLocale is not present, the hour format is unknown. + +**11.4.6.2. ActiveCalendarType Attribute** + +This attribute SHALL represent the calendar format that the Node is currently configured to use +when conveying dates. + +If not UseActiveLocale, this value SHALL take priority over any unit implied through the ActiveLo­ +cale attribute. +If UseActiveLocale, any unit implied through the ActiveLocale attribute is used as the calendar type, +and if ActiveLocale is not present, the calendar type is unknown. + +``` +Page 750 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.4.6.3. SupportedCalendarTypes Attribute** + +This attribute SHALL represent a list of CalendarTypeEnum values that are supported by the Node. +The list SHALL NOT contain any duplicate entries. The ordering of items within the list SHOULD +NOT express any meaning. The maximum length of the SupportedCalendarTypes list SHALL be +equivalent to the number of enumerations within CalendarTypeEnum. + +**11.5. Unit Localization Cluster** + +Nodes should be expected to be deployed to any and all regions of the world. These global regions +may have differing preferences for the units in which values are conveyed in communication to a +user. As such, Nodes that visually or audibly convey measurable values to the user need a mecha­ +nism by which they can be configured to use a user’s preferred unit. + +This cluster supports an interface to a Node. It provides attributes for determining and configuring +the units that a Node SHALL utilize when conveying values in communication to a user. + +**11.5.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.5.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node LUNIT +``` +**11.5.3. Cluster ID** + +``` +ID Name +0x002D Unit Localization +``` +**11.5.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 TEMP TemperatureUnit The Node can be con­ +figured to use different +units of temperature +when conveying values +to a user. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 751 +``` + +**11.5.5. Data Types** + +**11.5.5.1. TempUnitEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Fahrenheit Temperature conveyed +in Fahrenheit +``` +### M + +``` +1 Celsius Temperature conveyed +in Celsius +``` +### M + +``` +2 Kelvin Temperature conveyed +in Kelvin +``` +### M + +**11.5.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Tempera­ +tureUnit +``` +``` +Tem­ +pUnitEnu +m +``` +``` +all N RW VM TEMP +``` +**11.5.6.1. TemperatureUnit Attribute** + +The TemperatureUnit attribute SHALL indicate the unit for the Node to use only when conveying +temperature in communication to the user. If provided, this value SHALL take priority over any +unit implied through the ActiveLocale Attribute. + +**11.6. Power Source Configuration Cluster** + +This cluster is used to describe the configuration and capabilities of a Device’s power system. It pro­ +vides an ordering overview as well as linking to the one or more endpoints each supporting a +Power Source cluster. + +**11.6.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.6.2. Classification** + +``` +Page 752 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Hierarchy Role Scope PICS Code +Base Utility Node PSCFG +``` +**11.6.3. Cluster ID** + +``` +ID Name +0x002E Power Source Configuration +``` +**11.6.4. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Sources list[end­ +point-no] +``` +``` +max 6 N R V M +``` +**11.6.4.1. Sources Attribute** + +This list SHALL contain the set of all power sources capable of participating in the power system of +this Node. Each entry in the list SHALL be the endpoint number of an endpoint having a Power +Source cluster, which corresponds to a physical power source. The endpoint number SHALL be +unique within the list. + +The order of power sources on a Node is defined by the Order attribute of its associated Power +Source cluster provided on the endpoint. List entries SHALL be sorted in increasing order, that is, +an entry with a lower order SHALL have a lower index than any entry with a higher order. Multiple +entries MAY have the same order, there are no restrictions on their relative sorting. + +**11.7. Power Source Cluster** + +This cluster is used to describe the configuration and capabilities of a physical power source that +provides power to one or more endpoints on a node. In case the node has multiple power sources, +each SHALL be described by its own cluster instance. Each instance of this cluster MAY be associ­ +ated with one or more endpoints or the entire node. + +**11.7.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Added EndpointList attribute that maps a power +source to a list of endpoints +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 753 +``` + +``` +Revision Description +3 Added Q quality (replacing C quality) on BatPer­ +centRemaining, BatTimeRemaining and Bat­ +TimeToFullCharge +``` +**11.7.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node PS +``` +**11.7.3. Cluster ID** + +``` +ID Name +0x002F Power Source +``` +**11.7.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 WIRED Wired O.a A wired power +source +1 BAT Battery O.a A battery power +source +2 RECHG Rechargeable [BAT] A rechargeable +battery power +source +3 REPLC Replaceable [BAT] A replaceable bat­ +tery power source +``` +**11.7.5. Dependencies** + +This cluster SHOULD be on an endpoint that supports a device type that requires this cluster. This +cluster SHOULD NOT be just added as an extra cluster to an endpoint to conserve endpoint +instances. + +**11.7.6. Data Types** + +**11.7.6.1. WiredFaultEnum Type** + +This data type is derived from enum8. + +``` +Page 754 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0 Unspecified The Node detects an +unspecified fault on +this wired power +source. +``` +### M + +``` +1 OverVoltage The Node detects the +supplied voltage is +above maximum sup­ +ported value for this +wired power source. +``` +### M + +``` +2 UnderVoltage The Node detects the +supplied voltage is +below maximum sup­ +ported value for this +wired power source. +``` +### M + +**11.7.6.2. BatFaultEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified The Node detects an +unspecified fault on +this battery power +source. +``` +### M + +``` +1 OverTemp The Node detects the +temperature of this bat­ +tery power source is +above ideal operating +conditions. +``` +### M + +``` +2 UnderTemp The Node detects the +temperature of this bat­ +tery power source is +below ideal operating +conditions. +``` +### M + +**11.7.6.3. BatChargeFaultEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified The Node detects an +unspecified fault on +this battery source. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 755 +``` + +``` +Value Name Summary Conformance +1 AmbientTooHot The Node detects the +ambient temperature is +above the nominal +range for this battery +source. +``` +### M + +``` +2 AmbientTooCold The Node detects the +ambient temperature is +below the nominal +range for this battery +source. +``` +### M + +``` +3 BatteryTooHot The Node detects the +temperature of this bat­ +tery source is above the +nominal range. +``` +### M + +``` +4 BatteryTooCold The Node detects the +temperature of this bat­ +tery source is below the +nominal range. +``` +### M + +``` +5 BatteryAbsent The Node detects this +battery source is not +present. +``` +### M + +``` +6 BatteryOverVoltage The Node detects this +battery source is over +voltage. +``` +### M + +``` +7 BatteryUnderVoltage The Node detects this +battery source is under +voltage. +``` +### M + +``` +8 ChargerOverVoltage The Node detects the +charger for this battery +source is over voltage. +``` +### M + +``` +9 ChargerUnderVoltage The Node detects the +charger for this battery +source is under voltage. +``` +### M + +``` +10 SafetyTimeout The Node detects a +charging safety timeout +for this battery source. +``` +### M + +**11.7.6.4. PowerSourceStatusEnum Type** + +This data type is derived from enum8. + +``` +Page 756 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0 Unspecified Indicate the source sta­ +tus is not specified +``` +### M + +``` +1 Active Indicate the source is +available and currently +supplying power +``` +### M + +``` +2 Standby Indicate the source is +available, but is not +currently supplying +power +``` +### M + +``` +3 Unavailable Indicate the source is +not currently available +to supply power +``` +### M + +**11.7.6.5. WiredCurrentTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 AC Indicates AC current M +1 DC Indicates DC current M +``` +**11.7.6.6. BatChargeLevelEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 OK Charge level is nominal M +1 Warning Charge level is low, +intervention may soon +be required. +``` +### M + +``` +2 Critical Charge level is critical, +immediate intervention +is required +``` +### M + +**11.7.6.7. BatReplaceabilityEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified The replaceability is +unspecified or +unknown. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 757 +``` + +``` +Value Name Summary Conformance +1 NotReplaceable The battery is not +replaceable. +``` +### M + +``` +2 UserReplaceable The battery is replace­ +able by the user or cus­ +tomer. +``` +### M + +``` +3 FactoryReplaceable The battery is replace­ +able by an authorized +factory technician. +``` +### M + +**11.7.6.8. BatCommonDesignationEnum Type** + +This data type is derived from enum16. + +``` +Value Name Summary Conformance +0 Unspecified Common type is +unknown or unspeci­ +fied +``` +### M + +``` +1 AAA Common type is as +specified +``` +### M + +``` +2 AA Common type is as +specified +``` +### M + +``` +3 C Common type is as +specified +``` +### M + +``` +4 D Common type is as +specified +``` +### M + +``` +5 4v5 Common type is as +specified +``` +### M + +``` +6 6v0 Common type is as +specified +``` +### M + +``` +7 9v0 Common type is as +specified +``` +### M + +``` +8 1_2AA Common type is as +specified +``` +### M + +``` +9 AAAA Common type is as +specified +``` +### M + +``` +10 A Common type is as +specified +``` +### M + +``` +11 B Common type is as +specified +``` +### M + +``` +Page 758 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Value Name Summary Conformance** + +12 **F** Common type is as +specified + +### M + +13 **N** Common type is as +specified + +### M + +14 **No6** Common type is as +specified + +### M + +15 **SubC** Common type is as +specified + +### M + +16 **A23** Common type is as +specified + +### M + +17 **A27** Common type is as +specified + +### M + +18 **BA5800** Common type is as +specified + +### M + +19 **Duplex** Common type is as +specified + +### M + +20 **4SR44** Common type is as +specified + +### M + +21 **523** Common type is as +specified + +### M + +22 **531** Common type is as +specified + +### M + +23 **15v0** Common type is as +specified + +### M + +24 **22v5** Common type is as +specified + +### M + +25 **30v0** Common type is as +specified + +### M + +26 **45v0** Common type is as +specified + +### M + +27 **67v5** Common type is as +specified + +### M + +28 **J** Common type is as +specified + +### M + +29 **CR123A** Common type is as +specified + +### M + +30 **CR2** Common type is as +specified + +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 759 +``` + +``` +Value Name Summary Conformance +31 2CR5 Common type is as +specified +``` +### M + +``` +32 CR_P2 Common type is as +specified +``` +### M + +``` +33 CR_V3 Common type is as +specified +``` +### M + +``` +34 SR41 Common type is as +specified +``` +### M + +``` +35 SR43 Common type is as +specified +``` +### M + +``` +36 SR44 Common type is as +specified +``` +### M + +``` +37 SR45 Common type is as +specified +``` +### M + +``` +38 SR48 Common type is as +specified +``` +### M + +``` +39 SR54 Common type is as +specified +``` +### M + +``` +40 SR55 Common type is as +specified +``` +### M + +``` +41 SR57 Common type is as +specified +``` +### M + +``` +42 SR58 Common type is as +specified +``` +### M + +``` +43 SR59 Common type is as +specified +``` +### M + +``` +44 SR60 Common type is as +specified +``` +### M + +``` +45 SR63 Common type is as +specified +``` +### M + +``` +46 SR64 Common type is as +specified +``` +### M + +``` +47 SR65 Common type is as +specified +``` +### M + +``` +48 SR66 Common type is as +specified +``` +### M + +``` +49 SR67 Common type is as +specified +``` +### M + +Page 760 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Value Name Summary Conformance** + +50 **SR68** Common type is as +specified + +### M + +51 **SR69** Common type is as +specified + +### M + +52 **SR516** Common type is as +specified + +### M + +53 **SR731** Common type is as +specified + +### M + +54 **SR712** Common type is as +specified + +### M + +55 **LR932** Common type is as +specified + +### M + +56 **A5** Common type is as +specified + +### M + +57 **A10** Common type is as +specified + +### M + +58 **A13** Common type is as +specified + +### M + +59 **A312** Common type is as +specified + +### M + +60 **A675** Common type is as +specified + +### M + +61 **AC41E** Common type is as +specified + +### M + +62 **10180** Common type is as +specified + +### M + +63 **10280** Common type is as +specified + +### M + +64 **10440** Common type is as +specified + +### M + +65 **14250** Common type is as +specified + +### M + +66 **14430** Common type is as +specified + +### M + +67 **14500** Common type is as +specified + +### M + +68 **14650** Common type is as +specified + +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 761 +``` + +``` +Value Name Summary Conformance +69 15270 Common type is as +specified +``` +### M + +``` +70 16340 Common type is as +specified +``` +### M + +``` +71 RCR123A Common type is as +specified +``` +### M + +``` +72 17500 Common type is as +specified +``` +### M + +``` +73 17670 Common type is as +specified +``` +### M + +``` +74 18350 Common type is as +specified +``` +### M + +``` +75 18500 Common type is as +specified +``` +### M + +``` +76 18650 Common type is as +specified +``` +### M + +``` +77 19670 Common type is as +specified +``` +### M + +``` +78 25500 Common type is as +specified +``` +### M + +``` +79 26650 Common type is as +specified +``` +### M + +``` +80 32600 Common type is as +specified +``` +### M + +**11.7.6.9. BatApprovedChemistryEnum Type** + +This data type is derived from enum16. + +``` +Value Name Summary Conformance +0 Unspecified Cell chemistry is +unspecified or +unknown +``` +### M + +``` +1 Alkaline Cell chemistry is alka­ +line +``` +### M + +``` +2 LithiumCarbonFluo­ +ride +``` +``` +Cell chemistry is +lithium carbon fluoride +``` +### M + +``` +3 LithiumChromiumOx­ +ide +``` +``` +Cell chemistry is +lithium chromium +oxide +``` +### M + +``` +Page 762 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Value Name Summary Conformance** + +4 **LithiumCopperOxide** Cell chemistry is +lithium copper oxide + +### M + +5 **LithiumIronDisulfide** Cell chemistry is +lithium iron disulfide + +### M + +6 **LithiumManganese­ +Dioxide** + +``` +Cell chemistry is +lithium manganese +dioxide +``` +### M + +7 **LithiumThionylChlo­ +ride** + +``` +Cell chemistry is +lithium thionyl chloride +``` +### M + +8 **Magnesium** Cell chemistry is mag­ +nesium + +### M + +9 **MercuryOxide** Cell chemistry is mer­ +cury oxide + +### M + +10 **NickelOxyhydride** Cell chemistry is nickel +oxyhydride + +### M + +11 **SilverOxide** Cell chemistry is silver +oxide + +### M + +12 **ZincAir** Cell chemistry is zinc +air + +### M + +13 **ZincCarbon** Cell chemistry is zinc +carbon + +### M + +14 **ZincChloride** Cell chemistry is zinc +chloride + +### M + +15 **ZincManganeseDiox­ +ide** + +``` +Cell chemistry is zinc +manganese dioxide +``` +### M + +16 **LeadAcid** Cell chemistry is lead +acid + +### M + +17 **LithiumCobaltOxide** Cell chemistry is +lithium cobalt oxide + +### M + +18 **LithiumIon** Cell chemistry is +lithium ion + +### M + +19 **LithiumIonPolymer** Cell chemistry is +lithium ion polymer + +### M + +20 **LithiumIronPhos­ +phate** + +``` +Cell chemistry is +lithium iron phosphate +``` +### M + +21 **LithiumSulfur** Cell chemistry is +lithium sulfur + +### M + +22 **LithiumTitanate** Cell chemistry is +lithium titanate + +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 763 +``` + +``` +Value Name Summary Conformance +23 NickelCadmium Cell chemistry is nickel +cadmium +``` +### M + +``` +24 NickelHydrogen Cell chemistry is nickel +hydrogen +``` +### M + +``` +25 NickelIron Cell chemistry is nickel +iron +``` +### M + +``` +26 NickelMetalHydride Cell chemistry is nickel +metal hydride +``` +### M + +``` +27 NickelZinc Cell chemistry is nickel +zinc +``` +### M + +``` +28 SilverZinc Cell chemistry is silver +zinc +``` +### M + +``` +29 SodiumIon Cell chemistry is +sodium ion +``` +### M + +``` +30 SodiumSulfur Cell chemistry is +sodium sulfur +``` +### M + +``` +31 ZincBromide Cell chemistry is zinc +bromide +``` +### M + +``` +32 ZincCerium Cell chemistry is zinc +cerium +``` +### M + +**11.7.6.10. BatChargeStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown Unable to determine +the charging state +``` +### M + +``` +1 IsCharging The battery is charging M +2 IsAtFullCharge The battery is at full +charge +``` +### M + +``` +3 IsNotCharging The battery is not +charging +``` +### M + +**11.7.7. Attributes** + +``` +Page 764 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**ID Name Type Constraint Quality Default Access Confor­ +mance** + +0x0000 **Status** Power­ +SourceSta­ +tusEnum + +``` +desc R V M +``` +0x0001 **Order** uint8 all N R V M + +0x0002 **Descrip­ +tion** + +``` +string max 60 F R V M +``` +0x0003 **WiredAsse +ssedInput­ +Voltage** + +``` +uint32 all X C R V [WIRED] +``` +0x0004 **WiredAsse +ssedInput­ +Frequency** + +``` +uint16 all X C R V [WIRED] +``` +0x0005 **WiredCur­ +rentType** + +``` +WiredCur­ +rentType­ +Enum +``` +``` +desc F R V WIRED +``` +0x0006 **WiredAsse +ssedCur­ +rent** + +``` +uint32 all X C R V [WIRED] +``` +0x0007 **Wired­ +Nominal­ +Voltage** + +``` +uint32 all F R V [WIRED] +``` +0x0008 **Wired­ +Maxi­ +mumCur­ +rent** + +``` +uint32 all F R V [WIRED] +``` +0x0009 **WiredPre­ +sent** + +``` +bool all R V [WIRED] +``` +0x000A **ActiveWir +edFaults** + +``` +list[Wired­ +Fault­ +Enum] +``` +``` +max 8 R V [WIRED] +``` +0x000B **BatVoltage** uint32 all X C R V [BAT] + +0x000C **BatPer­ +centRemai +ning** + +``` +uint8 max 200 X Q R V [BAT] +``` +0x000D **Bat­ +TimeRe­ +maining** + +``` +uint32 all X Q R V [BAT] +``` +0x000E **BatCharge +Level** + +``` +BatCharge +LevelEnum +``` +``` +desc R V BAT +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 765 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x000F BatRe­ +place­ +ment­ +Needed +``` +``` +bool all R V BAT +``` +``` +0x0010 BatRe­ +placeabil­ +ity +``` +``` +BatRe­ +placeabili­ +tyEnum +``` +``` +all F R V BAT +``` +``` +0x0011 BatPre­ +sent +``` +``` +bool all R V [BAT] +``` +``` +0x0012 ActiveBat­ +Faults +``` +``` +list[Bat­ +Fault­ +Enum] +``` +``` +max 8 R V [BAT] +``` +``` +0x0013 BatRe­ +place­ +mentDe­ +scription +``` +``` +string max 60 F R V REPLC +``` +``` +0x0014 BatCom­ +monDesig­ +nation +``` +``` +BatCom­ +monDesig­ +natio­ +nEnum +``` +``` +desc F R V [REPLC] +``` +``` +0x0015 BatANSID­ +esignation +``` +``` +string max 20 F R V [REPLC] +``` +``` +0x0016 BatIECDes +ignation +``` +``` +string max 20 F R V [REPLC] +``` +``` +0x0017 BatAp­ +proved­ +Chemistry +``` +``` +BatAp­ +proved­ +Chem­ +istryEnum +``` +``` +desc F R V [REPLC] +``` +``` +0x0018 BatCapac­ +ity +``` +``` +uint32 all F R V [REPLC | +RECHG] +0x0019 BatQuan­ +tity +``` +``` +uint8 all F R V REPLC +``` +``` +0x001A BatCharge +State +``` +``` +BatCharge +StateEnum +``` +``` +desc R V RECHG +``` +``` +0x001B Bat­ +TimeTo­ +FullCharg +e +``` +``` +uint32 all X Q R V [RECHG] +``` +Page 766 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x001C BatFunc­ +tional­ +WhileChar +ging +``` +``` +bool all R V RECHG +``` +``` +0x001D BatCharg­ +ingCur­ +rent +``` +``` +uint32 all X C R V [RECHG] +``` +``` +0x001E Active­ +BatCharge +Faults +``` +``` +list[BatCha +rgeFault­ +Enum] +``` +``` +max 16 R V [RECHG] +``` +``` +0x001F End­ +pointList +``` +``` +list[end­ +point-no] +``` +### R V M + +**11.7.7.1. Status Attribute** + +This attribute SHALL indicate the participation of this power source in providing power to the Node +as specified in PowerSourceStatusEnum. + +**11.7.7.2. Order Attribute** + +This attribute SHALL indicate the relative preference with which the Node will select this source to +provide power. A source with a lower order SHALL be selected by the Node to provide power +before any other source with a higher order, if the lower order source is available (see Status). + +Note, Order is read-only and therefore NOT intended to allow clients control over power source +selection. + +**11.7.7.3. Description Attribute** + +This attribute SHALL provide a user-facing description of this source, used to distinguish it from +other power sources, e.g. "DC Power", "Primary Battery" or "Battery back-up". This attribute SHALL +NOT be used to convey information such as battery form factor, or chemistry. + +**11.7.7.4. WiredAssessedInputVoltage Attribute** + +This attribute SHALL indicate the assessed RMS or DC voltage currently provided by the hard-wired +source, in mV (millivolts). A value of NULL SHALL indicate the Node is currently unable to assess +the value. If the wired source is not connected, but the Node is still able to assess a value, then the +assessed value MAY be reported. + +**11.7.7.5. WiredAssessedInputFrequency Attribute** + +This attribute SHALL indicate the assessed frequency of the voltage, currently provided by the +hard-wired source, in Hz. A value of NULL SHALL indicate the Node is currently unable to assess +the value. If the wired source is not connected, but the Node is still able to assess a value, then the +assessed value MAY be reported. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 767 +``` + +**11.7.7.6. WiredCurrentType Attribute** + +This attribute SHALL indicate the type of current the Node expects to be provided by the hard- +wired source as specified in WiredCurrentTypeEnum. + +**11.7.7.7. WiredAssessedCurrent Attribute** + +This attribute SHALL indicate the assessed instantaneous current draw of the Node on the hard- +wired source, in mA (milliamps). A value of NULL SHALL indicate the Node is currently unable to +assess the value. If the wired source is not connected, but the Node is still able to assess a value, +then the assessed value MAY be reported. + +**11.7.7.8. WiredNominalVoltage Attribute** + +This attribute SHALL indicate the nominal voltage, printed as part of the Node’s regulatory compli­ +ance label in mV (millivolts), expected to be provided by the hard-wired source. + +**11.7.7.9. WiredMaximumCurrent Attribute** + +This attribute SHALL indicate the maximum current, printed as part of the Node’s regulatory com­ +pliance label in mA (milliamps), expected to be provided by the hard-wired source. + +**11.7.7.10. WiredPresent Attribute** + +This attribute SHALL indicate if the Node detects that the hard-wired power source is properly con­ +nected. + +**11.7.7.11. ActiveWiredFaults Attribute** + +This attribute SHALL indicate the set of wired faults currently detected by the Node on this power +source. This set is represented as a list of WiredFaultEnum. When the Node detects a fault has been +raised, the appropriate WiredFaultEnum value SHALL be added to this list, provided it is not +already present. This list SHALL NOT contain more than one instance of a specific WiredFaultEnum +value. When the Node detects all conditions contributing to a fault have been cleared, the corre­ +sponding WiredFaultEnum value SHALL be removed from this list. An empty list SHALL indicate +there are currently no active faults. The order of this list SHOULD have no significance. Clients +interested in monitoring changes in active faults MAY subscribe to this attribute, or they MAY sub­ +scribe to WiredFaultChange. + +**11.7.7.12. BatVoltage Attribute** + +This attribute SHALL indicate the currently measured output voltage of the battery in mV (milli­ +volts). A value of NULL SHALL indicate the Node is currently unable to assess the value. + +**11.7.7.13. BatPercentRemaining Attribute** + +This attribute SHALL indicate the estimated percentage of battery charge remaining until the bat­ +tery will no longer be able to provide power to the Node. Values are expressed in half percent units, +ranging from 0 to 200. E.g. a value of 48 is equivalent to 24%. A value of NULL SHALL indicate the +Node is currently unable to assess the value. + +``` +Page 768 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once every 10 seconds, or +- When it changes from null to any other value and vice versa. + +Since reporting consumes power, devices SHOULD be careful not to over-report. + +**11.7.7.14. BatTimeRemaining Attribute** + +This attribute SHALL indicate the estimated time in seconds before the battery will no longer be +able to provide power to the Node. A value of NULL SHALL indicate the Node is currently unable to +assess the value. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once every 10 seconds, or +- When it changes from null to any other value and vice versa. + +Since reporting consumes power, devices SHOULD be careful not to over-report. + +**11.7.7.15. BatChargeLevel Attribute** + +This attribute SHALL indicate a coarse ranking of the charge level of the battery, used to indicate +when intervention is required as specified in BatChargeLevelEnum. + +**11.7.7.16. BatReplacementNeeded Attribute** + +This attribute SHALL indicate if the battery needs to be replaced. Replacement MAY be simple rou­ +tine maintenance, such as with a single use, non-rechargeable cell. Replacement, however, MAY +also indicate end of life, or serious fault with a rechargeable or even non-replaceable cell. + +**11.7.7.17. BatReplaceability Attribute** + +This attribute SHALL indicate the replaceability of the battery as specified in BatReplaceabili­ +tyEnum. + +**11.7.7.18. BatPresent Attribute** + +This attribute SHALL indicate whether the Node detects that the batteries are properly installed. + +**11.7.7.19. ActiveBatFaults Attribute** + +This attribute SHALL indicate the set of battery faults currently detected by the Node on this power +source. This set is represented as a list of BatFaultEnum. When the Node detects a fault has been +raised, the appropriate BatFaultEnum value SHALL be added to this list, provided it is not already +present. This list SHALL NOT contain more than one instance of a specific BatFaultEnum value. +When the Node detects all conditions contributing to a fault have been cleared, the corresponding +BatFaultEnum value SHALL be removed from this list. An empty list SHALL indicate there are cur­ +rently no active faults. The order of this list SHOULD have no significance. Clients interested in +monitoring changes in active faults MAY subscribe to this attribute, or they MAY subscribe to Bat­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 769 +``` + +FaultChange. + +**11.7.7.20. BatReplacementDescription Attribute** + +This attribute SHALL provide a user-facing description of this battery, which SHOULD contain +information required to identify a replacement, such as form factor, chemistry or preferred manu­ +facturer. + +**11.7.7.21. BatCommonDesignation Attribute** + +This attribute SHALL indicate the ID of the common or colloquial designation of the battery, as +specified in BatCommonDesignationEnum. + +**11.7.7.22. BatANSIDesignation Attribute** + +This attribute SHALL indicate the string representing the ANSI designation for the battery as speci­ +fied in ANSI C18. + +**11.7.7.23. BatIECDesignation Attribute** + +This attribute SHALL indicate the string representing the IEC designation for the battery as speci­ +fied in IEC 60086. + +**11.7.7.24. BatApprovedChemistry Attribute** + +This attribute SHALL indicate the ID of the preferred chemistry of the battery source as specified in +BatApprovedChemistryEnum. + +**11.7.7.25. BatCapacity Attribute** + +This attribute SHALL indicate the preferred minimum charge capacity rating in mAh of individual, +user- or factory-serviceable battery cells or packs in the battery source. + +**11.7.7.26. BatQuantity Attribute** + +This attribute SHALL indicate the quantity of individual, user- or factory-serviceable battery cells +or packs in the battery source. + +**11.7.7.27. BatChargeState Attribute** + +This attribute SHALL indicate the current state of the battery source with respect to charging as +specified in BatChargeStateEnum. + +**11.7.7.28. BatTimeToFullCharge Attribute** + +This attribute SHALL indicate the estimated time in seconds before the battery source will be at full +charge. A value of NULL SHALL indicate the Node is currently unable to assess the value. + +Changes to this attribute SHALL only be marked as reportable in the following cases: + +- At most once every 10 seconds, or + +``` +Page 770 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- When it changes from null to any other value and vice versa. + +Since reporting consumes power, devices SHOULD be careful not to over-report. + +**11.7.7.29. BatFunctionalWhileCharging Attribute** + +This attribute SHALL indicate whether the Node can remain operational while the battery source is +charging. + +**11.7.7.30. BatChargingCurrent Attribute** + +This attribute SHALL indicate assessed current in mA (milliamps) presently supplied to charge the +battery source. A value of NULL SHALL indicate the Node is currently unable to assess the value. + +**11.7.7.31. ActiveBatChargeFaults Attribute** + +This attribute SHALL indicate the set of charge faults currently detected by the Node on this power +source. This set is represented as a list of BatChargeFaultEnum. When the Node detects a fault has +been raised, the appropriate BatChargeFaultEnum value SHALL be added to this list, provided it is +not already present. This list SHALL NOT contain more than one instance of a specific BatCharge­ +FaultEnum value. When the Node detects all conditions contributing to a fault have been cleared, +the corresponding BatChargeFaultEnum value SHALL be removed from this list. An empty list +SHALL indicate there are currently no active faults. The order of this list SHOULD have no signifi­ +cance. Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or +they MAY subscribe to the BatFaultChange event. + +**11.7.7.32. EndpointList Attribute** + +This attribute SHALL indicate a list of endpoints that are powered by the source defined by this +cluster. Multiple instances of this cluster MAY list the same endpoint, because it is possible for +power for an endpoint to come from multiple sources. In that case the Order attribute indicates +their priority. + +For each power source on a node, there SHALL only be one instance of this cluster. + +A cluster instance with an empty list SHALL indicate that the power source is for the entire node, +which includes all endpoints. + +A cluster instance with a non-empty list SHALL include the endpoint, upon which the cluster +instance resides. + +The above rules allow that some endpoints can have an unknown power source, and therefore +would not be indicated by any instance of this cluster. + +``` +Legacy Implementations +``` +``` +Legacy implementations of this cluster before revision 2, before this attribute was defined, +would have implemented this cluster on an application endpoint without indicating it in End­ +pointList (since that attribute did not exist in revision 1), because it represented a power +source for the endpoint, not the entire node. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 771 +``` + +``` +For example: Bridge implementations support endpoints for bridged devices that have differ­ +ent power sources. +``` +``` +Such implementations followed device type requirements and semantics outside of this clus­ +ter, because this attribute did not exist. +``` +``` +Future updates of such a cluster instance on the same endpoint, would allow that same end­ +point to be an entry in the EndpointList attribute. Therefore it is valid to list the endpoint +upon which the cluster instance exists. +``` +**Empty list examples** + +``` +Typically, there is one power source for the node. Also common is mains power for the node +with battery backup power for the node. In both these common cases, for each cluster instance +described, the list is empty. +``` +**Populated list example** + +``` +A node has a mains power source with Order as 0 (zero), but some application endpoints (not +all) have a battery back up source with Order as 1, which means this list is empty for the Power +Source cluster associated with the mains power, because it indicates the entire node, but the +Power Source cluster instance associated with the battery backup would list the endpoints that +have a battery backup. +``` +**11.7.8. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 WiredFault­ +Change +``` +### INFO V [WIRED] + +``` +0x01 BatFault­ +Change +``` +### INFO V [BAT] + +``` +0x02 BatCharge­ +FaultChange +``` +### INFO V [RECHG] + +**11.7.8.1. WiredFaultChange Event** + +The WiredFaultChange Event SHALL be generated when the set of wired faults currently detected +by the Node on this wired power source changes. This event SHALL correspond to a change in +value of ActiveWiredFaults. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Current list[Wired­ +FaultEnum] +``` +``` +max 8 empty M +``` +``` +1 Previous list[Wired­ +FaultEnum] +``` +``` +max 8 empty M +``` +``` +Page 772 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Current Field** + +This field SHALL represent the set of faults currently detected, as per ActiveWiredFaults. + +**Previous Field** + +This field SHALL represent the set of faults detected prior to this change event, as per ActiveWired­ +Faults. + +**11.7.8.2. BatFaultChange Event** + +The BatFaultChange Event SHALL be generated when the set of battery faults currently detected by +the Node on this battery power source changes. This event SHALL correspond to a change in value +of ActiveBatFaults. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Current list[BatFault­ +Enum] +``` +``` +max 8 empty M +``` +``` +1 Previous list[BatFault­ +Enum] +``` +``` +max 8 empty M +``` +**Current Field** + +This field SHALL represent the set of faults currently detected, as per ActiveBatFaults. + +**Previous Field** + +This field SHALL represent the set of faults detected prior to this change event, as per ActiveBat­ +Faults. + +**11.7.8.3. BatChargeFaultChange Event** + +The BatChargeFaultChange Event SHALL be generated when the set of charge faults currently +detected by the Node on this battery power source changes. This event SHALL correspond to a +change in value of ActiveBatChargeFaults. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Current list[BatCharg +eFaultEnum] +``` +``` +max 16 empty M +``` +``` +1 Previous list[BatCharg +eFaultEnum] +``` +``` +max 16 empty M +``` +**Current Field** + +This field SHALL represent the set of faults currently detected, as per ActiveBatChargeFaults. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 773 +``` + +**Previous Field** + +This field SHALL represent the set of faults detected prior to this change event, as per Active­ +BatChargeFaults. + +**11.7.9. Configuration Examples** + +The following examples illustrate use of the Order attribute in the Power Source Cluster. + +**11.7.9.1. Example: Redundant Mains Power Sources** + +This example describes a design with symmetric, dual-redundant mains power sources, where the +system is powered by either one of the power sources. The Node must define two Power Source +Clusters, one for each mains source. The system indicates no preference for either source, so the +sources have the same Order. + +_Power Source (on Endpoint 2)_ + +``` +Description: "Mains A" +Order: 0 +``` +_Power Source (on Endpoint 5)_ + +``` +Description: "Mains B" +Order: 0 +``` +**11.7.9.2. Example: Battery with Mains Power Back-up** + +This example describes a design with a built-in battery as the primary source, where the mains +power serves to keep the battery charged and act as back-up if the battery fails. The Node must +define two Power Source Clusters, one for the battery and another for the mains. Since the battery +is primary, it must have a lower Order than the mains source. + +_Power Source (on Endpoint 2)_ + +``` +Description: "Primary Battery" +Order: 0 +``` +_Power Source (on Endpoint 5)_ + +``` +Description: "Mains" +Order: 1 +``` +**11.7.9.3. Example: Mains Power with Battery Back-up** + +This example describes a design where the system always runs from the a mains power source and +the back-up battery is out-of-circuit until mains power fails at which point the back-up battery pow­ +ers the system. The Node must define two Power Source Clusters, one for the mains and another for + +``` +Page 774 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +the battery. Since the mains source is primary, it must have a lower Order than the battery source. + +_Power Source (on Endpoint 2)_ + +``` +Description: "Mains" +Order: 0 +``` +_Power Source (on Endpoint 5)_ + +``` +Description: "Battery Back-up" +Order: 1 +``` +**11.7.9.4. Example: Battery with Dual Back-up** + +This example describes a design with a built-in battery as the primary source, and where two wired +sources, USB and a DC adapter, redundantly serve to keep the battery charged and act as back-up if +the battery fails. The Node must define three Power Source Clusters, one for each of the battery, the +USB source, and the DC adapter. Since the battery is primary, the battery source must have a lower +Order than the other sources. This system has no preference between the DC Adapter and USB +sources, so these sources will have the same Order. + +_Power Source (on Endpoint 2)_ + +``` +Description: "Primary Battery" +Order: 0 +``` +_Power Source (on Endpoint 5)_ + +``` +Description: "DC Adapter" +Order: 1 +``` +_Power Source (on Endpoint 7)_ + +``` +Description: "USB Power" +Order: 1 +``` +**11.7.9.5. Example: Mains Power with Battery Powered Peripheral** + +This example describes a design with a mains powered core and battery powered peripheral. In +this example both power sources are required for proper operation. The Node must define two +Power Source Clusters, one for the wired source and one for the battery. Since both sources are +required, both sources will have the same Order. We will use Endpoint 2 for the mains power and +Endpoint 7 for the battery. + +_Power Source (on Endpoint 2)_ + +``` +Description: "Mains Power" +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 775 +``` + +``` +Order: 0 +``` +_Power Source (on Endpoint 7)_ + +``` +Description: "Peripheral Battery" +Order: 0 +``` +**11.8. Power Topology Cluster** + +The Power Topology Cluster provides a mechanism for expressing how power is flowing between +endpoints. + +**11.8.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.8.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Application Endpoint PWRTL +``` +**11.8.3. Cluster ID** + +``` +ID Name +0x009C Power Topology +``` +**11.8.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 NODE NodeTopology O.a This endpoint pro­ +vides or consumes +power to/from the +entire node +1 TREE TreeTopology O.a This endpoint pro­ +vides or consumes +power to/from +itself and its child +endpoints +``` +``` +Page 776 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Conformance Summary +2 SET SetTopology O.a This endpoint pro­ +vides or consumes +power to/from a +specified set of +endpoints +3 DYPF DynamicPower­ +Flow +``` +``` +[SET] The specified set +of endpoints may +change +``` +**11.8.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Avail­ +ableEnd­ +points +``` +``` +list[end­ +point-no] +``` +``` +max 20 F R V SET +``` +``` +0x0001 ActiveEnd +points +``` +``` +list[end­ +point-no] +``` +``` +max 20 N R V DYPF +``` +**11.8.5.1. AvailableEndpoints Attribute** + +This attribute SHALL indicate the list of endpoints capable of providing power to and/or consuming +power from the endpoint hosting this server. + +**11.8.5.2. ActiveEndpoints Attribute** + +This attribute SHALL indicate the current list of endpoints currently providing or consuming power +to or from the endpoint hosting this server. This list SHALL be a subset of the value of the Avail­ +ableEndpoints attribute. + +**11.9. Network Commissioning Cluster** + +Network commissioning is part of the overall Node commissioning. The main goal of Network Com­ +missioning Cluster is to associate a Node with or manage a Node’s one or more network interfaces. +These network interfaces can include the following types. + +- Wi-Fi (IEEE 802.11-2020) +- Ethernet (802.3) +- Thread (802.15.4) + +An instance of the Network Commissioning Cluster only applies to a single network interface +instance present. An interface, in this context, is a unique entity that can have an IPv6 address +assigned to it and ingress and egress IP packets. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 777 +``` + +**11.9.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Support determining capabilities for Wi-Fi and +Thread interfaces. Additional Wi-Fi directed +scanning requirements. +``` +**11.9.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node CNET +``` +**11.9.3. Cluster ID** + +``` +ID Name +0x0031 Network Commissioning +``` +**11.9.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Conformance Summary +0 WI WiFiNetworkIn­ +terface +``` +``` +O.a Wi-Fi related fea­ +tures +1 TH ThreadNetworkIn­ +terface +``` +``` +O.a Thread related +features +2 ET EthernetNetwork­ +Interface +``` +``` +O.a Ethernet related +features +``` +**11.9.5. Data Types** + +**11.9.5.1. WiFiSecurityBitmap Type** + +This data type is derived from map8. + +WiFiSecurityBitmap encodes the supported Wi-Fi security types present in the Security field of the +WiFiInterfaceScanResultStruct. + +``` +Page 778 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Name Summary Conformance +0 Unencrypted Supports unencrypted +Wi-Fi +``` +### M + +``` +1 WEP Supports Wi-Fi using +WEP security +``` +### M + +``` +2 WPA-PERSONAL Supports Wi-Fi using +WPA-Personal security +``` +### M + +``` +3 WPA2-PERSONAL Supports Wi-Fi using +WPA2-Personal secu­ +rity +``` +### M + +``` +4 WPA3-PERSONAL Supports Wi-Fi using +WPA3-Personal secu­ +rity +``` +### M + +**11.9.5.2. ThreadCapabilitiesBitmap Type** + +This data type is derived from map16. + +The ThreadCapabilitiesBitmap encodes the supported Thread features and capabilities of a Thread- +enabled network interface. + +``` +Bit Name Summary Conformance +0 IsBorderRouterCa­ +pable +``` +``` +Thread Border Router +functionality is present +``` +### O + +``` +1 IsRouterCapable Router mode is sup­ +ported (interface could +be in router or REED +mode) +``` +### O + +``` +2 IsSleepyEndDeviceCa­ +pable +``` +``` +Sleepy end-device +mode is supported +``` +### O + +``` +3 IsFullThreadDevice Device is a full Thread +device (opposite of Min­ +imal Thread Device) +``` +### O + +``` +4 IsSynchronizedSleep­ +yEndDeviceCapable +``` +``` +Synchronized sleepy +end-device mode is +supported +``` +### O + +### NOTE + +``` +The valid combinations of capabilities are restricted and dependent on Thread ver­ +sion. +``` +**11.9.5.3. WiFiBandEnum Type** + +This data type is derived from enum8. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 779 +``` + +WiFiBandEnum encodes a supported Wi-Fi frequency band present in the WiFiBand field of the +WiFiInterfaceScanResultStruct. + +``` +Value Name Summary Conformance +0 2G4 2.4GHz - 2.401GHz to +2.495GHz +(802.11b/g/n/ax) +``` +``` +O.b+ +``` +``` +1 3G65 3.65GHz - 3.655GHz to +3.695GHz (802.11y) +``` +``` +O.b+ +``` +``` +2 5G 5GHz - 5.150GHz to +5.895GHz +(802.11a/n/ac/ax) +``` +``` +O.b+ +``` +``` +3 6G 6GHz - 5.925GHz to +7.125GHz (802.11ax / +Wi-Fi 6E) +``` +``` +O.b+ +``` +``` +4 60G 60GHz - 57.24GHz to +70.20GHz (802.11ad/ay) +``` +``` +O.b+ +``` +``` +5 1G Sub-1GHz - 755MHz to +931MHz (802.11ah) +``` +``` +O.b+ +``` +**11.9.5.4. NetworkCommissioningStatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Success OK, no error M +1 OutOfRange Value Outside Range M +2 BoundsExceeded A collection would +exceed its size limit +``` +### M + +``` +3 NetworkIDNotFound The NetworkID is not +among the collection of +added networks +``` +### M + +``` +4 DuplicateNetworkID The NetworkID is +already among the col­ +lection of added net­ +works +``` +### M + +``` +5 NetworkNotFound Cannot find AP: SSID +Not found +``` +### M + +``` +6 RegulatoryError Cannot find AP: Mis­ +match on band/chan­ +nels/regulatory domain +/ 2.4GHz vs 5GHz +``` +### M + +``` +Page 780 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +7 AuthFailure Cannot associate due to +authentication failure +``` +### M + +``` +8 UnsupportedSecurity Cannot associate due to +unsupported security +mode +``` +### M + +``` +9 OtherConnectionFail­ +ure +``` +``` +Other association fail­ +ure +``` +### M + +``` +10 IPV6Failed Failure to generate an +IPv6 address +``` +### M + +``` +11 IPBindFailed Failure to bind Wi-Fi <- +> IP interfaces +``` +### M + +``` +12 UnknownError Unknown error M +``` +**11.9.5.5. NetworkInfoStruct Type** + +NetworkInfoStruct struct describes an existing network configuration, as provided in the Networks +attribute. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Net­ +workID +``` +``` +octstr 1 to 32 M +``` +``` +1 Connected bool M +``` +**NetworkID Field** + +Every network is uniquely identified (for purposes of commissioning) by a NetworkID mapping to +the following technology-specific properties: + +- SSID for Wi-Fi +- Extended PAN ID for Thread +- Network interface instance name at operating system (or equivalent unique name) for Ethernet. + +The semantics of the NetworkID field therefore varies between network types accordingly. It con­ +tains SSID for Wi-Fi networks, Extended PAN ID (XPAN ID) for Thread networks and netif name for +Ethernet networks. + +### NOTE + +``` +SSID in Wi-Fi is a collection of 1-32 bytes, the text encoding of which is not specified. +Implementations must be careful to support reporting byte strings without requir­ +ing a particular encoding for transfer. Only the commissioner should try to poten­ +tially decode the bytes. The most common encoding is UTF-8, however this is just a +convention. Some configurations may use Latin-1 or other character sets. A commis­ +sioner MAY decode using UTF-8, replacing encoding errors with "?" at the applica­ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 781 +``` + +``` +tion level while retaining the underlying representation. +``` +XPAN ID is a big-endian 64-bit unsigned number, represented on the first 8 octets of the octet string. + +**Connected Field** + +This field SHALL indicate the connected status of the associated network, where "connected" means +currently linked to the network technology (e.g. Associated for a Wi-Fi network, media connected +for an Ethernet network). + +**11.9.5.6. WiFiInterfaceScanResultStruct Type** + +WiFiInterfaceScanResultStruct represents a single Wi-Fi network scan result. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Security WiFiSecu­ +rityBitmap +``` +``` +all WI +``` +``` +1 SSID octstr max 32 WI +2 BSSID octstr 6 WI +3 Channel uint16 all WI +4 WiFiBand WiFiBan­ +dEnum +``` +``` +all [WI] +``` +``` +5 RSSI int8 all [WI] +``` +**WiFiBand Field** + +This field, if present, MAY be used to differentiate overlapping channel number values across dif­ +ferent Wi-Fi frequency bands. + +**RSSI Field** + +This field, if present, SHALL denote the signal strength in dBm of the associated scan result. + +**11.9.5.7. ThreadInterfaceScanResultStruct Type** + +ThreadInterfaceScanResultStruct represents a single Thread network scan result. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 PanId uint16 max 65534 TH +1 Extended­ +PanId +``` +``` +uint64 all TH +``` +``` +2 Network­ +Name +``` +``` +string 1 to 16 TH +``` +``` +3 Channel uint16 all TH +``` +``` +Page 782 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +4 Version uint8 all TH +5 Extended +Address +``` +``` +hwadr all TH +``` +``` +6 RSSI int8 all TH +7 LQI uint8 all TH +``` +**ExtendedAddress Field** + +ExtendedAddress stands for an IEEE 802.15.4 Extended Address. + +**11.9.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 MaxNet­ +works +``` +``` +uint8 min 1 F R A M +``` +``` +0x0001 Networks list[Net­ +workInfoS­ +truct] +``` +``` +max +MaxNet­ +works +``` +``` +empty R A M +``` +``` +0x0002 ScanMax­ +TimeSec­ +onds +``` +``` +uint8 desc F R V WI | TH +``` +``` +0x0003 Connect­ +Max­ +TimeSec­ +onds +``` +``` +uint8 desc F R V WI | TH +``` +``` +0x0004 Inter­ +faceEn­ +abled +``` +``` +bool N true RW VA M +``` +``` +0x0005 LastNet­ +work­ +ingStatus +``` +``` +Network­ +Commis­ +sioningSta­ +tusEnum +``` +``` +X null R A M +``` +``` +0x0006 LastNet­ +workID +``` +``` +octstr 1 to 32 X null R A M +``` +``` +0x0007 LastCon­ +nectError­ +Value +``` +``` +int32 X null R A M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 783 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0008 Support­ +ed­ +WiFiBand +s +``` +``` +list[WiFiBa +ndEnum] +``` +``` +min 1 F MS R V WI +``` +``` +0x0009 Support­ +edThread­ +Features +``` +``` +ThreadCa­ +pabilities­ +Bitmap +``` +### F MS R V TH + +``` +0x000A Thread­ +Version +``` +``` +uint16 F MS R V TH +``` +**11.9.6.1. MaxNetworks Attribute** + +This SHALL indicate the maximum number of network configuration entries that can be added, +based on available device resources. The length of the Networks attribute SHALL be less than or +equal to this value. + +**11.9.6.2. Networks Attribute** + +This attribute SHALL indicate the network configurations that are usable on the network interface +represented by this cluster server instance. + +The order of configurations in the list reflects precedence. That is, any time the Node attempts to +connect to the network it SHALL attempt to do so using the configurations in Networks Attribute in +the order as they appear in the list. + +The order of list items SHALL only be modified by the AddOrUpdateThreadNetwork, AddOrUp­ +dateWiFiNetwork and ReorderNetwork commands. In other words, the list SHALL be stable over +time, unless mutated externally. + +Ethernet networks SHALL be automatically populated by the cluster server. Ethernet Network Com­ +missioning Cluster instances SHALL always have exactly one NetworkInfoStruct instance in their +Networks attribute. There SHALL be no way to add, update or remove Ethernet network configura­ +tions to those Cluster instances. + +**11.9.6.3. ScanMaxTimeSeconds Attribute** + +This attribute SHALL indicate the maximum duration taken, in seconds, by the network interface +on this cluster server instance to provide scan results. + +See ScanNetworks for usage. + +**11.9.6.4. ConnectMaxTimeSeconds Attribute** + +This attribute SHALL indicate the maximum duration taken, in seconds, by the network interface +on this cluster server instance to report a successful or failed network connection indication. This +maximum time SHALL account for all operations needed until a successful network connection is + +``` +Page 784 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +deemed to have occurred, including, for example, obtaining IP addresses, or the execution of neces­ +sary internal retries. + +**11.9.6.5. InterfaceEnabled Attribute** + +This attribute SHALL indicate whether the associated network interface is enabled or not. By +default all network interfaces SHOULD be enabled during initial commissioning (InterfaceEnabled +set to true). + +It is undefined what happens if InterfaceEnabled is written to false on the same interface as that +which is used to write the value. In that case, it is possible that the Administrator would have to +await expiry of the fail-safe, and associated recovery of network configuration to prior safe values, +before being able to communicate with the node again (see ArmFailSafe). + +It MAY be possible to disable Ethernet interfaces but it is implementation-defined. If not supported, +a write to this attribute with a value of false SHALL fail with a status of INVALID_ACTION. When +disabled, an Ethernet interface would longer employ media detection. That is, a simple unplug and +replug of the cable SHALL NOT re-enable the interface. + +On Ethernet-only Nodes, there SHALL always be at least one of the Network Commissioning server +cluster instances with InterfaceEnabled set to true. + +**11.9.6.6. LastNetworkingStatus Attribute** + +This attribute SHALL indicate the status of the last attempt either scan or connect to an operational +network, using this interface, whether by invocation of the ConnectNetwork command or by +autonomous connection after loss of connectivity or during initial establishment. If no such attempt +was made, or no network configurations exist in the Networks attribute, then this attribute SHALL +be set to null. + +This attribute is present to assist with error recovery during Network commissioning and to assist +in non-concurrent networking commissioning flows. + +**11.9.6.7. LastNetworkID Attribute** + +This attribute SHALL indicate the NetworkID used in the last attempt to connect to an operational +network, using this interface, whether by invocation of the ConnectNetwork command or by +autonomous connection after loss of connectivity or during initial establishment. If no such attempt +was made, or no network configurations exist in the Networks attribute, then this attribute SHALL +be set to null. + +If a network configuration is removed from the Networks attribute using the RemoveNetwork com­ +mand after a connection attempt, this field MAY indicate a NetworkID that is no longer configured +on the Node. + +This attribute is present to assist with error recovery during Network commissioning and to assist +in non-concurrent networking commissioning flows. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 785 +``` + +**11.9.6.8. LastConnectErrorValue Attribute** + +This attribute SHALL indicate the ErrorValue used in the last failed attempt to connect to an opera­ +tional network, using this interface, whether by invocation of the ConnectNetwork command or by +autonomous connection after loss of connectivity or during initial establishment. If no such attempt +was made, or no network configurations exist in the Networks attribute, then this attribute SHALL +be set to null. + +If the last connection succeeded, as indicated by a value of Success in the LastNetworkingStatus +attribute, then this field SHALL be set to null. + +This attribute is present to assist with error recovery during Network commissioning and to assist +in non-concurrent networking commissioning flows. + +**11.9.6.9. SupportedWiFiBands Attribute** + +This attribute SHALL indicate all the frequency bands supported by the Wi-Fi interface configured +by the cluster instance. + +**11.9.6.10. SupportedThreadFeatures Attribute** + +This attribute SHALL indicate all of the Thread features supported by the Thread interface config­ +ured by the cluster instance. + +This attribute is primarily used to determine the most important general capabilities of the Thread +interface associated with the cluster instance, as opposed to the current runtime dynamic configu­ +ration. Note that most run-time details of the actual Thread interface are found in the Thread Net­ +work Diagnostics cluster, if supported. + +**11.9.6.11. ThreadVersion Attribute** + +This attribute SHALL indicate the Thread version supported by the Thread interface configured by +the cluster instance. + +The format SHALL match the value mapping found in the "Version TLV" section of Thread specifica­ +tion. For example, Thread 1.3.0 would have ThreadVersion set to 4. + +**11.9.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 ScanNetworks client ⇒ server ScanNetwork­ +sResponse +``` +### A WI | TH + +``` +0x01 ScanNetwork­ +sResponse +``` +``` +client ⇐ server N WI | TH +``` +``` +0x02 AddOrUp­ +dateWiFiNet­ +work +``` +``` +client ⇒ server NetworkConfi­ +gResponse +``` +### A WI + +``` +Page 786 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Direction Response Access Conformance +0x03 AddOrUp­ +dateThread­ +Network +``` +``` +client ⇒ server NetworkConfi­ +gResponse +``` +### A TH + +``` +0x04 RemoveNet­ +work +``` +``` +client ⇒ server NetworkConfi­ +gResponse +``` +### A WI | TH + +``` +0x05 NetworkConfi­ +gResponse +``` +``` +client ⇐ server N WI | TH +``` +``` +0x06 ConnectNet­ +work +``` +``` +client ⇒ server ConnectNet­ +workResponse +``` +### A WI | TH + +``` +0x07 ConnectNet­ +workResponse +``` +``` +client ⇐ server N WI | TH +``` +``` +0x08 ReorderNet­ +work +``` +``` +client ⇒ server NetworkConfi­ +gResponse +``` +### A WI | TH + +**11.9.7.1. ScanNetworks Command** + +This command SHALL scan on the Cluster instance’s associated network interface for either of: + +- All available networks (non-directed scanning) +- Specific networks (directed scanning) + +Scanning for available networks detects all networks of the type corresponding to the cluster server +instance’s associated network interface that are possible to join, such as all visible Wi-Fi access +points for Wi-Fi cluster server instances, all Thread PANs for Thread cluster server instances, +within bounds of the maximum response size. + +Scanning for a specific network (i.e. directed scanning) takes place if a network identifier (e.g. Wi-Fi +SSID) is provided in the command arguments. Directed scanning SHALL restrict the result set to the +specified network only. + +If this command is received without an armed fail-safe context (see ArmFailSafe), then this com­ +mand SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator. + +The client SHALL NOT expect the server to be done scanning and have responded with ScanNet­ +worksResponse before ScanMaxTimeSeconds seconds have elapsed. Enough transport time affor­ +dances for retries SHOULD be expected before a client determines the operation to have timed-out. + +This command SHALL fail with a status code of BUSY if the server determines that it will fail to reli­ +ably send a response due to changes of networking interface configuration at runtime for the inter­ +face over which the command was invoked, or if it is currently unable to proceed with such an +operation. + +For Wi-Fi-supporting servers (WI feature) the server SHALL always honor directed scans, and +attempt to provide all matching BSSID which are reachable on the bands which would otherwise be +attempted if a ConnectNetwork having the specified SSID were to take place. This command is use­ +ful for clients to determine reachability capabilities as seen by the server’s own radios. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 787 +``` + +For Wi-Fi-supporting servers the server SHALL always scan on all bands supported by the interface +associated with the cluster instance on which the command was invoked. + +If the command was invoked over the same link whose configuration is managed by a given server +cluster instance, there MAY be an impact on other communication from the invoking client, as well +as other clients, while the network interface is processing the scan. Clients SHOULD NOT use this +command unless actively in the process of re-configuring network connectivity. + +The arguments for this command are as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 SSID octstr 1 to 32 X null [WI] +1 Bread­ +crumb +``` +``` +uint64 all O +``` +**SSID Field** + +This field, if present, SHALL contain the SSID for a directed scan of that particular Wi-Fi SSID. Oth­ +erwise, if the field is absent, or if it is null, this SHALL indicate scanning of all BSSID in range. This +field SHALL be ignored for ScanNetworks invocations on non-Wi-Fi server instances. + +**Breadcrumb Field** + +The Breadcrumb field, if present, SHALL be used to atomically set the Breadcrumb attribute in the +General Commissioning cluster on success of the associated command. If the command fails, the +Breadcrumb attribute in the General Commissioning cluster SHALL be left unchanged. + +**11.9.7.2. ScanNetworksResponse Command** + +This command SHALL contain the status of the last ScanNetworks command, and the associated +scan results if the operation was successful. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Network­ +ingStatus +``` +``` +Network­ +Commission­ +ingSta­ +tusEnum +``` +``` +desc M +``` +``` +1 DebugText string max 512 O +2 WiFiScan­ +Results +``` +``` +list[WiFiIn­ +terfaceScan­ +ResultStruct] +``` +``` +desc WI +``` +``` +3 Thread­ +ScanResults +``` +``` +list[Thread­ +InterfaceS­ +canResult­ +Struct] +``` +``` +desc TH +``` +``` +Page 788 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Results are valid only if NetworkingStatus is Success. + +Before generating a ScanNetworksResponse, the server SHALL set the LastNetworkingStatus +attribute value to the NetworkingStatus matching the response. + +**NetworkingStatus Field** + +The NetworkingStatus field SHALL indicate the status of the last scan operation, taking one of these +values: + +- Success: Scanning succeeded. +- NetworkNotFound: No instance of an explicitly-provided network identifier was found during + the scan. This error cannot occur if no network identifier was provided, such as when scanning + for all available networks. +- OutOfRange: Network identifier was invalid (e.g. empty, too long, etc). +- RegulatoryError: Could not scan on any bands due to lack of regulatory configuration. +- UnknownError: An internal error occurred during scanning. + +**DebugText Field** + +This field, if present and non-empty, MAY contain error information which MAY be communicated +to the user in case the NetworkingStatus was not Success. Its purpose is to help developers in trou­ +bleshooting errors and MAY go into logs or crash reports. + +**WiFiScanResults Field** + +If NetworkingStatus was Success, this field SHALL contain the Wi-Fi network scan results. The list +MAY be empty if none were found in range on the bands supported by the interface, or if directed +scanning had been used and the desired SSID was not found in range. + +The maximum number of results present in the result list supported MAY depend on memory and +MAY contain a subset of possibilities, to avoid memory exhaustion on the cluster server and avoid +crossing the maximum command response size supported (see Section 4.4.4, “Message Size Require­ +ments”). + +The order in which results are reported is implementation-specific. Results SHOULD be reported in +decreasing RSSI order, even if RSSI is not reported in the response, to maximize the likelihood that +most likely to be reachable elements are included within the size limits of the response. + +**ThreadScanResults Field** + +If NetworkingStatus was Success, this field SHALL contain the Thread network scan results. The list +MAY be empty if none were found in range on the bands supported by the interface. + +The maximum number of results present in the result list supported MAY depend on memory and +MAY contain a subset of possibilities, to avoid memory exhaustion on the cluster server and avoid +crossing the maximum command response size supported (see Section 4.4.4, “Message Size Require­ +ments”). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 789 +``` + +The order in which results are reported is implementation-specific. Results SHOULD be reported in +decreasing LQI order, to maximize the likelihood that most likely to be reachable elements are +included within the size limits of the response. + +**11.9.7.3. AddOrUpdateWiFiNetwork Command** + +This command SHALL be used to add or modify Wi-Fi network configurations. + +If this command is received without an armed fail-safe context (see ArmFailSafe), then this com­ +mand SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator. + +The Credentials associated with the network are not readable after execution of this command, as +they do not appear in the Networks attribute, for security reasons. + +If this command contains a ClientIdentifier, and the Networks list does not contain an entry with a +matching ClientIdentifier, then this command SHALL fail with a status of NOT_FOUND. + +See Section 11.9.7.5, “Common processing of AddOrUpdateWiFiNetwork and AddOrUpdateThread­ +Network” for behavior of addition/update. + +The data for this command is as follows: + +``` +ID Name Type Constraint Default Conformance +0 SSID octstr max 32 M +1 Credentials octstr max 64 M +2 Breadcrumb uint64 all O +``` +**SSID Field** + +This field SHALL contain the SSID to which to attempt connection. Specific BSSID selection is not +supported by this cluster. + +**Credentials Field** + +Credentials is the passphrase or PSK for the network (if any is needed). + +Security type, cipher and credential format (passphrase or PSK) SHALL be contextually auto- +selected during execution of the ConnectNetwork Command and during subsequent operational +state network connections, based on the most secure Wi-Fi security type available within beacons +and probe responses for the set of all discovered BSSIDs for the configured SSID. The type of PSK or +passphrase used SHALL be inferred based on the length and contents of the Credentials field pro­ +vided, matching the security type chosen. + +Valid Credentials length are: + +- 0 bytes: Unsecured (open) connection +- 5 bytes: WEP-64 passphrase +- 10 hexadecimal ASCII characters: WEP-64 40-bit hex raw PSK + +``` +Page 790 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- 13 bytes: WEP-128 passphrase +- 26 hexadecimal ASCII characters: WEP-128 104-bit hex raw PSK +- 8..63 bytes: WPA/WPA2/WPA3 passphrase +- 64 bytes: WPA/WPA2/WPA3 raw hex PSK + +These lengths SHALL be contextually interpreted based on the security type of the BSSID where +connection will occur. + +When the length of Credentials and available set of BSSID admits more than one option, such as the +presence of both WPA2 and WPA security type within the result set, WPA2 SHALL be considered +more secure. + +Note that it MAY occur that a station cannot connect to a particular access point with higher secu­ +rity and selects a lower security connectivity type if the link quality is deemed to be too low to +achieve successful operation, or if all retry attempts fail. + +**Breadcrumb Field** + +See Breadcrumb for usage. + +**11.9.7.4. AddOrUpdateThreadNetwork Command** + +This command SHALL be used to add or modify Thread network configurations. + +If this command is received without an armed fail-safe context (see ArmFailSafe), then this com­ +mand SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator. + +See Section 11.9.7.5, “Common processing of AddOrUpdateWiFiNetwork and AddOrUpdateThread­ +Network” for behavior of addition/update. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Opera­ +tional­ +Dataset +``` +``` +octstr max 254 M +``` +``` +1 Bread­ +crumb +``` +``` +uint64 all O +``` +The XPAN ID in the OperationalDataset serves as the NetworkID for the network configuration to be +added or updated. + +If the Networks attribute does not contain an entry with the same NetworkID as the one provided +in the OperationalDataset, the operation SHALL be considered an addition, otherwise, it SHALL be +considered an update. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 791 +``` + +**OperationalDataset Field** + +The OperationalDataset field SHALL contain the Thread Network Parameters, including channel, +PAN ID, and Extended PAN ID. + +The encoding for the OperationalDataset field is defined in the Thread specification. + +The client SHALL pass the OperationalDataset as an opaque octet string. + +**Breadcrumb Field** + +See Breadcrumb for usage. + +**11.9.7.5. Common processing of AddOrUpdateWiFiNetwork and AddOrUpdateThreadNetwork** + +Both AddOrUpdateWiFiNetwork and AddOrUpdateThreadNetwork operate similarly, against differ­ +ent underlying technologies. The processing of these commands in the addition and update case is +covered by the following subsections. + +**Processing an addition** + +If the Networks attribute is already full, the command SHALL immediately respond with Network­ +ConfigResponse having NetworkingStatus status field set to BoundsExceeded. + +If any of the parameters in the OperationalDataset are invalid, the command SHALL immediately +respond with NetworkConfigResponse having NetworkingStatus status field set to a value different +than Success and consistent with the error. + +If validation of all parameters has succeeded, this command SHALL append the configuration at the +end of the existing list in the Networks attribute, making this new network the one with least prior­ +ity. + +On success, the NetworkConfigResponse command SHALL have its NetworkIndex field set to the 0- +based index of the entry in the Networks attribute that was just added. + +**Processing an update** + +If any of the parameters in the OperationalDataset are invalid, the command SHALL immediately +respond with NetworkConfigResponse having NetworkingStatus status field set to a value different +than Success and consistent with the error. + +If validation of all parameters has succeeded, this command SHALL update the existing entry +indexed by NetworkID in the Networks attribute, keeping existing position within the list. + +On success, the NetworkConfigResponse command SHALL have its NetworkIndex field set to the 0- +based index of the entry in the Networks attribute that was just updated, and a NetworkingStatus +status field set to Success. + +**11.9.7.6. RemoveNetwork Command** + +This command SHALL remove the network configuration from the Cluster if there was already a +network configuration with the same NetworkID. The relative order of the entries in the Networks + +``` +Page 792 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +attribute SHALL remain unchanged, except for the removal of the requested network configura­ +tion. + +If this command is received without an armed fail-safe context (see ArmFailSafe), then this com­ +mand SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NetworkID octstr 1 to 32 M +1 Bread­ +crumb +``` +``` +uint64 all O +``` +If the Networks attribute does not contain a matching entry, the command SHALL immediately +respond with NetworkConfigResponse having NetworkingStatus status field set to NetworkIdNot­ +Found. + +On success, the NetworkConfigResponse command SHALL have its NetworkIndex field set to the 0- +based index of the entry in the Networks attribute that was just removed, and a NetworkingStatus +status field set to Success. + +**NetworkID Field** + +This field SHALL contain the NetworkID for the entry to remove: the SSID for Wi-Fi and XPAN ID +for Thread. + +**Breadcrumb Field** + +See Breadcrumb for usage. + +**11.9.7.7. NetworkConfigResponse Command** + +This response command relates status information for some commands which require it as their +response command. See each individual cluster server command for the situations that may cause +a NetworkingStatus different than Success. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Network­ +ingStatus +``` +``` +Network­ +Commission­ +ingSta­ +tusEnum +``` +``` +desc M +``` +``` +1 DebugText string max 512 O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 793 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +2 Net­ +workIndex +``` +``` +uint8 max +(MaxNet­ +works - 1) +``` +### O + +Before generating a NetworkConfigResponse, the server SHALL set the LastNetworkingStatus +attribute value to the NetworkingStatus matching the response. + +Before generating a NetworkConfigResponse, the server SHALL set the LastNetworkID attribute +value to the NetworkID that was used in the command for which an invocation caused the response +to be generated. + +**NetworkingStatus Field** + +The NetworkingStatus field SHALL indicate the status of the last operation attempting to modify the +Networks attribute configuration, taking one of these values: + +- Success: Operation succeeded. +- OutOfRange: Network identifier was invalid (e.g. empty, too long, etc). +- BoundsExceeded: Adding this network configuration would exceed the limit defined by MaxNet­ + works. +- NetworkIdNotFound: The network identifier was expected to be found, but was not found + among the added network configurations in Networks attribute. +- UnknownError: An internal error occurred during the operation. + +**DebugText Field** + +See DebugText for usage. + +**NetworkIndex Field** + +When the NetworkingStatus is Success, this field SHALL be present. It SHALL contain the 0-based +index of the entry in the Networks attribute that was last added, updated or removed successfully +by the associated request command. + +**11.9.7.8. ConnectNetwork Command** + +This command SHALL attempt to connect to a network whose configuration was previously added +by either the AddOrUpdateWiFiNetwork or AddOrUpdateThreadNetwork commands. Network is +identified by its NetworkID. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NetworkID octstr 1 to 32 M +``` +``` +Page 794 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 Bread­ +crumb +``` +``` +uint64 all O +``` +This command SHALL fail with a BUSY status code returned to the initiator if the server is currently +unable to proceed with such an operation, such as if it is currently attempting to connect in the +background, or is already proceeding with a prior ConnectNetwork. + +If this command is received without an armed fail-safe context (see ArmFailSafe), then this com­ +mand SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator. + +Before connecting to the new network, the Node SHALL disconnect the operational network con­ +nections managed by any other Network Commissioning cluster instances (whether under the Root +Node or a Secondary Network Interface), where those connections are not represented by an entry +in the Networks attribute of the corresponding cluster instance. This ensures that an Administrator +or Commissioner can reliably reconfigure the operational network connection of a device that has +one or more Secondary Network interfaces, for example by removing the active network configura­ +tion from one cluster instance, followed by adding a new configuration and calling ConnectNet­ +work on a different cluster instance. + +Success or failure of this command SHALL be communicated by the ConnectNetworkResponse com­ +mand, unless some data model validations caused a FAILURE status to be sent prior to finishing +execution of the command. The ConnectNetworkResponse SHALL indicate the value Success in the +NetworkingStatus field on successful connection. On failure to connect, the ConnectNetworkRe­ +sponse SHALL contain an appropriate NetworkingStatus, DebugText and ErrorValue indicating the +reason for failure. + +The amount of time needed to determine successful or failing connectivity on the cluster server’s +associated interface is provided by the ConnectMaxTimeSeconds attribute. Clients SHALL NOT con­ +sider the connection to have timed-out until at least that duration has taken place. For non-concur­ +rent commissioning situations, the client SHOULD allow additional margin of time to account for its +delay in executing operational discovery of the Node once it is connected to the new network. + +On successful connection, the entry associated with the given Network configuration in the Net­ +works attribute SHALL indicate its Connected field set to true, and all other entries, if any exist, +SHALL indicate their Connected field set to false. + +On failure to connect, the entry associated with the given Network configuration in the Networks +attribute SHALL indicate its Connected field set to false. + +The precedence order of any entry subject to ConnectNetwork SHALL NOT change within the Net­ +works attribute. + +Even after successfully connecting to a network, the configuration SHALL revert to the prior state +of configuration if the CommissioningComplete command (see CommissioningComplete) is not suc­ +cessfully invoked before expiry of the Fail-Safe timer. + +When non-concurrent commissioning is being used by a Commissioner or Administrator, the Con­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 795 +``` + +nectNetworkResponse SHALL be sent with the NetworkingStatus field set to Success prior to closing +the commissioning channel, even if not yet connected to the operational network, unless the device +would be incapable of joining that network, in which case the usual failure path described in the +prior paragraphs SHALL be followed. Once the commissioning channel is closed, the operational +channel will be started. It is possible that the only method to determine success of the operation is +operational discovery of the Node on the new operational network. Therefore, before invoking the +ConnectNetwork command, the client SHOULD re-invoke the Arm Fail-Safe command with a dura­ +tion that meets the following: + +1. Sufficient time to meet the minimum required time (see ConnectMaxTimeSeconds) that may be + taken by the server to connect to the desired network. +2. Sufficient time to account for possible message-layer retries when a response is requested. +3. Sufficient time to allow operational discovery on the new network by a Commissioner or + Administrator. +4. Sufficient time to establish a CASE session after operational discovery +5. Not so long that, in error situations, the delay to reverting back to being discoverable for com­ + missioning with a previous configuration would cause significant user-perceived delay. + +Note as well that the CommissioningTimeout duration provided in a prior OpenCommissioningWin­ +dow or OpenBasicCommissioningWindow command may impact the total time available to proceed +with error recovery after a connection failure. + +The LastNetworkingStatus, LastNetworkID and LastConnectErrorValue attributes MAY assist the +client in determining the reason for a failure after reconnecting over a Commissioning channel, +especially in non-concurrent commissioning situations. + +**NetworkID Field** + +This field SHALL contain the NetworkID for the entry used to configure the connection: the SSID for +Wi-Fi and XPAN ID for Thread. + +**Breadcrumb Field** + +See Breadcrumb for usage. + +**11.9.7.9. ConnectNetworkResponse Command** + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Network­ +ingStatus +``` +``` +Network­ +Commission­ +ingSta­ +tusEnum +``` +``` +all M +``` +``` +1 DebugText string O +2 ErrorValue int32 all X M +``` +``` +Page 796 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Before generating a ConnectNetworkResponse, the server SHALL: + +- Set the LastNetworkingStatus attribute value to the NetworkingStatus matching the response. +- Set the LastNetworkID attribute value to the NetworkID that was used in the ConnectNetwork + command which caused the response to be generated. +- Set the LastConnectErrorValue attribute value to the ErrorValue matching the response, includ­ + ing setting it to null if the ErrorValue is not applicable. + +**NetworkingStatus Field** + +The NetworkingStatus field SHALL indicate the status of the last connection attempt, taking one of +these values: + +- Success: Connection succeeded. +- NetworkNotFound: No instance of an explicitly-provided network identifier was found during + the attempt to join the network. +- OutOfRange: Network identifier was invalid (e.g. empty, too long, etc). +- NetworkIdNotFound: The network identifier was not found among the added network configu­ + rations in Networks attribute. +- RegulatoryError: Could not connect to a network due to lack of regulatory configuration. +- UnknownError: An internal error occurred during the operation. +- Association errors (see also description of errors in NetworkCommissioningStatusEnum): Auth­ + Failure, UnsupportedSecurity, OtherConnectionFailure, IPV6Failed, IPBindFailed + +**DebugText Field** + +See DebugText for usage. + +**ErrorValue Field** + +- ErrorValue interpretation for Wi-Fi association errors: + ◦ On any association failure during enabling of a network, the ErrorValue field SHALL be set + to the Status Code value that was present in the last frame related to association where Sta­ + tus Code was not equal to zero and which caused the failure of a final retry attempt, if this + final failure was due to one of the following Management frames: + ▪ Association Response (Type 0, Subtype 1) + ▪ Reassociation Response (Type 0, Subtype 3) + ▪ Authentication (Type 0, Subtype 11) + ◦ Table 9-50 "Status Codes" in IEEE 802.11-2020 contains a description of all values possible, + which can unambiguously be used to determine the cause, such as an invalid security type, + unsupported rate, etc. +- Otherwise, the ErrorValue field SHALL contain an implementation-dependent value which MAY + be used by a reader of the structure to record, report or diagnose the failure. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 797 +``` + +**11.9.7.10. ReorderNetwork Command** + +This command SHALL set the specific order of the network configuration selected by its NetworkID +in the Networks attribute to match the position given by NetworkIndex. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NetworkID octstr 1 to 32 M +1 Net­ +workIndex +``` +``` +uint8 desc M +``` +``` +2 Bread­ +crumb +``` +``` +uint64 all O +``` +**NetworkID Field** + +This field SHALL contain the NetworkID for the entry to reorder: the SSID for Wi-Fi and XPAN ID +for Thread. + +**NetworkIndex Field** + +This field SHALL contain the 0-based index of the new desired position of the entry in the Networks +attribute. + +**Breadcrumb Field** + +See Breadcrumb for usage. + +**Effect when received** + +If the Networks attribute does not contain a matching entry, the command SHALL immediately +respond with NetworkConfigResponse having NetworkingStatus status field set to NetworkIdNot­ +Found. + +If the NetworkIndex field has a value larger or equal to the current number of entries in the Net­ +works attribute, the command SHALL immediately respond with NetworkConfigResponse having +NetworkingStatus status field set to OutOfRange. + +On success, the NetworkConfigResponse command SHALL have its NetworkIndex field set to the 0- +based index of the entry in the Networks attribute that was just updated, matching the incoming +NetworkIndex, and a NetworkingStatus status field set to Success. + +The entry selected SHALL be inserted at the new position in the list. All other entries, if any exist, +SHALL be moved to allow the insertion, in a way that they all retain their existing relative order +between each other, with the exception of the newly re-ordered entry. + +Re-ordering to the same NetworkIndex as the current location SHALL be considered as a success +and yield no visible changes of the Networks attribute. + +``` +Page 798 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Examples of re-ordering** + +To better illustrate the re-ordering operation, consider this initial state, exemplary of a Wi-Fi +device: + +``` +Index in list NetworkID field Connected field +0 FancyCat false +1 BlueDolphin true +2 Home-Guest false +3 WillowTree false +``` +On receiving ReorderNetwork with: + +- NetworkID = Home-Guest +- NetworkIndex = 0 + +The outcome, after applying to the **initial state** would be: + +``` +Index in list NetworkID field Connected field +0 Home-Guest false +1 FancyCat false +2 BlueDolphin true +3 WillowTree false +``` +In the above outcome, FancyCat and BlueDolphin moved "down" and Home-Guest became the high­ +est priority network in the list. + +On receiving ReorderNetwork with: + +- NetworkID = FancyCat +- NetworkIndex = 3 + +The outcome, after applying to the **initial state** would be: + +``` +Index in list NetworkID field Connected field +0 BlueDolphin true +1 Home-Guest false +2 WillowTree false +3 FancyCat false +``` +In the above outcome, BlueDolphin, Home-Guest and WillowTree moved "up" and FancyCat became +the lowest priority network in the list. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 799 +``` + +**11.9.8. Usage of networking configurations** + +This section describes how to ensure deterministic and well-behaved network connectivity, both +when concurrent and non-concurrent commissioning flows (see Section 5.5, “Commissioning +Flows”) are used. + +Operational Networking configuration is managed by the set of Network Commissioning cluster +server instances distributed on a Node’s Endpoints. + +Since Matter employs IPv6 communication and DNS-SD for operational Discovery, there is a funda­ +mental aspect of multi-homing present, where a Node with multiple concurrently operated net­ +work interfaces device may be reachable using a variety of addresses on different network tech­ +nologies. Care SHOULD be taken by Administrators and Commissioners to avoid making strong +assumptions about single address reachability. Administrators and Commissioners SHOULD be pre­ +pared to attempt reachability tests against specific network technologies if the final desired state of +networking requires a specific reachable path. + +A Node MAY be configured in such a way that there are no Network Commissioning cluster server +instances present, in which case the remainder of this section SHALL NOT apply. + +**11.9.8.1. Network Interfaces** + +**Primary Network Interface** + +The primary network interface of a Node SHALL be the one present on the root node endpoint (see +Section 9.2, “Endpoint Composition”). This interface SHOULD be the one most likely to yield an +operational reachable state if appropriately configured. + +**Secondary Network Interfaces** + +The secondary network interfaces SHOULD be additional technologies that MAY increase reachabil­ +ity or support a stub router feature. These interfaces SHALL be hosted by endpoints other than the +root node endpoint, which SHALL support the Secondary Network Interface device type. + +A Node supporting secondary network interfaces SHALL support the concurrent connection com­ +missioning flow (see Figure 32, “Concurrent connection commissioning flow”). Therefore, if the pri­ +mary network configuration fails, the Commissioner can proceed to configure the secondary net­ +work interfaces via the established commissioning channel. + +**11.9.8.2. Order of connectivity during connection establishment** + +When at least one Network Commissioning cluster server instance (hereafter, "Network Commis­ +sioning cluster" for short), the following behavior SHOULD take place for each interface associated +with a Network Commissioning cluster, in increasing order of associated endpoint number: + +1. If the Network Commissioning cluster’s InterfaceEnabled attribute is set to false, skip the pro­ + cessing the interface altogether. +2. Set all configurations of the Networks attribute entry’s Connected field to false +3. Iterate through all configurations in the Networks attribute + +``` +Page 800 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +a. If there was a "last known good" network configuration, that is, the one which was both last +successfully connected during prior boot and over which at least one secure channel +exchange message was received, it MAY be used as the first attempt. Otherwise, iterate +through all configurations in the precedence order of the list, starting at index 0. +``` +4. Attempt to connect to the technology, using the current iteration’s network configuration +5. On success, set the Connected state of the list entry to true, and stop attempting further connec­ + tion. Otherwise, on failure, move to the next configuration. + +**11.9.8.3. Connectivity management during commissioning or administration** + +When a network interface is configured during commissioning or reconfigured during ongoing +administration, behavior is different than for the startup case described previously, since there are +tentative attempts being made to make a Node reachable on an operational network. + +Network configuration can be seen as: + +- A list of existing configurations, reflected by the Networks attribute. + ◦ The list SHALL be managed by the AddOrUpdateWiFiNetwork, AddOrUpdateThreadNet­ + work, RemoveNetwork and ReorderNetwork commands. + ◦ The list SHALL be tentative until committed by successful invocation of the Commissioning­ + Complete command, or reverted to prior configuration by the expiry of the Fail-Safe timer + (see ArmFailSafe). +- A current candidate configuration, the subject of the most recent ConnectNetwork command. + ◦ There SHALL NOT be new connections to any network during the Fail-Safe timer period + unless attempted by invocation of the ConnectNetwork command. + +Failures of connection during the Fail-Safe timer window SHALL cause the Node to follow the steps +in Section 5.5.1, “Commissioning Flows Error Handling” after recording the cause of the failure in +the LastNetworkingStatus, LastNetworkID and LastConnectErrorValue attributes. + +After Commissioning or reconfiguration ends successfully, because of successful invocation of the +CommissioningComplete command, the cluster server SHOULD NOT attempt to change connected +network until connectivity failure or restart occurs, but rather it SHALL commit the tentative con­ +figuration to persistent storage so that it is usable the next time connectivity establishment is +needed. + +After Commissioning or reconfiguration ends in failure due to expiry of the Fail-Safe timer, the +Node SHALL revert to the network configuration present prior to the Fail-Safe timer being armed. + +Because it is possible that multiple network configurations being present could successfully result +in an established operational network connection, but only some of these configurations actually +have the desired reachability by Administrators on certain fabrics, the following precautions +SHOULD be taken to avoid a situation where a Node forever dwells on a network with successful +connectivity, but no reachable peers: + +- Commissioners and Administrators MAY notify users if multiple independent configurations + exist that could cause an alternate configuration to make the device unreachable for reconfigu­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 801 +``` + +``` +ration by Nodes on the current client’s fabric in the future. +``` +- Commissioners and Administrators SHOULD avoid configuring Nodes in ways where it may be + ambiguous to end-users which final network configuration will take place. +- Cluster servers on devices with no user interface to express current network configuration to + an end-user SHOULD be configured to only support a single entry in the Networks attribute. +- Upon discovering that a user is desiring to configure a Network in a way that would change the + set of configured networks, and there are multiple fabrics configured in the Fabrics attribute of + the Node Operational Credentials cluster, the client SHOULD notify the user that some other + Administrators on other fabrics MAY fail to reach the Node and report connectivity failures. + +**11.10. General Commissioning Cluster** + +This cluster is used to manage basic commissioning lifecycle. + +This cluster also represents responsibilities related to commissioning that don’t well fit other com­ +missioning clusters, like Section 11.9, “Network Commissioning Cluster”. It also hosts functionalities +those other clusters may depend on. + +**11.10.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Add Enhanced Setup Flow +``` +**11.10.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node CGEN +``` +**11.10.3. Cluster ID** + +``` +ID Name +0x0030 General Commissioning +``` +**11.10.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Page 802 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Bit Code Feature Summary +0 TC TermsAndConditions Supports Terms & Con­ +ditions acknowledge­ +ment +``` +**11.10.4.1. Enhanced Setup Flow Terms & Conditions Feature** + +The node supports commissioning using Enhanced Setup Flow Terms & Conditions. Support for this +feature is limited to nodes that use Commissioning Custom Flow. + +**11.10.5. Data Types** + +**11.10.5.1. CommissioningErrorEnum Type** + +This data type is derived from enum8. + +This enumeration is used by several response commands in this cluster to indicate particular +errors. + +``` +Value Name Summary Conformance +0 OK No error M +1 ValueOutsideRange Attempting to set regu­ +latory configuration to +a region or indoor/out­ +door mode for which +the server does not +have proper configura­ +tion. +``` +### M + +``` +2 InvalidAuthentication Executed Commission­ +ingComplete outside +CASE session. +``` +### M + +``` +3 NoFailSafe Executed Commission­ +ingComplete when +there was no active +Fail-Safe context. +``` +### M + +``` +4 BusyWithOtherAdmin Attempting to arm fail- +safe or execute Com­ +missioningComplete +from a fabric different +than the one associated +with the current fail- +safe context. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 803 +``` + +``` +Value Name Summary Conformance +5 RequiredTCNotAc­ +cepted +``` +``` +One or more required +TC features from the +Enhanced Setup Flow +were not accepted. +``` +### TC + +``` +6 TCAcknowledge­ +mentsNotReceived +``` +``` +No acknowledgements +from the user for the +TC features were +received. +``` +### TC + +``` +7 TCMinVersionNotMet The version of the TC +features acknowledged +by the user did not +meet the minimum +required version. +``` +### TC + +**11.10.5.2. RegulatoryLocationTypeEnum Type** + +This data type is derived from enum8. + +This enumeration is used by the RegulatoryConfig and LocationCapability attributes to indicate pos­ +sible radio usage. + +``` +Value Name Summary Conformance +0 Indoor Indoor only M +1 Outdoor Outdoor only M +2 IndoorOutdoor Indoor/Outdoor M +``` +**11.10.5.3. BasicCommissioningInfo Type** + +This structure provides some constant values that MAY be of use to all commissioners. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 FailSafe­ +Ex­ +piryLengt +hSeconds +``` +``` +uint16 all M +``` +``` +1 MaxCu­ +mulative­ +Fail­ +safeSec­ +onds +``` +``` +uint16 desc M +``` +``` +Page 804 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**FailSafeExpiryLengthSeconds Field** + +This field SHALL contain a conservative initial duration (in seconds) to set in the FailSafe for the +commissioning flow to complete successfully. This may vary depending on the speed or sleepiness +of the Commissionee. This value, if used in the ArmFailSafe command’s ExpiryLengthSeconds field +SHOULD allow a Commissioner to proceed with a nominal commissioning without having to-rearm +the fail-safe, with some margin. + +**MaxCumulativeFailsafeSeconds Field** + +This field SHALL contain a conservative value in seconds denoting the maximum total duration for +which a fail safe timer can be re-armed. See Section 11.10.7.2.1, “Fail Safe Context”. + +The value of this field SHALL be greater than or equal to the FailSafeExpiryLengthSeconds. Absent +additional guidelines, it is RECOMMENDED that the value of this field be aligned with the initial +Announcement Duration and default to 900 seconds. + +**11.10.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x00 Bread­ +crumb +``` +``` +uint64 all 0 RW VA M +``` +``` +0x01 BasicCom­ +mis­ +sioning­ +Info +``` +``` +BasicCom­ +mis­ +sioningInfo +``` +``` +desc F R V M +``` +``` +0x02 Regulato­ +ryConfig +``` +``` +Regulato­ +ryLoca­ +tionType­ +Enum +``` +``` +all Location­ +Capability +``` +### R V M + +``` +0x03 Location­ +Capability +``` +``` +Regulato­ +ryLoca­ +tionType­ +Enum +``` +``` +all F IndoorOut­ +door +``` +### R V M + +``` +0x04 Support­ +sConcur­ +rentCon­ +nection +``` +``` +bool all F true R V M +``` +``` +0x05 TCAccept­ +edVersion +``` +``` +uint16 all N R A TC +``` +``` +0x06 TCMinRe­ +quiredVer­ +sion +``` +``` +uint16 all N R A TC +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 805 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x07 TCAc­ +knowl­ +edgements +``` +``` +map16 all N R A TC +``` +``` +0x08 TCAc­ +knowl­ +edge­ +mentsRe­ +quired +``` +``` +bool all N true R A TC +``` +``` +0x09 TCUpdat­ +eDeadline +``` +``` +uint32 all N X R A TC +``` +**11.10.6.1. Breadcrumb Attribute** + +This attribute allows for the storage of a client-provided small payload which Administrators and +Commissioners MAY write and then subsequently read, to keep track of their own progress. This +MAY be used by the Commissioner to avoid repeating already-executed actions upon re-establishing +a commissioning link after an error. + +On start/restart of the server, such as when a device is power-cycled, this attribute SHALL be reset +to zero. + +Some commands related to commissioning also have a side-effect of updating or resetting this +attribute and this is specified in their respective functional descriptions. + +The format of the value within this attribute is unspecified and its value is not otherwise used by +the functioning of any cluster, other than being set as a side-effect of commands where this behav­ +ior is described. + +**11.10.6.2. BasicCommissioningInfo Attribute** + +This attribute SHALL describe critical parameters needed at the beginning of commissioning flow. +See BasicCommissioningInfo for more information. + +**11.10.6.3. RegulatoryConfig Attribute** + +This attribute SHALL indicate the regulatory configuration for the product. + +Note that the country code is part of Basic Information Cluster and therefore NOT listed on the Reg­ +ulatoryConfig attribute. + +**11.10.6.4. LocationCapability Attribute** + +LocationCapability is statically set by the manufacturer and indicates if this Node needs to be told +an exact RegulatoryLocation. For example a Node which is "Indoor Only" would not be certified for +outdoor use at all, and thus there is no need for a commissioner to set or ask the user about +whether the device will be used inside or outside. However a device which states its capability is + +``` +Page 806 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +"Indoor/Outdoor" means it would like clarification if possible. + +For Nodes without radio network interfaces (e.g. Ethernet-only devices), the value IndoorOutdoor +SHALL always be used. + +The default value of the RegulatoryConfig attribute is the value of LocationCapability attribute. This +means devices always have a safe default value, and Commissioners which choose to implement +smarter handling can. + +**11.10.6.5. SupportsConcurrentConnection Attribute** + +This attribute SHALL indicate whether this device supports "concurrent connection flow" commis­ +sioning mode (see Section 5.5, “Commissioning Flows”). If false, the device only supports "non-con­ +current connection flow" mode. + +**11.10.6.6. TCAcceptedVersion Attribute** + +This attribute SHALL indicate the last version of the T&Cs for which the device received user +acknowledgements. On factory reset this field SHALL be reset to 0. + +When Custom Commissioning Flow is used to obtain user consent (e. g. because the Commissioner +does not support the TC feature), the manufacturer-provided means for obtaining user consent +SHALL ensure that this attribute is set to a value which is greater than or equal to TCMinRequired­ +Version before returning the user back to the originating Commissioner (see Enhanced Setup Flow). + +**11.10.6.7. TCMinRequiredVersion Attribute** + +This attribute SHALL indicate the minimum version of the texts presented by the Enhanced Setup +Flow that need to be accepted by the user for this device. This attribute MAY change as the result of +an OTA update. + +If an event such as a software update causes TCAcceptedVersion to become less than TCMinRe­ +quiredVersion, then the device SHALL update TCAcknowledgementsRequired to True so that an +administrator can detect that a newer version of the texts needs to be presented to the user. + +**11.10.6.8. TCAcknowledgements Attribute** + +This attribute SHALL indicate the user’s response to the presented terms. Each bit position corre­ +sponds to a user response for the associated index of matching text, such that bit 0 (bit value 1) is +for text index 0. Bit 15 (bit value 0x8000) is for text index 15. A bit value of 1 indicates acceptance +and a value of 0 indicates non-acceptance. For example, if there are two texts that were presented +where the first (bit 0, value 1) was declined and the second accepted (bit 1, value 2), we would +expect the resulting value of the map to be 2. + +Whenever a user provides responses to newly presented terms and conditions, this attribute +SHALL be updated with the latest responses. This MAY happen in response to updated terms that +were presented to the user. On a factory reset this field SHALL be reset with all bits set to 0. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 807 +``` + +**11.10.6.9. TCAcknowledgementsRequired Attribute** + +This attribute SHALL indicate whether SetTCAcknowledgements is currently required to be called +with the inclusion of mandatory terms accepted. + +This attribute MAY be present and False in the case where no terms and conditions are currently +mandatory to accept for CommissioningComplete to succeed. + +This attribute MAY appear, or become True after commissioning (e.g. due to a firmware update) to +indicate that new Terms & Conditions are available that the user must accept. + +Upon Factory Data Reset, this attribute SHALL be set to a value of True. + +When Custom Commissioning Flow is used to obtain user consent (e.g. because the Commissioner +does not support the TC feature), the manufacturer-provided means for obtaining user consent +SHALL ensure that this attribute is set to False before returning the user back to the original Com­ +missioner (see Enhanced Setup Flow). + +**11.10.6.10. TCUpdateDeadline Attribute** + +This attribute SHALL indicate the System Time in seconds when any functionality limitations will +begin due to a lack of acceptance of updated Terms and Conditions, as described in Section 5.7.4.5, +“Presenting Updated Terms and Conditions”. + +A null value indicates that there is no pending deadline for updated TC acceptance. + +**11.10.7. Commands** + +For all client-to-server commands in this cluster, if the client deems that it has timed-out in receiv­ +ing the corresponding response command to any request, the corresponding step in the commis­ +sioning flow SHALL be considered to have failed, with the error handled as described in Section +5.5.1, “Commissioning Flows Error Handling”. + +``` +ID Name Direction Response Access Conformance +0x00 ArmFailSafe client ⇒ server ArmFailSafeRe­ +sponse +``` +### A M + +``` +0x01 ArmFailSafeR­ +esponse +``` +``` +client ⇐ server N M +``` +``` +0x02 SetRegulato­ +ryConfig +``` +``` +client ⇒ server SetRegulato­ +ryConfigRe­ +sponse +``` +### A M + +``` +0x03 SetRegulato­ +ryConfigRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x04 Commission­ +ingComplete +``` +``` +client ⇒ server Commission­ +ingCom­ +pleteResponse +``` +### A F M + +``` +Page 808 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Direction Response Access Conformance +0x05 Commission­ +ingCom­ +pleteResponse +``` +``` +client ⇐ server N M +``` +``` +0x06 SetTCAc­ +knowledge­ +ments +``` +``` +client ⇒ server SetTCAcknowl­ +edgementsRe­ +sponse +``` +### A TC + +``` +0x07 SetTCAc­ +knowledge­ +mentsRe­ +sponse +``` +``` +client ⇐ server N TC +``` +**11.10.7.1. Common fields in General Commissioning cluster responses** + +Some response commands have a DebugText argument which SHOULD NOT be presented directly +in user interfaces. Its purpose is to help developers in troubleshooting errors. The value MAY go +into logs or crash reports. + +**11.10.7.2. ArmFailSafe Command** + +The arguments for this command are as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ExpiryLengt +hSeconds +``` +``` +uint16 900 M +``` +``` +1 Bread­ +crumb +``` +``` +uint64 M +``` +Success or failure of this command SHALL be communicated by the ArmFailSafeResponse com­ +mand, unless some data model validations caused a failure status code to be issued during the pro­ +cessing of the command. + +If the fail-safe timer is not currently armed, the commissioning window is open, and the command +was received over a CASE session, the command SHALL leave the current fail-safe state unchanged +and immediately respond with an ArmFailSafeResponse containing an ErrorCode value of Busy­ +WithOtherAdmin. This is done to allow commissioners, which use PASE connections, the opportu­ +nity to use the failsafe during the relatively short commissioning window. + +Otherwise, the command SHALL arm or re-arm the "fail-safe timer" with an expiry time set for a +duration of ExpiryLengthSeconds, or disarm it, depending on the situation: + +- If ExpiryLengthSeconds is 0 and the fail-safe timer was already armed and the accessing fabric + matches the Fabric currently associated with the fail-safe context, then the fail-safe timer + SHALL be immediately expired (see further below for side-effects of expiration). +- If ExpiryLengthSeconds is 0 and the fail-safe timer was not armed, then this command invoca­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 809 +``` + +``` +tion SHALL lead to a success response with no side-effects against the fail-safe context. +``` +- If ExpiryLengthSeconds is non-zero and the fail-safe timer was not currently armed, then the + fail-safe timer SHALL be armed for that duration. +- If ExpiryLengthSeconds is non-zero and the fail-safe timer was currently armed, and the access­ + ing Fabric matches the fail-safe context’s associated Fabric, then the fail-safe timer SHALL be re- + armed to expire in ExpiryLengthSeconds. +- Otherwise, the command SHALL leave the current fail-safe state unchanged and immediately + respond with ArmFailSafeResponse containing an ErrorCode value of BusyWithOtherAdmin, + indicating a likely conflict between commissioners. + +The value of the Breadcrumb field SHALL be written to the Breadcrumb on successful execution of +the command. + +If the receiver restarts unexpectedly (e.g., power interruption, software crash, or other reset) the +receiver SHALL behave as if the fail-safe timer expired and perform the sequence of clean-up steps +listed below. + +On successful execution of the command, the ErrorCode field of the ArmFailSafeResponse SHALL +be set to OK. + +**Fail Safe Context** + +When first arming the fail-safe timer, a 'Fail Safe Context' SHALL be created on the receiver, to +track the following state information while the fail-safe is armed: + +- The fail-safe timer duration. +- The state of all Network Commissioning Networks attribute configurations, to allow recovery of + connectivity after Fail-Safe expiry. +- Whether an AddNOC command or UpdateNOC command has taken place. +- A Fabric Index for the fabric-scoping of the context, starting at the accessing fabric index for the + ArmFailSafe command, and updated with the Fabric Index associated with an AddNOC com­ + mand or an UpdateNOC command being invoked successfully during the ongoing Fail-Safe + timer period. +- The operational credentials associated with any Fabric whose configuration is affected by the + UpdateNOC command. +- Optionally: the previous state of non-fabric-scoped data that is mutated during the fail-safe + period. + +Note the following to assist in understanding the above state-keeping, which summarizes other nor­ +mative requirements in the respective sections: + +- The AddNOC command can only be invoked once per contiguous non-expiring fail-safe timer + period, and only if no UpdateNOC command was previously processed within the same fail-safe + timer period. +- The UpdateNOC command can only be invoked once per contiguous non-expiring fail-safe timer + period, can only be invoked over a CASE session, and only if no AddNOC command was previ­ + +``` +Page 810 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ously processed in the same fail-safe timer period. +``` +``` +On creation of the Fail Safe Context a second timer SHALL be created to expire at MaxCumulative­ +FailsafeSeconds as specified in BasicCommissioningInfo. This Cumulative Fail Safe Context timer +(CFSC timer) serves to limit the lifetime of any particular Fail Safe Context; it SHALL NOT be +extended or modified on subsequent invocations of ArmFailSafe associated with this Fail Safe Con­ +text. Upon expiry of the CFSC timer, the receiver SHALL execute cleanup behavior equivalent to +that of fail-safe timer expiration as detailed in Section 11.10.7.2.2, “Behavior on expiry of Fail-Safe +timer”. Termination of the session prior to the expiration of that timer for any reason (including a +successful end of commissioning or an expiry of a fail-safe timer) SHALL also delete the CFSC timer. +``` +``` +Behavior on expiry of Fail-Safe timer +``` +``` +If the fail-safe timer expires before the CommissioningComplete command is successfully invoked, +the following sequence of clean-up steps SHALL be executed, in order, by the receiver: +``` +1. Terminate any open PASE secure session by clearing any associated Secure Session Context at + the Server. +2. Revoke the temporary administrative privileges granted to any open PASE session (see Section + 6.6.2.9, “Bootstrapping of the Access Control Cluster”) at the Server. +3. If an AddNOC or UpdateNOC command has been successfully invoked, terminate all CASE ses­ + sions associated with the Fabric whose Fabric Index is recorded in the Fail-Safe context (see + ArmFailSafe) by clearing any associated Secure Session Context at the Server. +4. Reset the configuration of all Network Commissioning Networks attribute to their state prior to + the Fail-Safe being armed. +5. If an UpdateNOC command had been successfully invoked, revert the state of operational key + pair, NOC and ICAC for that Fabric to the state prior to the Fail-Safe timer being armed, for the + Fabric Index that was the subject of the UpdateNOC command. +6. If an AddNOC command had been successfully invoked, achieve the equivalent effect of invok­ + ing the RemoveFabric command against the Fabric Index stored in the Fail-Safe Context for the + Fabric Index that was the subject of the AddNOC command. This SHALL remove all associations + to that Fabric including all fabric-scoped data, and MAY possibly factory-reset the device + depending on current device state. This SHALL only apply to Fabrics added during the fail-safe + period as the result of the AddNOC command. +7. If the CSRRequest command had been successfully invoked, but no AddNOC or UpdateNOC com­ + mand had been successfully invoked, then the new operational key pair temporarily generated + for the purposes of NOC addition or update (see Node Operational CSR Procedure) SHALL be + removed as it is no longer needed. +8. Remove any RCACs added by the AddTrustedRootCertificate command that are not currently + referenced by any entry in the Fabrics attribute. +9. Reset the Breadcrumb attribute to zero. +10. Optionally: if no factory-reset resulted from the previous steps, it is RECOMMENDED that the +Node rollback the state of all non fabric-scoped data present in the Fail-Safe context. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 811 +``` + +**11.10.7.3. ArmFailSafeResponse Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ErrorCode Commis­ +sioningEr­ +rorEnum +``` +### OK M + +``` +1 DebugText String max 128 "" M +``` +**ErrorCode Field** + +This field SHALL contain the result of the operation, based on the behavior specified in the func­ +tional description of the ArmFailSafe command. + +**DebugText Field** + +See Section 11.10.7.1, “Common fields in General Commissioning cluster responses”. + +**11.10.7.4. SetRegulatoryConfig Command** + +This SHALL add or update the regulatory configuration in the RegulatoryConfig Attribute to the +value provided in the NewRegulatoryConfig field. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NewRegula­ +toryConfig +``` +``` +Regulatory­ +Location­ +TypeEnum +``` +### M + +``` +1 Coun­ +tryCode +``` +``` +string 2 M +``` +``` +2 Bread­ +crumb +``` +``` +uint64 M +``` +Success or failure of this command SHALL be communicated by the SetRegulatoryConfigResponse +command, unless some data model validations caused a failure status code to be issued during the +processing of the command. + +The CountryCode field SHALL conforms to ISO 3166-1 alpha-2 and SHALL be used to set the Loca­ +tion attribute reflected by the Basic Information Cluster. + +If the server limits some of the values (e.g. locked to a particular country, with no regulatory data +for others), then setting regulatory information outside a valid country or location SHALL still set +the Location attribute reflected by the Basic Information Cluster configuration, but the SetRegulato­ +ryConfigResponse replied SHALL have the ErrorCode field set to ValueOutsideRange error. + +If the LocationCapability attribute is not Indoor/Outdoor and the NewRegulatoryConfig value + +``` +Page 812 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +received does not match either the Indoor or Outdoor fixed value in LocationCapability, then the +SetRegulatoryConfigResponse replied SHALL have the ErrorCode field set to ValueOutsideRange +error and the RegulatoryConfig attribute and associated internal radio configuration SHALL remain +unchanged. + +If the LocationCapability attribute is set to Indoor/Outdoor, then the RegulatoryConfig attribute +SHALL be set to match the NewRegulatoryConfig field. + +On successful execution of the command, the ErrorCode field of the SetRegulatoryConfigResponse +SHALL be set to OK. + +The Breadcrumb field SHALL be used to atomically set the Breadcrumb attribute on success of this +command, when SetRegulatoryConfigResponse has the ErrorCode field set to OK. If the command +fails, the Breadcrumb attribute SHALL be left unchanged. + +**11.10.7.5. SetRegulatoryConfigResponse Command** + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ErrorCode Commis­ +sioningEr­ +rorEnum +``` +### OK M + +``` +1 DebugText String "" M +``` +**ErrorCode Field** + +This field SHALL contain the result of the operation, based on the behavior specified in the func­ +tional description of the SetRegulatoryConfig command. + +**DebugText Field** + +See Section 11.10.7.1, “Common fields in General Commissioning cluster responses”. + +**11.10.7.6. CommissioningComplete Command** + +This command has no data. + +Success or failure of this command SHALL be communicated by the CommissioningCompleteRe­ +sponse command, unless some data model validations caused a failure status code to be issued dur­ +ing the processing of the command. + +This command signals the Server that the Commissioner or Administrator has successfully com­ +pleted all steps needed during the Fail-Safe period, such as commissioning (see Section 5.5, “Com­ +missioning Flows”) or other Administrator operations requiring usage of the Fail Safe timer. It +ensures that the Server is configured in a state such that it still has all necessary elements to be +fully operable within a Fabric, such as ACL entries (see Section 9.10, “Access Control Cluster”) and +operational credentials (see Section 6.4, “Node Operational Credentials Specification”), and that the +Node is reachable using CASE (see Section 4.14.2, “Certificate Authenticated Session Establishment + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 813 +``` + +(CASE)”) over an operational network. + +An ErrorCode of NoFailSafe SHALL be responded to the invoker if the CommissioningComplete +command was received when no Fail-Safe context exists. + +If Terms and Conditions are required, then an ErrorCode of TCAcknowledgementsNotReceived +SHALL be responded to the invoker if the user acknowledgements to the required Terms and Con­ +ditions have not been provided. If the TCAcceptedVersion for the provided acknowledgements is +less than TCMinRequiredVersion, then an ErrorCode of TCMinVersionNotMet SHALL be responded +to the invoker. + +This command is fabric-scoped, so cannot be issued over a session that does not have an associated +fabric, i.e. over PASE session prior to an AddNOC command. In addition, this command is only per­ +mitted over CASE and must be issued by a node associated with the ongoing Fail-Safe context. An +ErrorCode of InvalidAuthentication SHALL be responded to the invoker if the CommissioningCom­ +plete command was received outside a CASE session (e.g., over Group messaging, or PASE session +after AddNOC), or if the accessing fabric is not the one associated with the ongoing Fail-Safe con­ +text. + +This command SHALL only result in success with an ErrorCode value of OK in the Commissioning­ +CompleteResponse if received over a CASE session and the accessing fabric index matches the Fab­ +ric Index associated with the current Fail-Safe context. In other words: + +- If no AddNOC command had been successfully invoked, the CommissioningComplete command + must originate from the Fabric that initiated the Fail-Safe context. +- After an AddNOC command has been successfully invoked, the CommissioningComplete com­ + mand must originate from the Fabric which was joined through the execution of that command, + which updated the Fail-Safe context’s Fabric Index. + +On successful execution of the CommissioningComplete command, where the CommissioningCom­ +pleteResponse has an ErrorCode of OK, the following actions SHALL be undertaken on the Server: + +1. The Fail-Safe timer associated with the current Fail-Safe context SHALL be disarmed. +2. The commissioning window at the Server SHALL be closed. +3. Any temporary administrative privileges automatically granted to any open PASE session + SHALL be revoked (see Section 6.6.2.9, “Bootstrapping of the Access Control Cluster”). +4. The Secure Session Context of any PASE session still established at the Server SHALL be cleared. +5. The Breadcrumb attribute SHALL be reset to zero. + +After receipt of a CommissioningCompleteResponse with an ErrorCode value of OK, a client cannot +expect any previously established PASE session to still be usable, due to the server having cleared +such sessions. + +**11.10.7.7. CommissioningCompleteResponse Command** + +The data for this command is as follows: + +``` +Page 814 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ErrorCode Commis­ +sioningEr­ +rorEnum +``` +### OK M + +``` +1 DebugText String "" M +``` +**ErrorCode Field** + +This field SHALL contain the result of the operation, based on the behavior specified in the func­ +tional description of the CommissioningComplete command. + +**DebugText Field** + +See Section 11.10.7.1, “Common fields in General Commissioning cluster responses”. + +**11.10.7.8. SetTCAcknowledgements Command** + +This command sets the user acknowledgements received in the Enhanced Setup Flow Terms & Con­ +ditions into the node. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TCVersion uint16 all M +1 TCUserRe­ +sponse +``` +``` +map16 all M +``` +**TCVersion field** + +This field SHALL contain the version of the Enhanced Setup Flow Terms & Conditions that were +presented to the user. + +**TCUserResponse field** + +This field SHALL contain the user responses to the Enhanced Setup Flow Terms & Conditions as a +map where each bit set in the bitmap corresponds to an accepted term in the file located at +EnhancedSetupFlowTCUrl. + +**Effect on Receipt** + +This command SHALL copy the user responses and accepted version to the presented Enhanced +Setup Flow Terms & Conditions from the values provided in the TCUserResponse and TCVersion +fields to the TCAcknowledgements Attribute and the TCAcceptedVersion Attribute fields respec­ +tively. + +This command SHALL result in success with an ErrorCode value of OK in the SetTCAcknowledge­ +mentsResponse if all required terms were accepted by the user. Specifically, all bits have a value of +1 in TCAcknowledgements whose ordinal is marked as required in the file located at EnhancedSe­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 815 +``` + +tupFlowTCUrl. + +If the TCVersion field is less than the TCMinRequiredVersion, then the ErrorCode of TCMinVersion­ +NotMet SHALL be returned and TCAcknowledgements SHALL remain unchanged. + +If TCVersion is greater than or equal to TCMinRequiredVersion, but the TCUserResponse value indi­ +cates that not all required terms were accepted by the user, then the ErrorCode of RequiredTCNo­ +tAccepted SHALL be returned and TCAcknowledgements SHALL remain unchanged. + +**11.10.7.9. SetTCAcknowledgementsResponse Command** + +This command is used to convey the result from SetTCAcknowledgements. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ErrorCode Commis­ +sioningEr­ +rorEnum +``` +### OK M + +**ErrorCode Field** + +This field SHALL contain the result of the operation, based on the behavior specified in the func­ +tional description of the SetTCAcknowledgements command. + +**11.11. Diagnostic Logs Cluster** + +This Cluster supports an interface to a Node. It provides commands for retrieving unstructured +diagnostic logs from a Node that may be used to aid in diagnostics. It will often be the case that +unstructured diagnostic logs will be Node-wide and not specific to any subset of Endpoints. When +present, this Cluster SHALL be implemented once for the Node. The Node SHOULD also implement +the BDX Initiator and BDX Sender roles as defined in the BDX Protocol. + +**11.11.1. Revision History** + +The global ClusterRevision Attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.11.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node DLOG +``` +``` +Page 816 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.11.3. Cluster ID** + +``` +ID Name +0x0032 Diagnostic Logs +``` +**11.11.4. Data Types** + +**11.11.4.1. IntentEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 EndUserSupport Logs to be used for end- +user support +``` +### M + +``` +1 NetworkDiag Logs to be used for net­ +work diagnostics +``` +### M + +``` +2 CrashLogs Obtain crash logs from +the Node +``` +### M + +**EndUserSupport Value** + +SHALL indicate that the purpose of the log request is to retrieve logs for the intention of providing +support to an end-user. + +**NetworkDiag Value** + +SHALL indicate that the purpose of the log request is to diagnose the network(s) for which the Node +is currently commissioned (and/or connected) or has previously been commissioned (and/or con­ +nected). + +**CrashLogs Value** + +SHALL indicate that the purpose of the log request is to retrieve any crash logs that may be present +on a Node. + +**11.11.4.2. StatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Success Successful transfer of +logs +``` +### M + +``` +1 Exhausted All logs has been trans­ +ferred +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 817 +``` + +``` +Value Name Summary Conformance +2 NoLogs No logs of the +requested type avail­ +able +``` +### M + +``` +3 Busy Unable to handle +request, retry later +``` +### M + +``` +4 Denied The request is denied, +no logs being trans­ +ferred +``` +### M + +**Success Value** + +SHALL be used if diagnostic logs will be or are being transferred. + +**Exhausted Value** + +SHALL be used when a BDX session is requested, however, all available logs were provided in a +LogContent field. + +**NoLogs Value** + +SHALL be used if the Node does not currently have any diagnostic logs of the requested type +(Intent) to transfer. + +**Busy Value** + +SHALL be used if the Node is unable to handle the request (e.g. in the process of another transfer) +and the Client SHOULD re-attempt the request later. + +**Denied Value** + +SHALL be used if the Node is denying the current transfer of diagnostic logs for any reason. + +**11.11.4.3. TransferProtocolEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 ResponsePayload Logs to be returned as a +response +``` +### M + +``` +1 BDX Logs to be returned +using BDX +``` +### M + +**ResponsePayload Value** + +SHALL be used by a Client to request that logs are transferred using the LogContent attribute of the +response + +``` +Page 818 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**BDX Value** + +SHALL be used by a Client to request that logs are transferred using BDX as defined in BDX Protocol + +**11.11.5. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 RetrieveL­ +ogsRequest +``` +``` +client ⇒ server RetrieveL­ +ogsResponse +``` +### O M + +``` +0x01 RetrieveL­ +ogsResponse +``` +``` +client ⇐ server N M +``` +**11.11.5.1. RetrieveLogsRequest Command** + +Reception of this command starts the process of retrieving diagnostic logs from a Node. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Intent IntentEnum all M +1 Requested­ +Protocol +``` +``` +TransferPro­ +tocolEnum +``` +``` +all M +``` +``` +2 Transfer­ +FileDesigna­ +tor +``` +``` +string max 32 O +``` +**Intent Field** + +This field SHALL indicate why the diagnostic logs are being retrieved from the Node. A Node MAY +utilize this field to selectively determine the logs to transfer. + +**RequestedProtocol Field** + +This field SHALL be used to indicate how the log transfer is to be realized. If the field is set to BDX, +then if the receiving Node supports BDX it SHALL attempt to use BDX to transfer any potential diag­ +nostic logs; if the receiving Node does not support BDX then the Node SHALL follow the require­ +ments defined for a TransferProtocolEnum of ResponsePayload. If this field is set to ResponsePay­ +load the receiving Node SHALL only utilize the LogContent field of the RetrieveLogsResponse com­ +mand to transfer diagnostic log information. + +**TransferFileDesignator Field** + +This field SHALL be present if the RequestedProtocol is BDX. The TransferFileDesignator SHALL be +set as the File Designator of the BDX transfer if initiated. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 819 +``` + +**Effect on Receipt** + +On receipt of this command, the Node SHALL respond with a RetrieveLogsResponse command. + +If the RequestedProtocol is set to BDX the Node SHOULD immediately realize the RetrieveLogsRe­ +sponse command by initiating a BDX Transfer, sending a BDX SendInit message with the File Desig­ +nator field of the message set to the value of the TransferFileDesignator field of the RetrieveLogsRe­ +quest. On reception of a BDX SendAccept message the Node SHALL send a RetrieveLogsResponse +command with a Status field set to Success and proceed with the log transfer over BDX. If a failure +StatusReport is received in response to the SendInit message, the Node SHALL send a RetrieveL­ +ogsResponse command with a Status of Denied. In the case where the Node is able to fit the entirety +of the requested logs within the LogContent field, the Status field of the RetrieveLogsResponse +SHALL be set to Exhausted and a BDX session SHALL NOT be initiated. + +If the RequestedProtocol is set to BDX and either the Node does not support BDX or it is not possible +for the Node to establish a BDX session, then the Node SHALL utilize the LogContent field of the +RetrieveLogsResponse command to transfer as much of the current logs as it can fit within the +response, and the Status field of the RetrieveLogsResponse SHALL be set to Exhausted. + +If the RequestedProtocol is set to ResponsePayload the Node SHALL utilize the LogContent field of +the RetrieveLogsResponse command to transfer as much of the current logs as it can fit within the +response, and a BDX session SHALL NOT be initiated. + +If the RequestedProtocol is set to BDX and there is no TransferFileDesignator the command SHALL +fail with a Status Code of INVALID_COMMAND. + +If the Intent and/or the RequestedProtocol arguments contain invalid (out of range) values the com­ +mand SHALL fail with a Status Code of INVALID_COMMAND. + +**11.11.5.2. RetrieveLogsResponse Command** + +This SHALL be generated as a response to the RetrieveLogsRequest. + +The data for this command is shown in the following. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status StatusEnum all M +1 LogContent octstr max 1024 M +2 UTCTime­ +Stamp +``` +``` +epoch-us all O +``` +``` +3 TimeSince­ +Boot +``` +``` +system-us all O +``` +**Status Field** + +This field SHALL indicate the result of an attempt to retrieve diagnostic logs. + +``` +Page 820 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**LogContent Field** + +This field SHALL be included in the command if the Status field has a value of Success or +Exhausted. A Node SHOULD utilize this field to transfer the newest diagnostic log entries. This field +SHALL be empty if BDX is requested and the Status field has a value of Success. + +**UTCTimeStamp Field** + +This field SHOULD be included in the command if the Status field has a value of Success and the +Node maintains a wall clock. When included, the UTCTimeStamp field SHALL contain the value of +the oldest log entry in the diagnostic logs that are being transferred. + +**TimeSinceBoot Field** + +This field SHOULD be included in the command if the Status field has a value of Success. When +included, the TimeSinceBoot field SHALL contain the time of the oldest log entry in the diagnostic +logs that are being transferred represented by the number of microseconds since the last time the +Node went through a reboot. + +**11.12. General Diagnostics Cluster** + +The General Diagnostics Cluster, along with other diagnostics clusters, provide a means to acquire +standardized diagnostics metrics that MAY be used by a Node to assist a user or Administrator in +diagnosing potential problems. The General Diagnostics Cluster attempts to centralize all metrics +that are broadly relevant to the majority of Nodes. + +**11.12.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 UpTime attribute now mandatory, and added +TimeSnapshot command, added DMTEST fea­ +ture. +``` +**11.12.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node DGGEN +``` +**11.12.3. Cluster ID** + +``` +ID Name +0x0033 General Diagnostics +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 821 +``` + +**11.12.4. Features** + +The following table indicates the features for this cluster: + +``` +Bit Code Feature Conformance Summary +0 DMTEST DataModelTest desc Support specific +testing needs for +extended Data +Model features +``` +**11.12.4.1. DataModelTest Feature** + +This feature indicates support for extended Data Model testing commands, which are required in +some situations. + +This feature SHALL be supported if the MaxPathsPerInvoke attribute of the Basic Information Clus­ +ter has a value > 1. + +**11.12.5. Data Types** + +**11.12.5.1. HardwareFaultEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified The Node has encoun­ +tered an unspecified +fault. +``` +### M + +``` +1 Radio The Node has encoun­ +tered a fault with at +least one of its radios. +``` +### O + +``` +2 Sensor The Node has encoun­ +tered a fault with at +least one of its sensors. +``` +### O + +``` +3 ResettableOverTemp The Node has encoun­ +tered an over-tempera­ +ture fault that is reset­ +table. +``` +### O + +``` +4 NonReset­ +tableOverTemp +``` +``` +The Node has encoun­ +tered an over-tempera­ +ture fault that is not +resettable. +``` +### O + +``` +5 PowerSource The Node has encoun­ +tered a fault with at +least one of its power +sources. +``` +### O + +``` +Page 822 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +6 VisualDisplayFault The Node has encoun­ +tered a fault with at +least one of its visual +displays. +``` +### O + +``` +7 AudioOutputFault The Node has encoun­ +tered a fault with at +least one of its audio +outputs. +``` +### O + +``` +8 UserInterfaceFault The Node has encoun­ +tered a fault with at +least one of its user +interfaces. +``` +### O + +``` +9 NonVolatileMemory­ +Error +``` +``` +The Node has encoun­ +tered a fault with its +non-volatile memory. +``` +### O + +``` +10 TamperDetected The Node has encoun­ +tered disallowed physi­ +cal tampering. +``` +### O + +**11.12.5.2. RadioFaultEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified The Node has encoun­ +tered an unspecified +radio fault. +``` +### M + +``` +1 WiFiFault The Node has encoun­ +tered a fault with its +Wi-Fi radio. +``` +### O + +``` +2 CellularFault The Node has encoun­ +tered a fault with its +cellular radio. +``` +### O + +``` +3 ThreadFault The Node has encoun­ +tered a fault with its +802.15.4 radio. +``` +### O + +``` +4 NFCFault The Node has encoun­ +tered a fault with its +NFC radio. +``` +### O + +``` +5 BLEFault The Node has encoun­ +tered a fault with its +BLE radio. +``` +### O + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 823 +``` + +``` +Value Name Summary Conformance +6 EthernetFault The Node has encoun­ +tered a fault with its +Ethernet controller. +``` +### O + +**11.12.5.3. NetworkFaultEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified The Node has encoun­ +tered an unspecified +fault. +``` +### M + +``` +1 HardwareFailure The Node has encoun­ +tered a network fault as +a result of a hardware +failure. +``` +### O + +``` +2 NetworkJammed The Node has encoun­ +tered a network fault as +a result of a jammed +network. +``` +### O + +``` +3 ConnectionFailed The Node has encoun­ +tered a network fault as +a result of a failure to +establish a connection. +``` +### O + +**11.12.5.4. InterfaceTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified Indicates an interface +of an unspecified type. +``` +### M + +``` +1 WiFi Indicates a Wi-Fi inter­ +face. +``` +### O + +``` +2 Ethernet Indicates a Ethernet +interface. +``` +### O + +``` +3 Cellular Indicates a Cellular +interface. +``` +### O + +``` +4 Thread Indicates a Thread +interface. +``` +### O + +``` +Page 824 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.12.5.5. BootReasonEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified The Node is unable to +identify the Power-On +reason as one of the +other provided enu­ +meration values. +``` +### M + +``` +1 PowerOnReboot The Node has booted as +the result of physical +interaction with the +device resulting in a +reboot. +``` +### M + +``` +2 BrownOutReset The Node has rebooted +as the result of a +brown-out of the +Node’s power supply. +``` +### M + +``` +3 SoftwareWatchdogRe­ +set +``` +``` +The Node has rebooted +as the result of a soft­ +ware watchdog timer. +``` +### M + +``` +4 HardwareWatchdo­ +gReset +``` +``` +The Node has rebooted +as the result of a hard­ +ware watchdog timer. +``` +### M + +``` +5 SoftwareUpdateCom­ +pleted +``` +``` +The Node has rebooted +as the result of a com­ +pleted software update. +``` +### M + +``` +6 SoftwareReset The Node has rebooted +as the result of a soft­ +ware initiated reboot. +``` +### M + +**11.12.5.6. NetworkInterface Type** + +This structure describes a network interface supported by the Node, as provided in the NetworkIn­ +terfaces attribute. + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Name string max 32 M +1 IsOpera­ +tional +``` +``` +bool M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 825 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +2 Off­ +Premis­ +eServices­ +Reach­ +ableIPv4 +``` +``` +bool X null M +``` +``` +3 Off­ +Premis­ +eServices­ +Reach­ +ableIPv6 +``` +``` +bool X null M +``` +``` +4 Hard­ +wareAd­ +dress +``` +``` +Hardware +Address +``` +### M + +``` +5 IPv4Ad­ +dresses +``` +``` +list[ipv4ad +dr] +``` +``` +max 4 M +``` +``` +6 IPv6Ad­ +dresses +``` +``` +list[ipv6ad +dr] +``` +``` +max 8 M +``` +``` +7 Type Interface­ +TypeEnum +``` +### M + +**Name Field** + +This field SHALL indicate a human-readable (displayable) name for the network interface, that is +different from all other interfaces. + +**IsOperational Field** + +This field SHALL indicate if the Node is currently advertising itself operationally on this network +interface and is capable of successfully receiving incoming traffic from other Nodes. + +**OffPremiseServicesReachableIPv4 Field** + +This field SHALL indicate whether the Node is currently able to reach off-premise services it uses +by utilizing IPv4. The value SHALL be null if the Node does not use such services or does not know +whether it can reach them. + +**OffPremiseServicesReachableIPv6 Field** + +This field SHALL indicate whether the Node is currently able to reach off-premise services it uses +by utilizing IPv6. The value SHALL be null if the Node does not use such services or does not know +whether it can reach them. + +**HardwareAddress Field** + +This field SHALL contain the current link-layer address for a 802.3 or IEEE 802.11-2020 network + +``` +Page 826 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +interface and contain the current extended MAC address for a 802.15.4 interface. The byte order of +the octstr SHALL be in wire byte order. For addresses values less than 64 bits, the first two bytes +SHALL be zero. + +**IPv4Addresses Field** + +This field SHALL provide a list of the IPv4 addresses that are currently assigned to the network +interface. + +**IPv6Addresses Field** + +This field SHALL provide a list of the unicast IPv6 addresses that are currently assigned to the net­ +work interface. This list SHALL include the Node’s link-local address and SHOULD include any +assigned GUA and ULA addresses. This list SHALL NOT include any multicast group addresses to +which the Node is subscribed. + +**Type Field** + +This field SHALL indicate the type of the interface using the InterfaceTypeEnum. + +**11.12.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Network­ +Interfaces +``` +``` +list[Net­ +workInter­ +face] +``` +``` +max 8 R V M +``` +``` +0x0001 Reboot­ +Count +``` +``` +uint16 N R V M +``` +``` +0x0002 UpTime uint64 C R V M +0x0003 TotalOper­ +ational­ +Hours +``` +``` +uint32 N C R V O +``` +``` +0x0004 BootRea­ +son +``` +``` +BootReaso­ +nEnum +``` +### R V O + +``` +0x0005 Active­ +Hardware­ +Faults +``` +``` +list[Hard­ +wareFault­ +Enum] +``` +``` +max 11 R V O +``` +``` +0x0006 ActiveRa­ +dioFaults +``` +``` +list[Radio­ +Fault­ +Enum] +``` +``` +max 7 R V O +``` +``` +0x0007 ActiveNet­ +work­ +Faults +``` +``` +list[Net­ +workFault­ +Enum] +``` +``` +max 4 R V O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 827 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0008 TestEvent­ +Trig­ +gersEn­ +abled +``` +``` +bool all R V M +``` +``` +0x0009 DoNotUse X +``` +Attribute 0x0009 SHALL NOT be used in any implementation of previous, current or future version +of this specification. + +**11.12.6.1. NetworkInterfaces Attribute** + +The NetworkInterfaces attribute SHALL be a list of NetworkInterface structs. Each logical network +interface on the Node SHALL be represented by a single entry within the NetworkInterfaces +attribute. + +**11.12.6.2. RebootCount Attribute** + +The RebootCount attribute SHALL indicate a best-effort count of the number of times the Node has +rebooted. The RebootCount attribute SHOULD be incremented each time the Node reboots. The +RebootCount attribute SHALL NOT be incremented when a Node wakes from a low-power or sleep +state. The RebootCount attribute SHALL only be reset to 0 upon a factory reset of the Node. + +**11.12.6.3. UpTime Attribute** + +The UpTime attribute SHALL indicate a best-effort assessment of the length of time, in seconds, +since the Node’s last reboot. This attribute SHOULD be incremented to account for the periods of +time that a Node is in a low-power or sleep state. This attribute SHALL only be reset upon a device +reboot. This attribute SHALL be based on the same System Time source as those used to fulfill any +usage of the system-us and system-ms data types within the server. + +**11.12.6.4. TotalOperationalHours Attribute** + +The TotalOperationalHours attribute SHALL indicate a best-effort attempt at tracking the length of +time, in hours, that the Node has been operational. The TotalOperationalHours attribute SHOULD +be incremented to account for the periods of time that a Node is in a low-power or sleep state. The +TotalOperationalHours attribute SHALL only be reset upon a factory reset of the Node. + +**11.12.6.5. BootReason Attribute** + +The BootReason attribute SHALL indicate the reason for the Node’s most recent boot. + +**11.12.6.6. ActiveHardwareFaults Attribute** + +The ActiveHardwareFaults attribute SHALL indicate the set of faults currently detected by the +Node. When the Node detects a fault has been raised, the appropriate HardwareFaultEnum value +SHALL be added to this list. This list SHALL NOT contain more than one instance of a specific Hard­ +wareFaultEnum value. When the Node detects that all conditions contributing to a fault has been + +``` +Page 828 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +cleared, the corresponding HardwareFaultEnum value SHALL be removed from this list. An empty +list SHALL indicate there are currently no active faults. The order of this list SHOULD have no sig­ +nificance. Clients interested in monitoring changes in active faults MAY subscribe to this attribute, +or they MAY subscribe to HardwareFaultChange. + +**11.12.6.7. ActiveRadioFaults Attribute** + +The ActiveRadioFaults attribute SHALL indicate the set of faults currently detected by the Node. +When the Node detects a fault has been raised, the appropriate RadioFaultEnum value SHALL be +added to this list. This list SHALL NOT contain more than one instance of a specific RadioFaultEnum +value. When the Node detects that all conditions contributing to a fault has been cleared, the corre­ +sponding RadioFaultEnum value SHALL be removed from this list. An empty list SHALL indicate +there are currently no active faults. The order of this list SHOULD have no significance. Clients +interested in monitoring changes in active faults MAY subscribe to this attribute, or they MAY sub­ +scribe to RadioFaultChange. + +**11.12.6.8. ActiveNetworkFaults Attribute** + +The ActiveNetworkFaults attribute SHALL indicate the set of faults currently detected by the Node. +When the Node detects a fault has been raised, the appropriate NetworkFaultEnum value SHALL be +added to this list. This list SHALL NOT contain more than one instance of a specific NetworkFault­ +Enum value. When the Node detects that all conditions contributing to a fault has been cleared, the +corresponding NetworkFaultEnum value SHALL be removed from this list. An empty list SHALL +indicate there are currently no active faults. The order of this list SHOULD have no significance. +Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or they +MAY subscribe to NetworkFaultChange. + +**11.12.6.9. TestEventTriggersEnabled Attribute** + +The TestEventTriggersEnabled attribute SHALL indicate whether the Node has any TestEventTrig­ +ger configured. When this attribute is true, the Node has been configured with one or more test +event triggers by virtue of the internally programmed EnableKey value (see TestEventTrigger) +being set to a non-zero value. This attribute can be used by Administrators to detect if a device was +inadvertently commissioned with test event trigger mode enabled, and take appropriate action (e.g. +warn the user and/or offer to remove all fabrics on the Node). + +**11.12.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 TestEventTrig­ +ger +``` +``` +client ⇒ server Y M M +``` +``` +0x01 TimeSnapshot client ⇒ server TimeSnap­ +shotResponse +``` +### O M + +``` +0x02 TimeSnap­ +shotResponse +``` +``` +client ⇐ server N M +``` +``` +0x03 Payload­ +TestRequest +``` +``` +client ⇒ server PayloadTestRe­ +sponse +``` +### M DMTEST + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 829 +``` + +``` +ID Name Direction Response Access Conformance +0x04 Payload­ +TestResponse +``` +``` +server ⇒ client N DMTEST +``` +**11.12.7.1. TestEventTrigger Command** + +This command SHALL be supported to provide a means for certification tests to trigger some test- +plan-specific events, necessary to assist in automation of device interactions for some certification +test cases. This command SHALL NOT cause any changes to the state of the device that persist after +the last fabric is removed. + +The fields for the TestEventTrigger command are as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 EnableKey octstr 16 M +1 EventTrig­ +ger +``` +``` +uint64 M +``` +**EnableKey Field** + +The EnableKey is a 128 bit value provided by the client in this command, which needs to match a +value chosen by the manufacturer and configured on the server using manufacturer-specific +means, such as pre-provisioning. The value of all zeroes is reserved to indicate that no EnableKey is +set. Therefore, if the EnableKey field is received with all zeroes, this command SHALL FAIL with a +response status of CONSTRAINT_ERROR. + +The EnableKey SHOULD be unique per exact set of devices going to a certification test. + +Devices not targeted towards going to a certification test event SHALL NOT have a non-zero +EnableKey value configured, so that only devices in test environments are responsive to this com­ +mand. + +In order to prevent unwittingly actuating a particular trigger, this command SHALL respond with a +response status of CONSTRAINT_ERROR if the EnableKey field does not match the a-priori value +configured on the device. + +**EventTrigger Field** + +This field SHALL indicate the test or test mode which the client wants to trigger. + +The expected side-effects of EventTrigger values are out of scope of this specification and will be +described within appropriate certification test literature provided to manufacturers by the Connec­ +tivity Standards Alliance, in conjunction with certification test cases documentation. + +Values of EventTrigger in the range 0xFFFF_FFFF_0000_0000 through 0xFFFF_FFFF_FFFF_FFFF are +reserved for testing use by manufacturers and will not appear in CSA certification test literature. + +If the value of EventTrigger received is not supported by the receiving Node, this command SHALL + +``` +Page 830 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +fail with a status code of INVALID_COMMAND. + +Otherwise, if the EnableKey value matches the configured internal value for a particular Node, and +the EventTrigger value matches a supported test event trigger value, the command SHALL succeed +and execute the expected trigger action. + +If no specific test event triggers are required to be supported by certification test requirements for +the features that a given product will be certified against, this command MAY always fail with the +INVALID_COMMAND status, equivalent to the situation of receiving an unknown EventTrigger, for +all possible EventTrigger values. + +**11.12.7.2. TimeSnapshot Command** + +This command MAY be used by a client to obtain a correlated view of both System Time, and, if cur­ +rently synchronized and supported, "wall clock time" of the server. This can help clients establish +time correlation between their concept of time and the server’s concept of time. This is especially +useful when processing event histories where some events only contain System Time. + +Upon command invocation, the server SHALL respond with a TimeSnapshotResponse. + +**11.12.7.3. TimeSnapshotResponse Command** + +This command SHALL be generated in response to a TimeSnapshot command. + +When generating this response, all fields SHALL be gathered as close together in time as possible, +so that the time jitter between the values is minimized. + +If the Time Synchronization cluster is supported by the node, the PosixTimeMs field SHALL NOT be +null unless the UTCTime attribute in the Time Synchronization cluster is also null. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0x00 System­ +TimeMs +``` +``` +system-ms all MS M +``` +``` +0x01 Posix­ +TimeMs +``` +``` +posix-ms all X null M +``` +**SystemTimeMs Field** + +This SHALL indicate the current System Time in milliseconds (type system-ms), with the value +taken at the time of processing of the TimeSnapshot command that generated this response. + +The value SHALL be taken from the same clock which populates the Timestamp field in events +when using System Time for the field. + +**PosixTimeMs Field** + +This SHALL indicate the current time in POSIX Time in milliseconds, with the value taken from the +same source that could populate the Timestamp field of events. This value SHALL only be null +when any the following are true: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 831 +``` + +- The node doesn’t support the Time Synchronization cluster. +- The node’s Time Synchronization cluster instance’s UTCTime attribute is null. + +**11.12.7.4. PayloadTestRequest Command** + +This command provides a means for certification tests or manufacturer’s internal tests to validate +particular command handling and encoding constraints by generating a response of a given size. + +This command SHALL use the same EnableKey behavior as the TestEventTrigger command, whereby +processing of the command is only enabled when the TestEventTriggersEnabled field is true, which +SHALL NOT be true outside of certification testing or manufacturer’s internal tests. + +The fields for the PayloadTestRequest command are as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0x00 EnableKey octstr 16 M +0x01 Value uint8 M +0x02 Count uint16 max 2048 M +``` +**EnableKey field** + +This field SHALL have the same meaning and usage as the TestEventTrigger EnableKey field. + +**Value field** + +This field SHALL indicate the value to use in every byte of the PayloadTestResponse’s Payload field. + +**Count field** + +This field SHALL indicate the number of times to repeat the Value in the PayloadTestResponse’s +Payload field. + +**Effect upon receipt** + +This command SHALL respond with a response status of CONSTRAINT_ERROR if either: + +- The EnableKey field does not match the a-priori value configured on the device. +- The TestEventTriggersEnabled field is currently false. + +Otherwise, the server SHALL respond with a PayloadTestResponse command with a Payload field +value containing Count instances of the Value byte. If the response is too large to send, the server +SHALL fail the command and respond with a response status of RESOURCE_EXHAUSTED. + +For example: + +- If Value is 0x55 and the Count is zero, then the PayloadTestResponse would have the Payload + field set to an empty octet string. +- If Value is 0xA5 and the Count is 10, the PayloadTestResponse would have the Payload field set + +``` +Page 832 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +to a content whose hexadecimal representation would be A5A5A5A5A5A5A5A5A5A5, and base64 rep­ +resentation would be paWlpaWlpaWlpQ==. +``` +**11.12.7.5. PayloadTestResponse Command** + +This command is sent by the server on receipt of the PayloadTestRequest command. + +This command SHALL have the following data fields: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0x00 Payload octstr max 2048 M +``` +**Payload Field** + +This field SHALL contain the computed response of the PayloadTestRequest command. + +**11.12.8. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 Hardware­ +FaultChange +``` +### CRITICAL V O + +``` +0x01 RadioFault­ +Change +``` +### CRITICAL V O + +``` +0x02 NetworkFault­ +Change +``` +### CRITICAL V O + +``` +0x03 BootReason CRITICAL V M +``` +**11.12.8.1. HardwareFaultChange Event** + +The HardwareFaultChange Event SHALL indicate a change in the set of hardware faults currently +detected by the Node. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Current list[Hard­ +wareFault­ +Enum] +``` +``` +max 11 M +``` +``` +1 Previous list[Hard­ +wareFault­ +Enum] +``` +``` +max 11 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 833 +``` + +**Current Field** + +This field SHALL represent the set of faults currently detected, as per HardwareFaultEnum. + +**Previous Field** + +This field SHALL represent the set of faults detected prior to this change event, as per Hardware­ +FaultEnum. + +**11.12.8.2. RadioFaultChange Event** + +The RadioFaultChange Event SHALL indicate a change in the set of radio faults currently detected +by the Node. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Current list[Radio­ +FaultEnum] +``` +``` +max 7 M +``` +``` +1 Previous list[Radio­ +FaultEnum] +``` +``` +max 7 M +``` +**Current Field** + +This field SHALL represent the set of faults currently detected, as per RadioFaultEnum. + +**Previous Field** + +This field SHALL represent the set of faults detected prior to this change event, as per RadioFault­ +Enum. + +**11.12.8.3. NetworkFaultChange Event** + +The NetworkFaultChange Event SHALL indicate a change in the set of network faults currently +detected by the Node. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Current list[Network­ +FaultEnum] +``` +``` +max 4 M +``` +``` +1 Previous list[Network­ +FaultEnum] +``` +``` +max 4 M +``` +**Current Field** + +This field SHALL represent the set of faults currently detected, as per NetworkFaultEnum. + +``` +Page 834 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Previous Field** + +This field SHALL represent the set of faults detected prior to this change event, as per Network­ +FaultEnum. + +**11.12.8.4. BootReason Event** + +The BootReason Event SHALL indicate the reason that caused the device to start-up. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 BootReason BootReaso­ +nEnum +``` +### M + +**BootReason Field** + +This field SHALL contain the reason for this BootReason event. + +**11.13. Software Diagnostics Cluster** + +The Software Diagnostics Cluster provides a means to acquire standardized diagnostics metrics that +MAY be used by a Node to assist a user or Administrator in diagnosing potential problems. The Soft­ +ware Diagnostics Cluster attempts to centralize all metrics that are relevant to the software that +may be running on a Node. + +**11.13.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.13.2. Classification** + +``` +Hierarchy Role Scope PICS Code Quality +Base Utility Node DGSW K +``` +**11.13.3. Cluster ID** + +``` +ID Name +0x0034 Software Diagnostics +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 835 +``` + +**11.13.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 WTRMRK Watermarks Node makes available +the metrics for high +watermark related to +memory consumption. +``` +**11.13.5. Data Types** + +**11.13.5.1. ThreadMetricsStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ID uint64 all M +1 Name string max 8 empty O +2 Stack­ +FreeCur­ +rent +``` +``` +uint32 all MS O +``` +``` +3 Stack­ +FreeMini­ +mum +``` +``` +uint32 all MS O +``` +``` +4 StackSize uint32 all MS O +``` +**ID Field** + +The Id field SHALL be a server-assigned per-thread unique ID that is constant for the duration of +the thread. Efforts SHOULD be made to avoid reusing ID values when possible. + +**Name Field** + +The Name field SHALL be set to a vendor defined name or prefix of the software thread that is sta­ +tic for the duration of the thread. + +**StackFreeCurrent Field** + +The StackFreeCurrent field SHALL indicate the current amount of stack memory, in bytes, that are +not being utilized on the respective thread. + +**StackFreeMinimum Field** + +The StackFreeMinimum field SHALL indicate the minimum amount of stack memory, in bytes, that +has been available at any point between the current time and this attribute being reset or initial­ +ized on the respective thread. This value SHALL only be reset upon a Node reboot or upon receiv­ +ing of the ResetWatermarks command. + +``` +Page 836 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**StackSize Field** + +The StackSize field SHALL indicate the amount of stack memory, in bytes, that has been allocated +for use by the respective thread. + +**11.13.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Thread­ +Metrics +``` +``` +list[Thread +Metric­ +sStruct] +``` +``` +max 64 R V O +``` +``` +0x0001 Cur­ +rentHeapF +ree +``` +``` +uint64 R V O +``` +``` +0x0002 Cur­ +rentHea­ +pUsed +``` +``` +uint64 R V O +``` +``` +0x0003 Cur­ +rentHeap +HighWa­ +termark +``` +``` +uint64 R V WTRMRK +``` +**11.13.6.1. ThreadMetrics Attribute** + +The ThreadMetrics attribute SHALL be a list of ThreadMetricsStruct structs. Each active thread on +the Node SHALL be represented by a single entry within the ThreadMetrics attribute. + +**11.13.6.2. CurrentHeapFree Attribute** + +The CurrentHeapFree attribute SHALL indicate the current amount of heap memory, in bytes, that +are free for allocation. The effective amount MAY be smaller due to heap fragmentation or other +reasons. + +**11.13.6.3. CurrentHeapUsed Attribute** + +The CurrentHeapUsed attribute SHALL indicate the current amount of heap memory, in bytes, that +is being used. + +**11.13.6.4. CurrentHeapHighWatermark Attribute** + +The CurrentHeapHighWatermark attribute SHALL indicate the maximum amount of heap memory, +in bytes, that has been used by the Node. This value SHALL only be reset upon a Node reboot or +upon receiving of the ResetWatermarks command. + +**11.13.7. Commands** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 837 +``` + +``` +ID Name Direction Response Access Conformance +0x00 ResetWater­ +marks +``` +``` +client ⇒ server Y M WTRMRK +``` +**11.13.7.1. ResetWatermarks Command** + +Receipt of this command SHALL reset the following values which track high and lower watermarks: + +- The StackFreeMinimum field of the ThreadMetrics attribute +- The CurrentHeapHighWatermark attribute + +This command has no payload. + +**Effect on Receipt** + +On receipt of this command, the Node SHALL make the following modifications to attributes it sup­ +ports: + +If implemented, the server SHALL set the value of the CurrentHeapHighWatermark attribute to the +value of the CurrentHeapUsed attribute. + +If implemented, the server SHALL set the value of the StackFreeMinimum field for every thread to +the value of the corresponding thread’s StackFreeCurrent field. + +**11.13.8. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 SoftwareFault INFO V O +``` +**11.13.8.1. SoftwareFault Event** + +The SoftwareFault Event SHALL be generated when a software fault takes place on the Node. + +The event’s data are as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ID uint64 all 0 M +1 Name string max 8 empty O +2 Fault­ +Recording +``` +``` +octstr max 1024 empty O +``` +**ID Field** + +The ID field SHALL be set to the ID of the software thread in which the last software fault occurred. + +``` +Page 838 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Name Field** + +The Name field SHALL be set to a manufacturer-specified name or prefix of the software thread in +which the last software fault occurred. + +**FaultRecording Field** + +The FaultRecording field SHALL be a manufacturer-specified payload intended to convey informa­ +tion to assist in further diagnosing or debugging a software fault. The FaultRecording field MAY be +used to convey information such as, but not limited to, thread backtraces or register contents. + +**11.14. Thread Network Diagnostics Cluster** + +The Thread Network Diagnostics Cluster provides a means to acquire standardized diagnostics met­ +rics that MAY be used by a Node to assist a user or Administrator in diagnosing potential problems. +The Thread Network Diagnostics Cluster attempts to centralize all metrics that are relevant to a +potential Thread radio running on a Node. + +**11.14.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Remove optionality from FrameErrorRate and +MessageErrorRate +3 Add ExtAddress and Rloc16 attributes +``` +**11.14.2. Classification** + +``` +Hierarchy Role Scope PICS Code Quality +Base Utility Node DGTHREAD K +``` +**11.14.3. Cluster ID** + +``` +ID Name +0x0035 Thread Network Diagnostics +``` +**11.14.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 839 +``` + +``` +Bit Code Feature Summary +0 PKTCNT PacketCounts Server supports the +counts for the number +of received and trans­ +mitted packets on the +Thread interface. +1 ERRCNT ErrorCounts Server supports the +counts for the number +of errors that have +occurred during the +reception and transmis­ +sion of packets on the +Thread interface. +2 MLECNT MLECounts Server supports the +counts for various MLE +layer happenings. +3 MACCNT MACCounts Server supports the +counts for various MAC +layer happenings. +``` +**11.14.5. Data Types** + +**11.14.5.1. NetworkFaultEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified Indicates an unspeci­ +fied fault. +``` +### M + +``` +1 LinkDown Indicates the Thread +link is down. +``` +### M + +``` +2 HardwareFailure Indicates there has +been Thread hardware +failure. +``` +### M + +``` +3 NetworkJammed Indicates the Thread +network is jammed. +``` +### M + +**11.14.5.2. ConnectionStatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Connected Node is connected M +1 NotConnected Node is not connected M +``` +``` +Page 840 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.14.5.3. RoutingRoleEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified Unspecified routing +role. +``` +### M + +``` +1 Unassigned The Node does not cur­ +rently have a role as a +result of the Thread +interface not currently +being configured or +operational. +``` +### M + +``` +2 SleepyEndDevice The Node acts as a +Sleepy End Device with +RX-off-when-idle sleepy +radio behavior. +``` +### M + +``` +3 EndDevice The Node acts as an +End Device without RX- +off-when-idle sleepy +radio behavior. +``` +### M + +``` +4 REED The Node acts as an +Router Eligible End +Device. +``` +### M + +``` +5 Router The Node acts as a +Router Device. +``` +### M + +``` +6 Leader The Node acts as a +Leader Device. +``` +### M + +**11.14.5.4. NeighborTableStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ExtAd­ +dress +``` +``` +uint64 all M +``` +``` +1 Age uint32 all M +2 Rloc16 uint16 all M +3 Link­ +Frame­ +Counter +``` +``` +uint32 all M +``` +``` +4 MleFrame­ +Counter +``` +``` +uint32 all M +``` +``` +5 LQI uint8 0 to 255 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 841 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +6 Aver­ +ageRssi +``` +``` +int8 -128 to 0 X null M +``` +``` +7 LastRssi int8 -128 to 0 X null M +8 FrameEr­ +rorRate +``` +``` +uint8 0 to 100 0 M +``` +``` +9 Mes­ +sageError­ +Rate +``` +``` +uint8 0 to 100 0 M +``` +``` +10 RxOn­ +WhenIdle +``` +``` +bool all M +``` +``` +11 FullThrea +dDevice +``` +``` +bool all M +``` +``` +12 FullNet­ +workData +``` +``` +bool all M +``` +``` +13 IsChild bool all M +``` +**ExtAddress Field** + +This field SHALL specify the IEEE 802.15.4 extended address for the neighboring Node. + +**Age Field** + +This field SHALL specify the duration of time, in seconds, since a frame has been received from the +neighboring Node. + +**Rloc16 Field** + +This field SHALL specify the RLOC16 of the neighboring Node. + +**LinkFrameCounter Field** + +This field SHALL specify the number of link layer frames that have been received from the neigh­ +boring node. This field SHALL be reset to 0 upon a reboot of the Node. + +**MleFrameCounter Field** + +This field SHALL specify the number of Mesh Link Establishment frames that have been received +from the neighboring node. This field SHALL be reset to 0 upon a reboot of the Node. + +**LQI Field** + +This field SHALL specify the implementation specific mix of IEEE 802.15.4 PDU receive quality indi­ +cators, scaled from 0 to 255. + +``` +Page 842 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**AverageRssi Field** + +This field SHOULD specify the average RSSI across all received frames from the neighboring Node +since the receiving Node’s last reboot. If there is no known received frames this field SHOULD have +the value of null. This field SHALL have the units of dBm, having the range -128 dBm to 0 dBm. + +**LastRssi Field** + +This field SHALL specify the RSSI of the most recently received frame from the neighboring Node. If +there is no known last received frame the LastRssi field SHOULD have the value of null. This field +SHALL have the units of dBm, having the range -128 dBm to 0 dBm. + +**FrameErrorRate Field** + +This field SHALL specify the percentage of received frames from the neighboring Node that have +resulted in errors. + +**MessageErrorRate Field** + +This field SHALL specify the percentage of received messages from the neighboring Node that have +resulted in errors. + +**RxOnWhenIdle Field** + +This field SHALL specify if the neighboring Node is capable of receiving frames while the Node is in +an idle state. + +**FullThreadDevice Field** + +This field SHALL specify if the neighboring Node is a full Thread device. + +**FullNetworkData Field** + +This field SHALL specify if the neighboring Node requires the full Network Data. If set to False, the +neighboring Node only requires the stable Network Data. + +**IsChild Field** + +This field SHALL specify if the neighboring Node is a direct child of the Node reporting the Neigh­ +borTable attribute. + +**11.14.5.5. RouteTableStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ExtAd­ +dress +``` +``` +uint64 M +``` +``` +1 Rloc16 uint16 M +2 RouterId uint8 M +3 NextHop uint8 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 843 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +4 PathCost uint8 M +5 LQIIn uint8 M +6 LQIOut uint8 M +7 Age uint8 M +8 Allocated bool M +9 LinkEstab­ +lished +``` +``` +bool M +``` +**ExtAddress Field** + +This field SHALL specify the IEEE 802.15.4 extended address for the Node for which this route table +entry corresponds. + +**Rloc16 Field** + +This field SHALL specify the RLOC16 for the Node for which this route table entry corresponds. + +**RouterId Field** + +This field SHALL specify the Router ID for the Node for which this route table entry corresponds. + +**NextHop Field** + +This field SHALL specify the Router ID for the next hop in the route to the Node for which this route +table entry corresponds. + +**PathCost Field** + +This Field SHALL specify the cost of the route to the Node for which this route table entry corre­ +sponds. + +**LQIIn Field** + +This field SHALL specify the implementation specific mix of IEEE 802.15.4 PDU receive quality indi­ +cators, scaled from 0 to 255, from the perspective of the Node reporting the neighbor table. + +**LQIOut Field** + +This field SHALL specify the implementation specific mix of IEEE 802.15.4 PDU receive quality indi­ +cators, scaled from 0 to 255, from the perspective of the Node specified within the NextHop field. + +**Age Field** + +This field SHALL specify the duration of time, in seconds, since a frame has been received from the +Node for which this route table entry corresponds. + +``` +Page 844 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Allocated Field** + +This field SHALL specify if the router ID as defined within the RouterId field has been allocated. + +**LinkEstablished Field** + +This field SHALL specify if a link has been established to the Node for which this route table entry +corresponds. + +**11.14.5.6. SecurityPolicy Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Rotation­ +Time +``` +``` +uint16 M +``` +``` +1 Flags uint16 M +``` +**RotationTime Field** + +This field SHALL specify the interval of time, in hours, that Thread security keys are rotated. This +attribute SHALL be null when there is no dataset configured. + +**Flags Field** + +This field SHALL specify the flags as specified in Thread 1.3.0 section 8.10.1.15. This attribute SHALL +be null when there is no dataset configured. + +**11.14.5.7. OperationalDatasetComponents Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Active­ +Time­ +stampPre­ +sent +``` +``` +bool M +``` +``` +1 Pending­ +Time­ +stampPre­ +sent +``` +``` +bool M +``` +``` +2 Mas­ +terKeyPre­ +sent +``` +``` +bool M +``` +``` +3 Network­ +NamePre­ +sent +``` +``` +bool M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 845 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +4 Extended­ +PanIdPre­ +sent +``` +``` +bool M +``` +``` +5 MeshLo­ +calPrefix­ +Present +``` +``` +bool M +``` +``` +6 DelayPre­ +sent +``` +``` +bool M +``` +``` +7 PanIdPre­ +sent +``` +``` +bool M +``` +``` +8 ChannelP­ +resent +``` +``` +bool M +``` +``` +9 PskcPre­ +sent +``` +``` +bool M +``` +``` +10 Security­ +PolicyPre­ +sent +``` +``` +bool M +``` +``` +11 Channel­ +MaskPre­ +sent +``` +``` +bool M +``` +**ActiveTimestampPresent Field** + +This field SHALL be True if the Node has an active timestamp present, else False. + +**PendingTimestampPresent Field** + +This field SHALL be True if the Node has a pending timestamp is present, else False. + +**MasterKeyPresent Field** + +This field SHALL be True if the Node has the Thread master key, else False. + +**NetworkNamePresent Field** + +This field SHALL be True if the Node has the Thread network’s name, else False. + +**ExtendedPanIdPresent Field** + +This field SHALL be True if the Node has an extended Pan ID, else False. + +**MeshLocalPrefixPresent Field** + +This field SHALL be True if the Node has the mesh local prefix, else False. + +``` +Page 846 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**DelayPresent Field** + +This field SHALL be True if the Node has the Thread network delay set, else False. + +**PanIdPresent Field** + +This field SHALL be True if the Node has a Pan ID, else False. + +**ChannelPresent Field** + +This field SHALL be True if the Node has configured an operational channel for the Thread net­ +work, else False. + +**PskcPresent Field** + +This field SHALL be True if the Node has been configured with the Thread network Pskc, else False. + +**SecurityPolicyPresent Field** + +This field SHALL be True if the Node has been configured with the Thread network security poli­ +cies, else False. + +**ChannelMaskPresent Field** + +This field SHALL be True if the Node has available a mask of available channels, else False. + +**11.14.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Channel uint16 all X R V M +0x0001 Routing­ +Role +``` +``` +Routin­ +gRoleEnum +``` +``` +all X R V M +``` +``` +0x0002 Network­ +Name +``` +``` +String max 16 X R V M +``` +``` +0x0003 PanId uint16 all X R V M +0x0004 Extended­ +PanId +``` +``` +uint64 all X R V M +``` +``` +0x0005 MeshLo­ +calPrefix +``` +``` +ipv6pre all X R V M +``` +``` +0x0006 Overrun­ +Count +``` +``` +uint64 all C 0 R V ERRCNT +``` +``` +0x0007 Neigh­ +borTable +``` +``` +list[Neigh­ +borTa­ +bleStruct] +``` +``` +all [] R V M +``` +``` +0x0008 RouteTabl +e +``` +``` +list[RouteT +ableStruct] +``` +``` +all [] R V M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 847 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0009 Parti­ +tionId +``` +``` +uint32 all X R V M +``` +``` +0x000A Weighting uint16 max 255 X R V M +0x000B DataVer­ +sion +``` +``` +uint16 max 255 X R V M +``` +``` +0x000C Stable­ +DataVer­ +sion +``` +``` +uint16 max 255 X R V M +``` +``` +0x000D Leader­ +RouterId +``` +``` +uint8 max 62 X R V M +``` +``` +0x000E DetachedR +oleCount +``` +``` +uint16 all C 0 R V [MLECNT] +``` +``` +0x000F ChildRole­ +Count +``` +``` +uint16 all C 0 R V [MLECNT] +``` +``` +0x0010 Router­ +RoleCount +``` +``` +uint16 all C 0 R V [MLECNT] +``` +``` +0x0011 Leader­ +RoleCount +``` +``` +uint16 all C 0 R V [MLECNT] +``` +``` +0x0012 AttachAt­ +tempt­ +Count +``` +``` +uint16 all C 0 R V [MLECNT] +``` +``` +0x0013 Partition­ +IdChange­ +Count +``` +``` +uint16 all C 0 R V [MLECNT] +``` +``` +0x0014 BetterPar­ +titionAt­ +tachAt­ +tempt­ +Count +``` +``` +uint16 all C 0 R V [MLECNT] +``` +``` +0x0015 Par­ +entChange +Count +``` +``` +uint16 all C 0 R V [MLECNT] +``` +``` +0x0016 TxTotal­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0017 TxUnicast­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0018 TxBroad­ +castCount +``` +``` +uint32 all C 0 R V [MACCNT] +``` +Page 848 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**ID Name Type Constraint Quality Default Access Confor­ +mance** + +0x0019 **TxAckRe­ +quested­ +Count** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x001A **TxAcked­ +Count** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x001B **TxNoAck­ +Request­ +edCount** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x001C **TxData­ +Count** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x001D **TxDat­ +aPoll­ +Count** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x001E **TxBeacon­ +Count** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x001F **TxBeacon­ +Request­ +Count** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x0020 **TxOther­ +Count** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x0021 **TxRetryCo +unt** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x0022 **TxDirect­ +MaxRetry­ +Ex­ +piryCount** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x0023 **TxIndi­ +rect­ +MaxRetry­ +Ex­ +piryCount** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x0024 **TxErrCca­ +Count** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x0025 **TxErrAbo +rtCount** + +``` +uint32 all C 0 R V [MACCNT] +``` +0x0026 **TxEr­ +rBusy­ +Channel­ +Count** + +``` +uint32 all C 0 R V [MACCNT] +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 849 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0027 RxTotal­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0028 RxUnicast­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0029 RxBroad­ +castCount +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x002A RxData­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x002B RxDat­ +aPoll­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x002C RxBeacon­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x002D RxBeacon­ +Request­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x002E RxOther­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x002F RxAd­ +dressFil­ +tered­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0030 RxDestAd­ +drFil­ +tered­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0031 RxDupli­ +cated­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0032 RxEr­ +rNoFrame +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0033 RxErrUnk­ +nown­ +Neighbor­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0034 RxErrIn­ +validSr­ +cAddr­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +Page 850 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0035 RxErrSec­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0036 RxErrFc­ +sCount +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0037 RxEr­ +rOther­ +Count +``` +``` +uint32 all C 0 R V [MACCNT] +``` +``` +0x0038 Active­ +Time­ +stamp +``` +``` +uint64 all X 0 R V O +``` +``` +0x0039 Pending­ +Time­ +stamp +``` +``` +uint64 all X 0 R V O +``` +``` +0x003A Delay uint32 all X 0 R V O +0x003B Security­ +Policy +``` +``` +Security­ +Policy +``` +### X R V M + +``` +0x003C Channel­ +Page0­ +Mask +``` +``` +octstr 4 X R V M +``` +``` +0x003D Opera­ +tional­ +Dataset­ +Compo­ +nents +``` +``` +Opera­ +tional­ +Dataset­ +Compo­ +nents +``` +### X R V M + +``` +0x003E ActiveNet­ +work­ +FaultsList +``` +``` +list[Net­ +workFault­ +Enum] +``` +``` +max 4 R V M +``` +``` +0x003F ExtAd­ +dress +``` +``` +uint64 all X R V P, M +``` +``` +0x0040 Rloc16 uint16 all X R V P, M +``` +**11.14.6.1. Channel Attribute** + +The Channel attribute SHALL indicate the 802.15.4 channel number configured on the Node’s +Thread interface (that is, the Active Operational Dataset’s current Channel value). A value of null +SHALL indicate that the Thread interface is not currently configured or operational. + +**11.14.6.2. RoutingRole Attribute** + +The RoutingRole attribute SHALL indicate the role that this Node has within the routing of mes­ +sages through the Thread network, as defined by RoutingRoleEnum. The potential roles are defined + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 851 +``` + +in the following table. A value of null SHALL indicate that the Thread interface is not currently con­ +figured or operational. + +**11.14.6.3. NetworkName Attribute** + +The NetworkName attribute SHALL indicate a human-readable (displayable) name for the Thread +network that the Node has been configured to join to. A value of null SHALL indicate that the +Thread interface is not currently configured or operational. + +**11.14.6.4. PanId Attribute** + +The PanId attribute SHALL indicate the 16-bit identifier of the Node on the Thread network. A value +of null SHALL indicate that the Thread interface is not currently configured or operational. + +**11.14.6.5. ExtendedPanId Attribute** + +The ExtendedPanId attribute SHALL indicate the unique 64-bit identifier of the Node on the Thread +network. A value of null SHALL indicate that the Thread interface is not currently configured or +operational. + +**11.14.6.6. MeshLocalPrefix Attribute** + +The MeshLocalPrefix attribute SHALL indicate the mesh-local IPv6 prefix for the Thread network +that the Node has been configured to join to. A value of null SHALL indicate that the Thread inter­ +face is not currently configured or operational. + +**11.14.6.7. OverrunCount Attribute** + +The OverrunCount attribute SHALL indicate the number of packets dropped either at ingress or +egress, due to lack of buffer memory to retain all packets on the ethernet network interface. The +OverrunCount attribute SHALL be reset to 0 upon a reboot of the Node. + +**11.14.6.8. NeighborTable Attribute** + +The NeighborTable attribute SHALL indicate the current list of Nodes that comprise the neighbor +table on the Node. + +**11.14.6.9. RouteTable Attribute** + +The RouteTable attribute SHALL indicate the current list of router capable Nodes for which routes +have been established. + +**11.14.6.10. PartitionId Attribute** + +The PartitionId attribute SHALL indicate the Thread Leader Partition Id for the Thread network to +which the Node is joined. This attribute SHALL be null if not attached to a Thread network. + +**11.14.6.11. Weighting Attribute** + +The Weighting attribute SHALL indicate the Thread Leader Weight used when operating in the +Leader role. This attribute SHALL be null if not attached to a Thread network. + +``` +Page 852 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.14.6.12. DataVersion Attribute** + +The DataVersion attribute SHALL indicate the full Network Data Version the Node currently uses. +This attribute SHALL be null if not attached to a Thread network. + +**11.14.6.13. StableDataVersion Attribute** + +The StableDataVersion attribute SHALL indicate the Network Data Version for the stable subset of +data the Node currently uses. This attribute SHALL be null if not attached to a Thread network. + +**11.14.6.14. LeaderRouterId Attribute** + +The LeaderRouterId attribute SHALL indicate the 8-bit LeaderRouterId the Node SHALL attempt to +utilize upon becoming a router or leader on the Thread network. This attribute SHALL be null if not +attached to a Thread network. + +**11.14.6.15. DetachedRoleCount Attribute** + +The DetachedRoleCount attribute SHALL indicate the number of times the Node entered the OT_DE­ +VICE_ROLE_DETACHED role as specified within the Thread specification. This value SHALL only be +reset upon a Node reboot. + +**11.14.6.16. ChildRoleCount Attribute** + +The ChildRoleCount attribute SHALL indicate the number of times the Node entered the OT_DE­ +VICE_ROLE_CHILD role as specified within the Thread specification. This value SHALL only be reset +upon a Node reboot. + +**11.14.6.17. RouterRoleCount Attribute** + +The RouterRoleCount attribute SHALL indicate the number of times the Node entered the OT_DE­ +VICE_ROLE_ROUTER role as specified within the Thread specification. This value SHALL only be +reset upon a Node reboot. + +**11.14.6.18. LeaderRoleCount Attribute** + +The LeaderRoleCount attribute SHALL indicate the number of times the Node entered the OT_DE­ +VICE_ROLE_LEADER role as specified within the Thread specification. This value SHALL only be +reset upon a Node reboot. + +**11.14.6.19. AttachAttemptCount Attribute** + +The AttachAttemptCount attribute SHALL indicate the number of attempts that have been made to +attach to a Thread network while the Node was detached from all Thread networks. This value +SHALL only be reset upon a Node reboot. + +**11.14.6.20. PartitionIdChangeCount Attribute** + +The PartitionIdChangeCount attribute SHALL indicate the number of times that the Thread net­ +work that the Node is connected to has changed its Partition ID. This value SHALL only be reset +upon a Node reboot. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 853 +``` + +**11.14.6.21. BetterPartitionAttachAttemptCount Attribute** + +The BetterPartitionAttachAttemptCount attribute SHALL indicate the number of times a Node has +attempted to attach to a different Thread partition that it has determined is better than the parti­ +tion it is currently attached to. This value SHALL only be reset upon a Node reboot. + +**11.14.6.22. ParentChangeCount Attribute** + +The ParentChangeCount attribute SHALL indicate the number of times a Node has changed its par­ +ent. This value SHALL only be reset upon a Node reboot. + +**11.14.6.23. TxTotalCount Attribute** + +The TxTotalCount attribute SHALL indicate the total number of unique MAC frame transmission +requests. The TxTotalCount attribute SHALL only be incremented by 1 for each MAC transmission +request regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions. This value +SHALL only be reset upon a Node reboot. + +**11.14.6.24. TxUnicastCount Attribute** + +The TxUnicastCount attribute SHALL indicate the total number of unique unicast MAC frame trans­ +mission requests. The TxUnicastCount attribute SHALL only be incremented by 1 for each unicast +MAC transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or retrans­ +missions. This value SHALL only be reset upon a Node reboot. + +**11.14.6.25. TxBroadcastCount Attribute** + +The TxBroadcastCount attribute SHALL indicate the total number of unique broadcast MAC frame +transmission requests. The TxBroadcastCount attribute SHALL only be incremented by 1 for each +broadcast MAC transmission request regardless of the amount of CCA failures, CSMA-CA attempts, +or retransmissions. This value SHALL only be reset upon a Node reboot. + +**11.14.6.26. TxAckRequestedCount Attribute** + +The TxAckRequestedCount attribute SHALL indicate the total number of unique MAC frame trans­ +mission requests with requested acknowledgment. The TxAckRequestedCount attribute SHALL only +be incremented by 1 for each MAC transmission request with requested acknowledgment regard­ +less of the amount of CCA failures, CSMA-CA attempts, or retransmissions. This value SHALL only +be reset upon a Node reboot. + +**11.14.6.27. TxAckedCount Attribute** + +The TxAckedCount attribute SHALL indicate the total number of unique MAC frame transmission +requests that were acked. The TxAckedCount attribute SHALL only be incremented by 1 for each +MAC transmission request that is acked regardless of the amount of CCA failures, CSMA-CA +attempts, or retransmissions. This value SHALL only be reset upon a Node reboot. + +**11.14.6.28. TxNoAckRequestedCount Attribute** + +The TxNoAckRequestedCount attribute SHALL indicate the total number of unique MAC frame + +``` +Page 854 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +transmission requests without requested acknowledgment. The TxNoAckRequestedCount attribute +SHALL only be incremented by 1 for each MAC transmission request that is does not request +acknowledgement regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions. + +**11.14.6.29. TxDataCount Attribute** + +The TxDataCount attribute SHALL indicate the total number of unique MAC Data frame transmis­ +sion requests. The TxDataCount attribute SHALL only be incremented by 1 for each MAC Data +frame transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or +retransmissions. This value SHALL only be reset upon a Node reboot. + +**11.14.6.30. TxDataPollCount Attribute** + +The TxDataPollCount attribute SHALL indicate the total number of unique MAC Data Poll frame +transmission requests. The TxDataPollCount attribute SHALL only be incremented by 1 for each +MAC Data Poll frame transmission request regardless of the amount of CCA failures, CSMA-CA +attempts, or retransmissions. This value SHALL only be reset upon a Node reboot. + +**11.14.6.31. TxBeaconCount Attribute** + +The TxBeaconCount attribute SHALL indicate the total number of unique MAC Beacon frame trans­ +mission requests. The TxBeaconCount attribute SHALL only be incremented by 1 for each MAC Bea­ +con frame transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or +retransmissions. + +**11.14.6.32. TxBeaconRequestCount Attribute** + +The TxBeaconRequestCount attribute SHALL indicate the total number of unique MAC Beacon +Request frame transmission requests. The TxBeaconRequestCount attribute SHALL only be incre­ +mented by 1 for each MAC Beacon Request frame transmission request regardless of the amount of +CCA failures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node +reboot. + +**11.14.6.33. TxOtherCount Attribute** + +The TxOtherCount attribute SHALL indicate the total number of unique MAC frame transmission +requests that are not counted by any other attribute. The TxOtherCount attribute SHALL only be +incremented by 1 for each MAC frame transmission request regardless of the amount of CCA fail­ +ures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node reboot. + +**11.14.6.34. TxRetryCount Attribute** + +The TxRetryCount attribute SHALL indicate the total number of MAC retransmission attempts. The +TxRetryCount attribute SHALL only be incremented by 1 for each retransmission attempt that may +be triggered by lack of acknowledgement, CSMA/CA failure, or other type of transmission error. +This value SHALL only be reset upon a Node reboot. + +**11.14.6.35. TxDirectMaxRetryExpiryCount Attribute** + +The TxDirectMaxRetryExpiryCount attribute SHALL indicate the total number of unique MAC + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 855 +``` + +transmission packets that meet maximal retry limit for direct packets. The TxDirectMaxRetryEx­ +piryCount attribute SHALL only be incremented by 1 for each unique MAC transmission packets +that meets the maximal retry limit for direct packets. This value SHALL only be reset upon a Node +reboot. + +**11.14.6.36. TxIndirectMaxRetryExpiryCount Attribute** + +The TxIndirectMaxRetryExpiryCount attribute SHALL indicate the total number of unique MAC +transmission packets that meet maximal retry limit for indirect packets. The TxIndirectMaxRetry­ +ExpiryCount attribute SHALL only be incremented by 1 for each unique MAC transmission packets +that meets the maximal retry limit for indirect packets. This value SHALL only be reset upon a +Node reboot. + +**11.14.6.37. TxErrCcaCount Attribute** + +The TxErrCcaCount attribute SHALL indicate the total number of CCA failures. The TxErrCcaCount +attribute SHALL only be incremented by 1 for each instance of a CCA failure. This value SHALL only +be reset upon a Node reboot. + +**11.14.6.38. TxErrAbortCount Attribute** + +The TxErrAbortCount attribute SHALL indicate the total number of unique MAC transmission +request failures caused by an abort error. The TxErrAbortCount attribute SHALL only be incre­ +mented by 1 for each unique MAC transmission request failure caused by an abort error. + +**11.14.6.39. TxErrBusyChannelCount Attribute** + +The TxErrBusyChannelCount attribute SHALL indicate the total number of unique MAC transmis­ +sion request failures caused by an error as the result of a busy channel (a CSMA/CA fail). The TxEr­ +rBusyChannelCount attribute SHALL only be incremented by 1 for each unique MAC transmission +request failure caused by a busy channel such as a CSMA/CA failure. + +**11.14.6.40. RxTotalCount Attribute** + +The RxTotalCount attribute SHALL indicate the total number of received unique MAC frames. This +value SHALL only be reset upon a Node reboot. + +**11.14.6.41. RxUnicastCount Attribute** + +The RxUnicastCount attribute SHALL indicate the total number of received unique unicast MAC +frames. This value SHALL only be reset upon a Node reboot. + +**11.14.6.42. RxBroadcastCount Attribute** + +The RxBroadcastCount attribute SHALL indicate the total number of received unique broadcast +MAC frames. This value SHALL only be reset upon a Node reboot. + +**11.14.6.43. RxDataCount Attribute** + +The RxDataCount attribute SHALL indicate the total number of received unique MAC Data frames. + +``` +Page 856 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +This value SHALL only be reset upon a Node reboot. + +**11.14.6.44. RxDataPollCount Attribute** + +The RxDataPollCount attribute SHALL indicate the total number of received unique MAC Data Poll +frames. This value SHALL only be reset upon a Node reboot. + +**11.14.6.45. RxBeaconCount Attribute** + +The RxBeaconCount attribute SHALL indicate the total number of received unique MAC Beacon +frames. This value SHALL only be reset upon a Node reboot. + +**11.14.6.46. RxBeaconRequestCount Attribute** + +The RxBeaconRequestCount attribute SHALL indicate the total number of received unique MAC +Beacon Request frames. This value SHALL only be reset upon a Node reboot. + +**11.14.6.47. RxOtherCount Attribute** + +The RxOtherCount attribute SHALL indicate the total number of received unique MAC frame +requests that are not counted by any other attribute. This value SHALL only be reset upon a Node +reboot. + +**11.14.6.48. RxAddressFilteredCount Attribute** + +The RxAddressFilteredCount attribute SHALL indicate the total number of received unique MAC +frame requests that have been dropped as a result of MAC filtering. This value SHALL only be reset +upon a Node reboot. + +**11.14.6.49. RxDestAddrFilteredCount Attribute** + +The RxDestAddrFilteredCount attribute SHALL indicate the total number of received unique MAC +frame requests that have been dropped as a result of a destination address check. This value SHALL +only be reset upon a Node reboot. + +**11.14.6.50. RxDuplicatedCount Attribute** + +The RxDuplicatedCount attribute SHALL indicate the total number of received MAC frame requests +that have been dropped as a result of being a duplicate of a previously received MAC frame request. +This value SHALL only be reset upon a Node reboot. + +**11.14.6.51. RxErrNoFrameCount Attribute** + +The RxErrNoFrameCount attribute SHALL indicate the total number of received unique MAC frame +requests that have been dropped as a result of missing or malformed frame contents. This value +SHALL only be reset upon a Node reboot. + +**11.14.6.52. RxErrUnknownNeighborCount Attribute** + +The RxErrUnknownNeighborCount attribute SHALL indicate the total number of received unique +MAC frame requests that have been dropped as a result of originating from an unknown neighbor + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 857 +``` + +device. This value SHALL only be reset upon a Node reboot. + +**11.14.6.53. RxErrInvalidSrcAddrCount Attribute** + +The RxErrInvalidSrcAddrCount attribute SHALL indicate the total number of received unique MAC +frame requests that have been dropped as a result of containing an invalid source address. This +value SHALL only be reset upon a Node reboot. + +**11.14.6.54. RxErrSecCount Attribute** + +The RxErrSecCount attribute SHALL indicate the total number of received unique MAC frame +requests that have been dropped as a result of an error with the security of the received frame. This +value SHALL only be reset upon a Node reboot. + +**11.14.6.55. RxErrFcsCount Attribute** + +The RxErrFcsCount attribute SHALL indicate the total number of received unique MAC frame +requests that have been dropped as a result of an error with the FCS of the received frame. This +value SHALL only be reset upon a Node reboot. + +**11.14.6.56. RxErrOtherCount Attribute** + +The RxErrOtherCount attribute SHALL indicate the total number of received unique MAC frame +requests that have been dropped as a result of an error that is not counted by any other attribute. +This value SHALL only be reset upon a Node reboot. + +**11.14.6.57. ActiveTimestamp Attribute** + +This attribute SHALL be null when there is no dataset configured. + +**11.14.6.58. PendingTimestamp Attribute** + +This attribute SHALL be null when there is no dataset configured. + +**11.14.6.59. Delay Attribute** + +This attribute SHALL be null when there is no dataset configured. + +**11.14.6.60. SecurityPolicy Attribute** + +The SecurityPolicy attribute indicates the current security policies for the Thread partition to which +a Node is connected. This attribute SHALL be null when there is no dataset configured. + +**11.14.6.61. ChannelPage0Mask Attribute** + +The ChannelPage0Mask attribute indicates the channels within channel page 0, in the 2.4GHz ISM +band. The channels are represented in most significant bit order, with bit value 1 meaning selected, +bit value 0 meaning unselected. For example, the most significant bit of the left-most byte indicates +channel 0. If channel 0 and channel 10 are selected, the mask would be: 80 20 00 00. This attribute +SHALL be null when there is no dataset configured. + +``` +Page 858 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.14.6.62. OperationalDatasetComponents Attribute** + +The OperationalDatasetComponents attribute is a collection of flags to indicate the presence of vari­ +ous operationally acquired values. + +**11.14.6.63. ActiveNetworkFaults Attribute** + +The ActiveNetworkFaults attribute SHALL indicate the set of faults currently detected by the Node. +When the Node detects a fault has been raised, the appropriate NetworkFaultEnum value SHALL be +added to this list. This list SHALL NOT contain more than one instance of a specific NetworkFault­ +Enum value. When the Node detects that all conditions contributing to a fault has been cleared, the +corresponding NetworkFaultEnum value SHALL be removed from this list. An empty list SHALL +indicate there are currently no active faults. The order of this list SHOULD have no significance. +Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or they +MAY subscribe to NetworkFaultChange + +**ExtAddress Attribute** + +This attribute SHALL indicate the IEEE 802.15.4 extended address for the Node. A value of null +SHALL indicate that the extended address is not yet known. + +**Rloc16 Attribute** + +This attribute SHALL indicate the RLOC16 of the Node. A value of null SHALL indicate that the +Thread interface is not currently configured or operational. + +**11.14.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 ResetCounts client ⇒ server Y M ERRCNT +``` +**11.14.7.1. ResetCounts Command** + +Reception of this command SHALL reset the following attributes to 0: + +- OverrunCount + +This command has no associated data. Upon completion, this command SHALL send a status code +set to a value of SUCCESS back to the initiator. + +**11.14.8. Events** + +``` +ID Name Priority Access Conformance +0x00 ConnectionStatus INFO V O +0x01 NetworkFault­ +Change +``` +### INFO V O + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 859 +``` + +**11.14.8.1. NetworkFaultChange Event** + +The NetworkFaultChange Event SHALL indicate a change in the set of network faults currently +detected by the Node. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Current list[Network­ +FaultEnum] +``` +``` +max 4 M +``` +``` +1 Previous list[Network­ +FaultEnum] +``` +``` +max 4 M +``` +**Current Field** + +This field SHALL represent the set of faults currently detected, as per Section 11.14.5.1, “Network­ +FaultEnum Type”. + +**Previous Field** + +This field SHALL represent the set of faults detected prior to this change event, as per Section +11.14.5.1, “NetworkFaultEnum Type”. + +**11.14.8.2. ConnectionStatus Event** + +The ConnectionStatus Event SHALL indicate that a Node’s connection status to a Thread network +has changed. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Connection­ +Status +``` +``` +Connection­ +StatusEnum +``` +### M + +**11.15. Wi-Fi Network Diagnostics Cluster** + +The Wi-Fi Network Diagnostics Cluster provides a means to acquire standardized diagnostics met­ +rics that MAY be used by a Node to assist a user or Administrator in diagnosing potential problems. +The Wi-Fi Network Diagnostics Cluster attempts to centralize all metrics that are relevant to a +potential Wi-Fi radio running on a Node. + +**11.15.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +``` +Page 860 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.15.2. Classification** + +``` +Hierarchy Role Scope PICS Code Quality +Base Utility Node DGWIFI K +``` +**11.15.3. Cluster ID** + +``` +ID Name +0x0036 Wi-Fi Network Diagnostics +``` +**11.15.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 PKTCNT PacketCounts Node makes available +the counts for the num­ +ber of received and +transmitted packets on +the Wi-Fi interface. +1 ERRCNT ErrorCounts Node makes available +the counts for the num­ +ber of errors that have +occurred during the +reception and transmis­ +sion of packets on the +Wi-Fi interface. +``` +**11.15.5. Data Types** + +**11.15.5.1. SecurityTypeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unspecified Indicate the usage of an +unspecified Wi-Fi secu­ +rity type +``` +### M + +``` +1 None Indicate the usage of no +Wi-Fi security +``` +### M + +``` +2 WEP Indicate the usage of +WEP Wi-Fi security +``` +### M + +``` +3 WPA Indicate the usage of +WPA Wi-Fi security +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 861 +``` + +``` +Value Name Summary Conformance +4 WPA2 Indicate the usage of +WPA2 Wi-Fi security +``` +### M + +``` +5 WPA3 Indicate the usage of +WPA3 Wi-Fi security +``` +### M + +**11.15.5.2. WiFiVersionEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 a Indicate the network +interface is currently +using 802.11a against +the wireless access +point. +``` +### M + +``` +1 b Indicate the network +interface is currently +using 802.11b against +the wireless access +point. +``` +### M + +``` +2 g Indicate the network +interface is currently +using 802.11g against +the wireless access +point. +``` +### M + +``` +3 n Indicate the network +interface is currently +using 802.11n against +the wireless access +point. +``` +### M + +``` +4 ac Indicate the network +interface is currently +using 802.11ac against +the wireless access +point. +``` +### M + +``` +5 ax Indicate the network +interface is currently +using 802.11ax against +the wireless access +point. +``` +### M + +``` +Page 862 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +6 ah Indicate the network +interface is currently +using 802.11ah against +the wireless access +point. +``` +### M + +**11.15.5.3. AssociationFailureCauseEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown The reason for the fail­ +ure is unknown. +``` +### M + +``` +1 AssociationFailed An error occurred dur­ +ing association. +``` +### M + +``` +2 AuthenticationFailed An error occurred dur­ +ing authentication. +``` +### M + +``` +3 SsidNotFound The specified SSID +could not be found. +``` +### M + +**11.15.5.4. ConnectionStatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Connected Indicate the node is +connected +``` +### M + +``` +1 NotConnected Indicate the node is not +connected +``` +### M + +**11.15.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 BSSID octstr 6 X null R V M +0x0001 Security­ +Type +``` +``` +Security­ +TypeEnum +``` +``` +all X null R V M +``` +``` +0x0002 WiFiVer­ +sion +``` +``` +WiFiVer­ +sionEnum +``` +``` +all X null R V M +``` +``` +0x0003 Channel­ +Number +``` +``` +uint16 all X null R V M +``` +``` +0x0004 RSSI int8 -120 to 0 X C null R V M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 863 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0005 Beacon­ +LostCount +``` +``` +uint32 all X C 0 R V ERRCNT +``` +``` +0x0006 BeaconRx­ +Count +``` +``` +uint32 all X C 0 R V PKTCNT +``` +``` +0x0007 Packet­ +Multicas­ +tRxCount +``` +``` +uint32 all X C 0 R V PKTCNT +``` +``` +0x0008 Packet­ +Multicast­ +TxCount +``` +``` +uint32 all X C 0 R V PKTCNT +``` +``` +0x0009 PacketUni­ +castRx­ +Count +``` +``` +uint32 all X C 0 R V PKTCNT +``` +``` +0x000A PacketUni­ +castTx­ +Count +``` +``` +uint32 all X C 0 R V PKTCNT +``` +``` +0x000B Current­ +MaxRate +``` +``` +uint64 all X C 0 R V O +``` +``` +0x000C Overrun­ +Count +``` +``` +uint64 all X C 0 R V ERRCNT +``` +For all attributes listed above, a null value SHALL be returned if the interface is not currently con­ +figured or operational. + +**11.15.6.1. BSSID Attribute** + +The BSSID attribute SHALL indicate the BSSID for which the Wi-Fi network the Node is currently +connected. + +**11.15.6.2. SecurityType Attribute** + +The SecurityType attribute SHALL indicate the current type of Wi-Fi security used. + +**11.15.6.3. WiFiVersion Attribute** + +The WiFiVersion attribute SHALL indicate the current 802.11 standard version in use by the Node, +per the table below. + +**11.15.6.4. ChannelNumber Attribute** + +The ChannelNumber attribute SHALL indicate the channel that Wi-Fi communication is currently +operating on. + +``` +Page 864 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.15.6.5. RSSI Attribute** + +The RSSI attribute SHALL indicate the current RSSI of the Node’s Wi-Fi radio in dBm. + +**11.15.6.6. BeaconLostCount Attribute** + +The BeaconLostCount attribute SHALL indicate the count of the number of missed beacons the +Node has detected. If the Node does not have an ability to count beacons expected and not received, +this value MAY remain set to zero. + +**11.15.6.7. BeaconRxCount Attribute** + +The BeaconRxCount attribute SHALL indicate the count of the number of received beacons. The +total number of expected beacons that could have been received during the interval since associa­ +tion SHOULD match the sum of BeaconRxCount and BeaconLostCount. If the Node does not have an +ability to report count of beacons received, this value MAY remain set to zero. + +**11.15.6.8. PacketMulticastRxCount Attribute** + +The PacketMulticastRxCount attribute SHALL indicate the number of multicast packets received by +the Node. + +**11.15.6.9. PacketMulticastTxCount Attribute** + +The PacketMulticastTxCount attribute SHALL indicate the number of multicast packets transmitted +by the Node. + +**11.15.6.10. PacketUnicastRxCount Attribute** + +The PacketUnicastRxCount attribute SHALL indicate the number of unicast packets received by the +Node. + +**11.15.6.11. PacketUnicastTxCount Attribute** + +The PacketUnicastTxCount attribute SHALL indicate the number of unicast packets transmitted by +the Node. + +**11.15.6.12. CurrentMaxRate Attribute** + +The CurrentMaxRate attribute SHALL indicate the current maximum PHY rate of transfer of data in +bits-per-second. + +**11.15.6.13. OverrunCount Attribute** + +The OverrunCount attribute SHALL indicate the number of packets dropped either at ingress or +egress, due to lack of buffer memory to retain all packets on the network interface. The Overrun­ +Count attribute SHALL be reset to 0 upon a reboot of the Node. + +**11.15.7. Commands** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 865 +``` + +``` +ID Name Direction Response Access Conformance +0x00 ResetCounts client ⇒ server Y O ERRCNT +``` +**11.15.7.1. ResetCounts Command** + +Reception of this command SHALL reset the following attributes to 0: + +- BeaconLostCount +- BeaconRxCount +- PacketMulticastRxCount +- PacketMulticastTxCount +- PacketUnicastRxCount +- PacketUnicastTxCount + +This command has no associated data. + +**11.15.8. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 Disconnection info V O +0x01 Association­ +Failure +``` +``` +info V O +``` +``` +0x02 Connection­ +Status +``` +``` +info V O +``` +**11.15.8.1. Disconnection Event** + +The Disconnection Event SHALL indicate that a Node’s Wi-Fi connection has been disconnected as a +result of de-authenticated or dis-association and indicates the reason. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ReasonCode uint16 M +``` +**ReasonCode Field** + +This field SHALL contain the Reason Code field value for the Disassociation or Deauthentication +event that caused the disconnection and the value SHALL align with Table 9-49 "Reason codes" of +IEEE 802.11-2020. + +**11.15.8.2. AssociationFailure Event** + +The AssociationFailure event SHALL indicate that a Node has attempted to connect, or reconnect, to +a Wi-Fi access point, but is unable to successfully associate or authenticate, after exhausting all +internal retries of its supplicant. + +``` +Page 866 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Association­ +Failure­ +Cause +``` +``` +Association­ +Failure­ +CauseEnum +``` +``` +all M +``` +``` +1 Status uint16 all M +``` +**AssociationFailureCause Field** + +The Status field SHALL be set to a value from the AssociationFailureCauseEnum. + +**Status Field** + +The Status field SHALL be set to the Status Code value that was present in the last frame related to +association where Status Code was not equal to zero and which caused the failure of a last trial +attempt, if this last failure was due to one of the following Management frames: + +- Association Response (Type 0, Subtype 1) +- Reassociation Response (Type 0, Subtype 3) +- Authentication (Type 0, Subtype 11) + +Table 9-50 "Status codes" of IEEE 802.11-2020 contains a description of all values possible. + +**11.15.8.3. ConnectionStatus Event** + +The ConnectionStatus Event SHALL indicate that a Node’s connection status to a Wi-Fi network has +changed. Connected, in this context, SHALL mean that a Node acting as a Wi-Fi station is success­ +fully associated to a Wi-Fi Access Point. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Connection­ +Status +``` +``` +Connection­ +StatusEnum +``` +### M + +**11.16. Ethernet Network Diagnostics Cluster** + +The Ethernet Network Diagnostics Cluster provides a means to acquire standardized diagnostics +metrics that MAY be used by a Node to assist a user or Administrator in diagnosing potential prob­ +lems. The Ethernet Network Diagnostics Cluster attempts to centralize all metrics that are relevant +to a potential Ethernet connection to a Node. + +**11.16.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 867 +``` + +``` +Revision Description +1 Initial revision +``` +**11.16.2. Classification** + +``` +Hierarchy Role Scope PICS Code Quality +Base Utility Node DGETH K +``` +**11.16.3. Cluster ID** + +``` +ID Name +0x0037 Ethernet Network Diagnostics +``` +**11.16.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 PKTCNT PacketCounts Node makes available +the counts for the num­ +ber of received and +transmitted packets on +the ethernet interface. +1 ERRCNT ErrorCounts Node makes available +the counts for the num­ +ber of errors that have +occurred during the +reception and transmis­ +sion of packets on the +ethernet interface. +``` +**11.16.5. Data Types** + +**11.16.5.1. PHYRateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Rate10M PHY rate is 10Mbps M +1 Rate100M PHY rate is 100Mbps M +2 Rate1G PHY rate is 1Gbps M +3 Rate2_5G PHY rate is 2.5Gbps M +4 Rate5G PHY rate is 5Gbps M +``` +``` +Page 868 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +5 Rate10G PHY rate is 10Gbps M +6 Rate40G PHY rate is 40Gbps M +7 Rate100G PHY rate is 100Gbps M +8 Rate200G PHY rate is 200Gbps M +9 Rate400G PHY rate is 400Gbps M +``` +**11.16.6. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 PHYRate PHYRa­ +teEnum +``` +``` +all X null R V O +``` +``` +0x0001 FullDu­ +plex +``` +``` +bool all X null R V O +``` +``` +0x0002 PacketRx­ +Count +``` +``` +uint64 all C 0 R V PKTCNT +``` +``` +0x0003 PacketTx­ +Count +``` +``` +uint64 all C 0 R V PKTCNT +``` +``` +0x0004 TxEr­ +rCount +``` +``` +uint64 all C 0 R V ERRCNT +``` +``` +0x0005 Collision­ +Count +``` +``` +uint64 all C 0 R V ERRCNT +``` +``` +0x0006 Overrun­ +Count +``` +``` +uint64 all C 0 R V ERRCNT +``` +``` +0x0007 CarrierDe­ +tect +``` +``` +bool all X C null R V O +``` +``` +0x0008 TimeSin­ +ceReset +``` +``` +uint64 all C 0 R V O +``` +**11.16.6.1. PHYRate Attribute** + +The PHYRate attribute SHALL indicate the current nominal, usable speed at the top of the physical +layer of the Node. A value of null SHALL indicate that the interface is not currently configured or +operational. + +**11.16.6.2. FullDuplex Attribute** + +The FullDuplex attribute SHALL indicate if the Node is currently utilizing the full-duplex operating +mode. A value of null SHALL indicate that the interface is not currently configured or operational. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 869 +``` + +**11.16.6.3. PacketRxCount Attribute** + +The PacketRxCount attribute SHALL indicate the number of packets that have been received on the +ethernet network interface. The PacketRxCount attribute SHALL be reset to 0 upon a reboot of the +Node. + +**11.16.6.4. PacketTxCount Attribute** + +The PacketTxCount attribute SHALL indicate the number of packets that have been successfully +transferred on the ethernet network interface. The PacketTxCount attribute SHALL be reset to 0 +upon a reboot of the Node. + +**11.16.6.5. TxErrCount Attribute** + +The TxErrCount attribute SHALL indicate the number of failed packet transmissions that have +occurred on the ethernet network interface. The TxErrCount attribute SHALL be reset to 0 upon a +reboot of the Node. + +**11.16.6.6. CollisionCount Attribute** + +The CollisionCount attribute SHALL indicate the number of collisions that have occurred while +attempting to transmit a packet on the ethernet network interface. The CollisionCount attribute +SHALL be reset to 0 upon a reboot of the Node. + +**11.16.6.7. OverrunCount Attribute** + +The OverrunCount attribute SHALL indicate the number of packets dropped either at ingress or +egress, due to lack of buffer memory to retain all packets on the ethernet network interface. The +OverrunCount attribute SHALL be reset to 0 upon a reboot of the Node. + +**11.16.6.8. CarrierDetect Attribute** + +The CarrierDetect attribute SHALL indicate the value of the Carrier Detect control signal present on +the ethernet network interface. A value of null SHALL indicate that the interface is not currently +configured or operational. + +**11.16.6.9. TimeSinceReset Attribute** + +The TimeSinceReset attribute SHALL indicate the duration of time, in minutes, that it has been +since the ethernet network interface has reset for any reason. + +**11.16.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 ResetCounts client ⇒ server Y M PKTCNT | +ERRCNT +``` +**11.16.7.1. ResetCounts Command** + +Reception of this command SHALL reset the following attributes to 0: + +``` +Page 870 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- PacketRxCount +- PacketTxCount +- TxErrCount +- CollisionCount +- OverrunCount + +This command has no associated data. + +**11.17. Time Synchronization Cluster** + +Accurate time is required for a number of reasons, including scheduling, display and validating +security materials. + +This section describes a mechanism for Nodes to achieve and maintain time synchronization. The +Time Synchronization cluster provides attributes for reading a Node’s current time. It also allows +Administrators to set current time, time zone and daylight savings time (DST) settings. + +The Time Synchronization cluster MAY be present on the root node endpoint, and SHALL NOT be +present on any other Endpoint of any Node. + +**11.17.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +2 Make TrustedTimeSource fabric-aware, add TSC +feature, define list max sizes, change writable +attributes to commands, remote port, add +attribute for DNS support +``` +**11.17.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node TIMESYNC +``` +**11.17.3. Cluster ID** + +``` +ID Name +0x0038 Time Synchronization +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 871 +``` + +**11.17.4. Terminology** + +``` +Term Definition +DNS-SD Domain name service - service discovery +RFC 6763 +DST Daylight Savings Time +GNSS Global Navigation Satellite System. This is a +satellite system that provides global geo-spatial +positioning. GNSS systems include the NAVSTAR +global positioning system (GPS), Galileo, +GLONASS and BeiDou +NTP Network Time Protocol RFC 5905 +NTS Network Time Security RFC 8915 +PTP Precision Time Protocol IEEE 1588-2008 +SNTP Simple Network Time Protocol. This is a simpli­ +fied version of the Network Time Protocol. It is +also covered by RFC 5905 +``` +**11.17.5. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 TZ TimeZone Server supports time +zone. +1 NTPC NTPClient Server supports an NTP +or SNTP client. +2 NTPS NTPServer Server supports an NTP +server role. +3 TSC TimeSyncClient Time synchronization +client cluster is present. +``` +**11.17.5.1. TimeZone Feature** + +Allows a server to translate a UTC time to a local time using the time zone and daylight savings time +(DST) offsets. If a server supports the TimeZone feature, it SHALL support the SetTimeZone and +SetDSTOffset commands, and TimeZone and DSTOffset attributes, and SHALL expose the local time +through the LocalTime attribute. + +**11.17.5.2. NTPClient Feature** + +Allows a node to use NTP/SNTP for time synchronization. + +``` +Page 872 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.17.5.3. NTPServer Feature** + +Allows a Node to host an NTP server for the network so that other Nodes can achieve a high accu­ +racy time synchronization within the network. See Section 11.17.15, “Acting as an NTP Server”. + +**11.17.5.4. TimeSyncClient Feature** + +This node also supports a time synchronization client and can connect to and read time from other +nodes. + +**11.17.6. Data Types** + +**11.17.6.1. GranularityEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 NoTimeGranularity This indicates that the +node is not currently +synchronized with a +UTC Time source and +its clock is based on the +Last Known Good UTC +Time only. +``` +### M + +``` +1 MinutesGranularity This indicates the node +was synchronized to an +upstream source in the +past, but sufficient +clock drift has occurred +such that the clock +error is now > 5 sec­ +onds. +``` +### M + +``` +2 SecondsGranularity This indicates the node +is synchronized to an +upstream source using +a low resolution proto­ +col. UTC Time is accu­ +rate to ± 5 seconds. +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 873 +``` + +``` +Value Name Summary Conformance +3 MillisecondsGranular­ +ity +``` +``` +This indicates the node +is synchronized to an +upstream source using +high resolution time- +synchronization proto­ +col such as NTP, or has +built-in GNSS with +some amount of jitter +applying its GNSS time­ +stamp. UTC Time is +accurate to ± 50 ms. +``` +### M + +``` +4 MicrosecondsGranu­ +larity +``` +``` +This indicates the node +is synchronized to an +upstream source using +a highly precise time- +synchronization proto­ +col such as PTP, or has +built-in GNSS. UTC time +is accurate to ± 10 μs. +``` +### M + +**11.17.6.2. TimeSourceEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 None Node is not currently +synchronized with a +UTC Time source. +``` +### M + +``` +1 Unknown Node uses an unlisted +time source. +``` +### M + +``` +2 Admin Node received time +from a client using the +SetUTCTime Command. +``` +### M + +``` +3 NodeTimeCluster Synchronized time by +querying the Time Syn­ +chronization cluster of +another Node. +``` +### M + +``` +4 NonMatterSNTP SNTP from a server not +in the Matter network. +NTS is not used. +``` +### M + +``` +Page 874 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Value Name Summary Conformance** + +5 **NonMatterNTP** NTP from servers not +in the Matter network. +None of the servers +used NTS. + +### M + +6 **MatterSNTP** SNTP from a server +within the Matter net­ +work. NTS is not used. + +### M + +7 **MatterNTP** NTP from servers +within the Matter net­ +work. None of the +servers used NTS. + +### M + +8 **MixedNTP** NTP from multiple +servers in the Matter +network and external. +None of the servers +used NTS. + +### M + +9 **NonMatterSNTPNTS** SNTP from a server not +in the Matter network. +NTS is used. + +### M + +10 **NonMatterNTPNTS** NTP from servers not +in the Matter network. +NTS is used on at least +one server. + +### M + +11 **MatterSNTPNTS** SNTP from a server +within the Matter net­ +work. NTS is used. + +### M + +12 **MatterNTPNTS** NTP from a server +within the Matter net­ +work. NTS is used on at +least one server. + +### M + +13 **MixedNTPNTS** NTP from multiple +servers in the Matter +network and external. +NTS is used on at least +one server. + +### M + +14 **CloudSource** Time synchronization +comes from a vendor +cloud-based source (e.g. +"Date" header in +authenticated HTTPS +connection). + +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 875 +``` + +``` +Value Name Summary Conformance +15 PTP Time synchronization +comes from PTP. +``` +### M + +``` +16 GNSS Time synchronization +comes from a GNSS +source. +``` +### M + +**11.17.6.3. TimeZoneDatabaseEnum Type** + +This data type is derived from enum8. It indicates what the device knows about the contents of the +IANA Time Zone Database. Partial support on a device MAY be used to omit historical data, less +commonly used time zones, and/or time zones not related to the region a product is sold in. + +``` +Value Name Summary Conformance +0 Full Node has a full list of +the available time +zones +``` +### M + +``` +1 Partial Node has a partial list +of the available time +zones +``` +### M + +``` +2 None Node does not have a +time zone database +``` +### M + +**11.17.6.4. TrustedTimeSourceStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 FabricIn­ +dex +``` +``` +fabric-idx all M +``` +``` +1 NodeID node-id all M +2 Endpoint endpoint- +no +``` +``` +all M +``` +**FabricIndex Field** + +The Fabric Index associated with the Fabric of the client which last set the value of the trusted time +source node. + +**NodeID Field** + +Node ID of the trusted time source node on the Fabric associated with the entry. + +**Endpoint Field** + +Endpoint on the trusted time source node that contains the Time Synchronization cluster server. + +``` +Page 876 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.17.6.5. FabricScopedTrustedTimeSourceStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 NodeID node-id all M +1 Endpoint endpoint- +no +``` +``` +all M +``` +**NodeID Field** + +Node ID of the trusted time source node on the Fabric of the issuer. + +**Endpoint Field** + +Endpoint on the trusted time source node that contains the Time Synchronization cluster server. +This is provided to avoid having to do discovery of the location of that endpoint by walking over all +endpoints and checking their Descriptor Cluster. + +**11.17.6.6. TimeZoneStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Offset int32 -43200 to +50400 +``` +### M + +``` +1 ValidAt epoch-us all M +2 Name string 0 to 64 O +``` +**Offset Field** + +The time zone offset from UTC in seconds. + +**ValidAt Field** + +The UTC time when the offset SHALL be applied. + +**Name Field** + +The time zone name SHOULD provide a human-readable time zone name and it SHOULD use the +country/city format specified by the IANA Time Zone Database. The Name field MAY be used for dis­ +play. If the node supports a TimeZoneDatabase it MAY use the Name field to set its own DST offsets +if it has database information for the supplied time zone Name and the given Offset matches. + +**11.17.6.7. DSTOffsetStruct Type** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Offset int32 desc M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 877 +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +1 ValidStart­ +ing +``` +``` +epoch-us all M +``` +``` +2 ValidUntil epoch-us all X M +``` +**Offset Field** + +The DST offset in seconds. Normally this is in the range of 0 to 3600 seconds (1 hour), but this field +will accept any values in the int32 range to accommodate potential future legislation that does not +fit with these assumptions. + +**ValidStarting Field** + +The UTC time when the offset SHALL be applied. + +**ValidUntil Field** + +The UTC time when the offset SHALL stop being applied. Providing a null value here indicates a +permanent DST change. If this value is non-null the value SHALL be larger than the ValidStarting +time. + +**11.17.7. Status Codes** + +**11.17.7.1. StatusCodeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x02 TimeNotAccepted Node rejected the +attempt to set the UTC +time +``` +### M + +**11.17.8. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 UTCTime epoch-us all X C null R V M +0x0001 Granular­ +ity +``` +``` +Granulari­ +tyEnum +``` +``` +desc NoTime­ +Granular­ +ity +``` +### R V M + +``` +0x0002 Time­ +Source +``` +``` +Time­ +SourceEnu +m +``` +``` +desc None R V O +``` +``` +Page 878 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0003 Trusted­ +Time­ +Source +``` +``` +Trusted­ +Time­ +SourceS­ +truct +``` +``` +all X N null R V TSC +``` +``` +0x0004 Default­ +NTP +``` +``` +string max 128 X N null R V NTPC +``` +``` +0x0005 TimeZone list[Time­ +Zon­ +eStruct] +``` +``` +1 to 2 N [{0,0}] R V TZ +``` +``` +0x0006 DSTOffset list[DSTOff­ +setStruct] +``` +### N [] R V TZ + +``` +0x0007 LocalTime epoch-us all X C null R V TZ +0x0008 TimeZone­ +Database +``` +``` +TimeZone­ +Data­ +baseEnum +``` +``` +all F None R V TZ +``` +``` +0x0009 NTPServer +Available +``` +``` +bool all False R V NTPS +``` +``` +0x000A Time­ +ZoneList­ +MaxSize +``` +``` +uint8 1 to 2 F R V TZ +``` +``` +0x000B DSTOff­ +setList­ +MaxSize +``` +``` +uint8 min 1 F R V TZ +``` +``` +0x000C Supports­ +DNSRe­ +solve +``` +``` +bool all F False R V NTPC +``` +**11.17.8.1. UTCTime Attribute** + +If the node has achieved time synchronization, this SHALL indicate the current time as a UTC +epoch-us (Epoch Time in Microseconds). + +If the node has not achieved time synchronization, this SHALL be null. This attribute MAY be set +when a SetUTCTime is received. + +**11.17.8.2. Granularity Attribute** + +The granularity of the error that the node is willing to guarantee on the time synchronization. It is +of type GranularityEnum. + +This value SHALL be set to NoTimeGranularity if UTCTime is null and SHALL NOT be set to NoTime­ +Granularity if UTCTime is non-null. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 879 +``` + +**11.17.8.3. TimeSource Attribute** + +The node’s time source. This attribute indicates what method the node is using to sync, whether the +source uses NTS or not and whether the source is internal or external to the Matter network. This +attribute MAY be used by a client to determine its level of trust in the UTCTime. It is of type Time­ +SourceEnum. + +If a node is unsure if the selected NTP server is within the Matter network, it SHOULD select one of +the NonMatter* values. + +This value SHALL be set to None if UTCTime is null and SHALL NOT be set to None if UTCTime is +non-null. + +**11.17.8.4. TrustedTimeSource Attribute** + +A Node ID, endpoint, and associated fabric index of a Node that MAY be used as trusted time source. +See Section 11.17.13, “Time source prioritization”. This attribute reflects the last value set by an +administrator using the SetTrustedTimeSource command. If the value is null, no trusted time +source has yet been set. + +**11.17.8.5. DefaultNTP Attribute** + +The default NTP server that this Node MAY use if other time sources are unavailable. This attribute +is settable by an Administrator using the SetDefaultNTP command. It SHOULD be set by the Com­ +missioner during commissioning. If no default NTP server is available, the Commissioner MAY set +this value to null. The default IANA assigned NTP port of 123 SHALL be used to access the NTP +server. + +If set, the format of this attribute SHALL be a domain name or a static IPv6 address with no port, in +text format, as specified in RFC 5952. The address format SHALL follow the recommendations in +Section 4 and SHALL NOT contain a port number. + +**11.17.8.6. TimeZone Attribute** + +A list of time zone offsets from UTC and when they SHALL take effect. This attribute uses a list of +time offset configurations to allow Nodes to handle scheduled regulatory time zone changes. This +attribute SHALL NOT be used to indicate daylight savings time changes (see DSTOffset attribute for +daylight savings time). + +The first entry SHALL have a ValidAt entry of 0. If there is a second entry, it SHALL have a non-zero +ValidAt time. + +If a node supports a TimeZoneDatabase, and it has data for the given time zone Name and the given +Offset matches, the node MAY update its own DSTOffset attribute to add new DST change times as +required, based on the Name fields of the TimeZoneStruct. Administrators MAY add additional +entries to the DSTOffset of other Nodes with the same time zone, if required. + +If a node does not support a TimeZoneDatabase, the Name field of the TimeZoneStruct is only +applicable for client-side localization. In particular: + +- If the node does not support a TimeZoneDatabase, the Name field SHALL NOT be used to calcu­ + +``` +Page 880 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +late the local time. +``` +- If the node does not support a TimeZoneDatabase, the Name field SHALL NOT be used to calcu­ + late DST start or end dates. + +When time passes, the node SHOULD remove any entries which are no longer active and change +the ValidAt time for the currently used TimeZoneStruct list item to zero. + +This attribute SHALL have at least one entry. If the node does not have a default time zone and no +time zone has been set, it MAY set this value to a list containing a single TimeZoneStruct with an off­ +set of 0 (UTC) and a ValidAt time of 0. + +**11.17.8.7. DSTOffset Attribute** + +A list of offsets to apply for daylight savings time, and their validity period. + +List entries SHALL be sorted by ValidStarting time. + +A list entry SHALL NOT have a ValidStarting time that is smaller than the ValidUntil time of the pre­ +vious entry. There SHALL be at most one list entry with a null ValidUntil time and, if such an entry +is present, it SHALL appear last in the list. + +Over time, the node SHOULD remove any entries which are no longer active from the list. + +Over time, if the node supports a TimeZoneDatabase and it has information available for the given +time zone name, it MAY update its own list to add additional entries. + +If a time zone does not use DST, this SHALL be indicated by a single entry with a 0 offset and a null +ValidUntil field. + +**11.17.8.8. LocalTime Attribute** + +The computed current local time of the node as a epoch-us (Epoch Time in Microseconds). The +value of LocalTime SHALL be the sum of the UTCTime, the offset of the currently valid TimeZon­ +eStruct from the TimeZone attribute (converted to microseconds), and the offset of the currently +valid DSTOffsetStruct from the DSTOffset attribute (converted to microseconds), if such an entry +exists. + +If the node has not achieved time synchronization, this SHALL be null. If the node has an empty +DSTOffset, this SHALL be null. + +**11.17.8.9. TimeZoneDatabase Attribute** + +Indicates whether the node has access to a time zone database. Nodes with a time zone database +MAY update their own DSTOffset attribute to add new entries and MAY push DSTOffset updates to +other Nodes in the same time zone as required. + +**11.17.8.10. NTPServerAvailable Attribute** + +If the node is running an RFC 5905 NTPv4 compliant server on port 123, this value SHALL be True. + +If the node is not currently running an NTP server, this value SHALL be False. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 881 +``` + +**11.17.8.11. TimeZoneListMaxSize Attribute** + +Number of supported list entries in the TimeZone attribute. This attribute may take the value of 1 +or 2, where the optional second list entry MAY be used to handle scheduled regulatory time zone +changes. + +**11.17.8.12. DSTOffsetListMaxSize Attribute** + +Number of supported list entries in DSTOffset attribute. This value must be at least 1. + +**11.17.8.13. SupportsDNSResolve Attribute** + +This attribute is true if the node supports resolving a domain name. DefaultNTP Address values for +these nodes MAY include domain names. If this is False, the Address for a DefaultNTP SHALL be an +IPv6 address. + +**11.17.9. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 SetUTCTime client ⇒ server Y A M +0x01 SetTrusted­ +TimeSource +``` +``` +client ⇒ server Y A F TSC +``` +``` +0x02 SetTimeZone client ⇒ server SetTime­ +ZoneResponse +``` +### M TZ + +``` +0x03 SetTime­ +ZoneResponse +``` +``` +client ⇐ server N TZ +``` +``` +0x04 SetDSTOffset client ⇒ server Y M TZ +0x05 SetDefaultNTP client ⇒ server Y A NTPC +``` +**11.17.9.1. SetUTCTime Command** + +The data for this command are as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UTCTime epoch-us all 0 M +1 Granularity Granulari­ +tyEnum +``` +``` +all NoTime­ +Granularity +``` +### M + +``` +2 TimeSource Time­ +SourceEnum +``` +``` +all None O +``` +This command MAY be issued by Administrator to set the time. If the Commissioner does not have a +valid time source, it MAY send a Granularity of NoTimeGranularity. + +Upon receipt of this command, the node MAY update its UTCTime attribute to match the time speci­ +fied in the command, if the stated Granularity and TimeSource are acceptable. The node SHALL + +``` +Page 882 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +update its UTCTime attribute if its current Granularity is NoTimeGranularity. + +If the time is updated, the node SHALL also update its Granularity attribute based on the granular­ +ity specified in the command and the expected clock drift of the node. This SHOULD normally be +one level lower than the stated command Granularity. It SHALL also update its TimeSource +attribute to Admin. It SHALL also update its Last Known Good UTC Time as defined in Section +3.5.6.1, “Last Known Good UTC Time”. + +If the node updates its UTCTime attribute, it SHALL accept the command with a status code of SUC­ +CESS. If it opts to not update its time, it SHALL fail the command with a cluster specific Status Code +of TimeNotAccepted. + +**UTCTime Field** + +This SHALL give the Client’s UTC Time. + +**Granularity Field** + +This SHALL give the Client’s Granularity, as described in Granularity. + +**TimeSource Field** + +This SHALL give the Client’s TimeSource, as described in TimeSource. + +**11.17.9.2. SetTrustedTimeSource Command** + +This command SHALL set the TrustedTimeSource attribute. + +Upon receipt of this command: + +- If the TrustedTimeSource field in the command is null, the node SHALL set the TrustedTime­ + Source attribute to null and SHALL generate a MissingTrustedTimeSource event. +- Otherwise, the node SHALL set the TrustedTimeSource attribute to a struct which has NodeID + and Endpoint fields matching those in the TrustedTimeSource field and has its FabricIndex field + set to the command’s accessing fabric index. + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Confor­ +mance +0 Trusted­ +TimeSource +``` +``` +FabricScope­ +dTrusted­ +Time­ +SourceStruct +``` +### X M + +**TrustedTimeSource Field** + +This field contains the Node ID and endpoint of a trusted time source on the accessing fabric. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 883 +``` + +**11.17.9.3. SetTimeZone Command** + +This command is used to set the time zone of the node. The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 TimeZone list[Time­ +ZoneStruct] +``` +``` +1 to 2 M +``` +If the given list is larger than the TimeZoneListMaxSize, the node SHALL respond with +RESOURCE_EXHAUSTED and the TimeZone attribute SHALL NOT be updated. + +If the given list does not conform to the list requirements in TimeZone attribute the node SHALL +respond with a CONSTRAINT_ERROR and the TimeZone attribute SHALL NOT be updated. + +If there are no errors in the list, the TimeZone field SHALL be copied to the TimeZone attribute. A +TimeZoneStatus event SHALL be generated with the new time zone information. + +If the node supports a time zone database and it has information available for the time zone that +will be applied, it MAY set its DSTOffset attribute, otherwise the DSTOffset attribute SHALL be set to +an empty list. A DSTTableEmpty event SHALL be generated if the DSTOffset attribute is empty. A +DSTStatus event SHALL be generated if the node was previously applying a DST offset. + +**11.17.9.4. SetTimeZoneResponse Command** + +This command SHALL be generated in response to a SetTimeZone command. The data for this com­ +mand SHALL be as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 DSTOffset­ +sRequired +``` +``` +bool all true M +``` +**DSTOffsetsRequired Field** + +If the node supports a time zone database with information for the time zone that will be applied, it +MAY use this information to set the DSTOffset attribute. If the node is setting its own DSTOffset +attribute, the DSTOffsetsRequired field SHALL be set to false, otherwise it SHALL be set to true. + +**11.17.9.5. SetDSTOffset Command** + +This command is used to set the DST offsets for a node. The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 DSTOffset list[DSTOff­ +setStruct] +``` +### M + +- If the length of DSTOffset is larger than DSTOffsetListMaxSize, the node SHALL respond with + +``` +Page 884 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### RESOURCE_EXHAUSTED. + +- Else if the list entries do not conform to the list requirements for DSTOffset attribute, the node + SHALL respond with CONSTRAINT_ERROR. + +If there are no errors in the list, the DSTOffset field SHALL be copied to the DSTOffset attribute. + +If the DSTOffset attribute change causes a corresponding change to the DST state, a DSTStatus event +SHALL be generated. If the list is empty, the node SHALL generate a DSTTableEmpty event. + +**11.17.9.6. SetDefaultNTP Command** + +This command is used to set the DefaultNTP attribute. If the DefaultNTP Address field does not con­ +form to the requirements in the DefaultNTP attribute description, the command SHALL fail with a +status code of INVALID_COMMAND. If the node does not support DNS resolution (as specified in +SupportsDNSResolve) and the provided Address is a domain name, the command SHALL fail with a +status code of INVALID_COMMAND. Otherwise, the node SHALL set the DefaultNTP attribute to +match the DefaultNTP provided in this command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 DefaultNTP string max 128 X M +``` +**DefaultNTP Field** + +This field contains the address of an NTP server than can be used as a fallback for time synchro­ +nization. The format of this field SHALL follow the requirements in the DefaultNTP attribute +description. + +**11.17.10. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 DST­ +TableEmpty +``` +### INFO V TZ + +``` +0x01 DSTStatus INFO V TZ +0x02 TimeZoneSta­ +tus +``` +### INFO V TZ + +``` +0x03 TimeFailure INFO V M +0x04 MissingTrust­ +edTimeSource +``` +### INFO V TSC + +**11.17.10.1. DSTTableEmpty Event** + +This event SHALL be generated when the node stops applying the current DSTOffset and there are +no entries in the list with a larger ValidStarting time, indicating the need to possibly get new DST +data. This event SHALL also be generated if the DSTOffset list is cleared either by a SetTimeZone +command, or by a SetDSTOffset command with an empty list. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 885 +``` + +The node SHALL generate this event if the node has not generated a DSTTableEmpty event in the +last hour, and the DSTOffset list is empty when the node attempts to update its time. DST­ +TableEmpty events corresponding to a time update SHOULD NOT be generated more often than +once per hour. + +There is no data for this event. + +**11.17.10.2. DSTStatus Event** + +This event SHALL be generated when the node starts or stops applying a DST offset. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 DSTOffse­ +tActive +``` +``` +bool M +``` +**DSTOffsetActive Field** + +Indicates whether the current DST offset is being applied (i.e, daylight savings time is applied, as +opposed to standard time). + +**11.17.10.3. TimeZoneStatus Event** + +This event SHALL be generated when the node changes its time zone offset or name. It SHALL NOT +be sent for DST changes that are not accompanied by a time zone change. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Offset int32 -43200 to +50400 +``` +### M + +``` +1 Name string 0 to 64 bytes O +``` +**Offset Field** + +Current time zone offset from UTC in seconds. + +**Name Field** + +Current time zone name. This name SHOULD use the country/city format specified by the +IANA Time Zone Database. + +**11.17.10.4. TimeFailure Event** + +This event SHALL be generated if the node has not generated a TimeFailure event in the last hour, +and the node is unable to get a time from any source. This event SHOULD NOT be generated more +often than once per hour. + +``` +Page 886 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.17.10.5. MissingTrustedTimeSource Event** + +This event SHALL be generated if the TrustedTimeSource is set to null upon fabric removal or by a +SetTrustedTimeSource command. + +This event SHALL also be generated if the node has not generated a MissingTrustedTimeSource +event in the last hour, and the node fails to update its time from the TrustedTimeSource because +the TrustedTimeSource is null or the specified peer cannot be reached. MissingTrustedTimeSource +events corresponding to a time update SHOULD NOT be generated more often than once per hour. + +**11.17.11. Time Synchronization at Commissioning** + +During commissioning the Commissioner SHOULD set the UTCTime, and set up the TrustedTime­ +Source, DefaultNTP, TimeZone and DSTOffsets as required. Please see Commissioning Flows. Note +that the commissioner MAY opt to not set the time so the node SHOULD NOT depend on having time +during commissioning. + +**11.17.12. Time Synchronization during operation** + +Nodes MAY perform time synchronization using a trusted external source, RFC 5905 or by reading +the UTC time from the Time Synchronization cluster of another Node with the desired Granularity +and TimeSource. When using NTPv4 / SNTPv4, Nodes capable of external communication SHOULD +use network time security (NTS) if that is available on the server (RFC 8915). This specification +DOES NOT mandate that Nodes should include a TCP/TLS stack and a set of adequate Root CA cer­ +tificates solely to support NTS, but that if a Node already has these capabilities, then it SHOULD +implement and attempt NTS for NTP. + +Nodes SHOULD attempt to perform a time synchronization after a restart or upon any change of +Node state where timekeeping was lost. Nodes SHOULD attempt this time synchronization prior to +using any security material which may have expired. If a Node is unable to achieve time synchro­ +nization using the steps outlined in Section 11.17.13, “Time source prioritization”, the Node MAY +retry or fall back to the stored Last Known Good UTC Time (Section 3.5.6.1, “Last Known Good UTC +Time”). + +Since Matter does not mandate external network connectivity for use, device manufacturers should +be aware that it is possible to be operating in a network where time is not available from any +source. Product manufacturers may wish to account for this possibility when specifying their clock +drift requirements. The estimated clock drift is reported using the Granularity attribute. + +**11.17.13. Time source prioritization** + +Nodes SHALL prioritize time synchronization sources in the following order: + +1. GNSS time source, if supported by the Node. +2. Trusted, high-resolution, external time source (ex. PTP, network NTP, trusted cloud-based + source), if supported by the Node and external connectivity is available. +3. If NTPClient (NTPC) feature is supported: NTP server defined in the DHCPv6 NTP server option, + if DHCPv6 is supported on the Node. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 887 +``` + +4. If NTPClient (NTPC) feature is supported: NTP server defined by DHCP if the Node supports + IPv4. +5. If NTPClient (NTPC) feature is supported: NTP server identified by a DNS-SD query for + _ntp._udp. If multiple servers respond, Nodes with full NTP support SHOULD query multiple + servers. Nodes using SNTP SHOULD select any server from the list. +6. If TimeSyncClient (TSC) feature is supported: the Time Synchronization cluster of another Node + SHOULD be queried in the following order: + a.TrustedTimeSource provided by an Administrator. +b. Any of the Node’s current peers per any data model binding that support the Time Synchro­ +nization cluster and have the desired Granularity and TimeSource. +c.Enumerate all Nodes using DNS-SD query for _matter._tcp and select a peer that supports +the Time Synchronization cluster and has the desired Granularity and TimeSource. +7. If NTPClient (NTPC) feature is supported: Fallback NTP server defined during commissioning. + +Nodes that use GNSS or a trusted external source SHOULD check the remaining time synchroniza­ +tion sources to determine if they SHOULD act as an NTP server (see Section 11.17.15, “Acting as an +NTP Server”). + +**11.17.14. Time synchronization maintenance** + +Nodes SHALL adjust their Granularity attribute based on their assessed time synchronization error. +Nodes running an NTP server (Section 11.17.15, “Acting as an NTP Server”) SHALL maintain a Gran­ +ularity of SecondsGranularity or better and SHOULD maintain an accuracy of MillisecondsGranu­ +larity or better. + +A Node with a Granularity of NoTimeGranularity SHALL attempt to sync its time at least once a day. +Nodes SHOULD NOT query the Time Synchronization cluster of another Node more than once per +30 minutes. + +**11.17.15. Acting as an NTP Server** + +Any capable Node with always-on power source that has and can maintain a time synchronization +Granularity of MillisecondsGranularity or better, SHOULD act as an NTP server. Any capable Node +that reaches the final stage in the Section 11.17.13, “Time source prioritization” mechanism +SHOULD act as an NTP server for the network. + +A Node hosting an NTP server SHALL update the NTPServerAvailable attribute and SHOULD adver­ +tise an _ntp._udp DNS-SD service. A Node hosting an NTP server SHOULD support network time +security (NTS). A Node hosting an NTP server SHOULD implement leap smearing. + +**11.17.16. Implementation Guidance** + +This specification offers several options for getting time in order to support Nodes with various +capabilities. This section is not intended as a requirement, but is used to illustrate how various +Nodes might implement this specification. + +``` +Page 888 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.17.16.1. Example: Constrained Node with no schedule capabilities** + +This type of Node would not need to support the TimeZone (TZ) feature or the NTPServer (NTPS) +feature. A constrained node can choose to get time either by using a time synchronization client +cluster to read the time from a trusted node (if the TSC feature is supported), and / or by using the +NTPClient (if the NTPC feature is supported). A constrained node supporting NTPC would likely use +an SNTP implementation. + +A node supporting both the NTPC and TSC features would have the following attributes: + +- UTCTime +- Granularity +- TimeSource (optional) +- TrustedTimeSource +- DefaultNTP + +To achieve time synchronization, the Node would start at Step 3 of Section 11.17.13, “Time source +prioritization” (Steps 1 and 2 do not apply). + +If the Node opts to support only the TSC feature, it would have the following attributes: + +- UTCTime +- Granularity +- TimeSource (optional) +- TrustedTimeSource + +To achieve time synchronization, the Node would start at step 6 (querying a Time Synchronization +cluster) of Section 11.17.13, “Time source prioritization” (other steps do not apply). + +If the Node opts to support only the NTPC feature, it would have the following attributes: + +- UTCTime +- Granularity +- TimeSource (optional) +- DefaultNTP + +To achieve time synchronization, the Node would start at step 3 of Section 11.17.13, “Time source +prioritization” and would bypass step 6. + +In all cases, if the Node wishes to maintain time synchronization by re-querying, it would set its +Granularity attribute as appropriate at each update. This would probably be either Milliseconds­ +Granularity or SecondsGranularity depending on the round-trip delay and the frequency of +updates. If the Node wishes to use a single time synchronization, but will not continue to synchro­ +nize during operation, it may either set the Granularity as appropriate and downgrade as the clock +drifts, or may simply opt to set the Granularity to MinutesGranularity. If supported, the TimeSource +attribute would be set as appropriate. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 889 +``` + +**11.17.16.2. Example: Intermittently connected device with schedule capability** + +This type of Node would need to support the TimeZone (TZ) feature to support scheduling, but +would not support the NTPServer (NTPS) feature as it is an intermittently connected device and +would not make a reliable server. As with the Constrained Node with no schedule capabilities +example, this type of Node can choose to get time either by using the time synchronization client +cluster to read the time from a trusted node (if the TSC feature is supported) and / or by using an +NTPClient (if the NTPC feature is supported). + +This type of Node would support all the attributes described in the Constrained Node with no +schedule capabilities example with the appropriate features. Because it additionally supports the +TimeZone (TZ) feature, it would also support the following attributes: + +- TimeZoneListMaxSize +- TimeZone +- DSTOffsetListMaxSize +- DSTOffset +- LocalTime +- TimeZoneDatabase + +During commissioning, the Node should receive time zone information from the commissioner. If +the Node has access to a time zone database, it can opt to fill its own DSTOffset attribute, otherwise +it should also receive DSTOffset information from the Commissioner. During operation, this type of +Node would use the same methods of getting time as the Constrained Node with no schedule capa­ +bilities example, setting the Granularity and optional TimeSource as appropriate. It would also use +the information from the TimeZone and DSTOffset to calculate a local time. + +**11.17.16.3. Example: Hub-like Node** + +These types of Nodes are normally relatively capable, high-powered and always-on. These would +most likely include time zone support for scheduling and display. Often these will have significant +software beyond this specification and are likely to already have built-in mechanisms for time syn­ +chronization. Such Nodes SHOULD support an NTP server to serve time to other Nodes in the net­ +work. This type of Node may opt to support the TimeSyncClient (TSC) and NTPClient (NTPC) as +backup, but can omit these if it has a reliable time source. It would support the following attributes +based on the supported features: + +- UTCTime +- Granularity +- TimeSource (optional) +- TrustedTimeSource (if TSC supported) +- DefaultNTP (if NTPC supported) +- TimeZoneListMaxSize +- TimeZone +- DSTOffsetListMaxSize + +``` +Page 890 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- DSTOffset +- LocalTime +- TimeZoneDatabase +- NTPServerAvailable + +To achieve time synchronization, these Nodes would likely use Step 1 or Step 2 of Section 11.17.13, +“Time source prioritization”, using the remaining options as fallback if necessary. The Node would +then set its Granularity and TimeSource as appropriate, and would maintain its times, Granularity +and TimeSource. The Node SHOULD also start an NTP server, update the NTPServerAvailable +attribute and advertise using DNS-SD on _ntp._udp. + +If a time-zone database is supported (Node can calculate DST times from TimeZone settings), these +Nodes MAY subscribe to the DSTTableEmpty Events of Nodes with no TimeZoneDatabase support. +Upon receipt of these events the Node SHOULD calculate and set new DST values for such Nodes by +writing the DSTOffset attribute. These nodes MAY also subscribe to the TimeFailure and Miss­ +ingTrustedTimeSource events for Nodes in its fabric and supply time or time sources as required. + +**11.18. Node Operational Credentials Cluster** + +This cluster is used to add or remove Node Operational credentials on a Commissionee or Node, as +well as manage the associated Fabrics. + +**11.18.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.18.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node OPCREDS +``` +**11.18.3. Cluster ID** + +``` +ID Name +0x003E Operational Credentials +``` +**11.18.4. Data Types** + +**11.18.4.1. RESP_MAX Constant Type** + +A RESP_MAX constant appears in the description of some command fields in this cluster and within + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 891 +``` + +the description of some associated serialization schemes. + +The value RESP_MAX SHALL be 900 bytes. + +The current limit of 900 bytes was chosen to accommodate the maximum size of IPv6 frames, trans­ +port headers, message layer headers and integrity protection and Interaction Model protocol +encoding, while accounting for sufficient remaining space for signatures and to allow extensions to +larger key and digest sizes in the future. + +**11.18.4.2. CertificateChainTypeEnum Type** + +This data type is derived from enum8. + +This enumeration is used by the CertificateChainRequest command to convey which certificate +from the device attestation certificate chain to transmit back to the client. + +``` +Value Name Summary Conformance +1 DACCertificate Request the DER- +encoded DAC certificate +``` +### M + +``` +2 PAICertificate Request the DER- +encoded PAI certificate +``` +### M + +**11.18.4.3. NodeOperationalCertStatusEnum Type** + +This data type is derived from enum8. + +This enumeration is used by the NOCResponse common response command to convey detailed out­ +come of several of this cluster’s operations. + +``` +Value Name Summary Conformance +0 OK OK, no error M +1 InvalidPublicKey Public Key in the NOC +does not match the +public key in the +NOCSR +``` +### M + +``` +2 InvalidNodeOpId The Node Operational +ID in the NOC is not for­ +matted correctly. +``` +### M + +``` +3 InvalidNOC Any other validation +error in NOC chain +``` +### M + +``` +4 MissingCsr No record of prior CSR +for which this NOC +could match +``` +### M + +``` +5 TableFull NOCs table full, cannot +add another one +``` +### M + +``` +Page 892 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +6 InvalidAdminSubject Invalid CaseAdminSub­ +ject field for an +AddNOC command. +``` +### M + +``` +7 Reserved for future use M +8 Reserved for future use M +9 FabricConflict Trying to AddNOC +instead of UpdateNOC +against an existing Fab­ +ric. +``` +### M + +``` +10 LabelConflict Label already exists on +another Fabric. +``` +### M + +``` +11 InvalidFabricIndex FabricIndex argument +is invalid. +``` +### M + +**11.18.4.4. NOCStruct Type** + +This encodes a fabric sensitive NOC chain, underpinning a commissioned Operational Identity for a +given Node. + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 NOC octstr max 400 S M +2 ICAC octstr max 400 X S M +``` +Note that the Trusted Root CA Certificate is not included in this structure. The roots are available in +the TrustedRootCertificates attribute of the Node Operational Credentials cluster. + +**NOC Field** + +This field SHALL contain the NOC for the struct’s associated fabric, encoded using Matter Certificate +Encoding. + +**ICAC Field** + +This field SHALL contain the ICAC or the struct’s associated fabric, encoded using Matter Certificate +Encoding. If no ICAC is present in the chain, this field SHALL be set to null. + +**11.18.4.5. FabricDescriptorStruct Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 893 +``` + +``` +Access Quality: Fabric Scoped +1 RootPub­ +licKey +``` +``` +octstr 65 M +``` +``` +2 VendorID vendor-id desc M +3 FabricID fabric-id M +4 NodeID node-id M +5 Label string max 32 "" M +``` +This structure encodes a Fabric Reference for a fabric within which a given Node is currently com­ +missioned. + +**RootPublicKey Field** + +This field SHALL contain the public key for the trusted root that scopes the fabric referenced by +FabricIndex and its associated operational credential (see Section 6.4.5.3, “Trusted Root CA Certifi­ +cates”). The format for the key SHALL be the same as that used in the ec-pub-key field of the Matter +Certificate Encoding for the root in the operational certificate chain. + +**VendorID Field** + +This field SHALL contain the value of AdminVendorID provided in the AddNOC command that led +to the creation of this FabricDescriptorStruct. The set of allowed values is defined in AdminVen­ +dorID. + +The intent is to provide some measure of user transparency about which entities have Administer +privileges on the Node. + +Clients SHALL consider the VendorID field value to be untrustworthy until the NOC chain associ­ +ated with the fabric has passed the Vendor ID Validation Procedure against the associated RCAC. + +**FabricID Field** + +This field SHALL contain the FabricID allocated to the fabric referenced by FabricIndex. This field +SHALL match the value found in the matter-fabric-id field from the operational certificate provid­ +ing the operational identity under this Fabric. + +**NodeID Field** + +This field SHALL contain the NodeID in use within the fabric referenced by FabricIndex. This field +SHALL match the value found in the matter-node-id field from the operational certificate providing +this operational identity. + +**Label Field** + +This field SHALL contain a commissioner-set label for the fabric referenced by FabricIndex. This +label is set by the UpdateFabricLabel command. + +``` +Page 894 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.18.4.6. Attestation Elements** + +The Attestation Elements contain the metadata related to attestation, encoded in Matter TLV. + +_Attestation Elements TLV_ + +``` +attestation-elements => STRUCTURE [ tag-order ] +{ +certification_declaration[1] : OCTET STRING, +attestation_nonce[2] : OCTET STRING [ length 32 ], +timestamp[3] : UNSIGNED INTEGER [ range 32-bits ], +firmware_information[4, optional] : OCTET STRING, +} +``` +Any context-specific tags not listed in the above schema for Attestation Elements SHALL be +reserved for future use, and SHALL be silently ignored if seen by a Commissioner which cannot +understand them. + +**11.18.4.7. Attestation Information** + +The Attestation Information is the combination of a Matter TLV payload, containing the Attestation +Elements, as well as a signature over an attestation_tbs message containing the in-band-transmitted +attestation_elements_message and a secret out-of-band Attestation Challenge. + +The Attestation Information SHALL be computed as follows: + +1. Encode the attestation-elements structure with an anonymous tag into an octet string called + attestation_elements_message. + ◦ The firmware_information field SHALL be an octet string, as described in Section 6.3.2, + “Firmware Information”. + ◦ The certification_declaration field SHALL be the DER-encoded octet string representation of + a CMS(RFC5652)-encoded certification declaration, as described in Section 6.3, “Certification + Declaration”. + ◦ The timestamp field SHALL be in epoch-s. + ◦ The attestation_nonce field SHALL match the AttestationNonce field provided in the Attesta­ + tionRequest Command that triggered the generation of the Attestation Elements. + ◦ Vendor specific information, if present, SHALL be encoded using fully qualified tags. Such + fields allow the Node taking part in the Device Attestation Procedure to communicate ven­ + dor-specific information that MAY aid in device commissioning. Commissioners that do not + understand the format of the data MAY ignore them. + ◦ The resulting attestation_elements_message, including optional fields, SHALL be no more + than RESP_MAX bytes once serialized. + +``` +attestation_elements_message = +{ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 895 +``` + +``` +certification_declaration(1) = certification_declaration, +attestation_nonce(2) = attestation_nonce, +timestamp(3) = timestamp, +firmware_information(4) = firmware_information, +``` +``` +... optional fields per attestation-elements .. +} +``` +2. Obtain the AttestationChallenge from a CASE session, resumed CASE session, or PASE session + depending on the method used to establish the current session. This is an octet string of length + CRYPTO_SYMMETRIC_KEY_LENGTH_BITS. Save it for the next step as attestation_challenge. +3. Locally generate an attestation_tbs message as an octet string by concatenating the attesta­ + tion_elements_message and the attestation_challenge: + ◦ attestation_tbs = attestation_elements_message || attestation_challenge +4. Compute the attestation_signature and record it as an ec-signature octet string: + +``` +attestation_signature = Crypto_Sign( +message = attestation_tbs, +privateKey = Device Attestation Private Key +) +``` +5. Fill the AttestationElements field of the AttestationResponse Command using the contents of the + attestation_elements_message octet string. +6. Fill the AttestationSignature field of the AttestationResponse Command using the contents of the + attestation_signature octet string. +7. Note that the attestation_challenge SHALL NOT be included in any of the payloads conveyed as + part of the Attestation Information. + +See Section F.2, “Device Attestation Response test vector” for an example computation of the above +messages and application payloads. + +**11.18.4.8. NOCSR Elements** + +The NOCSR Elements contain the metadata related to NOCSR, encoded in Matter TLV. + +_NOCSR Elements TLV_ + +``` +nocsr-elements => STRUCTURE [ tag-order ] +{ +csr[1] : OCTET STRING, +CSRNonce[2] : OCTET STRING [ length 32 ], +vendor_reserved1[3, optional] : OCTET STRING, +vendor_reserved2[4, optional] : OCTET STRING, +vendor_reserved3[5, optional] : OCTET STRING +``` +``` +Page 896 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### } + +Any context-specific tags not listed in the above schema for NOCSR Elements SHALL be reserved for +future use, and SHALL be silently ignored if seen by a Commissioner which cannot understand +them. + +**11.18.4.9. NOCSR Information** + +The NOCSR Information is the combination of a Matter TLV payload, containing the NOCSR Ele­ +ments, as well as a signature over an nocsr_tbs message containing the in-band-transmitted noc­ +sr_elements_message and a secret out-of-band Attestation Challenge, using the Attestation Private +Key that is unique to the device producing the NOCSR Information. + +The NOCSR Information SHALL be computed as follows: + +1. Encode the nocsr-elements structure with an anonymous tag into an octet string called noc­ + sr_elements_message. + +``` +◦ The csr field SHALL be a DER-encoded octet string of a properly encoded PKCS #10 Certifi­ +cate Signing Request (CSR), signed with the Node Operational Private Key associated with +the Node Operational Public Key, which is the subjectPublicKey field of the CSR. See Section +6.4.6.1, “Node Operational Certificate Signing Request (NOCSR) Procedure” for details about +the generation of the Node Operational Key Pair, and the contents of the CSR. +◦ The CSRNonce field SHALL match the CSR Nonce field in the corresponding CSRRequest +Command. +◦ The vendor_reserved1 through vendor_reserved3 fields allow the Node taking part in the +NOCSR Procedure to communicate vendor-specific information that MAY aid in device com­ +missioning. Commissioners that do not understand the format of the data MAY ignore them. +◦ The resulting nocsr_elements_message, including optional fields, SHALL be no more than +RESP_MAX bytes once serialized. +``` +``` +nocsr_elements_message = +{ +csr(1) = node_operational_csr_der_bytes, +CSRNonce(2) = CSRNonce, +``` +``` +... optional fields per nocsr-elements .. +} +``` +2. Obtain the AttestationChallenge from a CASE session, resumed CASE session, or PASE session + depending on the method used to establish the current session. This is an octet string of length + CRYPTO_SYMMETRIC_KEY_LENGTH_BITS. Save it for the next step as attestation_challenge. +3. Locally generate an nocsr_tbs message as an octet string by concatenating the nocsr_ele­ + ments_message and the attestation_challenge: + ◦ nocsr_tbs = nocsr_elements_message || attestation_challenge + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 897 +``` + +4. Compute the attestation_signature and record it as an ec-signature octet string: + +``` +attestation_signature = Crypto_Sign( +message = nocsr_tbs, +privateKey = Device Attestation Private Key +) +``` +5. Fill the NOCSRElements field of the CSRResponse Command using the contents of the nocsr_ele­ + ments_message octet string. +6. Fill the AttestationSignature field of the CSRResponse Command using the contents of the attes­ + tation_signature octet string. +7. Note that the attestation_challenge SHALL NOT be included in any of the payloads conveyed as + part of the NOCSR Information. + +See Section F.3, “Node Operational CSR Response test vector” for an example computation of the +above messages and application payloads. + +**11.18.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 NOCs list[NOC­ +Struct] +``` +``` +max Sup­ +portedFab­ +rics +``` +### N C R A F M + +``` +0x0001 Fabrics list[Fab­ +ricDescrip­ +torStruct] +``` +``` +max Sup­ +portedFab­ +rics +``` +### N R V F M + +``` +0x0002 Support­ +edFabrics +``` +``` +uint8 5 to 254 F R V M +``` +``` +0x0003 Commis­ +sioned­ +Fabrics +``` +``` +uint8 max Sup­ +portedFab­ +rics +``` +### N R V M + +``` +0x0004 Trusted­ +RootCer­ +tificates +``` +``` +list[octstr] max Sup­ +portedFab­ +rics[max +400] +``` +### N C R V M + +``` +0x0005 Current­ +FabricIn­ +dex +``` +``` +uint8 0 R V M +``` +**11.18.5.1. NOCs Attribute** + +This attribute contains all NOCs applicable to this Node, encoded as a read-only list of NOCStruct. + +``` +Page 898 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Operational Certificates SHALL be added through the AddNOC command, and SHALL be removed +through the RemoveFabric command. + +Upon Factory Data Reset, this attribute SHALL be set to a default value of an empty list. + +The number of entries in this list SHALL match the number of entries in the Fabrics attribute. + +**11.18.5.2. Fabrics Attribute** + +This attribute describes all fabrics to which this Node is commissioned, encoded as a read-only list +of FabricDescriptorStruct. This information MAY be computed directly from the NOCs attribute. + +Upon Factory Data Reset, this attribute SHALL be set to a default value of an empty list. + +The number of entries in this list SHALL match the number of entries in the NOCs attribute. + +**11.18.5.3. SupportedFabrics Attribute** + +This attribute contains the number of Fabrics that are supported by the device. This value is fixed +for a particular device. + +**11.18.5.4. CommissionedFabrics Attribute** + +This attribute contains the number of Fabrics to which the device is currently commissioned. This +attribute SHALL be equal to the following: + +- The number of entries in the NOCs attribute. +- The number of entries in the Fabrics attribute. + +Upon Factory Data Reset, this attribute SHALL be set to a default value of 0. + +**11.18.5.5. TrustedRootCertificates Attribute** + +This attribute SHALL contain a read-only list of Trusted Root CA Certificates (RCAC) installed on the +Node, as octet strings containing their Matter Certificate Encoding representation. + +These certificates are installed through the AddTrustedRootCertificate command. + +Depending on the method of storage employed by the server, either shared storage for identical +root certificates shared by many fabrics, or individually stored root certificate per fabric, multiple +identical root certificates MAY legally appear within the list. + +To match a root with a given fabric, the root certificate’s subject and subject public key need to be +cross-referenced with the NOC or ICAC certificates that appear in the NOCs attribute for a given fab­ +ric. + +Upon Factory Data Reset, this attribute SHALL be set to a default value whereby the list is empty. + +**11.18.5.6. CurrentFabricIndex Attribute** + +This attribute SHALL contain accessing fabric index. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 899 +``` + +This attribute is useful to contextualize Fabric-Scoped entries obtained from response commands or +attribute reads, since a given Fabric may be referenced by a different Fabric Index locally on a +remote Node. + +**11.18.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 AttestationRe­ +quest +``` +``` +client ⇒ server AttestationRe­ +sponse +``` +### A M + +``` +0x01 AttestationRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x02 Certificate­ +ChainRequest +``` +``` +client ⇒ server Certificate­ +ChainResponse +``` +### A M + +``` +0x03 Certificate­ +ChainRe­ +sponse +``` +``` +client ⇐ server N M +``` +``` +0x04 CSRRequest client ⇒ server CSRResponse A M +0x05 CSRResponse client ⇐ server N M +0x06 AddNOC client ⇒ server NOCResponse A M +0x07 UpdateNOC client ⇒ server NOCResponse A F M +0x08 NOCResponse client ⇐ server N M +0x09 UpdateFabri­ +cLabel +``` +``` +client ⇒ server NOCResponse A F M +``` +``` +0x0A RemoveFabric client ⇒ server NOCResponse A M +0x0B AddTrusted­ +RootCertifi­ +cate +``` +``` +client ⇒ server Y A M +``` +**11.18.6.1. AttestationRequest Command** + +This command SHALL be generated to request the Attestation Information, in the form of an Attes­ +tationResponse Command. If the AttestationNonce that is provided in the command is malformed, a +recipient SHALL fail the command with a Status Code of INVALID_COMMAND. The Attestation­ +Nonce field SHALL be used in the computation of the Attestation Information. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Attestation­ +Nonce +``` +``` +octstr 32 M +``` +**11.18.6.2. AttestationResponse Command** + +This command SHALL be generated in response to an Attestation Request command. + +``` +Page 900 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +See Section 11.18.4.7, “Attestation Information” for details about the generation of the fields within +this response command. + +See Section F.2, “Device Attestation Response test vector” for an example computation of an Attesta­ +tionResponse. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Attesta­ +tionEle­ +ments +``` +``` +octstr max RESP_­ +MAX +``` +### M + +``` +1 Attesta­ +tionSigna­ +ture +``` +``` +octstr 64 M +``` +**AttestationElements Field** + +This field SHALL contain the octet string of the serialized attestation_elements_message. + +**AttestationSignature Field** + +This field SHALL contain the octet string of the necessary attestation_signature as described in Sec­ +tion 11.18.4.7, “Attestation Information”. + +**11.18.6.3. CertificateChainRequest Command** + +If the CertificateType is not a valid value per CertificateChainTypeEnum then the command SHALL +fail with a Status Code of INVALID_COMMAND. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Certificate­ +Type +``` +``` +Certificate­ +ChainType­ +Enum +``` +``` +desc M +``` +**11.18.6.4. CertificateChainResponse Command** + +This command SHALL be generated in response to a CertificateChainRequest command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Certificate octstr max 600 M +``` +**Certificate Field** + +This field SHALL be the DER encoded certificate corresponding to the CertificateType field in the +CertificateChainRequest command. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 901 +``` + +**11.18.6.5. CSRRequest Command** + +This command SHALL be generated to execute the Node Operational CSR Procedure and subse­ +quently return the NOCSR Information, in the form of a CSRResponse Command. + +The CSRNonce field SHALL be used in the computation of the NOCSR Information. If the CSRNonce +is malformed, then this command SHALL fail with an INVALID_COMMAND status code. + +If the IsForUpdateNOC field is present and set to true, but the command was received over a PASE +session, the command SHALL fail with an INVALID_COMMAND status code, as it would never be +possible to use a resulting subsequent certificate issued from the CSR with the UpdateNOC com­ +mand, which is forbidden over PASE sessions. + +If the IsForUpdateNOC field is present and set to true, the internal state of the CSR associated key­ +pair SHALL be tagged as being for a subsequent UpdateNOC, otherwise the internal state of the CSR +SHALL be tagged as being for a subsequent AddNOC. See AddNOC and UpdateNOC for details about +the processing. + +If this command is received without an armed fail-safe context (see ArmFailSafe), then this com­ +mand SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator. + +If a prior UpdateNOC or AddNOC command was successfully executed within the fail-safe timer +period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini­ +tiator. + +If the Node Operational Key Pair generated during processing of the Node Operational CSR Proce­ +dure is found to collide with an existing key pair already previously generated and installed, and +that check had been executed, then this command SHALL fail with a FAILURE status code sent back +to the initiator. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 CSRNonce octstr 32 M +1 IsForUp­ +dateNOC +``` +``` +bool false O +``` +**11.18.6.6. CSRResponse Command** + +This command SHALL be generated in response to a CSRRequest Command. + +See Section 11.18.4.9, “NOCSR Information” for details about the generation of the fields within this +response command. + +See Section F.3, “Node Operational CSR Response test vector” for an example computation of a CSR­ +Response. + +``` +Page 902 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NOCSREle­ +ments +``` +``` +octstr max RESP_­ +MAX +``` +### M + +``` +1 Attesta­ +tionSigna­ +ture +``` +``` +octstr 64 M +``` +**NOCSRElements Field** + +This field SHALL contain the octet string of the serialized nocsr_elements_message. + +**AttestationSignature Field** + +This field SHALL contain the octet string of the necessary attestation_signature as described in Sec­ +tion 11.18.4.9, “NOCSR Information”. + +**11.18.6.7. AddNOC and UpdateNOC Commands Overview** + +The AddNOC command is used to commission a Node into a Fabric by providing a usable NOC and +ICAC, with associated Node Operational IDs. + +The UpdateNOC command is used to update existing credentials within a Fabric, for the purposes +of: + +- Rotating the Node Operational Key Pair in use +- Updating the contents of the NOC and optionally the ICAC certificates (subjects, issuers, keys, + etc) under the current root of trust and Fabric + +Both of these commands receive an NOCValue and optional ICACValue fields and require some com­ +mon validation in addition to their specific behavior. + +**NOCValue and ICACValue Fields** + +The NOCValue and ICACValue fields SHALL be octet strings that represent a certificate encoded +using Matter Certificate Encoding. + +Upon receipt, the NOCValue and ICACValue chain SHALL be validated in the following ways: + +1. Verify the NOC using: + +``` +a. Crypto_VerifyChain(certificates = [NOCValue, ICACValue, RootCACertificate]) if ICACValue is +present, +b. Crypto_VerifyChain(certificates = [NOCValue, RootCACertificate]) if ICACValue is not present. +If this verification fails, the error status SHALL be InvalidNOC. +``` +2. The public key of the NOC SHALL match the last generated operational public key on this ses­ + sion, and therefore the public key present in the last CSRResponse provided to the Administra­ + tor or Commissioner that sent the AddNOC or UpdateNOC command. If this check fails, the error + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 903 +``` + +``` +status SHALL be InvalidPublicKey. +``` +3. The DN Encoding Rules SHALL be validated for every certificate in the chain, including valid + value range checks for identifiers such as Fabric ID and Node ID. If this validation fails, the + error status SHALL be InvalidNodeOpId if the matter-node-id attribute in the subject DN of the + NOC has a value outside the Operational Node ID range and InvalidNOC for all other failures. + +If any of the above validation checks fail, the server SHALL immediately respond to the client with +an NOCResponse. The StatusCode field of the NOCResponse SHALL be set to the error status value +specified in the above validation checks. + +These certificate validation steps are performed to ensure that operational credentials installed +match an operational key pair generated by the Device and respect the trust model assumptions +expressed in Section 6.4.5.1, “Node Operational Certificate (NOC)”. + +**Handling Errors** + +For any error described in the following subsections, the device SHALL immediately respond to the +client with an NOCResponse with the prescribed StatusCode field, and SHALL leave all non-volatile +state of the device untouched, as if the AddNOC command had never been received. The informa­ +tion about the last CSR state associated with this session SHALL also be untouched in this case, so +that a valid AddNOC command MAY still be issued later that would match that CSR state. The +DebugText field in the NOCResponse MAY be filled with debug information. + +The following failed preconditions error cases apply to all invocations of AddNOC: + +- If the device already has the CommissionedFabrics attribute equal to the SupportedFabrics + attribute, then the device’s operational credentials table is considered full and the device + SHALL process the error by responding with a StatusCode of TableFull as described in Section + 11.18.6.7.2, “Handling Errors”. +- If no context or memory exists of a prior CSRRequest command having been invoked in the + **same secure session** as that which is receiving this AddNOC or UpdateNOC invocation, then the + Node SHALL process the error by responding with a StatusCode of MissingCsr as described in + Section 11.18.6.7.2, “Handling Errors”. + +**11.18.6.8. AddNOC Command** + +This command SHALL add a new NOC chain to the device and commission a new Fabric association +upon successful validation of all arguments and preconditions. + +The new value SHALL immediately be reflected in the NOCs list attribute. + +A Commissioner or Administrator SHALL issue this command after issuing the CSRRequest com­ +mand and receiving its response. + +A Commissioner or Administrator SHOULD issue this command after performing the Attestation +Procedure. + +``` +Page 904 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NOCValue octstr max 400 M +1 ICACValue octstr max 400 O +2 IPKValue octstr 16 M +3 CaseAdmin­ +Subject +``` +``` +SubjectID M +``` +``` +4 AdminVen­ +dorId +``` +``` +vendor-id M +``` +**IPKValue Field** + +This field SHALL contain the value of the Epoch Key for the Identity Protection Key (IPK) to set for +the Fabric which is to be added. This is needed to bootstrap a necessary configuration value for sub­ +sequent CASE to succeed. See Section 4.14.2.6.1, “Identity Protection Key (IPK)” for details. + +The IPK SHALL be provided as an octet string of length CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES. + +On successful execution of the AddNOC command, the side-effect of having provided this field +SHALL be equivalent to having done a GroupKeyManagement cluster KeySetWrite command invo­ +cation using the newly joined fabric as the accessing fabric and with the following argument fields +(assuming KeySetWrite allowed a GroupKeySetID set to 0): + +``` +KeySetWrite +( +GroupKeySetStruct := +{ +GroupKeySetID := 0, +GroupKeySecurityPolicy := 0, +EpochKey0 := , +EpochStartTime0 := 0, +EpochKey1 := null +EpochStartTime1 := null +EpochKey2 := null, +EpochStartTime2 := null +} +) +``` +**CaseAdminSubject Field** + +If the AddNOC command succeeds according to the semantics of the following subsections, then the +Access Control SubjectID SHALL be used to atomically add an Access Control Entry enabling that +Subject to subsequently administer the Node whose operational identity is being added by this com­ +mand. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 905 +``` + +The format of the new Access Control Entry, created from this, SHALL be: + +### { + +``` +FabricIndex: **FabricIndex derived from current or new Fabric**, +Privilege: Administer, +AuthMode: CASE, +Subjects: [**CaseAdminSubject provided in the AddNOC command**], +Targets: [], // entire node +Extension: [] // empty +} +``` +### NOTE + +``` +Unless such an Access Control Entry is added atomically as described here, there +would be no way for the caller on its given Fabric to eventually add another Access +Control Entry for CASE authentication mode, to enable the new Administrator to +administer the device, since the Fabric Scoping of the Access Control List prevents +the current Node from being able to write new entries scoped to that Fabric, if the +session is established from CASE. While a session established from PASE does gain +Fabric Scope of a newly-joined Fabric, this argument is made mandatory to provide +symmetry between both types of session establishment, both of which need to even­ +tually add an "Administer Node over CASE" Access Control Entry to finalize new +Fabric configuration and subsequently be able to call the CommissioningComplete +command. +``` +**AdminVendorID Field** + +This field SHALL be set to the Vendor ID of the entity issuing the AddNOC command. This value +SHALL NOT be one of the reserved Vendor ID values defined in Table 1, “Vendor ID Allocations”. + +**Effect When Received** + +If this command is received without an armed fail-safe context (see ArmFailSafe), then this com­ +mand SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator. + +If a prior UpdateNOC or AddNOC command was successfully executed within the fail-safe timer +period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini­ +tiator. + +If the prior CSRRequest state that preceded AddNOC had the IsForUpdateNOC field indicated as +true, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the initia­ +tor. + +If no prior AddTrustedRootCertificate command was successfully executed within the fail-safe +timer period, then this command SHALL process an error by responding with a NOCResponse with +a StatusCode of InvalidNOC as described in Section 11.18.6.7.2, “Handling Errors”. In other words, +AddNOC always requires that the client provides the root of trust certificate within the same Fail- +Safe context as the rest of the new fabric’s operational credentials, even if some other fabric +already uses the exact same root of trust certificate. + +``` +Page 906 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +If the NOC provided in the NOCValue encodes an Operational Identifier for a pair already present on the device, then the device SHALL process the error by responding +with a StatusCode of FabricConflict as described in Section 11.18.6.7.2, “Handling Errors”. + +If the device already has the CommissionedFabrics attribute equal to the SupportedFabrics +attribute, then the device’s operational credentials table is considered full and the device SHALL +process the error by responding with a StatusCode of TableFull as described in Section 11.18.6.7.2, +“Handling Errors”. + +If the CaseAdminSubject field is not a valid ACL subject in the context of AuthMode set to CASE, +such as not being in either the Operational or CASE Authenticated Tag range, then the device +SHALL process the error by responding with a StatusCode of InvalidAdminSubject as described in +Section 11.18.6.7.2, “Handling Errors”. + +Otherwise, the command is considered an addition of credentials, also known as "joining a fabric", +and the following SHALL apply: + +1. A new FabricIndex SHALL be allocated, taking the next valid fabric-index value in monotoni­ + cally incrementing order, wrapping around from 254 (0xFE) to 1, since value 0 is reserved and + using 255 (0xFF) would prevent cluster specifications from using nullable fabric-idx fields. +2. An entry within the Fabrics attribute table SHALL be added, reflecting the matter-fabric-id RDN + within the NOC’s subject, along with the public key of the trusted root of the chain and the + AdminVendorID field. +3. The operational key pair associated with the incoming NOC from the NOCValue, and generated + by the prior CSRRequest command, SHALL be recorded for subsequent use during CASE within + the fail-safe timer period (see Section 5.5, “Commissioning Flows”). +4. The incoming NOCValue and ICACValue (if present) SHALL be stored under the FabricIndex + associated with the new Fabric Scope, along with the RootCACertificate provided with the prior + successful AddTrustedRootCertificate command invoked in the same fail-safe period. + a. Implementation of certificate chain storage MAY separate or otherwise encode the compo­ + nents of the array in implementation-specific ways, as long as they follow the correct format + when being read from the NOCs list or used within other protocols such as CASE. +5. The NOCs list SHALL reflect the incoming NOC from the NOCValue field and ICAC from the ICAC­ + Value field (if present). +6. The operational discovery service record SHALL immediately reflect the new Operational Iden­ + tifier, such that the Node immediately begins to exist within the Fabric and becomes reachable + over CASE under the new operational identity. +7. The receiver SHALL create and add a new Access Control Entry using the CaseAdminSubject + field to grant subsequent Administer access to an Administrator member of the new Fabric. It is + RECOMMENDED that the Administrator presented in CaseAdminSubject exist within the same + entity that is currently invoking the AddNOC command, within another of the Fabrics of which + it is a member. + a. If the Managed Device Feature is implemented by the ACL cluster, then one or more ARL + entries with the new FabricIndex MAY be added to the ARL attribute. +8. The incoming IPKValue SHALL be stored in the Fabric-scoped slot within the Group Key Man­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 907 +``` + +``` +agement cluster (see KeySetWrite), for subsequent use during CASE. +``` +9. The Fabric Index associated with the armed fail-safe context (see ArmFailSafe) SHALL be + updated to match the Fabric Index just allocated. + +10.If the current secure session was established with PASE, the receiver SHALL: + +``` +a.Augment the secure session context with the FabricIndex generated above, such that subse­ +quent interactions have the proper accessing fabric. +``` +11.If the current secure session was established with CASE, subsequent configuration of the newly +installed Fabric requires the opening of a new CASE session from the Administrator from the +Fabric just installed. This Administrator is the one listed in the CaseAdminSubject argument. + +Thereafter, the Node SHALL respond with an NOCResponse with a StatusCode of OK and a FabricIn­ +dex field matching the FabricIndex under which the new Node Operational Certificate (NOC) is +scoped. + +**11.18.6.9. UpdateNOC Command** + +This command SHALL replace the NOC and optional associated ICAC (if present) scoped under the +accessing fabric upon successful validation of all arguments and preconditions. The new value +SHALL immediately be reflected in the NOCs list attribute. + +A Commissioner or Administrator SHALL issue this command after issuing the CSRRequest Com­ +mand and receiving its response. + +A Commissioner or Administrator SHOULD issue this command after performing the Attestation +Procedure. + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Confor­ +mance +0 NOCValue octstr max 400 M +1 ICACValue octstr max 400 O +``` +**Effect When Received** + +If this command is received without an armed fail-safe context (see ArmFailSafe), then this com­ +mand SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator. + +If a prior UpdateNOC or AddNOC command was successfully executed within the fail-safe timer +period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini­ +tiator. + +If a prior AddTrustedRootCertificate command was successfully invoked within the fail-safe timer +period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini­ +tiator, since the only valid following logical operation is invoking the AddNOC command. + +If the prior CSRRequest state that preceded UpdateNOC had the IsForUpdateNOC field indicated as +false, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the initia­ + +``` +Page 908 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +tor. + +If any of the following conditions arise, the Node SHALL process an error by responding with an +NOCResponse with a StatusCode of InvalidNOC as described in Section 11.18.6.7.2, “Handling +Errors”: + +- The NOC provided in the NOCValue does not refer in its subject to the FabricID associated with + the accessing fabric. +- The ICAC provided in the ICACValue (if present) has a FabricID in its subject that does not match + the FabricID associated with the accessing fabric. + +Otherwise, the command is considered an update of existing credentials for a given Fabric, and the +following SHALL apply: + +1. The Operational Certificate under the accessing fabric index in the NOCs list SHALL be updated + to match the incoming NOCValue and ICACValue (if present), such that the Node’s Operational + Identifier within the Fabric immediately changes. + a. The operational key pair associated with the incoming NOC from the NOCValue, and gener­ + ated by the prior CSRRequest command, SHALL be committed to permanent storage, for + subsequent use during CASE. + b. The operational discovery service record SHALL immediately reflect the new Operational + Identifier. +c. All internal data reflecting the prior operational identifier of the Node within the Fabric +SHALL be revoked and removed, to an outcome equivalent to the disappearance of the prior +Node, except for the ongoing CASE session context, which SHALL temporarily remain valid +until the NOCResponse has been successfully delivered or until the next transport-layer +error, so that the response can be received by the Administrator invoking the command. + +Thereafter, the Node SHALL respond with an NOCResponse with a StatusCode of OK and a FabricIn­ +dex field matching the FabricIndex under which the updated NOC is scoped. + +**11.18.6.10. NOCResponse Command** + +This command SHALL be generated in response to the following commands: + +- AddNOC +- UpdateNOC +- UpdateFabricLabel +- RemoveFabric + +It provides status information about the success or failure of those commands. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 909 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StatusCode NodeOpera­ +tionalCert­ +StatusEnum +``` +### M + +``` +1 FabricIndex fabric-idx 1 to 254 O +2 DebugText string max 128 O +``` +**StatusCode Field** + +This field SHALL contain an NOCStatus value representing the status of an operation involving a +NOC. + +**FabricIndex Field** + +This field SHALL be present whenever StatusCode has a value of OK. If present, it SHALL contain +the Fabric Index of the Fabric last added, removed or updated. + +**DebugText Field** + +This field MAY contain debugging textual information from the cluster implementation, which +SHOULD NOT be presented to user interfaces in any way. Its purpose is to help developers in trou­ +bleshooting errors and the contents MAY go into logs or crash reports. + +**11.18.6.11. UpdateFabricLabel Command** + +This command SHALL be used by an Administrator to set the user-visible Label field for a given +Fabric, as reflected by entries in the Fabrics attribute. An Administrator SHALL use this command +to set the Label to a string (possibly selected by the user themselves) that the user can recognize +and relate to this Administrator + +- during the commissioning process, and +- whenever the user chooses to update this string. + +The Label field, along with the VendorID field in the same entry of the Fabrics attribute, SHOULD be +used by Administrators to provide additional per-fabric context when operations such as Remove­ +Fabric are considered or used. + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Confor­ +mance +0 Label string max 32 M +``` +**Label Field** + +This field SHALL contain the label to set for the fabric associated with the current secure session. + +``` +Page 910 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Effect on Receipt** + +If the Label field is identical to a Label already in use by a Fabric within the Fabrics list that is not +the accessing fabric, then an NOCResponse with a StatusCode of LabelConflict SHALL be returned +for the command and there SHALL NOT be any permanent changes to any Fabric data. + +Otherwise, the Label field for the accessing fabric SHALL immediately be updated to reflect the +Label argument provided. Following the update, an NOCResponse with a StatusCode of OK SHALL +be returned. + +If the command was invoked within a fail-safe context after a successful UpdateNOC command, +then the label update SHALL apply to the pending update state that will be reverted if fail-safe +expires prior to a CommissioningComplete command. In other words, label updates apply to the +state of the Fabrics Attribute as currently visible, even for an existing fabric currently in process of +being updated. + +**11.18.6.12. RemoveFabric Command** + +This command is used by Administrators to remove a given Fabric and **delete all associated fab­ +ric-scoped data**. + +If the given Fabric being removed is the last one to reference a given Trusted Root CA Certificate +stored in the Trusted Root Certificates list, then that Trusted Root Certificate SHALL be removed. + +### WARNING + +``` +This command, if referring to an already existing Fabric not under the control +of the invoking Administrator, SHALL ONLY be invoked after obtaining some +form of explicit user consent through some method executed by the Adminis­ +trator or Commissioner. This method of obtaining consent SHOULD employ as +much data as possible about the existing Fabric associations within the Fabrics +list, so that likelihood is as small as possible of a user removing a Fabric unwit­ +tingly. If a method exists for an Administrator or Commissioner to convey Fab­ +ric Removal to an entity related to that Fabric, whether in-band or out-of-band, +then this method SHOULD be used to notify the other Administrative Domain’s +party of the removal. Otherwise, users may only observe the removal of a Fab­ +ric association as persistently failing attempts to reach a Node operationally. +``` +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 FabricIndex fabric-idx 1 to 254 M +``` +**FabricIndex Field** + +This field SHALL contain the Fabric Index reference (see fabric-index) associated with the Fabric +which is to be removed from the device. + +**Effect on Receipt** + +If the FabricIndex field does not match the FabricIndex of any entry within the Fabrics list, then an +NOCResponse with a StatusCode of InvalidFabricIndex SHALL be returned for the command and + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 911 +``` + +there SHALL NOT be any permanent changes to any device data. + +Otherwise, one of the following outcomes SHALL occur: + +1. If the FabricIndex matches the last remaining entry in the Fabrics list, then the device SHALL + delete all Matter related data on the node which was created since it was commissioned. This + includes all Fabric-Scoped data, including Access Control List, Access Restriction List, bindings, + scenes, group keys, operational certificates, etc. All Trusted Roots SHALL also be removed. If a + time synchronization cluster is present on the Node, the TrustedTimeSource and DefaultNtp + SHALL be set to null. Any Matter related data including logs, secure sessions, exchanges and + interaction model constructs SHALL also be removed. Since this operation involves the removal + of the secure session data that may underpin the current set of exchanges, the Node invoking + the command SHOULD NOT expect a response before terminating its secure session with the + target. +2. If the FabricIndex does not equal the accessing fabric index, then the device SHALL begin the + process of irrevocably deleting all associated Fabric-Scoped data, including Access Control + Entries, Access Restriction Entries, bindings, group keys, operational certificates, etc. Any + remaining Trusted Roots no longer referenced by any operational certificate SHALL also be + removed. If a time synchronization cluster is present on the Node, and the TrustedTimeSource + FabricIndex matches the given FabricIndex, the TrustedTimeSource SHALL be set to null. All + secure sessions, exchanges and interaction model constructs related to the Operational Identity + under the given Fabric SHALL also be removed. Following the removal, an NOCResponse with a + StatusCode of OK SHALL be returned. +3. If the FabricIndex equals the accessing fabric index, then the device SHALL begin the process of + irrevocably deleting all associated Fabric-Scoped data, including Access Control Entries, Access + Restriction Entries, bindings, group keys, operational certificates, etc. Any remaining Trusted + Roots no longer referenced by any operational certificate SHALL also be removed. If a time syn­ + chronization cluster is present on the Node, and the TrustedTimeSource FabricIndex matches + the given FabricIndex, the TrustedTimeSource SHALL be set to null. All secure sessions, + exchanges and interaction model constructs related to the Operational Identity under the given + Fabric SHALL also be removed. Since this operation involves the removal of the secure session + data that may underpin the current set of exchanges, the Node invoking the command SHOULD + NOT expect a response before terminating its secure session with the target. + +**11.18.6.13. AddTrustedRootCertificate Command** + +This command SHALL add a Trusted Root CA Certificate, provided as its Matter Certificate Encoding +representation, to the TrustedRootCertificates Attribute list and SHALL ensure the next AddNOC +command executed uses the provided certificate as its root of trust. + +If the certificate from the RootCACertificate field is already installed, based on exact byte-for-byte +equality, then this command SHALL succeed with no change to the list. + +If this command is received without an armed fail-safe context (see ArmFailSafe), then this com­ +mand SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator. + +If a prior AddTrustedRootCertificate command was successfully invoked within the fail-safe timer +period, which would cause the new invocation to add a second root certificate within a given fail- + +``` +Page 912 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +safe timer period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back +to the initiator. + +If a prior UpdateNOC or AddNOC command was successfully executed within the fail-safe timer +period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini­ +tiator. + +If the certificate from the RootCACertificate field fails any validity checks, not fulfilling all the +requirements for a valid Matter Certificate Encoding representation, including a truncated or over­ +size value, then this command SHALL fail with an INVALID_COMMAND status code sent back to the +initiator. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 RootCACer­ +tificate +``` +``` +octstr max 400 M +``` +Note that the only method of removing a trusted root is by removing the Fabric that uses it as its +root of trust using the RemoveFabric command. + +**11.19. Administrator Commissioning Cluster** + +This cluster is used to trigger a Node to allow a new Administrator to commission it. It defines +Attributes, Commands and Responses needed for this purpose. + +There are two methods of commissioning, Basic Commissioning which MAY be supported and is +described in Section 5.6.2, “Basic Commissioning Method (BCM)” and Enhanced Commissioning +which SHALL be supported and is described in Section 5.6.3, “Enhanced Commissioning Method +(ECM)”. + +For the management of Operational Credentials and Trusted Root Certificates, the Node Operational +Credentials cluster is used. + +If the Administrator Commissioning Cluster server instance is present on an endpoint with the Root +Node device type in the Descriptor cluster DeviceTypeList, then: + +- The Commissioning Window SHALL be opened or closed on the node that the Root Node end­ + point is on. +- The attributes SHALL indicate the state of the node that the Root Node endpoint is on. + +If the Administrator Commissioning Cluster server instance is present on an endpoint with the +Bridged Node device type in the Descriptor cluster DeviceTypeList, then: + +- The Commissioning Window SHALL be opened or closed on the node represented by the + Bridged Node. +- The attributes SHALL indicate the state of the node that is represented by the Bridged Node. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 913 +``` + +**11.19.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.19.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node CADMIN +``` +**11.19.3. Cluster ID** + +``` +ID Name +0x003C Administrator Commissioning +``` +**11.19.4. Features** + +This cluster SHALL support the FeatureMap bitmap attribute as defined below. + +``` +Bit Code Feature Summary +0 BC Basic Node supports Basic +Commissioning +Method. +``` +**11.19.5. Data Types** + +**11.19.5.1. CommissioningWindowStatusEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 WindowNotOpen Commissioning win­ +dow not open +``` +### M + +``` +1 EnhancedWin­ +dowOpen +``` +``` +An Enhanced Commis­ +sioning Method win­ +dow is open +``` +### M + +``` +2 BasicWindowOpen A Basic Commissioning +Method window is +open +``` +### BC + +``` +Page 914 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.19.6. Status Codes** + +**11.19.6.1. StatusCodeEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0x02 Busy Could not be completed +because another com­ +missioning is in +progress +``` +### M + +``` +0x03 PAKEParameterError Provided PAKE parame­ +ters were incorrectly +formatted or otherwise +invalid +``` +### M + +``` +0x04 WindowNotOpen No commissioning win­ +dow was currently +open +``` +### M + +**11.19.7. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Window­ +Status +``` +``` +Commis­ +sioning­ +Window­ +Sta­ +tusEnum +``` +### R V M + +``` +0x0001 Admin­ +FabricIn­ +dex +``` +``` +fabric-idx X R V M +``` +``` +0x0002 Admin­ +VendorId +``` +``` +vendor-id X R V M +``` +**11.19.7.1. WindowStatus Attribute** + +This attribute SHALL indicate whether a new Commissioning window has been opened by an +Administrator, using either the OpenCommissioningWindow command or the OpenBasicCommis­ +sioningWindow command. + +This attribute SHALL revert to WindowNotOpen upon expiry of a commissioning window. + +### NOTE + +``` +An initial commissioning window is not opened using either the OpenCommission­ +ingWindow command or the OpenBasicCommissioningWindow command, and +therefore this attribute SHALL be set to WindowNotOpen on initial commissioning. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 915 +``` + +**11.19.7.2. AdminFabricIndex Attribute** + +When the WindowStatus attribute is not set to WindowNotOpen, this attribute SHALL indicate the +FabricIndex associated with the Fabric scoping of the Administrator that opened the window. This +MAY be used to cross-reference in the Fabrics attribute of the Node Operational Credentials cluster. + +If, during an open commissioning window, the fabric for the Administrator that opened the win­ +dow is removed, then this attribute SHALL be set to null. + +When the WindowStatus attribute is set to WindowNotOpen, this attribute SHALL be set to null. + +**11.19.7.3. AdminVendorId Attribute** + +When the WindowStatus attribute is not set to WindowNotOpen, this attribute SHALL indicate the +Vendor ID associated with the Fabric scoping of the Administrator that opened the window. This +field SHALL match the VendorID field of the Fabrics attribute list entry associated with the Admin­ +istrator having opened the window, at the time of window opening. If the fabric for the Administra­ +tor that opened the window is removed from the node while the commissioning window is still +open, this attribute SHALL NOT be updated. + +When the WindowStatus attribute is set to WindowNotOpen, this attribute SHALL be set to null. + +**11.19.8. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 OpenCommis­ +sioningWin­ +dow +``` +``` +client ⇒ server Y A T M +``` +``` +0x01 OpenBasic­ +Commission­ +ingWindow +``` +``` +client ⇒ server Y A T BC +``` +``` +0x02 RevokeCom­ +missioning +``` +``` +client ⇒ server Y A T M +``` +Only one commissioning window can be active at a time. If a Node receives another open commis­ +sioning command when an Open Commissioning Window is already active, it SHALL return a fail­ +ure response (see Section 11.19.6, “Status Codes”). + +**11.19.8.1. OpenCommissioningWindow Command** + +This command is used by a current Administrator to instruct a Node to go into commissioning +mode. The Enhanced Commissioning Method specifies a window of time during which an already +commissioned Node accepts PASE sessions. The current Administrator MUST specify a timeout +value for the duration of the OpenCommissioningWindow command. + +When the OpenCommissioningWindow command expires or commissioning completes, the Node +SHALL remove the Passcode by deleting the PAKE passcode verifier as well as stop publishing the +DNS-SD record corresponding to this command as described in Section 4.3.1, “Commissionable + +``` +Page 916 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Node Discovery”. The commissioning into a new Fabric completes when the Node successfully +receives a CommissioningComplete command, see Section 5.5, “Commissioning Flows”. + +The parameters for OpenCommissioningWindow command are as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Commis­ +sioning­ +Timeout +``` +``` +uint16 desc M +``` +``` +1 PAKEPass­ +codeVeri­ +fier +``` +``` +octstr all M +``` +``` +2 Discrimina­ +tor +``` +``` +uint16 0 to 4095 M +``` +``` +3 Iterations uint32 1000 to +100000 +``` +### M + +``` +4 Salt octstr 16 to 32 M +``` +A current Administrator MAY invoke this command to put a node in commissioning mode for the +next Administrator. On completion, the command SHALL return a cluster specific status code from +the Section 11.19.6, “Status Codes” below reflecting success or reasons for failure of the operation. +The new Administrator SHALL discover the Node on the IP network using DNS-based Service Dis­ +covery (DNS-SD) for commissioning. + +If any format or validity errors related to the PAKEPasscodeVerifier, Iterations or Salt arguments +arise, this command SHALL fail with a cluster specific status code of PAKEParameterError. + +If a commissioning window is already currently open, this command SHALL fail with a cluster spe­ +cific status code of Busy. + +If the fail-safe timer is currently armed, this command SHALL fail with a cluster specific status code +of Busy, since it is likely that concurrent commissioning operations from multiple separate Commis­ +sioners are about to take place. + +In case of any other parameter error, this command SHALL fail with a status code of COM­ +MAND_INVALID. + +**CommissioningTimeout Field** + +This field SHALL specify the time in seconds during which commissioning session establishment is +allowed by the Node. This timeout value SHALL follow guidance as specified in the initial +Announcement Duration. The CommissioningTimeout applies only to cessation of any announce­ +ments and to accepting of new commissioning sessions; it does not apply to abortion of connec­ +tions, i.e., a commissioning session SHOULD NOT abort prematurely upon expiration of this time­ +out. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 917 +``` + +**PAKEPasscodeVerifier Field** + +This field SHALL specify an ephemeral PAKE passcode verifier (see Section 3.10, “Password-Authen­ +ticated Key Exchange (PAKE)”) computed by the existing Administrator to be used for this commis­ +sioning. The field is concatenation of two values (w0 || L) SHALL be (CRYPTO_GROUP_SIZE_BYTES + +CRYPTO_PUBLIC_KEY_SIZE_BYTES)-octets long as detailed in Crypto_PAKEValues_Responder. It SHALL be +derived from an ephemeral passcode (See PAKE). It SHALL be deleted by the Node at the end of +commissioning or expiration of the OpenCommissioningWindow command, and SHALL be deleted +by the existing Administrator after sending it to the Node(s). + +**Discriminator Field** + +This field SHALL be used by the Node as the long discriminator for DNS-SD advertisement (see +Commissioning Discriminator) for discovery by the new Administrator. The new Administrator can +find and filter DNS-SD records by long discriminator to locate and initiate commissioning with the +appropriate Node. + +**Iterations Field** + +This field SHALL be used by the Node as the PAKE iteration count associated with the ephemeral +PAKE passcode verifier to be used for this commissioning, which SHALL be sent by the Node to the +new Administrator’s software as response to the PBKDFParamRequest during PASE negotiation. +The permitted range of values SHALL match the range specified in Section 3.9, “Password-Based +Key Derivation Function (PBKDF)”, within the definition of the Crypto_PBKDFParameterSet. + +**Salt Field** + +This field SHALL be used by the Node as the PAKE Salt associated with the ephemeral PAKE pass­ +code verifier to be used for this commissioning, which SHALL be sent by the Node to the new +Administrator’s software as response to the PBKDFParamRequest during PASE negotiation. The +constraints on the value SHALL match those specified in Section 3.9, “Password-Based Key Deriva­ +tion Function (PBKDF)”, within the definition of the Crypto_PBKDFParameterSet. + +When a Node receives the Open Commissioning Window command, it SHALL begin advertising on +DNS-SD as described in Section 4.3.1, “Commissionable Node Discovery” and for a time period as +described in CommissioningTimeout. When the command is received by a ICD, it SHALL enter into +active mode. The ICD SHALL remain in Active Mode as long as one of these conditions is met: + +- A commissioning window is open. +- There is an armed fail-safe timer. + +**11.19.8.2. OpenBasicCommissioningWindow Command** + +This command MAY be used by a current Administrator to instruct a Node to go into commissioning +mode, if the node supports the Basic Commissioning Method. The Basic Commissioning Method +specifies a window of time during which an already commissioned Node accepts PASE sessions. The +current Administrator SHALL specify a timeout value for the duration of the OpenBasicCommis­ +sioningWindow command. + +If a commissioning window is already currently open, this command SHALL fail with a cluster spe­ + +``` +Page 918 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +cific status code of Busy. + +If the fail-safe timer is currently armed, this command SHALL fail with a cluster specific status code +of Busy, since it is likely that concurrent commissioning operations from multiple separate Commis­ +sioners are about to take place. + +In case of any other parameter error, this command SHALL fail with a status code of COM­ +MAND_INVALID. + +The commissioning into a new Fabric completes when the Node successfully receives a Commis­ +sioningComplete command, see Section 5.5, “Commissioning Flows”. The new Administrator SHALL +discover the Node on the IP network using DNS-based Service Discovery (DNS-SD) for commission­ +ing. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Commis­ +sioning­ +Timeout +``` +``` +uint16 desc M +``` +**CommissioningTimeout Field** + +This field SHALL specify the time in seconds during which commissioning session establishment is +allowed by the Node. This timeout SHALL follow guidance as specified in the initial Announcement +Duration. + +When a Node receives the OpenBasicCommissioningWindow command, it SHALL begin advertising +on DNS-SD as described in Section 4.3.1, “Commissionable Node Discovery” and for a time period as +described in CommissioningTimeout. When the command is received by a ICD, it SHALL enter into +active mode. The ICD SHALL remain in Active Mode as long as one of these conditions is met: + +- A commissioning window is open. +- There is an armed fail-safe timer. + +**11.19.8.3. RevokeCommissioning Command** + +This command is used by a current Administrator to instruct a Node to revoke any active OpenCom­ +missioningWindow or OpenBasicCommissioningWindow command. This is an idempotent com­ +mand and the Node SHALL (for ECM) delete the temporary PAKEPasscodeVerifier and associated +data, and stop publishing the DNS-SD record associated with the OpenCommissioningWindow or +OpenBasicCommissioningWindow command, see Section 4.3.1, “Commissionable Node Discovery”. + +If no commissioning window was open at time of receipt, this command SHALL fail with a cluster +specific status code of WindowNotOpen. + +If the commissioning window was open and the fail-safe was armed when this command is +received, the device SHALL immediately expire the fail-safe and perform the cleanup steps outlined + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 919 +``` + +in Section 11.10.7.2.2, “Behavior on expiry of Fail-Safe timer”. + +**11.20. Over-the-Air (OTA) Software Update** + +**11.20.1. Scope & Purpose** + +The majority of IoT devices require security and/or functional feature updates during their lifetime. + +This section describes a set of OTA software update capabilities which enable an "OTA Requestor" to +be informed of, obtain, and install software updates from a Node fulfilling the role of an "OTA +Provider". + +An "OTA Requestor" is any Node implementing the OTA Requestor Device Type (0x0012), which ful­ +fills the client role for the OTA Software Update Provider cluster and the server role for the OTA +Software Update Requestor cluster. An "OTA Provider" is any Node implementing the OTA Provider +Device Type (0x0014), which fulfills the server role for the OTA Software Update Provider cluster +and the client role for the OTA Software Update Requestor cluster. + +The OTA updates capabilities are designed to support: + +- A mechanism to inform OTA Requestors about available OTA Providers. +- A mechanism to allow OTA Requestors to acquire information about available OTA Software + Images. +- A mechanism to allow constrained OTA Requestors to obtain OTA Software Images through a + local proxy, e.g. if they are not able or willing to proceed with a direct download from the Inter­ + net. +- A mechanism to allow OTA Requestors supporting legacy, non-native, or out-of-band update + methods to notify an OTA Provider of having completed an update out-of-band. +- A mechanism to allow deferred installation of a software update, based on administrative rules. +- A mechanism to allow user consent to be considered before offering Software Images to OTA + Requestors. + +OTA Requestors wishing to update their software using these capabilities MAY need to use an appli­ +cation bootloader and MAY require sufficient additional storage in order to download an OTA +image. + +Furthermore, to encourage interoperability and timely software updates, the OTA update mecha­ +nisms provide means of obtaining Software Images which can be uniformly implemented across +OTA Requestors on devices from a variety of different vendors. The OTA Providers SHOULD provide +services to OTA Requestors from vendors other than its own, as long as the location of Software +Update images for these vendors is found. The Distributed Compliance Ledger is one such central­ +ized source of software update image locations that MAY allow OTA Providers to provide OTA Soft­ +ware Update Images generically to devices from many vendors. + +**11.20.2. Functional overview** + +An OTA Requestor SHALL query the OTA Provider periodically to determine the availability of new + +``` +Page 920 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Software Images. The OTA Provider MAY learn, from backend systems inside or outside of Fabric +scope, of the availability of a new Software Image for an OTA Requestor. + +An OTA Requestor which has been updated using a mechanism beyond this Cluster MAY report to +an OTA Provider that a Software Image update has been completed. + +The OTA Provider MAY announce its presence to OTA Requestors on the Fabric to assist in discovery +of this service (see AnnounceOTAProvider). + +Nodes SHALL NOT rely solely on unsolicited OTA Provider announcements to discover available +OTA Providers and SHALL instead employ other means such as using OTA Provider records provi­ +sioned during Commissioning, or dynamic discovery of OTA Providers. + +OTA Requestors SHALL only upgrade to numerically newer versions and OTA Providers SHALL +only ever provide a numerically newer Software Image than a Node’s current version number (see +SoftwareVersion). Any functional rollback SHALL be affected by the Vendor creating a Software +Image with a newer (higher) version number, but whose binary contents may match prior func­ +tionality. + +All OTA Requestors SHALL support usage of a polling mechanism to send a query command to the +OTA Provider in order to determine if the OTA Provider has any new Software Images for it. Polling +simplifies processing for OTA Requestors that MAY need to perform special setup to get ready to +receive a Software Images, such as unlocking flash or allocating space for a new Software Images. + +It is ideal to have OTA Providers maintain as little state as possible since this will scale better when +there are hundreds of OTA Requestors in a given Fabric. The OTA Provider is not required to keep +track of what pieces of an image that a particular OTA Requestor has received. + +The flow for querying the availability of a new version is done using commands of the OTA +Provider Cluster. In case of a new image available matching an OTA Requestor’s request, the +response to the QueryImage command SHALL contain a URI where the given image can be down­ +loaded. + +The download protocol is separate from the Cluster commands. All OTA Providers SHALL support +the BDX Protocol to allow for the downloading of OTA images by both sleepy End Devices and more +capable devices, without requiring access to the public Internet from the OTA Requestor. OTA +Requestors SHOULD support the BDX Protocol. + +In order to maximize the interoperable combinations of deployed products and Fabric Administra­ +tors, the CSA’s Distributed Compliance Ledger (DCL) MAY contain sufficient OTA Software Update +information to cover a large number of products, using a federated mechanism of data mainte­ +nance. See Section 11.23, “Distributed Compliance Ledger” for details on the Distributed Compli­ +ance Ledger common data schemas. See Section 11.20.3.3.2, “Conceptual algorithm for matching +OTA Software Images applicable to a query” for the conceptual algorithm recommended for imple­ +mentation by OTA Providers to match records available in the DCL to incoming queries. + +**11.20.3. Software update workflow** + +The software update workflow consists of several steps executed in a sequence from an OTA +Requestor towards an OTA Provider. When a newer Software Image for an OTA Requestor is avail­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 921 +``` + +able on the OTA Provider this results in an updated Software Image being acquired and applied by +said OTA Requestor. + +The steps, in order, and assuming each step successfully leads to the next, are the following, with +each numbered according to Figure 91, “Detailed OTA Software Update Workflow”: + +- [10] OTA Provider optionally announces its presence to nodes (see AnnounceOTAProvider). This + MAY be used in addition to other OTA Provider discovery methods. +- [11] OTA Requestor determines OTA Provider to query. +- [11] OTA Requestor queries the OTA Provider for availability of an updated Software Image ver­ + sion. +- [30..34] OTA Provider obtains consent from user to apply the OTA update. +- [40..41] OTA Provider obtains a copy of the new Software Image, either in real time or in a time- + deferred manner, to provide to the OTA Requestor over BDX Protocol, or over an alternate sup­ + ported protocol that both OTA Provider and OTA Requestor support. If the Software Image hap­ + pens to be already available in the OTA Provider’s cache, this step can be skipped. +- [52] OTA Requestor downloads the update, either over BDX Protocol from OTA Provider acting + as a proxy, or over an alternate protocol that both OTA Provider and OTA Requestor support. +- [60] OTA Requestor notifies the OTA Provider that the download is complete and that it is ready + to apply the downloaded image. +- [61] OTA Provider responds with an authorization to apply the update, after an optional delay. +- [62] OTA Requestor applies the update and starts executing updated software. +- [63] OTA Requestor notifies the OTA Provider of having successfully applied the update. + +In order to illustrate more specifically these steps, Figure 91, “Detailed OTA Software Update Work­ +flow” below depicts a detailed sequence showing the following illustrative (not normative) aspects: + +- [10..21] Determining the availability of an OTA software update. +- [22] Deferral of download by OTA Provider responding with a "Busy" condition, while it obtains + user consent and obtains the Software Image from a vendor server based on information in the + OTA Provider’s OTA Software Update logic. +- Obtaining user consent in one of these ways: + ◦ [30..31] Out-of-band notification through some externally-provided user interface, such as a + mobile device terminal operated by an authorized user, and connected to OTA Provider’s + logic in some way. + ◦ [32..34] Reuse of prior user consent, perhaps from a continued but revokable authorization, + sent back to the OTA Provider by OTA Software Update logic. + ◦ Via the OTA Provider delegating to the OTA Requestor Node (see Section 11.20.3.4.1, “User + consent delegation to Nodes”). Note that this case is not illustrated in the sequence diagram. +- [40..41] Downloading and temporarily storing a Software Image by the OTA Provider, from a + Vendor’s server, over the public Internet, for the purposes of eventual proxied local download + by the OTA Requestor. + +``` +Page 922 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- [50..51] Responding positively to a subsequent query by the OTA Requestor, since an OTA soft­ + ware update is now definitely available. +- [52] Downloading of the Software Image from the OTA Provider by the OTA Requestor, using the + BDX Protocol against the temporary storage of the OTA Provider. +- [60..63] OTA Requestor performs the update (after permission from OTA Provider) + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 923 +``` + +_Figure 91. Detailed OTA Software Update Workflow_ + +Given that some of the above steps MAY fail to complete, and that some MAY provide a variety of +outcomes or replies, the following subsections give the necessary normative details describing the +sequence. + +``` +Page 924 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.20.3.1. Determining the OTA Provider to query** + +The discovery of available OTA Providers is necessary for OTA Requestors to be able to query for +new software images. Each OTA Requestor SHALL keep a list of OTA Provider Operational Identi­ +fiers (see Node Identifier) that it could query. + +A given OTA Requestor SHALL have sufficient storage to maintain one OTA Provider entry per Fab­ +ric within the DefaultOTAProviders default list. This default OTA Provider list MAY be augmented +by any means deemed acceptable by a given OTA Requestor, such that the internal list of possible +locations to query contains at least the DefaultOTAProviders, but it MAY contain more. For example, +it may contain cached locations that arose from the AnnounceOTAProvider command. + +When an OTA Requestor determines that it is time to query an OTA Provider, it MAY use any +method of its choosing to determine which OTA Provider to contact for its next query. + +An OTA Requestor MAY expunge OTA Providers from its OTA Provider list if it determines that the +entry is stale or obsolete. + +Discovery of additional OTA Providers MAY be done by handling the arrival of AnnounceO­ +TAProvider commands invoked by OTA Providers. + +Commissioners SHOULD add an entry to the DefaultOTAProviders list attribute, if an OTA Provider +is known at commissioning time, to reduce the delay between commissioning and first QueryImage +command. + +Whenever communicating with an OTA Provider location obtained either through the DefaultO­ +TAProviders attribute, or the AnnounceOTAProvider command, an OTA Requestor SHALL target all +interactions with that Node by interacting with the given Endpoint on the given ProviderNodeID +obtained from these sources. + +Discovery of additional OTA Providers MAY be done using runtime service discovery, which is out­ +side the scope of this specification. + +Nodes MAY attempt to contact OTA Providers that are known to them in any order if failing to reach +a default OTA Provider from an entry in the DefaultOTAProviders list. This approach would assist in +maximizing likelihood of eventual success. + +**11.20.3.2. Querying the OTA Provider** + +Query of the OTA Provider SHALL be done using the QueryImage command. The arguments for this +command provide sufficient information to allow the OTA Provider to determine the availability of +a new image for the querying OTA Requestor. + +An OTA Requestor SHALL NOT query more frequently than once every 120 seconds, unless a Node +loses its timekeeping state, due to events such as power loss or restart, that prevent applying such a +delay. This reduces the burden on both the OTA Providers providing the service to a large number +of nodes and the supporting networking infrastructure. It is recommended for OTA Requestors to +attempt a daily QueryImage command, if capable, to ensure timely access to updated software, +including security-critical updates. + +The OTA Provider SHALL use an algorithm deemed satisfactory by its implementer to determine + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 925 +``` + +the availability of a newer Software Image in response to a QueryImage command. This algorithm +will be called the "OTA Image Selection Logic" thereafter. + +The OTA Image Selection Logic MAY use any data it deems useful, either local to the equipment or +Node hosting the OTA Provider, or remote through external networks, to determine whether an +updated Software Image is available (see Section 11.20.3.3, “Availability of Software Images”). + +OTA Provider requests are idempotent. In cases where an OTA Requestor is repeating a request it +has already done, and the OTA Provider can detect this, it SHALL NOT behave differently on any +subsequent attempt compared to the first, unless a new Software Image has become available in +the meantime. That is, an OTA Provider SHALL NOT prevent an OTA Requestor from trying to make +the same query more than once. This requirement is critical to ensure that OTA Requestors which +encounter error conditions during OTA Image Query or OTA Image Transfer can eventually succeed +through retrying the same operation more than once. + +Upon final determination of the outcome of the QueryImage command, the OTA Provider SHALL +reply with a QueryImageResponse command. + +If an OTA Provider employs synchronous proxying (e.g. proxy-while-downloading) method to reach +off-Fabric Software Images and provide them over BDX Protocol to OTA Requestors, it SHALL +respond with a Status of DownloadProtocolNotSupported to an OTA Requestor in the QueryIm­ +ageResponse command if all the following conditions apply: + +1. A new Software Image is determined to be available. +2. The Software Image to proxy is served by a remote server that does NOT support range-based + transfers. +3. The OTA Requestor only supports BDX. +4. The OTA Provider does not support asynchronous proxying (e.g. download-then-proxy). + +The fields of the QueryImageResponse command convey the next steps to take. The primary indica­ +tion of action to be taken by the OTA Requestor is expressed in the Status field, with the other fields +providing the necessary details as described in the following subsections. + +Failure to receive an application-layer response from the OTA Provider after invoking the QueryIm­ +age command SHOULD be considered equivalent to having received a QueryImageResponse com­ +mand with a Status field containing NotAvailable (see Section 11.20.3.2.4, “Handling NotAvailable +value in Status field”). + +**Access Control Requirements** + +Commissioners or Administrators SHOULD install necessary ACL entries at Commissioning time or +later to enable the handling of the AnnounceOTAProvider commands by OTA Requestors. + +Below is an exemplary ACL entry for a Node implementing the OTA Requestor cluster server to sup­ +port the processing of the AnnounceOTAProvider command: + +### { + +``` +FabricIndex: , +``` +``` +Page 926 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Privilege: Operate, +AuthMode: CASE, +Subjects: [ ], +Targets: [ ] +} +``` +Commissioner or Administrator SHOULD install necessary ACL Entries at Commissioning time or +later to enable processing of QueryImage commands from OTA Requestors on their Fabric, other­ +wise that OTA Provider will not be usable by OTA Requestors. + +Below is an exemplary ACL entry for a Node implementing the OTA Provider cluster server to sup­ +port the processing of the QueryImage command: + +### { + +``` +FabricIndex: , +Privilege: Operate, +AuthMode: CASE, +Subjects: [ ], // Empty for "any" Node wildcard +Targets: [ ] +} +``` +Note that there may be a variety of ACL entry configurations that fulfill the necessary goals, includ­ +ing wildcard entries for the Administrators on a given Fabric. The examples above are for illustra­ +tion purposes only. + +**Handling UpdateAvailable value in Status field** + +The UpdateAvailable status indicates that the OTA Provider has an update available. + +The remaining fields within the QueryImageResponse command SHALL contain the information +necessary to allow the OTA Requestor to obtain an updated Software Image. + +The field ImageURI SHALL be set to a location from where the image can be downloaded. The URI +provided SHALL be for a protocol within the list of supported protocols provided in the request (see +ProtocolsSupported). Selection of the URI is based on the information available in the OTA +Provider’s Software Images data set. + +The field UpdateToken SHALL be populated by the OTA Provider with a value of its choosing, to +allow tracking of the flow from a given OTA Requestor when it sends further requests. The valid +length of the UpdateToken is between 8 and 32 bytes, inclusively. The token SHALL be recorded by +the OTA Requestor, until an OTA Software Update Image is either applied or discarded. This value +SHALL be provided to any subsequent ApplyUpdateRequest and NotifyUpdateApplied commands. + +The field SoftwareVersion SHALL be set to the version number matching the new Software Image. + +Handling of SoftwareVersion and ImageURI fields SHALL follow these rules: + +- If the SoftwareVersion field matches the version indicated in the header of a previously down­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 927 +``` + +``` +loaded OTA Software Image, one of two cases applies: +``` +1. Image was fully downloaded and verified: the OTA Requestor SHOULD skip the transfer step + (see Section 11.20.3.5, “Transfer of OTA Software Update images”), and move directly to the + apply step (see Section 11.20.3.6, “Applying a software update”). +2. Image was partially downloaded: the OTA Requestor SHOULD attempt to continue the trans­ + fer from where it left off, if it is capable, otherwise it SHALL start the transfer anew. See Sec­ + tion 11.20.3.5, “Transfer of OTA Software Update images” for a description of complete and + restarted downloads. +- If the SoftwareVersion field indicates a newer (numerically higher) version than the version +currently installed on the OTA Requestor, the OTA Requestor SHOULD proceed with OTA Image +Transfer (see Section 11.20.3.5, “Transfer of OTA Software Update images”), after awaiting at +least the delay stated by the DelayedActionTime field, if present. +- If the SoftwareVersion field indicates the same or an older (numerically lower) version, or if the +ImageURI field somehow contains information which cannot be used by the OTA Requestor, +then the OTA Requestor SHALL go back to awaiting its next OTA Software Update query oppor­ +tunity, following the rules previously stated in Section 11.20.3.2, “Querying the OTA Provider”. +In that case, the OTA Requestor MAY attempt to select a different OTA Provider according to Sec­ +tion 11.20.3.1, “Determining the OTA Provider to query”, which MAY cause the OTA Requestor to +immediately try another query, but to a different OTA Provider, thus not violating daily +allowance of a given OTA Requestor towards a given OTA Provider. + +**Handling Busy value in Status field** + +The Busy status indicates that the OTA Provider is busy for any reason and that it can only provide +a definite answer at a later time. This MAY be because the OTA Provider is currently determining +whether an update is available for the OTA Requestor that made the query. An OTA Requestor +SHOULD attempt to query the same OTA Provider again later at least once more if a Busy response +is obtained, rather than querying a different OTA Provider in its list, so that the OTA Provider that +replied Busy could have had resources available to determine availability. + +After a Busy status, the OTA Requestor SHALL NOT re-query the OTA Provider which was the sub­ +ject of the command sooner than the longest of either: + +- 2 minutes (120 seconds) from the last QueryImage command; +- the delay stated by the DelayedActionTime field, if present. + +Note that if a Node loses its timekeeping state due to events such as power loss or restart, the above +timing constraint MAY be ignored, however, the previously stated overriding constraint of a mini­ +mum delay of 120 seconds between queries to any single OTA Provider by a given OTA Requestor +has to be respected. + +**Handling NotAvailable value in Status field** + +The NotAvailable status indicates that there is definitely no update currently available from the +queried OTA Provider. + +The OTA Requestor MAY choose to attempt a QueryImage command on a different OTA Provider in +its OTA Provider List to determine if an update is available from that other OTA Provider. + +``` +Page 928 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Otherwise, if there are no other OTA Providers available to query, the OTA Requestor SHALL NOT +re-query the OTA Provider which was the subject of the command sooner than 2 minutes (120 sec­ +onds) from the last QueryImage command. Note that if a Node loses its timekeeping state due to +events such as power loss or restart, the above timing constraint MAY be ignored, however, the pre­ +viously stated overriding constraint of a minimum delay of 120 seconds between queries to any sin­ +gle OTA Provider by a given OTA Requestor have to be respected. + +**Handling errors from QueryImage Command** + +If an OTA Requestor hits error conditions of any kind in invoking the QueryImage command, +including receiving DownloadProtocolNotSupported in Status, there are two possible outcomes: + +1. If the OTA Requestor has a Software Image it had previously successfully downloaded and veri­ + fied, the OTA Requestor SHOULD skip the Query step, and move directly to the Apply step (see + Section 11.20.3.6, “Applying a software update”). This increases the likelihood that the OTA + Requestor will eventually succeed to apply a previously transferred Software Image. +2. If the OTA Requestor is still attempting to discover an OTA Update, it MAY choose to attempt a + QueryImage command on a different OTA Provider in its OTA Provider List, in which case the + timing for the query SHALL match the query timing constraints expressed in the previous para­ + graphs of this section. Otherwise, it SHALL continue to query the same OTA Provider, again fol­ + lowing the query timing constraints previously expressed. + +**11.20.3.3. Availability of Software Images** + +The algorithm used by the Image Selection Logic to determine availability of a new Software Image +SHALL consider all fields provided by the OTA Requestor and attempt to provide the newest match­ +ing Software Image. The OTA Image Selection Logic SHALL only provide newer (numerically +higher) SoftwareVersion than the SoftwareVersion sent in the query. See Section 11.20.3.3.2, “Con­ +ceptual algorithm for matching OTA Software Images applicable to a query” for more details. + +The OTA Provider MAY provide a Software Image that only conveys data for a subset of updateable +components within the OTA Requestor’s Node. These cases of partial or componentized software +updates are determined purely by the entity generating the OTA Software Image, and the OTA +Provider SHALL never mutate the contents of an OTA Software Image. + +The original provider of a Software Image SHOULD be able to assume the contents of the Software +Image will remain unchanged and signatures would remain valid. Therefore, an OTA Provider +SHALL NOT modify the contents of any Software Images other than allowing that OTA Requestor to +index into the Software Image using the BDX Protocol or other supported download protocol, such +that the OTA Requestor may obtain only the desired parts of the Software Image. + +The OTA Provider SHALL NOT hide or otherwise mask the contents of a Software Image available +for transfer to a requestor. + +In order for different vendors to participate as widely as possible in the distribution of Software +Images for the widest variety of products without requiring bilateral distribution agreements +between each pair, it is RECOMMENDED for vendors to participate in distribution schemes that +maximize availability across other vendors and OTA Providers. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 929 +``` + +Vendors SHOULD build data sets aggregating the metadata and payloads of Software Images to sup­ +port their OTA Image Selection Logic by any means they deem satisfactory. Vendors SHOULD refer +to canonical databases, such as the Distributed Compliance Ledger. + +Given that most Fabrics likely will contain a reduced subset of Nodes capable of acting as OTA +Providers compared to the larger set of vendors represented in the many deployed Nodes, it is +advantageous to end-users that Vendors attempt to cover as many other vendors with their data +sets. This will ensure that the majority of Software Image queries can be fulfilled if a vendor has +released a newer version than that installed on the querying OTA Requestor. + +**Download Protocol selection** + +The OTA Image Selection Logic SHALL consider the OTA Requestor’s supported download protocols +to determine whether to respond to a QueryImage command. + +If either the BDXSynchronous or BDXAsynchronous protocols are supported by the OTA Requestor, +the OTA Provider SHALL prefer to respond to the OTA Requestor with a BDX protocol URI, as long as +it can fulfill the role of BDX server for the OTA Requestor. + +Otherwise, if the HTTPS protocol is supported by the OTA Requestor, and the OTA Provider deter­ +mines that an OTA Software Image is available to fulfill the request from a server supporting +HTTPS, it SHOULD respond with the direct source URI, so that the OTA Requestor MAY download it +directly. + +Otherwise, if the VendorSpecific protocol is supported by the OTA Requestor, and the OTA Provider +has sufficient knowledge of the OTA Requestor’s capabilities based on the QueryImage command +arguments, it SHOULD respond with a URI which is known to be understood by the OTA Requestor. +It is RECOMMENDED to limit usage of this modality and prefer BDXSynchronous and BDXAsynchro­ +nous. + +**Conceptual algorithm for matching OTA Software Images applicable to a query** + +An OTA Provider MAY use any of the fields of the QueryImage command in any way it deems +applicable to determine whether an appropriate OTA Software image is available for the OTA +Requestor. + +However, to increase interoperability, OTA Providers which have access to the data present in the +Distributed Compliance Ledger (DCL), whether from cached subset or from a full replica, SHOULD +employ at least the common conceptual algorithm provided in this section to determine whether an +OTA Image is available. + +The information to access OTA Software Image locations for certified software versions is available +in the DCL DeviceSoftwareVersionModel Schema, which is indexed by VendorID, ProductID and +SoftwareVersion. + +The inputs to the conceptual algorithm are: + +- A subset of the fields of the QueryImage command as a structure named requestor: +- VendorID of the requestor as vendorID +- ProductID of the requestor as productID + +``` +Page 930 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Current SoftwareVersion of the requestor as softwareVersion +- The list of all current entries for the given VendorID and ProductID from the DeviceSoftwareVer­ + sionModel schema, ordered by SoftwareVersion, accounting for the following fields, as an array + candidates[] + ◦ SoftwareVersion of the entry as softwareVersion + ◦ SoftwareVersionValid of the entry as softwareVersionValid + ◦ MinApplicableSoftwareVersion of the entry as minApplicableSoftwareVersion + ◦ MaxApplicableSoftwareVersion of the entry as maxApplicableSoftwareVersion + +The output of the conceptual algorithm is a tuple of: + +- candidateWasFound, a boolean predicate indicating whether a newer version candidate was + found +- softwareVersionFound, the version of the newer version candidate, if candidateWasFound was true, + 0 otherwise. + +The algorithm is as follows: + +1. Assume no matching candidate found + ◦ candidateWasFound := False + ◦ softwareVersionFound := 0 +2. Obtain candidates from a DCL replica or from a DCL-based dataset for the given vendorID and + productID in the query, keeping only entries where softwareVersionValid is true. + ◦ An OTA Provider MAY as well filter available versions by certification compliance status (see + Section 11.23.8, “DeviceSoftwareCompliance / Compliance test result Schema”). +3. Sort all candidates by ascending softwareVersion. +4. Iterate through all candidates to find all positive matches within the sorted candidates. A "posi­ + tive match" is a candidate which fullfills every condition in the following list: + ◦ requestor.softwareVersion < candidate.softwareVersion + ◦ requestor.softwareVersion ≥ candidate.minApplicableSoftwareVersion + ◦ requestor.softwareVersion ≤ candidate.maxApplicableSoftwareVersion +5. From the positive matches, select the very last one of list, which will be the newest (numerically + highest) possible softwareVersion that could be used. If no positive matches were found, no new + software version is available. + +A pseudocode of the conceptual algorithm is presented below: + +``` +# Get candidates for VendorID/ProductID from DCL DeviceSoftwareVersionModel +# schema (e.g. from a replica) +candidates = obtain_candidates_from_dcl(requestor.vendorID, requestor.productID) +``` +``` +def find_newer_version(candidates, requestor): +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 931 +``` + +``` +# Ensure all candidate records are in monotonic increasing numerical order +sort(candidates, key="softwareVersion", order="ASCENDING") +``` +``` +currentCandidate = None +``` +``` +for candidate in candidates: +# Current version already newer: skip +if requestor.softwareVersion >= candidate.softwareVersion: +continue +``` +``` +# Candidate requires higher version than already installed: skip +if requestor.softwareVersion < candidate.minApplicableSoftwareVersion: +continue +``` +``` +# Candidate requires lower version than already installed: skip +if requestor.softwareVersion > candidate.maxApplicableSoftwareVersion: +continue +``` +``` +# Update potential candidate since it is applicable +currentCandidate = candidate +``` +``` +if currentCandidate is not None: +# Last value of currentCandidate is highest matching value +candidateWasFound = True +softwareVersionFound = currentCandidate.softwareVersion +else: +candidateWasFound = False +softwareVersionFound = 0 +``` +``` +return (candidateWasFound, softwareVersionFound) +``` +If candidateWasFound was true, then a version matching (softwareVersionFound) was found and its +location and associated metadata can be found in the DeviceSoftwareVersionModel schema of the +DCL. + +While the QueryImage command MAY also contain the Location, HardwareVersion and Meta­ +dataForProvider fields, they are optional to use by an OTA provider. These additional fields MAY +assist an OTA provider in supporting field trial and development policies. The certified releases +present in the DCL, however, are only indexed by VendorID, ProductID and SoftwareVersion, based +on the associated certification. + +Once an OTA software update file location (OtaUrl) and digest (OtaChecksum) are found for the +associated version candidate, an OTA provider MAY omit re-downloading the file, and serve a +cached copy if a local copy of a file exists which matches all of the following constraints from the + +``` +Page 932 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +candidate: + +- It has the same OtaChecksum +- It has the same OtaChecksumType +- It has the same OtaFileSize + +**11.20.3.4. Obtaining user consent for updating software** + +In the following subsections, the word "User" SHALL be construed to mean "an entity with suffi­ +cient privileges associated with the Fabric". For instance, this could be a home dweller having pre­ +viously configured Nodes or other services and currently having privilege to further affect such +configuration. The exact scope for what an "entity" for such a "User" role may be, and what "suffi­ +cient privilege" means, SHALL be implementation-dependent. + +An OTA Provider SHOULD obtain some form of "User Consent" prior to responding with a URI for a +Software Image or letting an OTA Requestor proceed with applying a previously downloaded +update. In the context of the OTA Cluster, "User Consent" SHALL be defined as any signal that an +OTA Provider may obtain through its implementation-specific logic, that conveys consent to pro­ +ceed from a User administratively allowed to give such consent in an informed manner. + +Example of "User Consent" include: + +- Triggering a notification to an interactive application user interface, where at least one User is + notified of the availability of new software for a given node, and where a signal of approval to + continue with the downloading and applying of that update can be conveyed back to the OTA + Provider. + ◦ Example: An OTA Provider detects the local presence of a mobile device with an application + supporting required User accounts through out-of-band means. The OTA Provider makes an + implementation-specific request over a protocol of its choice, in-band or out-of-band of the + Fabric, to obtain consent. The User is notified on screen with "An ExampleCompany Light + Bulb needs update to version 1.2.3. Tap here for release notes. Do you want to proceed?". + The User then selects "Agree to Update" and the signal is relayed back to the OTA Provider, + which then proceeds. +- Relaying of a previously stored consent signal, previously provided by a User at some point in + the past. The original capture of the stored consent signal should have been made after having + provided sufficient information to the User to understand the consequences of such stored con­ + sent. Multiple signals, covering different Nodes, Vendors or Device Classes, may be stored inde­ + pendently to affect a variety of deferred consent policies. + ◦ Example: An OTA Provider contacts an implementation-specific server with metadata about + the OTA Requestor and details for available Software Images, and obtains a consent signal + based on an Administrator having previously stated an account preference to "Always apply + software updates to light bulbs". The OTA Provider then proceeds further. + +**User consent delegation to Nodes** + +Some capable Nodes MAY have sufficient hardware capabilities to request user consent by means +such as display or voice, and subsequently recover user consent feedback through input mecha­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 933 +``` + +nisms. These devices MAY request optional delegation of user consent by the following method: + +1. The OTA Requestor SHALL set the RequestorCanConsent field in the QueryImageRequest to + True, indicating ability to obtain consent. +2. The OTA Provider, if it determines that the best way to obtain user consent is to delegate to the + OTA Requestor Node, SHALL include the UserConsentNeeded field, with a value set to True in + the QueryImageResponse, indicating that user consent was not previously obtained, and that + delegation SHALL occur. +3. The OTA Requestor, upon observing presence of UserConsentNeeded field set to True and the + availability of an image in the QueryImageResponse SHOULD proceed to obtain user consent + using its onboard means, prior to transferring the OTA Software Image reported. If the UserCon­ + sentNeeded field is set to False or absent, the OTA Requestor SHALL assume that the OTA + Provider already obtained sufficient user consent during the querying phase. + +The above method of obtaining User Consent at the OTA Requestor level SHALL NOT be used if a +Node is configured with the LocalConfigDisabled attribute set to True as reflected by the Basic +Information Cluster. + +**User consent recommendations** + +Because of the variety of Vendors and Devices, the concept of "User Consent" will necessarily take +many different forms. Therefore, it is RECOMMENDED that every implementer of OTA Provider +logic implement a transparent and easy-to-use set of functionality to allow Users to provide or deny +consent for software updates, in a way that functionally integrates with their products and respects +the general requirements stated above. Implementation of this feature is expected to improve "user +experience" and assist with building trust regarding the installation of new software on Nodes. + +It is RECOMMENDED that any method of consent that stores consent signals also provide a way to +revoke this consent in the future. + +It is RECOMMENDED that metadata from Software Images be used to convey as much information +as required within the available set, so that a User can make an informed decision based on the +nature of the product being updated, the human-readable instance of the new version number (e.g. +SoftwareVersionString in OTA Image Header), the changes made available, and their side-effects on +product functionality. Any URL for online contents conveyed during this process SHOULD point to +content that can be localized at the time of delivery, whenever possible. The responsibility for the +maintenance of such version information is on the Vendor providing the URL and metadata. The +OTA Provider and associated implementation-specific logic SHALL allow a User to consent to an +update, even if errors occur while trying to provide additional release information, as the metadata +within the Software Image should suffice to provide a first-order description of the new version, +which could then be researched or cross-referenced by the User. + +It is RECOMMENDED that Vendor-provided Software Update metadata, such as release note URLs, +be maintained in the long-term with stable locations, preferably in a manner allowing historical +caching by common online search engines, where applicable. See Section 11.23.7.11, +“ReleaseNotesUrl” and Section 11.21.2.4.8, “ReleaseNotesUrl field” for sources of such information. + +``` +Page 934 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.20.3.5. Transfer of OTA Software Update images** + +Execution of an OTA Software Update image’s transfer depends on the protocol provided in the +ImageURI field of the query response. + +The following are OTA Software Image transfer examples: + +- An OTA Requestor invokes a QueryImage command stating only support for BDX in its Proto­ + colsSupported. The OTA Provider, using its OTA Image Selection Logic, determines that a Soft­ + ware Image is available. There are several cases to be considered: + 1. The Software Image is at a URI referring to a resource on the public Internet (e.g. + https://domain.example/images/software.bin). + a. The OTA Provider MAY completely download the Software Image, temporarily, to local + storage. It would then reply to the OTA Requestor with a locally-accessible BDX URI, such + as bdx://8899AABBCCDDEEFF/software_8ce40aa1.bin. In that case, the OTA Requestor SHALL + proceed with the download from the OTA Provider using the BDX protocol. + b. The OTA Provider MAY employ a variety of buffering and proxying schemes of underly­ + ing HTTPS transfers to support the OTA Requestor downloading in real-time as a form of + direct proxy. It would immediately reply to the OTA Requestor with a locally-accessible + BDX URI, such as bdx://8899AABBCCDDEEFF/software_8ce40aa1.bin. In that case, the OTA + Requestor SHALL proceed with the download from the OTA Provider using the BDX pro­ + tocol. The only difference with the previous case is the fact that the transfer uses data + directly proxied in real-time, as opposed to the OTA Requestor downloading a pre-stored + cached copy of the same Software Image. + 2. The Software Image is already cached on the OTA Provider, either from pre-seeding over + some implementation-specific scheme, or from having previously served this software + update to another OTA Requestor. In that case, the OTA Provider SHALL reply to the OTA + Requestor with a locally-accessible BDX URI, such as bdx://8899AABBCCDDEEFF/soft­ + ware_8ce40aa1.bin. In that case, the OTA Requestor SHALL proceed with the download from + the OTA Provider using the BDX protocol. +- An OTA Requestor invokes a QueryImage command stating support for BDX and HTTPS in its + ProtocolsSupported. The OTA Provider, using its OTA Image Selection Logic, determines that a + Software Image is available. The Software Image is at a URI referring to a resource on the public + Internet (e.g. https://domain.example/images/software.bin). In the case of support for both + HTTPS and BDX, all of the above cases are applicable, in addition to the following: + ◦ The OTA Provider knows that the OTA Requestor supports HTTPS from the QueryImage com­ + mand. The OTA Provider MAY then respond directly to the OTA Requestor with the + https://domain.example/images/software.bin URI. The OTA Requestor SHALL proceed to + download from the public Internet using the HTTPS protocol. + +As described above, an OTA Provider SHALL either proxy synchronously or asynchronously the +actual Software Image data for BDX Protocol clients, when a Software Image is determined to be +available from the public Internet or from local storage. + +Upon receipt of a QueryImageResponse command containing a DelayedActionTime field, the OTA +Requestor SHALL wait for at least the stated delay time before initiating the first part of a file trans­ +fer for the URI provided. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 935 +``` + +The OTA Provider MAY expunge any previously cached Software Image downloaded on behalf of +other OTA Requestors, to save storage, at any time, as long as no transfer is currently in active +progress. It is RECOMMENDED that OTA Providers on a given Fabric maintain as much Software +Image cache as practical, to improve availability of software image and reduce latency between +QueryImage requests and availability of the matching QueryImageResponse for a new Software +Image ready to be downloaded. + +In order to support non-BDX protocols relying on the public Internet, or intranets, the OTA +Requestor SHALL only report support for protocols requiring public Internet access if it has deter­ +mined that it does indeed have access to the necessary network domains beyond the Fabric. The +OTA Requestor MAY employ any method it deems satisfactory to determine public Internet reacha­ +bility. Because of the variety of firewall and security policies on network infrastructure, it is REC­ +OMMENDED that all Nodes whose primary networking interactions lie within protocols in-band of +this wider specification support the BDX method, so that even if a Node cannot access the public +Internet, it MAY still obtain OTA Software Images by relying on a local OTA Provider which can. + +For BDX transfers, the following BDX-specific constraints SHALL be followed: + +- Receiver-Drive mode SHALL be used by the OTA Provider for any transfers initiated from a + secure channel on non-TCP transport. +- Asynchronous mode SHALL be used by the OTA Provider for any transfer initiated from a + secure channel on TCP transport. +- Idle time-out SHALL be no less than 5 minutes for either Receiver-Driver or Asynchronous + mode, before aborting a transfer. +- Block sizes constraints SHALL be as follows: + ◦ Maximum Block Size over all transports SHALL be a power of two if the OTA Requestor + requests a value larger than 128 bytes. + ◦ For an OTA Requestor-requested Maximum Block Size value between 16 and 128, the exact + requested value SHALL be used. This constraint allows low-power Nodes to precisely control + the block sizes to ensure their power constraints are respected, including enabling single- + frame block transfers over communication mediums where MTU is very small. + ◦ Maximum Block Size requested by OTA Requestors over non-TCP transports SHALL be no + larger than 1024 (2^10) bytes. OTA Providers SHALL support the Maximum Block Size of at + least 1024 bytes in those cases. + ◦ Maximum Block Size requested by OTA Requestors over TCP transport SHALL be no larger + than 8192 (2 ^ 13) bytes. OTA Providers SHALL support a Maximum Block Size of at least + 4096 (2^12) bytes in this case and MAY support 8192 bytes. + ◦ Actual Block Size used over all transports SHALL be the negotiated Maximum Block Size for + every block except the last one, which may be of any size less or equal to the Maximum + Block Size (including zero). +- The OTA Requestor SHALL NOT rely on the ReceiveAccept message from the OTA Provider hav­ + ing the RC[DEFLEN] bit set (see Section 11.22.5.4.2.1, “ReceiveAccept RC[DEFLEN]: definite length + present”) and the associated LEN field populated. Instead, OTA Requestors SHALL rely on OTA + Software Image metadata to determine the expected size to download. + +``` +Page 936 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- The ReceiveInit message from the OTA Requestor MAY have the RC[STARTOFS] bit set and asso­ + ciated STARTOFS field set to indicate the resumption of a transfer previously aborted, or to + affect partial windowed access to the portion of a Software Image desired. +- The ReceiveInit message from the OTA Requestor MAY have the RC[DEFLEN] bit set and associ­ + ated DEFLEN field set to state the desired maximum size of the transfer. + +Since OTA Requestors MAY need to read Software Image in parts, it is RECOMMENDED that OTA +Providers maintain cached Software Images for at least 5 minutes after closure of the last OTA +Requestor transfer, so that the OTA Requestor MAY come back to read different parts of an OTA file. + +In the case of very large Fabrics, it often occurs that there is a large number of the same model of +Node within a given location. Because of this, OTA Providers SHOULD avoid downloading the same +Software Image repeatedly for proxying if it can determine that multiple OTA Requestors are +requesting, or can be expected to request, the same Software Image. + +It is RECOMMENDED to keep Software Images cached for as long as practical to reduce having to +reach external off-Fabric resources frequently to address the update needs of a large fleet of identi­ +cal Nodes that could share a single pre-downloaded cached copy in the OTA Provider. This reduces +burden on content delivery servers for Software Images and reduces the amount of data trans­ +ferred by an OTA Provider from external off-Fabric servers to fulfill software update requirements. + +It is RECOMMENDED that Sleepy End Devices make their best effort to optimize their sleep intervals +during the OTA Software Image transfer process over BDX to ensure that the download completes +in a timely manner. However, it is acknowledged that some Sleepy End Devices might not be able to +do so, due to limitations related to their batteries or other constrained power sources. Therefore, +such devices MAY take much longer to complete the download process. + +In the case where a BDX transfer is aborted due to unforeseen circumstances (e.g. power loss, crash, +battery drain on either side), the OTA Requestor MAY try to use a partial (i.e. range-based) transfer +to recover and continue the download without having to start from the beginning of a given Soft­ +ware Image. An OTA Requestor SHALL abort retrying a transfer after three attempts in a row +where each yielded no forward progress. + +It is RECOMMENDED for the OTA Provider to validate the length and digest of proxied images +whenever possible (see OTA software update file Header field) to avoid continuing a transfer if the +data is obviously corrupted. + +In any situation where an OTA Requestor reaches a terminal failure point for a Software Image +transfer and all possible retries or alternate OTA Providers have been exhausted, that OTA +Requestor SHALL reset its entire software updating state and revert to doing a future query at the +next possible scheduled time, so that perhaps a new Software Image may be available again. + +The above situation may occur, for example, if an OTA Provider had cleared its Software Update +Image File cache for any reason, or if there is a transient network failure of sufficient duration to +prevent a complete transfer to take place. + +Once the entirety of a Software Image has been downloaded and is ready to apply, the OTA +Requestor SHALL execute the "Applying a software update" sequence of the next section. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 937 +``` + +**11.20.3.6. Applying a software update** + +Once a Software Image has been fully downloaded based on a QueryImageResponse command, the +OTA Requestor SHALL proceed with a sequence to determine when to apply the update by invoking +the ApplyUpdateRequest command. + +**UpdateToken usage** + +The OTA Requestor SHALL provide an UpdateToken to the OTA Provider with the ApplyUp­ +dateRequest command. This token SHALL be a previously provided UpdateToken from the last +QueryImageResponse, unless the token was lost by the OTA Requestor. In case of token loss, the OTA +Requestor SHALL use its Operational Node ID encoded as a 64-bit value in network byte order. This +UpdateToken MAY be used by an OTA Provider to track deferred OTA application or otherwise +allow short-term tracking of OTA Requestors for algorithmic bookkeeping. The OTA Provider SHALL +NOT consider an invalid UpdateToken as a reason to continuously deny or delay an OTA +Requestor’s request to apply a Software Image. + +**Update application process** + +On receipt of the ApplyUpdateRequest command, the OTA Provider SHALL respond with an action +to be taken by the OTA Requestor before activating the new version. The method used to determine +the Action field of the response MAY be based on implementation-specific rules and logic. + +Note that the DelayedActionTime field is a relative time delay from the moment of receipt, which +needs to be computed by the OTA Provider to reflect the difference between the OTA Provider’s cur­ +rent time and the desired time for execution of the Action. + +In case of a successful invocation, the following actions to be taken by the OTA Requestor are possi­ +ble, based on the Action field in the ApplyUpdateResponse command: + +- Proceed: Apply the update, taking in account the delay time stated in DelayedActionTime. + ◦ If the DelayedActionTime is zero, then the OTA Requestor SHALL apply the update without + additional delay. + ◦ If the DelayedActionTime is non-zero, the OTA Requestor SHALL await at least DelayedAc­ + tionTime seconds prior to applying the software update. An example use of this Action by an + OTA Provider is to schedule application of a Software Image based on a user’s preferred + update time for Nodes of a certain type (e.g. light bulbs or window coverings) to occur at a + time when the user is not at home, or when the temporary unavailability of the Node during + the update would not pose a problem. + ◦ When the Proceed action is given, the OTA Requestor SHALL NOT invoke the ApplyUp­ + dateRequest command again, unless the OTA Requestor suffers an error or unexpected con­ + dition while proceeding to apply the new Software Image. +- AwaitNextAction: Await at least the given delay time in DelayedActionTime before re-invoking + an ApplyUpdateRequest to get a new Action. + ◦ If the DelayedActionTime is less than 120 seconds (2 minutes), the OTA Requestor SHALL + assume a value of 120 seconds. + ◦ An example use of this Action by an OTA Provider is to schedule application of a Software + +``` +Page 938 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Image based on non-occupancy of a room, which Nodes collaborating with the OTA Provider +may be able to ascertain, but which may require several attempts over time. +◦ It is RECOMMENDED to keep usage of this Action to a practical minimum, as it may cause +OTA Requestors to be delayed in their application of a Software Image. +◦ The AwaitNextAction action SHALL NOT be emitted in such a way as to cause more than 24 +hours of delay in applying an available Software Image. It is expected that user consent hav­ +ing been previously granted should satisfy the overall scheduling constraint this imposes. +``` +- Discontinue: The OTA Provider is conveying a desire to rescind a previously provided Software + Image. + ◦ The DelayedActionTime SHALL be ignored by the OTA Requestor if present. + ◦ The OTA Requestor SHOULD clear its previously downloaded and verified Software Image, if + it had been obtained from the same OTA Provider as the one providing the Discontinue + action. + ◦ This action SHALL only be used as a stopgap when it is known that a given Software Image + previously provided may cause significant negative side-effects to an OTA Requestor, such as + unrecoverable loss of functionality, or other damage. + ◦ In case of receiving this action unexpectedly (e.g. from a different OTA Provider than the + one where a Software Image was downloaded), an OTA Requestor MAY ignore it and con­ + sider it the same way as if the ApplyUpdateRequest command had proceeded with an error. + +It is RECOMMENDED that for any OTA Requestor invoking the ApplyUpdateRequest command with +an unknown UpdateToken, the OTA Provider SHOULD assume that the OTA Requestor has a Soft­ +ware Image ready to apply and thus respond with the Proceed or Await action, rather than +responding with an error or Discontinue action. + +In case of time-out or any error in obtaining an answer to the ApplyUpdateRequest command, or in +case of a restart or other unrecoverable situation while awaiting the DelayedActionTime for a Pro­ +ceed or Await action, the OTA Requestor SHOULD retry to execute the "Querying the OTA Provider" +flow (see Section 11.20.3.2, “Querying the OTA Provider”) again, whenever the OTA Requestor +deems it possible. + +In case of failure of every possible retry mechanism for at least 3 total attempts, or over more than +24 hours, an OTA Requestor having successfully downloaded and verified a Software Image MAY +apply the update. This measure of last recourse is to avoid situations where a critical issue affecting +a particular software version would prevent an OTA Requestor or OTA Provider from properly exe­ +cuting the "Applying a Software Update" flow, thus leaving an OTA Requestor in reduced or a for­ +ever-impaired state that could otherwise be resolved by applying the Software Image it had suc­ +cessfully downloaded and verified. + +After completion of an update, an OTA Requestor SHOULD invoke a NotifyUpdateApplied command +to the OTA Provider which provided the initial query response to indicate that the OTA Requestor +has successfully applied the OTA Software Update Image. The OTA Requestor SHALL NOT retry at +the application level to invoke this command if a response is not received. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 939 +``` + +**11.20.4. Security considerations** + +Security for the OTA Software Update capabilities encompasses these areas: Software Image verifi­ +cation, Software Image transport, and Software Image encryption. Security mechanisms in given +applications dictate the security level of OTA upgrading. For example, an application with strict +security policies (such as a smart lock) MAY support Software Image encryption at rest beyond the +secure channel data-in-transit encryption, while other applications MAY only support data-in-tran­ +sit encryption. Each Vendor SHALL decide the list of required security policies for their use of the +OTA Software Update capabilities for a particular product. + +**11.20.4.1. Image Encryption** + +A Vendor MAY apply at-rest encryption to Software Image bodies, excluding the Software Update +Image Header, using any algorithm of its choosing. + +It is out of scope of this specification to mandate such means of protecting the confidentiality of the +Software Images. + +**11.20.4.2. Image Verification** + +**Asymmetric Verification of Authenticity and Integrity** + +The verification of the authenticity and integrity of Software Images by OTA Requestors is manda­ +tory for security reasons. This is most often accomplished through asymmetric encryption technolo­ +gies where only one entity is able to create a digital signature but many entities are able to verify it. +Software Images SHALL be signed by a private key used by the Vendor for software image signing +purposes, with that signature attached to the Software Image that is transported to the OTA +Requestor. Once the complete Software Image has been received, the signature SHALL be verified +using a matching public key known to the OTA Requestor performing the validation. See Section +13.5, “Firmware” for the associated security requirements. The format and algorithms used for +code signatures verification are out of scope of this specification. The OTA Provider SHOULD NOT +expect to be able to validate OTA Software Image signatures on its own. + +OTA Requestors MAY be pre-installed with the certificate (public key) of the entity that created the +signature, or they MAY receive the certificate over-the-air. How the signer’s security data is +obtained is considered outside the scope of the OTA Software Update Cluster and is Vendor Specific. +When signer certificates are sent over-the-air, they SHALL be securely transferred from a trusted +source to reduce the chance an attacker MAY inject their own signer certificate into the OTA +Requestor. + +Software Images with verification mechanisms built in MAY be transported over insecure commu­ +nication mechanisms while still maintaining their authenticity and integrity. In fact, it is likely that +the originator of the Software Image (a Vendor) will not be directly connected to any Fabric and +therefore distribute the Software Image across other mediums (such as the Internet) before arriv­ +ing on the Fabric. Therefore, it is crucial that the Software Image verification be independent of the +communication medium. Any attempts to tamper with the signature or the data itself SHALL be +detected and SHALL cause the Software Image to be rejected by the target OTA Requestor. A Soft­ +ware Image from an attacker that crafts its own signed image and tries to have it accepted would be +rejected since that image will not be signed by the Vendor’s signing authority. + +``` +Page 940 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Since Software Images MAY contain software for multiple sub-components (e.g. main processor +firmware, radio firmware, graphical/audio assets) which MAY each employ different code signing +keys, Software Images SHOULD provide at least an overall authenticity and integrity validation for +the entire image, regardless of how it is segmented. + +Individual Vendors MAY augment the basic security and authenticity schemes provided by the Soft­ +ware Images and provide their own extensions within the payloads. Those extensions are outside +the scope of the OTA Software Update Cluster. + +Software Images MAY be encrypted with symmetric keys such that only those OTA Requestors that +need to decrypt the Software Image have access to the key. This MAY be used to mask or obfuscate +the contents of Software Images from intermediate network participants conveying the Software +Images, while in transit and at rest. However, the security of this system is dependent on the secu­ +rity of all OTA Requestors that have access to the symmetric key and the method of storage of the +final Software Image at rest on a given OTA Requestor. The schemes employed by different Vendors +to encrypt the body of Software Images in transit and at rest, is outside of the scope of this specifica­ +tion. + +**11.20.5. Some special situations** + +With the mechanisms provided by this Cluster, roll-out of new Software Images applies equally to +all OTA Requestors of matching a given tuple, uniformly across the world. +The subsections below describe two situations where finer-grained roll-out can be achieved for +some regions or to distribute special non-standard versions. + +**11.20.5.1. Regional roll-out of Software Images** + +Some Manufacturers have a policy of rolling-out by region (i.e. set of countries), to provide world- +wide release schedule differentiation, as well as to test roll-outs gradually, among other reasons. +These regional roll-outs may only be feasible using manufacturer-specific schemes that are in addi­ +tion to the common flows described in this cluster. Common recommended behavior (see Section +11.20.3.3.2, “Conceptual algorithm for matching OTA Software Images applicable to a query”) does +not support regional roll-out since there does not exist a location tagging attribute in the Distrib­ +uted Compliance Ledger (DCL). For regional rolls-outs prior to full roll-out, refer to the overall tech­ +niques described in Section 11.20.5.2, “Roll-out of non-standard Software Images”. + +**11.20.5.2. Roll-out of non-standard Software Images** + +Many Manufacturers conduct field trials to test different versions of software (e.g. A/B-testing, beta +testing), or provide dedicated Software Images to a subset of Nodes to affect particular diagnosis +tasks, etc. The mechanism described in this cluster is not particularly well-suited for such fine- +grained deployment (unless the OTA Provider is provided by, or associated with, the Manufacturer). + +To achieve more targeted roll-out, Vendors MAY commission a Node on the same Fabric as the +devices requiring the special rules, so that it MAY provide OTA Provider capabilities beyond the +core interoperable aspects of this Cluster. Finer-grained selection MAY be applied by special OTA +Software Image Selection logic in a given OTA Provider, using the MetadataForProvider field and +MetadataForRequestor fields of the QueryImage command. Furthermore, such special OTA +Provider may identify itself by including the MetadataForNode field in a given AnnounceO­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 941 +``` + +TAProvider command. + +If such a special Software Image is running on an OTA Requestor, the OTA Requestor MAY reject +Software Images provided to it by an OTA Provider on the Fabric, to prevent loss of the non-stan­ +dard Software Image. A Factory Data Reset of the OTA Requestor SHALL remove such override. + +**11.20.5.3. Other considerations** + +While it is expected that Nodes fulfilling the role of OTA Provider will likely have high availability +within the Fabric, it may be possible some will be battery-operated or be power-cycled frequently. It +is RECOMMENDED that an OTA Provider Node that determines it cannot reliably stay available to +service OTA Requestors SHOULD avoid responding with an available OTA Software Image when +responding to a QueryImage command (see QueryImageResponse) unless it has sufficient availabil­ +ity to allow a long-running BDX Protocol transfer to finish. In general, OTA Provider role SHOULD +be fulfilled by a Node with a reliable network availability and stable power, especially if it is set as +a default in the DefaultOTAProviders attribute. + +**11.20.6. OTA Software Update Provider Cluster** + +**11.20.6.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.20.6.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node OTAP +``` +**11.20.6.3. Cluster ID** + +``` +ID Name +0x0029 OTA Software Update Provider +``` +**11.20.6.4. Data Types** + +**StatusEnum Type** + +This data type is derived from enum8. + +See Section 11.20.3.2, “Querying the OTA Provider” for the semantics of these values. + +``` +Page 942 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +0 UpdateAvailable Indicates that the OTA +Provider has an update +available. +``` +### M + +``` +1 Busy Indicates OTA Provider +may have an update, +but it is not ready yet. +``` +### M + +``` +2 NotAvailable Indicates that there is +definitely no update +currently available +from the OTA Provider. +``` +### M + +``` +3 DownloadProtocol­ +NotSupported +``` +``` +Indicates that the +requested download +protocol is not sup­ +ported by the OTA +Provider. +``` +### M + +**ApplyUpdateActionEnum Type** + +This data type is derived from enum8. + +See Section 11.20.3.6, “Applying a software update” for the semantics of the values. This enumera­ +tion is used in the Action field of the ApplyUpdateResponse command. See (Action). + +``` +Value Name Summary Conformance +0 Proceed Apply the update. M +1 AwaitNextAction Wait at least the given +delay time. +``` +### M + +``` +2 Discontinue The OTA Provider is +conveying a desire to +rescind a previously +provided Software +Image. +``` +### M + +**DownloadProtocolEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 BDXSynchronous Indicates support for +synchronous BDX. +``` +### M + +``` +1 BDXAsynchronous Indicates support for +asynchronous BDX. +``` +### O + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 943 +``` + +``` +Value Name Summary Conformance +2 HTTPS Indicates support for +HTTPS. +``` +### O + +``` +3 VendorSpecific Indicates support for +vendor specific proto­ +col. +``` +### O + +Note that only HTTP over TLS (HTTPS) is supported (see RFC 7230). Using HTTP without TLS SHALL +NOT be supported, as there is no way to authenticate the involved participants. + +**11.20.6.5. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 QueryImage client ⇒ server QueryImageRe­ +sponse +``` +### O M + +``` +0x01 QueryIm­ +ageResponse +``` +``` +client ⇐ server N M +``` +``` +0x02 ApplyUp­ +dateRequest +``` +``` +client ⇒ server ApplyUp­ +dateResponse +``` +### O M + +``` +0x03 ApplyUp­ +dateResponse +``` +``` +client ⇐ server N M +``` +``` +0x04 NotifyUp­ +dateApplied +``` +``` +client ⇒ server Y O M +``` +**QueryImage Command** + +Upon receipt, this command SHALL trigger an attempt to find an updated Software Image by the +OTA Provider to match the OTA Requestor’s constraints provided in the payload fields. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 VendorID vendor-id all M +1 ProductID uint16 all M +2 Software­ +Version +``` +``` +uint32 all M +``` +``` +3 Proto­ +colsSup­ +ported +``` +``` +list[Down­ +loadProto­ +colEnum] +``` +``` +max 8 M +``` +``` +4 Hardware­ +Version +``` +``` +uint16 all O +``` +``` +5 Location string 2 O +``` +``` +Page 944 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +6 Requestor­ +CanConsent +``` +``` +bool all False O +``` +``` +7 Meta­ +dataFor­ +Provider +``` +``` +octstr max 512 O +``` +**VendorID Field** + +The value SHALL be the Vendor ID applying to the OTA Requestor’s Node and SHALL match the +value reported by the Basic Information Cluster VendorID attribute. + +**ProductID Field** + +The value SHALL be the Product ID applying to the OTA Requestor’s Node and SHALL match the +value reported by the Basic Information Cluster ProductID attribute. + +**SoftwareVersion Field** + +The SoftwareVersion included in the request payload SHALL provide the value representing the +current version running on the OTA Requestor invoking the command. This version SHALL be +equal to the Software Version attribute of the Basic Information Cluster. + +**ProtocolsSupported Field** + +This field SHALL contain a list of all download protocols supported by the OTA Requestor. + +This field SHALL be used by the OTA Provider to generate the correct URI for the location of the +Software Image when one is found to be available. The values of BDX Synchronous and BDX Asyn­ +chronous SHALL always be supported by an OTA Provider. Furthermore, OTA Providers with access +to external networking SHOULD support the HTTPS protocol. OTA Providers MAY support other +protocols. + +The algorithm to select the specific protocol to use in a given Software Image URI is implementa­ +tion-dependent, provided that the rules in Section 11.20.3.3.1, “Download Protocol selection” are fol­ +lowed. + +See Section 11.20.3.2, “Querying the OTA Provider” and Section 11.20.3.5, “Transfer of OTA Software +Update images” for more details about usage of this field. + +**HardwareVersion Field** + +The value of this field, if present, SHALL contain the OTA Requestor’s hardware version, and SHALL +be equal to the HardwareVersion attribute of the Basic Information Cluster. + +**Location Field** + +The location, if present, SHALL provide the same value as the Basic Information Cluster Location + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 945 +``` + +attribute for the OTA Requestor as configured. This MAY be used by the OTA Provider logic to allow +per-region selection of the Software Image. + +**RequestorCanConsent Field** + +This field SHALL be set to true by an OTA Requestor that is capable of obtaining user consent for +OTA application by virtue of built-in user interface capabilities. Otherwise, it SHALL be false. + +See Section 11.20.3.4, “Obtaining user consent for updating software” for application details about +usage. + +**MetadataForProvider Field** + +This optional field, if present, SHALL consist of a top-level anonymous list; each list element SHALL +have a profile-specific tag encoded in fully-qualified form. Each list element SHALL contain a man­ +ufacturer-specific payload, which the OTA Requestor invoking this command wants to expose to the +receiving OTA Provider. This payload MAY be used for any purpose and SHOULD be as small as +practical. + +The use of this field SHOULD be restricted to Vendor-specific usage and SHALL NOT be used as a +selector required to match for the selection of a Software Image in production environments, +unless absolutely necessary, as the interpretation of this field may be ambiguous to OTA Providers +implementing the Cluster in a compliant but divergent way from the sender. + +An example of usage for this field is for an OTA Requestor to provide specific data about grouping +or authentication in field trial environments, where the OTA Provider is likely to understand it and +be able to act upon it, either for special selection of image, or recording of activity. + +An OTA Provider SHALL report the availability of Software Images, if one is found to be applicable +using the other provided fields, even if the MetadataForProvider field is deemed to contain invalid +or unknown information. That is, the contents of the MetadataForProvider field SHALL NOT be +used to deny a software update to an OTA Requestor, unless both OTA Requestor and OTA Provider +have an externally agreed-upon policy whereby strictly correct additional MetadataForProvider is +expected to fulfill the OTA Software Update process. + +**Usage of the QueryImage Command** + +OTA Requestors SHALL send a QueryImage command to the OTA Provider to determine the avail­ +ability of a new Software Image. + +See Section 11.20.3.2, “Querying the OTA Provider” for full details about the OTA Software Update +Query flow which makes use of this command. + +**QueryImageResponse Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Status StatusEnum all M +``` +``` +Page 946 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 DelayedAc­ +tionTime +``` +``` +uint32 all O +``` +``` +2 ImageURI string max 256 O +3 Software­ +Version +``` +``` +uint32 all O +``` +``` +4 Software­ +Version­ +String +``` +``` +string 1 to 64 O +``` +``` +5 UpdateTo­ +ken +``` +``` +octstr 8 to 32 O +``` +``` +6 UserCon­ +sentNeeded +``` +``` +bool all False O +``` +``` +7 Meta­ +dataForRe­ +questor +``` +``` +octstr max 512 O +``` +**Status Field** + +This field SHALL contain the primary response regarding the availability of a Software Image. + +See Section 11.20.3.2, “Querying the OTA Provider” for details about the possible values for this field +and their meaning. + +**DelayedActionTime Field** + +This field SHALL convey the minimum time to wait, in seconds from the time of this response, +before sending another QueryImage command or beginning a download from the OTA Provider. +OTA Requestors SHALL respect this minimum delay, unless they had previously restarted and lost +track of it. OTA Providers SHOULD expect OTA Requestors to follow this value to their best capabil­ +ity, however, a restarting Node MAY come back sooner, due to having lost track of this state +response. + +The DelayedActionTime field SHALL only be present if the Status field is set to Busy. + +See Section 11.20.3.2, “Querying the OTA Provider” for details about the rules regarding this field. + +**ImageURI Field** + +This field, when present, SHALL contain a URI where the OTA Requestor SHOULD download a Soft­ +ware Image. The syntax of the ImageURI field SHALL follow the URI syntax as specified in +RFC 3986. + +This field SHALL be present if it appears in a QueryImageResponse with a Status of UpdateAvail­ +able. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 947 +``` + +If the ImageURI specifies a BDX Protocol bdx: scheme, then the following rules describe the location +to be used for download: + +1. The URI’s scheme field SHALL be exactly bdx in lowercase characters. +2. The URI’s authority field SHALL contain only the host portion and SHALL use string representa­ + tion of the Operational Node ID of the Node where to proceed with the download, on the same + Fabric on which the OTA Requestor received the QueryImageResponse. +3. The encoding of the Node ID in the host field SHALL use an uppercase hexadecimal format, + using exactly 16 characters to encode the network byte order value of the NodeID, in a similar + fashion as the Node Identifier portion of the Operational Instance Name. + a.The Operational Node ID in the host field SHALL match the NodeID of the OTA Provider + responding with the QueryImageResponse. The usage of a different Node ID than that of the + provider is reserved for future use. This constraint reduces the number of independent + CASE secure channel sessions that have to be maintained to proceed with OTA software + updates, thus reducing energy and resource utilization for the software update process. +4. The user section of the authority field SHALL be absent, as there are no "users" to be considered. +5. The port section of the authority field SHALL be absent, as the port for transport SHALL be + determined through Operational Discovery of the target Node. +6. The URI SHALL NOT contain a query field. +7. The URI SHALL NOT contain a fragment field. +8. The path field SHALL employ absolute path representation and SHALL contain the file designa­ + tor of the software image to download at the BDX server. When used with the BDX server, the + leading / separating the URI authority from the path SHALL be omitted. When contacting the + BDX server, further processing of the file designator SHALL NOT be done, including handling of + URL-encoded escape sequences. Rather, the exact octets of the path, as received SHALL be the + values used by both client and server in handling the file designator. + a.The path SHALL only contain valid URI characters. + +These rules above for BDX URIs simplify parsing for OTA Requestors receiving Image URIs. The fol­ +lowing example procedure shows how the format constraints simplify the extraction of the neces­ +sary data to reach the BDX server for download. + +1. Verify that the URI is 24 characters or longer, which is the minimum length of a valid BDX URI + with all elements present, for example bdx://00112233AABBCCDD/0. +2. Verify the presence of prefix bdx:// indicating a BDX URI. +3. Extract the next 16 characters and convert from uppercase hexadecimal to a 64-bit scalar value, + considering network byte order. This is the destination Node ID. +4. Verify the presence of a path separator / and skip it. +5. Extract the remaining characters of the string as the file designator to employ when initiating + the BDX transfer. + +Example ImageURI values are below, and illustrate some but not all of valid and invalid cases: + +- Synchronous or Asynchronous BDX Protocol: + +``` +Page 948 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +◦ Valid: bdx://8899AABBCCDDEEFF/the_file_designator123 +▪ Node ID: 0x8899AABBCCDDEEFF +▪ File designator: the_file_designator123 +◦ Valid: bdx://0099AABBCCDDEE77/the%20file%20designator/some_more +▪ Node ID: 0x0099AABBCCDDEE77 +▪ File designator: the%20file%20designator/some_more. Note that the %20 are retained and +not converted to ASCII 0x20 (space). The file designator is the path as received verbatim, +after the first '/' (U+002F / SOLIDUS) following the host. +◦ Invalid: bdx://99AABBCCDDEE77/the_file_designator123 +▪ Node ID: Invalid since it is not exactly 16 characters long, due to having omitted leading +zeros. +◦ Invalid: bdx://0099aabbccddee77/the_file_designator123 +▪ Node ID: Invalid since lowercase hexadecimal was used. +◦ Invalid: bdx:8899AABBCCDDEEFF/the_file_designator123 +▪ Invalid since bdx scheme does not contain an authority, that is, it does not have // after +the first :. +``` +- HTTP over TLS: + ◦ Valid: https://example.domain:8466/software/image.bin + +See Section 11.20.3.2, “Querying the OTA Provider” for additional details about the flow. + +**SoftwareVersion Field** + +This field indicates the version of the image being provided to the OTA Requestor by the OTA +Provider when the Status is UpdateAvailable. + +This field SHALL be present if it appears in a QueryImageResponse with a Status of UpdateAvail­ +able. + +See Section 11.20.3.2, “Querying the OTA Provider” for additional details about the flow and accept­ +able values. + +**SoftwareVersionString Field** + +This field provides a string version of the image being provided to the OTA Requestor by the OTA +Provider when the Status is UpdateAvailable. + +This field SHALL be present if it appears in a QueryImageResponse with a Status of UpdateAvail­ +able. + +See Section 11.20.3.2, “Querying the OTA Provider” for additional details about the flow and accept­ +able values. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 949 +``` + +**UpdateToken Field** + +This optional field SHALL be present when the Status field contains UpdateAvailable. + +See Section 11.20.3.6.1, “UpdateToken usage” for additional details about the generation and usage +of UpdateToken. + +**UserConsentNeeded Field** + +This field, if present, SHALL only be interpreted if the OTA Requestor had previously indicated a +value of True in the RequestorCanConsent field of the QueryImageRequest. This field, when present +and set to True, SHALL indicate that a capable OTA Requestor must obtain user-visible consent +prior to downloading the OTA Software Image. + +See Section 11.20.3.4, “Obtaining user consent for updating software” for application details about +usage. + +**MetadataForRequestor Field** + +This optional field, if present, SHALL consist of a top-level anonymous list; each list element SHALL +have a profile-specific tag encoded in fully-qualified form. Each list element SHALL contain a man­ +ufacturer-specific payload, which the OTA Provider wants to expose to the receiving OTA Requestor. +This payload MAY be used for any purpose and SHOULD be as small as practical. + +The presence of this field SHALL NOT be required for correct operation of any OTA Provider com­ +pliant with this Cluster specification. + +The data for this field does not exist in any Distributed Compliance Ledger record and SHOULD +only be emitted by an OTA Provider with this additional knowledge if it has knowledge that the +receiving OTA Requestor MAY be able to use it. + +**ApplyUpdateRequest Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UpdateTo­ +ken +``` +``` +octstr 8 to 32 M +``` +``` +1 NewVersion uint32 all M +``` +**UpdateToken Field** + +This field SHALL contain the UpdateToken as specified in Section 11.20.3.6.1, “UpdateToken usage”. +This field MAY be used by the OTA Provider to track minimal lifecycle state to allow finer-grained +scheduling of the application of Software Images by OTA Requestors. + +**NewVersion Field** + +The NewVersion field included in the request payload SHALL provide the SoftwareVersion value of +the new Software Image which the OTA Requestor is ready to start applying. The OTA Provider MAY +use this new version to track or record Software Image application by OTA Requestors. + +``` +Page 950 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**When Generated** + +The ApplyUpdateRequest Command SHALL be invoked by an OTA Requestor once it is ready to +apply a previously downloaded Software Image. + +**Effect on Receipt** + +Upon receipt of this command the OTA Provider SHALL respond with an Action field consistent +with the next action the OTA Requestor should take, including any possible time delay. + +The OTA Provider SHALL NOT refer to previously stored state about any download progress to +reply. If any state keeping is done by the OTA Provider, it SHALL only relate to the UpdateToken and +the history of prior ApplyUpdateRequest commands. + +See Section 11.20.3.6, “Applying a software update” for a description of the flow in response to an +OTA Provider receiving an invocation of this command. + +**Handling Error Cases** + +See Section 11.20.3.6, “Applying a software update” for all error-handling information. + +**ApplyUpdateResponse Command** + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Action ApplyUp­ +dateActio­ +nEnum +``` +``` +all M +``` +``` +1 DelayedAc­ +tionTime +``` +``` +uint32 all M +``` +**Action Field** + +The Action field SHALL express the action that the OTA Provider requests from the OTA Requestor. +See Section 11.20.3.6, “Applying a software update” for a description of the Action values provided +in response to an OTA Provider receiving an invocation of this command. + +**DelayedActionTime Field** + +The minimum time period the OTA Requestor SHALL wait before executing the Action, in seconds +from receipt. + +If this field has a value higher than 86400 seconds (24 hours), then the OTA Requestor MAY assume +a value of 86400, in order to reduce undue Software Image application delays. + +**NotifyUpdateApplied Command** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 951 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 UpdateTo­ +ken +``` +``` +octstr 8 to 32 M +``` +``` +1 Software­ +Version +``` +``` +uint32 all M +``` +**UpdateToken Field** + +This field SHALL contain the UpdateToken as specified in Section 11.20.3.6.1, “UpdateToken usage”. + +**SoftwareVersion Field** + +The SoftwareVersion included in the request payload SHALL provide the same value as the Soft­ +wareVersion attribute in the invoking OTA Requestor’s Basic Information Cluster, and SHOULD be +consistent with the value representing a new version running on the Node invoking the command. + +**When Generated** + +The NotifyUpdateApplied command SHOULD be invoked in the following two circumstances: + +1. An OTA Requestor has just successfully applied a Software Image it had obtained from a previ­ + ous QueryImage response. +2. An OTA Requestor has just successfully applied a Software Image it had obtained through + means different than those of this Cluster. + +An OTA Provider MAY use the state of invocation of this command to help track the progress of +update for OTA Requestors it knows require a new OTA Software Image. However, due to the possi­ +bility that an OTA Requestor MAY never come back (e.g. device removed from Fabric altogether, or +a critical malfunction), an OTA Provider SHALL NOT expect every OTA Requestor to invoke this +command for correct operation of the OTA Provider. + +This command SHALL be considered optional and SHALL NOT result in reduced availability of the +OTA Provider functionality if OTA Requestors never invoke this command. + +**Effect on Receipt** + +An OTA Provider receiving an invocation of this command MAY log it internally. + +On receiving this command, an OTA Provider MAY use the information to update its bookkeeping of +cached Software Images, or use it for other similar administrative purposes. + +**11.20.7. OTA Software Update Requestor Cluster** + +**11.20.7.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Page 952 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Revision Description +1 Initial revision +``` +**11.20.7.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node OTAR +``` +**11.20.7.3. Cluster ID** + +``` +ID Name +0x002A OTA Software Update Requestor +``` +**11.20.7.4. Data Types** + +**AnnouncementReasonEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 SimpleAnnouncement An OTA Provider is +announcing its pres­ +ence. +``` +### M + +``` +1 UpdateAvailable An OTA Provider is +announcing, either to a +single Node or to a +group of Nodes, that a +new Software Image +MAY be available. +``` +### M + +``` +2 UrgentUpdateAvail­ +able +``` +``` +An OTA Provider is +announcing, either to a +single Node or to a +group of Nodes, that a +new Software Image +MAY be available, +which contains an +update that needs to be +applied urgently. +``` +### M + +**SimpleAnnouncement Value** + +An OTA Provider is announcing its presence, but there is no implication that an OTA Requestor +would have a new Software Image available if it queried immediately. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 953 +``` + +**UpdateAvailable Value** + +An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software +Image MAY be available. The details may only be obtained by executing a OTA Software Update +Query procedure. A receiving OTA Requestor SHOULD only query the indicated OTA Provider at the +ProviderLocation at its next upcoming OTA Provider query. + +**UrgentUpdateAvailable Value** + +An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software +Image MAY be available, which contains an update that needs to be applied urgently. The details +may only be obtained by executing a OTA Software Update Query procedure. A receiving OTA +Requestor SHOULD query the indicated OTA Provider at the ProviderLocation after a random jitter +delay between 1 and 600 seconds. This particular reason SHOULD only be employed when an +urgent update is available, such as an important security update, or just after initial commissioning +of a device, to assist OTA Requestors in more rapidly obtaining updated software. + +**UpdateStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown Current state is not yet +determined. +``` +### M + +``` +1 Idle Indicate a Node not yet +in the process of soft­ +ware update. +``` +### M + +``` +2 Querying Indicate a Node in the +process of querying an +OTA Provider. +``` +### M + +``` +3 DelayedOnQuery Indicate a Node waiting +after a Busy response. +``` +### M + +``` +4 Downloading Indicate a Node cur­ +rently in the process of +downloading a soft­ +ware update. +``` +### M + +``` +5 Applying Indicate a Node cur­ +rently in the process of +verifying and applying +a software update. +``` +### M + +``` +6 DelayedOnApply Indicate a Node waiting +caused by AwaitNex­ +tAction response. +``` +### M + +``` +7 RollingBack Indicate a Node in the +process of recovering +to a previous version. +``` +### M + +``` +Page 954 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +8 DelayedOnUserCon­ +sent +``` +``` +Indicate a Node is capa­ +ble of user consent. +``` +### M + +**Unknown Value** + +This value SHALL indicate that the current state is not yet determined. Nodes SHOULD attempt a +better state reporting. + +**Idle Value** + +This value SHALL indicate a Node not yet in the process of software update, for example because it +is awaiting the moment when a query will be made. + +**Querying Value** + +This value SHALL indicate a Node in the process of querying an OTA Provider with QueryImage +command, including during the process of awaiting a response to that command. + +**DelayedOnQuery Value** + +This value SHALL indicate a Node waiting because it received a prior QueryImageResponse with a +Status field indicating Busy. + +**Downloading Value** + +This value SHALL indicate a Node currently in the process of downloading a software update. + +**Applying Value** + +This value SHALL indicate a Node currently in the process of verifying and applying a software +update. + +**DelayedOnApply Value** + +This value SHALL indicate a Node waiting because it received a prior ApplyUpdateResponse with +an Action field set to AwaitNextAction. + +**RollingBack Value** + +This value SHALL indicate a Node in the process of recovering to a previous version from a new +version that was applied, but that could not remain in force, for reasons such as invalid data +detected on boot, or significant runtime issues such as reboot loops. Eventually, the next state seen +SHOULD be Unknown or Idle. + +**DelayedOnConsent Value** + +This value SHALL indicate a Node is capable of obtaining user consent through its own means, but +is currently awaiting that consent after having determined from a prior QueryImageResponse that +an update was available. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 955 +``` + +**ChangeReasonEnum Type** + +The ChangeReasonEnum Data Type is derived from enum8. + +``` +Value Name Summary Conformance +0 Unknown The reason for a state +change is unknown. +``` +### M + +``` +1 Success The reason for a state +change is the success of +a prior operation. +``` +### M + +``` +2 Failure The reason for a state +change is the failure of +a prior operation. +``` +### M + +``` +3 TimeOut The reason for a state +change is a time-out. +``` +### M + +``` +4 DelayByProvider The reason for a state +change is a request by +the OTA Provider to +wait. +``` +### O + +**Unknown Value** + +This value SHALL indicate that the reason for a state change is unknown. + +**Success Value** + +This value SHALL indicate that the reason for a state change is the success of a prior operation. + +**Failure Value** + +This value SHALL indicate that the reason for a state change is the failure of a prior operation. + +**TimeOut Value** + +This value SHALL indicate that the reason for a state change is a time-out condition as determined +by the OTA Requestor. + +**DelayByProvider Value** + +This value SHALL indicate that the reason for a state change is a request by the OTA Provider to +await for a delay. + +**ProviderLocation Type** + +This structure encodes a fabric-scoped location of an OTA provider on a given fabric. + +``` +Page 956 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 ProviderN +odeID +``` +``` +node-id M +``` +``` +2 Endpoint endpoint- +no +``` +### M + +**ProviderNodeID Field** + +This field SHALL contain the Node ID of the OTA Provider to contact within the Fabric identified by +the FabricIndex. + +**Endpoint Field** + +This field SHALL contain the endpoint number which has the OTA Provider device type and OTA +Software Update Provider cluster server on the ProviderNodeID. This is provided to avoid having to +do discovery of the location of that endpoint by walking over all endpoints and checking their +Descriptor Cluster. + +**11.20.7.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 DefaultO­ +TAProvide +rs +``` +``` +list[Provid +erLoca­ +tion] +``` +``` +desc N [] RW F VA M +``` +``` +0x0001 UpdatePos +sible +``` +``` +bool all True R V M +``` +``` +0x0002 UpdateS­ +tate +``` +``` +UpdateSta­ +teEnum +``` +``` +all Unknown R V M +``` +``` +0x0003 UpdateS­ +tateProgre +ss +``` +``` +uint8 0 to 100 X null R V M +``` +**DefaultOTAProviders Attribute** + +This field is a list of ProviderLocation whose entries SHALL be set by Administrators, either during +Commissioning or at a later time, to set the ProviderLocation for the default OTA Provider Node to +use for software updates on a given Fabric. + +There SHALL NOT be more than one entry per Fabric. On a list update that would introduce more +than one entry per fabric, the write SHALL fail with CONSTRAINT_ERROR status code. + +Provider Locations obtained using the AnnounceOTAProvider command SHALL NOT overwrite val­ +ues set in the DefaultOTAProviders attribute. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 957 +``` + +**UpdatePossible Attribute** + +This field SHALL be set to True if the OTA Requestor is currently able to be updated. Otherwise, it +SHALL be set to False in case of any condition preventing update being possible, such as insufficient +capacity of an internal battery. This field is merely informational for diagnostics purposes and +SHALL NOT affect the responses provided by an OTA Provider to an OTA Requestor. + +**UpdateState Attribute** + +This field SHALL reflect the current state of the OTA Requestor with regards to obtaining software +updates. See Section 11.20.7.4.2, “UpdateStateEnum Type” for possible values. + +This field SHOULD be updated in a timely manner whenever OTA Requestor internal state updates. + +**UpdateStateProgress Attribute** + +This field SHALL reflect the percentage value of progress, relative to the current UpdateState, if +applicable to the state. + +The value of this field SHALL be null if a progress indication does not apply to the current state. + +A value of 0 SHALL indicate that the beginning has occurred. A value of 100 SHALL indicate com­ +pletion. + +This field MAY be updated infrequently. Some care SHOULD be taken by Nodes to avoid over- +reporting progress when this attribute is part of a subscription. + +**11.20.7.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 AnnounceO­ +TAProvider +``` +``` +client ⇒ server Y A O +``` +**AnnounceOTAProvider Command** + +This command MAY be invoked by Administrators to announce the presence of a particular OTA +Provider. + +This command SHALL be scoped to the accessing fabric. + +If the accessing fabric index is 0, this command SHALL fail with an UNSUPPORTED_ACCESS status +code. + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Confor­ +mance +0 ProviderN­ +odeID +``` +``` +node-id M +``` +``` +1 VendorID vendor-id M +``` +``` +Page 958 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Access Quality: Fabric Scoped +2 Announce­ +mentReason +``` +``` +Announce­ +mentReaso­ +nEnum +``` +### M + +``` +3 Meta­ +dataForN­ +ode +``` +``` +octstr max 512 O +``` +``` +4 Endpoint endpoint-no M +``` +**ProviderNodeID Field** + +This field SHALL contain the Node ID of a Node implementing the OTA Provider cluster server, on +the accessing fabric. + +**VendorID Field** + +This field SHALL contain the assigned Vendor ID of the Node invoking this command, as it would +appear in that Node’s Basic Information Cluster VendorID attribute. + +**AnnouncementReason Field** + +This field SHALL contain a value expressing the reason for the announcement. + +**MetadataForNode Field** + +This optional field, if present, SHALL consist of a top-level anonymous list; each list element SHALL +have a profile-specific tag encoded in fully-qualified form. Each list element SHALL contain a man­ +ufacturer-specific payload, which the Node invoking this command wants to expose to the receiving +Node. This payload MAY be used for any purpose and SHOULD be as small as practical, especially if +invoked to groups, in order to reduce networking burden of these payloads. + +This field SHOULD only be included if the sending OTA Provider has knowledge that some recipient +can make use of it. + +**Endpoint Field** + +This field SHALL contain the endpoint number which has the OTA Provider device type and OTA +Software Update Provider cluster server on the ProviderNodeID. This is provided to avoid having to +do discovery of the location of that endpoint by walking over all endpoints and checking their +Descriptor Cluster. + +**When Generated** + +An OTA Provider MAY invoke this command directly to an OTA Requestor, to announce its presence +as an OTA Provider on the Fabric. + +These announcements, if made, SHOULD be made at most once every 24 hours for any given target +Node, to assist OTA Requestors in discovering available OTA Provider resources, unless the +AnnouncementReason is UrgentUpdateAvailable, in which case this command MAY be more fre­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 959 +``` + +quent. + +Any invocation SHALL be made with a delay of at least 1 second between invocations from a given +OTA Provider, to reduce burden on the networking infrastructure and affect a form of serialized jit­ +ter. It is RECOMMENDED to offset the first announcement of a round (i.e. new set of announce­ +ments after a previous complete set) by a random delay time with a distribution span of >= 60 sec­ +onds to jitter announcement schedules over time. + +**Effect on Receipt** + +On receipt of this command, an OTA Requestor SHOULD consider the new ProviderNodeID and +AnnouncementReason to possibly query for new software sooner than it would have with its +default behavior. + +The OTA Requestor SHOULD NOT update entries in the DefaultOTAProviders list based on +announcements. + +The receiving Node MAY ignore the content of the announcement if it is unable or unwilling to fur­ +ther query OTA Providers temporarily, or if its provider list is full. If the announcement is ignored, +the response SHOULD be SUCCESS. + +Depending on the value of the AnnouncementReason field, the OTA Requestor MAY have to query +the OTA Provider. See Section 11.20.7.6.1.3, “AnnouncementReason Field” for the different values +and their meaning. + +If present, the MetadataForNode field’s MAY be used by a receiving OTA Requestor in any way it +deems satisfactory. The MetadataForNode field SHOULD be empty under most normal operational +circumstance, but can be useful in environments such as field trials or integration test environ­ +ments to hint at additional capabilities which OTA Requestors MAY use in a particular Vendor-spe­ +cific context. + +**11.20.7.7. Events** + +``` +ID Name Priority Access Conformance +0x00 StateTransition INFO V M +0x01 VersionApplied CRITICAL V M +0x02 DownloadError INFO V M +``` +**StateTransition Event** + +This event SHALL be generated when a change of the UpdateState attribute occurs due to an OTA +Requestor moving through the states necessary to query for updates. + +The data of this event SHALL contain the following information: + +``` +Page 960 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Previ­ +ousState +``` +``` +UpdateSta­ +teEnum +``` +``` +Unknown M +``` +``` +1 NewState UpdateSta­ +teEnum +``` +### M + +``` +2 Reason ChangeRea­ +sonEnum +``` +### M + +``` +3 TargetSoft­ +wareVer­ +sion +``` +``` +uint32 X null M +``` +**PreviousState Field** + +This field SHALL be set to the state that preceded the transition causing this event to be generated, +if such a state existed. If no previous state exists, the value SHALL be Unknown. + +**NewState Field** + +This field SHALL be set to the state now in effect through the transition causing this event to be gen­ +erated. + +**Reason Field** + +This field SHALL be set to the reason why this event was generated. + +**TargetSoftwareVersion Field** + +This field SHALL be set to the target SoftwareVersion which is the subject of the operation, when­ +ever the NewState is Downloading, Applying or RollingBack. Otherwise TargetSoftwareVersion +SHALL be null. + +**VersionApplied Event** + +This event SHALL be generated whenever a new version starts executing after being applied due to +a software update. This event SHOULD be generated even if a software update was done using +means outside of this cluster. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Software­ +Version +``` +``` +uint32 M +``` +``` +1 ProductID uint16 M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 961 +``` + +**SoftwareVersion Field** + +This field SHALL be set to the same value as the one available in the Software Version attribute of +the Basic Information Cluster for the newly executing version. + +**ProductID Field** + +This field SHALL be set to the ProductID applying to the executing version, as reflected by the Basic +Information Cluster. This can be used to detect a product updating its definition due to a large-scale +functional update that may impact aspects of the product reflected in the DeviceModel schema of +the Distributed Compliance Ledger. + +**DownloadError Event** + +This event SHALL be generated whenever an error occurs during OTA Requestor download opera­ +tion. + +The data of this event SHALL contain the following information: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Software­ +Version +``` +``` +uint32 M +``` +``` +1 BytesDown­ +loaded +``` +``` +uint64 M +``` +``` +2 Pro­ +gressPer­ +cent +``` +``` +uint8 0 to 100 X null M +``` +``` +3 Platform­ +Code +``` +``` +int64 X null M +``` +**SoftwareVersion Field** + +This field SHALL be set to the value of the SoftwareVersion being downloaded, matching the Soft­ +wareVersion field of the QueryImageResponse that caused the failing download to take place. + +**BytesDownloaded Field** + +This field SHALL be set to the number of bytes that have been downloaded during the failing trans­ +fer that caused this event to be generated. + +**ProgressPercent Field** + +This field SHALL be set to the nearest integer percent value reflecting how far within the transfer +the failure occurred during the failing transfer that caused this event to be generated, unless the +total length of the transfer is unknown, in which case it SHALL be null. + +``` +Page 962 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**PlatformCode Field** + +This field SHOULD be set to some internal product-specific error code, closest in temporal/func­ +tional proximity to the failure that caused this event to be generated. Otherwise, it SHALL be null. +This event field MAY be used for debugging purposes and no uniform definition exists related to its +meaning. + +**11.21. Over-the-Air (OTA) Software Update File Format** + +**11.21.1. Scope & Purpose** + +The majority of devices will undergo an over-the-air (OTA) software update at some point during +their operational lifecycle. It cannot be assumed that the Node responsible for serving OTA updates +(OTA Provider) has any specific knowledge about the internals of OTA Requestor Nodes that are +receiving OTA updates. This section provides a standardized header that SHALL be included in all +OTA Software Images, in order to provide the necessary information for OTA Providers to validate +images available for a given OTA Requestor. + +It should be noted that while this specification standardizes an OTA Software Image header that +SHALL be used by all OTA Software Images, this specification does not further attempt to standard­ +ize the remaining contents of those files. + +**11.21.2. General Structure** + +The OTA Software Image file format is composed of a header followed by an opaque body. The +header describes general information about the file such as software version, and the Vendor ID +and Product ID for which the image applies, see Section 11.20.3.3.2, “Conceptual algorithm for +matching OTA Software Images applicable to a query”). + +OTA Software Image files SHALL use a fixed encoding. Individual fields of the OTA Software Image +file may be comprised of more complex data types that utilize other encoding schemes. + +The fields that comprise an OTA Software Image file, listed in the sequential order in which they +SHALL appear, are provided below. + +_Table 87. OTA Software Image File Layout_ + +``` +Name Type +FileIdentifier uint32 +TotalSize uint64 +HeaderSize uint32 +Header see Appendix A, Tag-length-value +(TLV) Encoding Format +Payload N/A +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 963 +``` + +**11.21.2.1. FileIdentifier field** + +The FileIdentifier field is a fixed-width, little-endian-encoded, unsigned 32-bit value that SHALL be +included at the beginning of all OTA software image files in order to quickly identify and distin­ +guish the file as being of that format, without having to examine the contents of the whole file. This +helps distinguishing the file from other file types in storage. The fixed constant value is defined to +be 0x1BEEF11E. + +**11.21.2.2. TotalSize field** + +The TotalSize field is a fixed-width, little-endian-encoded, unsigned 64-bit value that SHALL indi­ +cate the total size, in bytes, of the entire file, including all fields and Payload. This field SHALL +match the total stored size of the file. It SHALL match the sum of: + +- The sizes of the FileIdentifier, TotalSize, and HeaderSize fields. +- The value of the HeaderSize field of this header. +- The value of the PayloadSize field of the Header subfield. + +For example, given: + +- Size of total Header structure is 105 bytes, reflected as HeaderSize = 105 +- Payload size is 128KiB = 128 * 1024 bytes = 131072 bytes, reflected as Header.PayloadSize = + 131072 + +Then the TotalSize would be the sum of: + +- the size of the FileIdentifier, TotalSize, and HeaderSize fields: 4 + 8 + 4 = 16 bytes +- the HeaderSize value = 105 bytes +- the Header.PayloadSize value = 131072 bytes + +This would give a total of 16 + 105 + 131072 = 131193 bytes. The overall file SHALL have this size +and no more, and the TotalSize field SHALL contain that value. + +**11.21.2.3. HeaderSize field** + +The HeaderSize field is fixed-width, little-endian-encoded, unsigned 32-bit value that SHALL indi­ +cate the total size, in bytes, of the TLV-encoded Header field. + +**11.21.2.4. Header field** + +The Header is a TLV structure, encoded with anonymous outer tag, with the following format: + +``` +ota-image-header-struct => STRUCTURE [ tag-order ] +{ +VendorID [0] : UNSIGNED INTEGER [ range 16bits ], +ProductID [1] : UNSIGNED INTEGER [ range 16bits ], +SoftwareVersion [2] : UNSIGNED INTEGER [ range 32bits ], +``` +``` +Page 964 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +SoftwareVersionString [3] : STRING [ length 1..64 ], +PayloadSize [4] : UNSIGNED INTEGER [ range 64bits ], +MinApplicableSoftwareVersion [5, optional] : UNSIGNED INTEGER [ range 32bits ], +MaxApplicableSoftwareVersion [6, optional] : UNSIGNED INTEGER [ range 32bits ], +ReleaseNotesURL [7, optional] : STRING [ length 1..256 ], +ImageDigestType [8] : UNSIGNED INTEGER [ range 8bits ], +ImageDigest [9] : OCTET STRING [ length 0..64 ] +} +``` +**VendorID field** + +The VendorID field SHALL be used by an OTA Provider to determine if a Node is the intended recip­ +ient of the OTA software update file by checking that the VendorID field in the OTA software update +file matches the VendorID received in the Query Image command from the OTA Requestor. This +VendorID field MAY be zero, in which case this OTA software update file MAY apply to more than +one vendor. + +**ProductID field** + +The ProductID field MAY be used by an OTA Provider to determine if a Node is the intended recipi­ +ent of the OTA software update file by checking that the ProductID field in the OTA software update +file matches the ProductID received in the Query Image command from the OTA Requestor. This +ProductID field MAY be zero, in which case this OTA software update file MAY apply to more than +one product. + +**SoftwareVersion field** + +The SoftwareVersion field SHALL contain a totally orderable scalar representation of the version +for the software contained within the file. The SoftwareVersion value SHOULD NOT be displayed to +an end-user. + +For a given version, this SoftwareVersion field SHALL match what the Node will report in its Soft­ +wareVersion attribute in the Basic Information Cluster, once executing the version. + +**SoftwareVersionString field** + +The SoftwareVersionString field SHALL contain a human readable (displayable) representation of +the version for the software contained within the file. The SoftwareVersionString value SHALL NOT +be used by an OTA Provider to determine if the OTA software update file contains a newer image +than what is currently running on a Node. The SoftwareVersionString value SHOULD be displayed +to an end-user when communicating an identification for the software version. + +Format constraints for this field SHALL match the constraints of the SoftwareVersionString +attribute in the Basic Information Cluster. + +For a given version, this SoftwareVersionString field SHALL match what the Node will report in its +SoftwareVersionString attribute in the Basic Information Cluster, once executing the version. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 965 +``` + +**PayloadSize field** + +The PayloadSize field SHALL indicate the total size, in bytes, of the payload contained within this +OTA software update file, beyond the header. The length of all data beyond the terminating byte of +the header structure SHALL be equal to this field’s value. + +**MinApplicableSoftwareVersion field** + +The MinApplicableSoftwareVersion field, if present, SHALL be used by an OTA Provider to deter­ +mine if the OTA Software Image is suitable for the Node, by checking that the MinApplicableSoft­ +wareVersion field in the OTA software update file is less than or equal to the SoftwareVersion +received in the Query Image command from the OTA Requestor. + +**MaxApplicableSoftwareVersion field** + +The MaxApplicableSoftwareVersion field, if present, SHALL be used by an OTA Provider to deter­ +mine if the OTA Software Image is suitable for the Node, by checking that the MaxApplicableSoft­ +wareVersion field in the OTA software update file is greater than or equal to the SoftwareVersion +received in the Query Image command from the OTA Requestor. + +**ReleaseNotesUrl field** + +The ReleaseNotesUrl field, if present, SHOULD specify a link to a product specific web page that +contains release notes for the OTA software update file. The specified URL SHOULD resolve to a +maintained web page available at that URL for the lifetime of the software version’s availability. +The syntax of this field SHALL follow the syntax as specified in RFC 1738 and SHALL use the https +scheme. The maximum length of this field is 256 ASCII characters. + +**ImageDigestType field** + +The ImageDigestTypeField SHALL contain the algorithm used to compute the ImageDigest field. + +The value of this field SHALL be a supported numerical identifier value from the IANA Named +Information Hash Algorithm Registry [https://www.iana.org/assignments/named-information/named-informa­ +tion.xhtml#hash-alg] established as part of RFC 6920. For example, a value of 1 would match the sha- +256 identifier, which maps to the SHA-256 digest algorithm per Section 6.2 of FIPS 180-4 + +It is RECOMMENDED that a digest algorithm be chosen that has a minimum digest length of 256 +bits, such as sha-256 (ID 1 in the registry). + +**ImageDigest field** + +The ImageDigestField SHALL contain the digest of the entire payload of length PayloadSize that fol­ +lows the header. The digest SHALL be computed using the algorithm indicated in the ImageDigest­ +Type field. This digest SHOULD be used by OTA Providers to ensure they have obtained the entire +image expected, and that the contents matches the expectations. + +**11.21.3. Security considerations** + +The OTA Software Image file format does not specify the mechanisms that an OTA Requestor should +use to validate that a software image is valid for itself. Considerations relative to OTA Software + +``` +Page 966 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Image Signing are presented in Section 11.20.4.2, “Image Verification”. + +**11.22. Bulk Data Exchange Protocol (BDX)** + +**11.22.1. Overview** + +Nodes need the ability to transfer "files" between nodes. For example, uploading sensor data or +diagnostics data to another node or downloading software update images from a software update +server both require such a protocol. + +This document defines a Bulk Data Exchange (BDX) protocol, where files are modeled as collections +of bytes with some attached metadata. For the purposes of this protocol, files are opaque, and no +attempt is made to specify their format. However, the protocol allows for extensible metadata so +that higher-level applications can participate in the decision whether to proceed with a requested +file transfer. + +The Bulk Data Exchange (BDX) protocol has some semantic elements influenced by the Trivial File +Transfer Protocol (TFTP) RFC 1350. + +One major difference is that TFTP is defined to run over UDP only, while Bulk Data Transfers can +proceed over various reliable transports including both TCP and UDP, using the Message Reliability +Protocol (see Section 4.12, “Message Reliability Protocol (MRP)”). Therefore, BlockAck and BlockQuery +fulfill the role of application-layer control flow and acknowledgement rather than providing a relia­ +bility and retransmission mechanism. The availability of application-level flow control enables +highly power-constrained nodes to pace transfers in a way that respects their power limitations. + +**11.22.2. Terminology** + +**11.22.2.1. BDX Sender** + +The node that has bulk data to send to another node. + +**11.22.2.2. BDX Receiver** + +The node that receives bulk data from a Sender. + +**11.22.2.3. BDX Initiator** + +The node that initiates a bulk data transfer. The Initiator of a data transfer can either be the Sender +(for "upload", which starts with a SendInit) or the Receiver (for "download", which starts with a +ReceiveInit). + +**11.22.2.4. BDX Responder** + +The node that responds to the initiator by either accepting or rejecting the proposed bulk data +transfer and choosing parameters of the transfer compatible with those proposed by the Initiator. It +can also either be the Sender (for "download", which is when the Responder receives a ReceiveInit) +or the Receiver (for "upload", which is when the Responder receives a SendInit). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 967 +``` + +**11.22.2.5. BDX Synchronous / Asynchronous Modes** + +Bulk data transfers can operate in synchronous ("driven") or asynchronous mode. When operating +in synchronous mode, one party (the Driver) is responsible for controlling the rate at which the +transfer proceeds, and each message in the bulk data transfer protocol SHALL be acknowledged +before the next message will be sent. + +In asynchronous mode, there is no driver and successive messages are freely sent without waiting +for BlockAck responses from the Receiver. In asynchronous mode, flow control is provided by the +underlying transport (e.g. Matter over TCP). + +**11.22.2.6. BDX Driver** + +The node (either Sender or Receiver) that controls the rate at which a synchronous data transfer +proceeds by sending Block or BlockQuery messages to advance the transfer. This facility allows for +intermittently connected devices operating (e.g. due to battery constraints) to complete a bulk data +transfer without requiring them to stay active continuously during the transfer. In every synchro­ +nous bulk data transfer, exactly one device acts as Driver, and the transfer consists of a series of +request/responses, each one initiated by the Driver. + +BDX utilizes features of the underlying message layer to provide reliability and at-most-once deliv­ +ery semantics. If the transport fails to deliver the message within the specified parameters, the BDX +session SHOULD be aborted. For synchronous transfers, if the Driver fails to receive the response to +any given request that is not received within a particular application-determined time, it SHOULD +abort the session. + +**11.22.2.7. BDX Follower** + +The node (either Sender or Receiver) that "follows" the driver in the protocol flow. The protocol +defines the followers as devices that can never be sleepy. Follower either receives a BlockQuery to +send the data upon request from the driver or receives a new Block message and acknowledges it +with a BlockAck message (in synchronous mode). + +**11.22.2.8. BDX Session** + +A bulk data transfer Session is a series of messages passed between a Sender and Receiver that +begins with the Initiator starting the transfer negotiation, and ends with a BlockAckEOF from the +Receiver which indicates receipt of all transmitted data and ends the session. All messages in a ses­ +sion SHALL be sent within the scope of a single Exchange. Only one bulk data transfer session can +be in progress at any time during a Exchange. + +**11.22.3. Protocol Opcodes and Status Report Values** + +**11.22.3.1. BDX Protocol Messages** + +Each message in the BDX protocol is mapped to a unique Protocol Opcode, namespaced under the +PROTOCOL_ID_BDX Protocol ID: + +- Vendor ID = 0x0000 (Matter Common) +- Protocol ID = PROTOCOL_ID_BDX + +``` +Page 968 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Table 88. BDX Protocol Opcodes_ + +``` +Protocol Opcode Message +0x01 SendInit +0x02 SendAccept +0x03 Reserved for future use +0x04 ReceiveInit +0x05 ReceiveAccept +0x06 ... 0x0F Reserved for future use +0x10 BlockQuery +0x11 Block +0x12 BlockEOF +0x13 BlockAck +0x14 BlockAckEOF +0x15 BlockQueryWithSkip +``` +**11.22.3.2. BDX Status Codes** + +The list of status codes used in StatusReport messages to signify a reason for failing or rejecting a +transfer is provided in Table 89, “BDX Status reports”. For StatusReport messages, the protocol +needs to be defined as the BDX protocol, i.e. StatusReport(GeneralCode: FAILURE, ProtocolId: {Ven­ +dorID=0x0000, ProtocolId=BDX}, ProtocolCode: ). + +_Table 89. BDX Status reports_ + +``` +Status code +value +``` +``` +Error Description +``` +``` +0x0012 LENGTH_TOO_LARGE Definite length too large to support. For exam­ +ple, trying to SendInit with too large of a file. +0x0013 LENGTH_TOO_SHORT Definite length proposed for transfer is too +short for the context based on the responder’s +knowledge of expected size. +0x0014 LENGTH_MISMATCH Pre-negotiated size of transfer was not fulfilled +prior to BlockAckEOF. +0x0015 LENGTH_REQUIRED Responder can only support proposed transfer +if definite length is provided. +0x0016 BAD_MESSAGE_CONTENTS Received a malformed protocol message. +0x0017 BAD_BLOCK_COUNTER Received block counter out of order from +expectation. +0x0018 UNEXPECTED_MESSAGE Received a well-formed message that was con­ +textually inappropriate for the current state of +the transfer. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 969 +``` + +``` +Status code +value +``` +``` +Error Description +``` +``` +0x0019 RESPONDER_BUSY Responder is too busy to proceed with a new +transfer at this moment. +0x001F TRANSFER_FAILED_UN­ +KNOWN_ERROR +``` +``` +Other error occurred, such as perhaps an +input/output error occurring at one of the +peers. +0x0050 TRANSFER_METHOD_NOT_­ +SUPPORTED +``` +``` +Received a message that mismatches the cur­ +rent transfer mode. +0x0051 FILE_DESIGNATOR_UN­ +KNOWN +``` +``` +Attempted to request a file whose designator is +unknown to the responder. +0x0052 START_OFFSET_NOT_SUP­ +PORTED +``` +``` +Proposed transfer with explicit start offset is +not supported in current context. +0x0053 VERSION_NOT_SUPPORTED Could not find a common supported version +between initiator and responder. +0x005F UNKNOWN Other unexpected error. +``` +The following StatusReport message ProtocolCode values MAY occur at any time in response to any +BDX message: + +- _UNEXPECTED_MESSAGE_ : When a peer receives a well-formed message that was contextually + inappropriate for the current state of the transfer. For example, receiving a Block message + before a SendAccept message, or other logical inconsistencies. +- _BAD_MESSAGE_CONTENTS_ : When a peer receives a malformed protocol message. +- _TRANSFER_FAILED_UNKNOWN_ERROR_ : Other error occurred, such as perhaps an input/output + error occurring at either peer. +- _UNKNOWN_ : Internal error beyond the usual error handling. + +If any such StatusReport message is received, or any other unexpected StatusReport is received, the +receiving peer SHALL terminate its processing of the transfer and invalidate the exchange. + +**11.22.4. Security and Transport Constraints** + +In order to maintain data-in-transit confidentiality, and ensure authenticated message flows, the +BDX protocol SHALL only be executed over PASE or CASE encrypted session. This is enforced by the +fact that the only messages allowed to be transmitted without message security are the actual PASE +and CASE session establishment messages. + +The BDX protocol MAY be carried over any supported Matter messaging transport, such as BTP, TCP +or MRP, as long as the messages appear in a PASE or CASE session. + +Furthermore, the BDX protocol relies on transport-level reliability. Therefore, BDX SHALL always +be used over reliable transports. For example, usage with Matter messaging over UDP without MRP +reliability, that is, without using the R Flag in the Exchange Flags, would prevent the necessary reli­ +ability. + +``` +Page 970 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.22.5. Transfer Management Messages** + +**11.22.5.1.** SendInit **and** ReceiveInit **Messages** + +A SendInit message is sent by an Initiator to propose a BDX Transfer session where the Initiator +wants to be a Sender and deliver information to another node. + +A ReceiveInit message is sent by an Initiator to propose a BDX Transfer session where the Initiator +wants to be a Receiver and obtain information from another node. + +Any BDX transfer exchange begins with one of these two messages. + +Both SendInit and ReceiveInit initiate a negotiation for a number of parameters: + +- the Initiator (sender of the message) proposes the transfer parameters and the block size; +- the Responder (receiver of the message) responds with a set of parameters compatible with the + Initiator’s proposal, according to the Responder’s subset of capabilities in common with the Ini­ + tiator. + +The Responder SHALL indicate all the supported modes of operation applicable to the session by +replying, upon success, with SendAccept (in response to SendInit) or ReceiveAccept (in response to +ReceiveInit). + +The parameters in the SendAccept/ReceiveAccept message MUST be used in the transfer. If those +parameters are unacceptable to the Initiator, it MUST abort the transfer with an appropriate error +per Table 89, “BDX Status reports”. + +Possible replies for SendInit (See Section 11.22.7, “Synchronous Transfers Message Flows” for exam­ +ples): + +- Success: SendAccept, if the transfer is accepted by the Responder +- Failure: StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: ), + if the transfer is rejected by the Responder, or anything that prevents the Responder from being + able to proceed with the transfer as requested. + ◦ _FILE_DESIGNATOR_UNKNOWN_ : The file designator field was present and contained a file + designator not supported by the responder. + ◦ _START_OFFSET_NOT_SUPPORTED_ : The start offset field contained an invalid start offset, or + presence of start offset indicated by RC[STARTOFS] is not supported by the responder. + ◦ _LENGTH_TOO_LARGE_ : The definite length field was present, but too large for the responder. + ◦ _LENGTH_TOO_SHORT_ : The definite length field was present, but contextually too short + based on the responder’s knowledge of expected size. + ◦ _LENGTH_REQUIRED_ : The responder can only support the proposed transfer if the definite + length field is provided. + ◦ _TRANSFER_METHOD_NOT_SUPPORTED_ : The responder does not support the proposed + transfer control method. + ◦ _RESPONDER_BUSY_ : The responder is too busy to process another transfer. An initiator + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 971 +``` + +``` +SHOULD wait at least 60 seconds before attempting to initiate a new SendInit with this +responder. +``` +Possible replies for ReceiveInit (See Section 11.22.7, “Synchronous Transfers Message Flows” for +examples): + +- Success: ReceiveAccept, if the transfer is accepted by the Responder +- Failure: StatusReport(GeneralCode: FAILURE, ProtocolId: PROTOCOL_ID_BDX, ProtocolCode: + ), if the transfer is rejected by the Responder, or anything that prevents the + Responder from being able to proceed with the transfer as requested: + ◦ _FILE_DESIGNATOR_UNKNOWN_ : The file designator field was present and contained a file + designator not found or supported by the responder. + ◦ _START_OFFSET_NOT_SUPPORTED_ : The start offset field contained an invalid start offset, or + presence of start offset indicated by RC[STARTOFS] is not supported by the responder. + ◦ _LENGTH_TOO_LARGE_ : The definite length field was present, but too large for the responder. + ◦ _LENGTH_REQUIRED_ : The responder can only support the proposed transfer if the definite + length field is provided. + ◦ _TRANSFER_METHOD_NOT_SUPPORTED_ : The responder does not support the proposed + transfer control method. + ◦ _RESPONDER_BUSY_ : The responder is too busy to process another transfer. An initiator + SHOULD wait at least 60 seconds before attempting to initiate a new ReceiveInit with this + responder. + +The format of the SendInit and ReceiveInit messages is enumerated in Table 90, “Sen­ +dInit/ReceiveInit message fields”. + +_Table 90. SendInit/ReceiveInit message fields_ + +``` +Field Size Notes +Message ID: SendInit(0x01), ReceiveInit(0x04) +Proposed +Transfer Con­ +trol (PTC) +``` +``` +1 octet +``` +``` +Range Control +(RC) +``` +``` +1 octet +``` +``` +Proposed Max +Block Size +(PMBS) +``` +``` +2 octets Unsigned little-endian +``` +``` +Start Offset +(STARTOFS) +``` +``` +4/8 octets Optional. +``` +- Present if RC[STARTOFS] = 1 +- Size = 4 if RC[WIDERANGE] = 0 +- Size = 8 if RC[WIDERANGE] = 1 + +``` +Page 972 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Field Size Notes +Proposed Max +Length (LEN) +``` +``` +4/8 octets Optional. +``` +- Present if RC[DEFLEN] = 1 +- Size = 4 if RC[WIDERANGE] = 0 +- Size = 8 if RC[WIDERANGE] = 1 +File Designator +Length (FDL) + +``` +2 octets Unsigned little-endian +``` +``` +File Designator +(FD) +``` +``` +variable length +``` +``` +Metadata +(MDATA) +``` +``` +variable Optional, TLV. +``` +The following subsections describe the fields composing the SendInit and `ReceiveInit messages. + +**Proposed Transfer Control (** PTC **)** + +The Proposed Transfer Control (PTC) field specifies, as subfields, the highest version of the protocol +and the transfer modes supported by the Initiator of the transfer. All PTC subfields are Initiator-pro­ +posed. It is up to the Responder to decide what version and modes it will use. The first version, as of +Matter specification 1.0 is BDX Version 0. + +At least one of the PTC[RECEIVER_DRIVE] or PTC[SENDER_DRIVE] field bits SHALL be set in order for the +Responder to set the final transfer control. If neither PTC[RECEIVER_DRIVE] or PTC[SENDER_DRIVE] is +set, the transfer SHALL be rejected by the Responder. + +The PTC[ASYNC] bit is an optimization of the transfer and is subject to negotiation with the Respon­ +der. In general if the Initiator proposes an ASYNC transfer, it SHOULD also be prepared to accept a +synchronous transfer, and SHOULD at least list one of PTC[RECEIVER_DRIVE] or PTC[SENDER_DRIVE] in +the request. + +Multiple transfer modes can be specified, which signifies that the Initiator can support any of those +transfer modes. For example, if PTC[ASYNC], PTC[RECEIVER_DRIVE] and PTC[SENDER_DRIVE] bits are set +on a SendInit, it indicates that the Initiator supports 3 distinct transfer modes: synchronous Sender +drive, synchronous Receiver drive and asynchronous (drive is implied). Only one transfer mode +SHALL be used in the actual transfer. The Responder SHALL choose which one to use. If the +Responder supports both Sender and Receiver drive, it SHOULD prefer to use Sender drive to retain +the request/response semantics. + +_Table 91. SendInit/ReceiveInit Proposed Transfer Control (_ PTC _) field structure_ + +``` +bit 7 6 5 4 3 2 1 0 +RFU ASYNC RECEIVER +_DRIVE +``` +### SENDER_­ + +### DRIVE + +### VERSION + +The fields for PTC are: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 973 +``` + +**SendInit/ReceiveInit** PTC[VERSION] **: proposed protocol version** + +- Width: 4 bits +- Values: 0x00-0x0F proposed protocol version + +**SendInit/ReceiveInit** PTC[SENDER_DRIVE] **: sender drive supported** + +- Width: 1 bit +- Values: + ◦ 0 if Sender drive is not supported + ◦ 1 if Sender drive is supported by Initiator + +**SendInit/ReceiveInit** PTC[RECEIVER_DRIVE] **: receiver drive supported** + +- Width: 1 bit +- Values: + ◦ 0 if Receiver drive is not supported + ◦ 1 if Receiver drive is supported by Initiator + +**SendInit/ReceiveInit** PTC[ASYNC] **: asynchronous mode supported** + +- Width: 1 bit +- Values: + ◦ 0 if asynchronous mode is not supported + ◦ 1 if asynchronous mode is supported by Initiator + ◦ NOTE: Synchronous mode is always implicitly supported. + +**Range Control (** RC **)** + +The Range Control (RC) field specifies parameters related to offset and length of the transfer: + +- whether the transfer has a definite length (DEFLEN); +- whether an offset is present (STARTOFS); +- the width of the length and offset fields (WIDERANGE). + +_Table 92. SendInit/ReceiveInit Range Control (_ RC _) field structure_ + +``` +bit 7 6 5 4 3 2 1 0 +RFU WIDERA +NGE +``` +### RFU STARTOF + +### S + +### DEFLEN + +The fields for RC are: + +``` +Page 974 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**SendInit/ReceiveInit** RC[DEFLEN] **: definite length present** + +- Width: 1 bit + ◦ Values: + ▪ 0 if no length is present (indefinite length) + ▪ 1 if a definite length is present (see DEFLEN field) + +**SendInit/ReceiveInit** RC[STARTOFS] **: start offset present** + +- Width: 1 bit + ◦ Values: + ▪ 0 if a start offset is not present + ▪ 1 if a start offset is present + +**SendInit/ReceiveInit** RC[WIDERANGE] **: wide (64-bit) range enable for values** + +- Width: 1 bit + ◦ Values: + ▪ 0 to indicate that offset (STARTFOFS) and length (DEFLEN) are 4 octets (32-bit) little-endian + unsigned quantities. + ▪ 1 to indicate that offset (STARTFOFS) and length (DEFLEN) are 8 octets (64-bit) little-endian + unsigned quantities. + +**Proposed Max Block Size (** PMBS **)** + +The Proposed Max Block Size (PMBS) field specifies the maximum data size (in bytes) of the block +that the Initiator supports, exclusive of block header fields, such as a block counter. + +**Start Offset (** STARTOFS **)** + +The Start Offset (STARTOFS) field is an optional 32-bit/64-bit length that specifies the offset in bytes +from start of the file from which the Sender would start the transfer. This allows large file transfers +to be segmented into multiple bulk transfer sessions. The RC[STARTOFS] bit indicates whether this +start offset is present in the message. The RC[WIDERANGE] bit defines the size of start offset quantity +(32-bit or 64-bit). Receivers are not required to accept non-zero start offset transfers. Devices +SHOULD make every attempt to support non-zero start offset. If a Responder cannot accept a given +start offset, it MUST reject the SendInit with a StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, +ProtocolCode: START_OFFSET_NOT_SUPPORTED). See Table 89, “BDX Status reports”. + +**Length (** DEFLEN **)** + +The optional length (DEFLEN) field specifies a predetermined definite length for the transfer. For a +SendInit message, this field defines the number of bytes the Sender commits to sending to the +Receiver. For a ReceiveInit message, this field defines the maximum number of bytes that the +Receiver wishes to receive from the Sender. The SendAccept or ReceiveAccept response will then con­ +tain the expected length for the transfer. A Receiver receiving a premature BlockEOF would have to +consider the transfer failed. A length of 0 or a missing length field signifies an indefinite length. The + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 975 +``` + +RC(DEFLEN) bit indicates the presence of this field. The RC[WIDERANGE] bit indicates the width of this +field. + +**File Designator Length (** FDL **)** + +The File Designator Length (FDL) field is a 16-bit unsigned little-endian field over 2 octets that speci­ +fies the length of the upcoming file designator (FD) field, which has variable length. + +**File Designator (** FD **)** + +The File Designator (FD) field is a variable-length identifier chosen by the Initiator to identify the +payload to be transferred. In some applications, this identifier will need to be negotiated in +advance, so that the Responder will know how to handle the file designator. In other applications, +the file designator and optional metadata will be sufficient for the Responder to determine whether +to accept the file transfer and how to handle the data, allowing the transfer to proceed without any +additional message exchanges. + +The length of this field in bytes is provided by the previous File Designator Length (FDL) field. + +**Metadata (** MDATA **)** + +The Metadata (MDATA) field is an optional field, and allows the Initiator to send additional applica­ +tion-specific information about the file to be transferred. The contents of this field are not specified +here; applications can use it to avoid needing a separate round-trip negotiation of the file designa­ +tor, as described above. The TLV metadata consumes the rest of the payload for the SendInit +/ReceiveInit message, after all previous fields. + +**11.22.5.2. SendAccept Message** + +A SendAccept message is sent by the Responder as a response to SendInit in order to accept a BDX +Transfer session where the Initiator wants to be a Sender and deliver information (upload) to the +Responder. The final transfer parameters used are decided by the Responder, given the Initiator +proposals in the SendInit message. + +Responds to (See Section 11.22.7, “Synchronous Transfers Message Flows” for examples): + +- SendInit - to accept the proposed transfer. + +Possible replies (See Section 11.22.7, “Synchronous Transfers Message Flows” for examples): + +- Block - if the Initiator accepts the parameters from the SendAccept message, and the transfer + method is Sender drive. +- StatusReport - If there was another error the Initiator encountered. + +Possible follow-ups (See Section 11.22.7, “Synchronous Transfers Message Flows” for examples): + +- BlockQuery - if the proposed method is Receiver drive. If the Initiator does not accept the para­ + meters, it SHOULD ignore this and send a StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, + ProtocolCode: TRANSFER_METHOD_NOT_SUPPORTED) to end the transfer. + +``` +Page 976 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.22.5.3. ReceiveAccept Message** + +A ReceiveAccept message is sent by the Responder as a response to ReceiveInit in order to accept a +BDX Transfer session where the Initiator wants to be a Receiver and receive information (down­ +load) from the Responder. The final transfer parameters used are decided by the Responder, given +the Initiator proposals in the ReceiveInit message. + +Responds to (See Section 11.22.7, “Synchronous Transfers Message Flows” for examples): + +- ReceiveInit - to accept the proposed transfer. + +Possible replies (See Message Flows for examples): + +- BlockQuery - if the Initiator accepts the parameters from the ReceiveAccept message, and the + transfer method is Receiver drive. +- StatusReport - If there was another error the Initiator encountered. + +Possible follow-ups (See Section 11.22.7, “Synchronous Transfers Message Flows” for examples): + +- Block - if the proposed method is Sender drive. If the Initiator does not accept the parameters, it + SHOULD ignore this and send a StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, Protocol­ + Code: TRANSFER_METHOD_NOT_SUPPORTED) to end the transfer. + +**11.22.5.4. SendAccept and ReceiveAccept message fields** + +The format of the SendAccept message is enumerated in Table 93, “SendAccept message fields”. + +The format of the ReceiveAccept message is enumerated in Table 94, “ReceiveAccept message +fields”. + +Since the meaning of many fields overlap in these messages, they are described only once following +the ReceiveAccept message fields. + +_Table 93. SendAccept message fields_ + +``` +Field Size Notes +Message ID: SendAccept(0x02) +Transfer Con­ +trol (TC) +``` +``` +1 octet Must specify exactly one of: +``` +- TC[ASYNC] +- TC[RECEIVER_DRIVE] +- TC[SENDER_DRIVE] +Max Block Size +(MBS) + +``` +2 octets Unsigned little-endian. Must be <= PMBS. +``` +``` +Metadata +(MDATA) +``` +``` +variable Optional, TLV. +``` +_Table 94. ReceiveAccept message fields_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 977 +``` + +``` +Field Size Notes +Message ID: ReceiveAccept(0x05) +Transfer Con­ +trol (TC) +``` +``` +1 octet Must specify exactly one of: +``` +- TC[ASYNC] +- TC[RECEIVER_DRIVE] +- TC[SENDER_DRIVE] +Range Control +(RC) + +``` +1 octet +``` +``` +Max Block Size +(MBS) +``` +``` +2 octets Unsigned little-endian. Must be <= PMBS. +``` +``` +Length (LEN) 4/8 octets Optional. +``` +- Present if RC[DEFLEN] = 1 +- Size = 4 if RC[WIDERANGE] = 0 +- Size = 8 if RC[WIDERANGE] = 1 +Metadata +(MDATA) + +``` +variable Optional, TLV. +``` +The following subsections describe the fields composing the SendAccept and ReceiveAccept mes­ +sages. + +**Transfer control (** TC **)** + +The Transfer Control (TC) field specifies, as subfields, the transfer mode and protocol version. + +For the transfer mode (TC[SENDER_DRIVE], TC[RECEIVER_DRIVE]), exactly one mode SHALL be chosen +for this transfer, which MUST be one of the original proposed transfer methods sent by the Initia­ +tor. + +The version SHALL be the newest version that is supported by the Responder and is not newer than +the proposed version sent by the Initiator. If the Responder cannot support a version equal or older +to the proposed version, the Responder MUST send a StatusReport(GeneralCode: FAILURE, Proto­ +colId: BDX_, ProtocolCode: VERSION_NOT_SUPPORTED) to end the transfer. + +The Responder MAY reject a proposed asynchronous transfer (PTC[ASYNC] = 1) by sending a Status­ +Report(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: TRANSFER_METHOD_NOT_SUPPORTED) to +end the transfer. If the Initiator proposed both the PTC[RECEIVER_DRIVE] and PTC[SENDER_DRIVE], the +Responder SHALL select exactly one of those options. In that case, in order to retain the +request/response semantics, the Responder MUST default to TC[SENDER_DRIVE]. + +_Table 95. SendAccept/ReceiveAccept Transfer Control (_ TC _) field structure_ + +``` +bit 7 6 5 4 3 2 1 0 +RFU ASYNC RECEIVER +_DRIVE +``` +### SENDER_­ + +### DRIVE + +### VERSION + +``` +Page 978 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The fields for TC are: + +**SendAccept/ReceiveAccept** TC[VERSION] **: protocol version** + +- Width: 4 bits +- Values: 0x00-0x0F accepted protocol version + +**SendAccept/SendAccept** TC[SENDER_DRIVE] **: sender drive enabled** + +- Width: 1 bit +- Values: + ◦ 0 if Sender drive was not chosen + ◦ 1 if Sender drive was chosen (if this is set, TC[RECEIVER_DRIVE] MUST be 0) + +**SendAccept/ReceiveAccept** TC[RECEIVER_DRIVE] **: receiver drive enabled** + +- Width: 1 bit +- Values: + ◦ 0 if Receiver drive was not chosen + ◦ 1 if Receiver drive was chosen (if this is set, TC[SENDER_DRIVE] MUST be 0) + +**SendAccept/ReceiveAccept** TC[ASYNC] **: asynchronous mode enabled** + +- Width: 1 bit +- Values: + ◦ 0 if synchronous mode was chosen for the transfer. + ◦ 1 if asynchronous mode was chosen for the transfer. + ◦ NOTE: Synchronous mode is always implicitly supported. + +**ReceiveAccept Range Control (** RC **)** + +``` +NOTE This field is only present in ReceiveAccept messages. +``` +The Range Control (RC) field specifies parameters related to offset and length of the transfer: + +- whether the transfer has a definite length (DEFLEN); +- the width of the length and offset fields (WIDERANGE). + +_Table 96. ReceiveAccept Range Control (_ RC _) field structure_ + +``` +bit 7 6 5 4 3 2 1 0 +RFU WIDERA +NGE +``` +### RFU DEFLEN + +The fields for RC are: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 979 +``` + +**ReceiveAccept** RC[DEFLEN] **: definite length present** + +- Width: 1 bit + ◦ Values: + ▪ 0 if no length is present (indefinite length) + ▪ 1 if a definite length is present (see LEN field) + +**ReceiveAccept** RC[WIDERANGE] **: wide (64-bit) range enable for values** + +- Width: 1 bit + ◦ Values: + ▪ 0 to indicate that length LEN is a 4 octets (32-bit) little-endian unsigned quantity. + ▪ 1 to indicate that length LEN is a 8 octets (64-bit) little-endian unsigned quantity. + +**Max Block Size (** MBS **)** + +The Max Block Size (MBS) field specifies the maximum size, in bytes, of each block for this transfer. +The maximum whole block payload size will be the sum of the Max Block Size and the size of the +block parameters (such as the block counter). This value MUST be less than or equal to the pro­ +posed max block size (PMBS). + +**Length (** LEN **)** + +``` +NOTE This field is only present in ReceiveAccept messages, and only if RC[DEFLEN] = 1. +``` +The Length (LEN) field specifies the length of the transfer. If the Initiator indicated a definite length, +this length SHALL either be: + +- equal to the proposed definite length, if the remaining data in the file beyond the Start Offset + (STARTOFS) is larger or equal to the proposed length; +- smaller than the proposed definite length, if the remaining data in the file beyond the Start Off­ + set (STARTOFS) is smaller than the proposed length. + +If this field is present, and the Initiator indicated an indefinite length (i.e. RC[DEFLEN] = 0 in +ReceiveInit), this Length field SHALL be equal to the size of the file remaining (if known), or 0, for +indefinite. The absence of the Length (LEN) field implies indefinite length. + +**Metadata (** MDATA **)** + +The Metadata (MDATA) field is optional and allows the Responder to provide application-specific +metadata about the transfer in TLV format. The TLV metadata consumes the rest of the payload for +the SendAccept/ReceiveAccept message, after all previous fields. + +**11.22.6. Data Transfer Messages** + +``` +Page 980 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.22.6.1. Block Ordering Rules** + +The following behavior applies to all messages containing a Block Counter field. + +Queries (BlockQuery message) MUST be made in ascending and sequential Block Counter order. If +the arriving Block Counter at the recipient is not exactly equal to the previous `BlockQuery’s Block +Counter, plus 1 (i.e. next block is being directly asked), a block counter SHALL be considered out-of- +order by the recipient. + +Blocks (Block, BlockEOF message) MUST be sent in ascending and sequential Block Counter order. If +the arriving Block Counter at the recipient is not exactly equal to current expected Block Counter, +the block counter SHALL be considered out-of-order by the recipient. + +Block acknowledgements (BlockAck, BlockAckEOF messages) MUST be sent with the same Block +Counter as the previously received Block/BlockEOF, since they convey a direct acknowledgement. If +the arriving Block Counter at the recipient is not exactly equal to the last sent Block Counter, the +Block Counter SHALL be considered out-of-order by the recipient. + +On any out-of-order block counter condition described above, the recipient of the out-of-order mes­ +sage MUST send a StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: BAD_BLOCK_­ +COUNTER) and abort the transfer. On receiving a StatusReport(GeneralCode: FAILURE, ProtocolId: +BDX, ProtocolCode: BAD_BLOCK_COUNTER), the recipient MUST abort the transfer. + +Since Block Counter fields are always 32-bit unsigned integer values, but file sizes may be specified +over 64-bit lengths to support very large transfers, the ordering for a "next block counter" SHALL +use modulo 2^32 integer arithmetic. Therefore, if the last Block Counter was 0xFFFF_FFFF, the next +expected Block Counter would be 0x0000_0000. + +### NOTE + +``` +Since the data length of blocks does not need to exactly match the Max Block Size in +Block/BlockEOF messages, it is application-dependent whether Block Counters can be +used to statelessly track the offset within a span of initiated transfer. That is, the +relationship: current_offset = start_offset + (max_block_size * block_counter) is +true only if it is contextually known that this usage applies for a given transfer +application. This relationship, is MUST NOT be assumed, since it may not apply, such +as when variable-sized blocks are being sent to optimize a given data transfer flow. +``` +**11.22.6.2. BlockQuery Message** + +The BlockQuery message is sent by the driving Receiver to the follower to request the next block of +data. This message implies a BlockAck of the previous block if no BlockAck was explicitly sent. The +block counter SHOULD start at 0 at the start of the transfer, and increment by one for each subse­ +quent block. + +In asynchronous transfers, no BlockQuery messages are sent. + +The fields of the BlockQuery message are: + +_Table 97. BlockQuery message fields_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 981 +``` + +``` +Field Size Notes +Message ID: BlockQuery(0x10) +BlockCounter 4 octets Unsigned little-endian +``` +**11.22.6.3. BlockQueryWithSkip Message** + +The BlockQueryWithSkip message MAY be sent by a driving Receiver to the follower to request the +next block of data, after skipping an amount forward within the stream. This message implies a +BlockAck of the previous block if no BlockAck was explicitly sent. + +This message is semantically equivalent to a BlockQuery, but with the following additions: + +- Before the next Block is sent by the Sender, the cursor within the underlying data transferred + by the Sender SHALL be advanced by BytesToSkip bytes. +- If, after skipping BytesToSkip bytes, the cursor reaches the end of the file, or beyond, then the + next message from the Sender SHALL be a BlockEOF with empty contents. In other words, there + SHALL be no error indicated when receiving a request to skip past the end of the transferable + data. +- The amount of BytesToSkip MAY be a size that does not match the current transfer’s maximum + block size. + +This message enables seeking forward in BDX transfers without requiring the termination of a +transfer followed by the re-opening of a new one with a different STARTOFS field specified. + +In asynchronous transfers, no BlockQueryWithSkip messages are sent. + +The fields of the BlockQueryWithSkip message are: + +_Table 98. BlockQueryWithSkip message fields_ + +``` +Field Size Notes +Message ID: BlockQueryWithSkip(0x15) +BlockCounter 4 octets Unsigned little-endian +BytesToSkip 8 octets Unsigned little-endian +``` +**11.22.6.4. Block Message** + +The Block message is the container for the actual bulk transfer data. + +Blocks MUST be sent ascending and sequential block counter order (see Section 11.22.6.1, “Block +Ordering Rules”). Block data payload length does not need to exactly match the Max Block Size for +the transfer. + +The fields of the Block message are: + +_Table 99. Block message fields_ + +``` +Page 982 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Field Size Notes +Message ID: Block(0x11) +Block Counter 4 octets Unsigned little-endian +Data Variable Length • The data field’s length is that of the remain­ +der of the message payload after the Block +Counter field, since Matter messages have +definite length. +``` +- The length MUST be in the range [0 < + Length <= Max Block Size], where Max + Block Size is the negotiated Max Block Size + matching the SendAccept / ReceiveAccept + message that initiated the transfer. + +**11.22.6.5. BlockEOF Message** + +The BlockEOF message represents the final block in a data transfer. + +Note that, unlike a Block, BlockEOF MAY have a data length of zero. If the entire transfer fits within +the negotiated block size, the BlockEOF SHALL be the one and only message sent in the exchange +and no Block messages will be sent. In that trivial case, the Block Counter would be 0 in the Block­ +EOF. + +On receipt of this message, the recipient SHALL verify that the pre-negotiated file size was trans­ +ferred, if a definite size had been given. If the Receiver finds a discrepancy between the pre-negoti­ +ated size of the file and the amount of data that the Sender has sent, then it MAY consider the trans­ +fer failed. In that case, the Receiver MAY respond with a StatusReport(GeneralCode: FAILURE, Proto­ +colId: BDX, ProtocolCode: LENGTH_MISMATCH) message. + +Blocks MUST be sent ascending and sequential block counter order (see Section 11.22.6.1, “Block +Ordering Rules”). Block data payload length does not need to exactly match the Max Block Size for +the transfer. + +_Table 100. BlockEOF message fields_ + +``` +Field Size Notes +Message ID: BlockEOF(0x12) +Block Counter 4 octets Unsigned little-endian +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 983 +``` + +``` +Field Size Notes +Data Variable Length • The data field’s length is that of the remain­ +der of the message payload after the Block +Counter field, since Matter messages have +definite length. +``` +- The length MUST be in the range [0 <= + Length <= Max Block Size], where Max + Block Size is the negotiated Max Block Size + matching the SendAccept / ReceiveAccept + message that initiated the transfer. In con­ + trast to the Block message, a length of 0 is + permissible to indicate an empty file. + +**11.22.6.6. BlockAck Message** + +The BlockAck message is an application-level acknowledgement that a Block was received, and not +necessarily that the Block’s data was stored. + +If the Sender is driving in a synchronous transfer, the Receiver MUST send a BlockAck in response to +each block of data received. If the Receiver is driving in a synchronous transfer, the Receiver MAY +send a BlockAck after receipt of a Block, and before its next BlockQuery. For example, the Receiver +SHOULD send a BlockAck if it knows it will be going to sleep for some time before the next Block­ +Query, so that the Sender can free resources associated with the last block. + +In asynchronous transfers, no BlockAck messages are sent. + +The Block Counter in a BlockAck MUST correspond to the Block Counter which was embedded in the +Block being acknowledged (see Section 11.22.6.1, “Block Ordering Rules”). + +_Table 101. BlockAck message fields_ + +``` +Field Size Notes +Message ID: BlockAck(0x13) +BlockCounter 4 octets Unsigned little-endian +``` +**11.22.6.7. BlockAckEOF Message** + +The BlockAckEOF message is sent in response to BlockEOF to indicate that the Receiver has received +all data. + +This message MUST be sent in both synchronous and asynchronous transfers. This signals the end +of the ongoing bulk data transfer session and a successful transfer of the file. The table below enu­ +merates the contents of the message + +The Block Counter in a BlockAckEOF MUST correspond to the Block Counter which was embedded in +the BlockEOF being acknowledged (see Section 11.22.6.1, “Block Ordering Rules”). + +_Table 102. BlockAckEOF message fields_ + +``` +Page 984 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Field Size Notes +Message ID: BlockAckEOF(0x14) +BlockCounter 4 octets Unsigned little-endian +``` +**11.22.7. Synchronous Transfers Message Flows** + +_Figure 92. Version negotiation: both participants support V1 of the protocol_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 985 +``` + +_Figure 93. Version negotiation: Initiator supports V2 of the protocol, while Responder supports V1_ + +``` +Page 986 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 94. Synchronous file sending from sleepy device acting as driving Sender_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 987 +``` + +_Figure 95. Synchronous file sending to sleepy device acting as driving Receiver_ + +``` +Page 988 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 96. Synchronous file receiving by sleepy device acting as driving Receiver_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 989 +``` + +_Figure 97. Synchronous file receiving by device acting as driving Receiver, including BlockQueryWithSkip_ + +``` +Page 990 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 98. Synchronous file receive from sleepy device acting as driving Sender_ + +In the following flow, the Initiator wants to continue downloading (receiving) a file after the first +200 bytes were received in a previous transfer. The entire remaining contents is desired until the +end of the file. Therefore, the proposed start offset (STARTOFS) is set to the offset of the first byte +desired in the first block transferred. The proposed length (PLEN) is set to 0 (or omitted) to announce +desire to receive as much as is available from the Sender. + +During negotiation, the length (LEN) field of ReceiveAccept is set to the known remaining file size by +the Sender. This could have also been omitted in case the Sender could not or would not state the +maximal amount of data to read. Observe that block numbering begins at 0 for every transfer, even +if the start offset is not 0. Block indices are always 0-based for every transfer. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 991 +``` + +_Figure 99. Re-started receive from sleepy device acting as driving Sender_ + +In the following flow, the Initiator wants to download (receive) only a section of a file, starting at +offset 200, and of length 1000. + +During negotiation, the length (LEN) field of ReceiveAccept is set to match the proposed desired +region length by the Sender. The range is fully-specified by the \[startOffset .. startOffset + + +``` +Page 992 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +length] span. + +_Figure 100. Range-based receive from sleepy device acting as driving Sender_ + +**11.22.8. Asynchronous Transfers Message Flows** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 993 +``` + +_Figure 101. Asynchronous file sending_ + +``` +Page 994 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 102. Asynchronous file receiving_ + +**11.23. Distributed Compliance Ledger** + +**11.23.1. Scope & Purpose** + +The CSA’s DCL (Distributed Compliance Ledger) is a distributed store of information used for track­ +ing certification status and Vendor maintained information such as, but not limited to, product +name, product description, and firmware URL. This information is cryptographically secured by +digital signatures and is made available via CSA approved synchronized servers or nodes that are +geographically distributed. + +The Policies, Procedure and Governance of DCL is maintained by Board approved committees that + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 995 +``` + +comprise Test Certification Oversight Committee (TCOC) and Security Advisory Group (SEC AG). + +Distributed Compliance Ledger [https://github.com/zigbee-alliance/distributed-compliance-ledger] is an open- +source project designed to: + +- Act as a data store for device models' information and their compliance status. +- Act as a secure distribution point of device meta data as made available by vendors. +- Act as a secure distribution point of Product Attestation Authorities certificates. +- Act as a secure distribution point of Operational Root CA Certificates (RCAC). + +The DCL is owned and hosted by CSA members in a way that, + +- Write access to Ledger is restricted + ◦ Vendors role can add new device models that belong to the VendorID that is associated with + the public key of that vendor. VendorID is associated to the vendor public key during vendor + account creation process. + ◦ Vendor role can update a subset of existing device model information, such as product + name, product description, firmware and hardware info. Updates are only allowed if the + device is associated with the same vendor account. + ◦ A TestHouse role can write the test status for each device to the Ledger. + ◦ A ZBCertificationCenter role can write the confirmation of the Compliance or revoke the + Compliance status of a device model to the Ledger. +- Read access from DCL is public + ◦ Read DeviceModel info, including firmware and hardware versions from the DCL. + ◦ Read the Device compliance state from the Ledger. + ◦ Read the Product Attestation Authorities certificates. + ◦ Read the Operational Root CA Certificates (RCAC). + +The DCL is cryptographically secure, machine-readable, and distributed. More details about the +Ledger can be found here [https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/ +DCL-Overview.pdf]. + +While the DCL repository [https://github.com/zigbee-alliance/distributed-compliance-ledger/] functionality +MAY contain more features which MAY evolve independently from those described in this section, +this section SHALL be the normative source of truth for usage of the DCL within this specification. + +The DCL best practice guidelines are available in Section 13.6.9, “Distributed Compliance Ledger”. + +**11.23.2. Schemas** + +Ledger data is available in following representational schemas. + +- Vendor Schema + ◦ Provide general information about a Vendor such as Company legal name, Preferred brand + name associated with VendorID, Landing page URL for vendor, etc. + +``` +Page 996 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Product Attestation Authority and Intermediate Certificate Schema + ◦ Provide a list of Product Attestation Authorities Certificates for the approved PAAs. + ◦ Optionally, provide a list of Product Attestation Authorities Intermediate Certificates that + have been added into this schema. +- Operational Root and Intermediate Certificate Schema + ◦ Provide a list of Operational Root CA Certificates (RCAC) have been added into this schema. + ◦ Provide a list of Operational Intermediate CA Certificates (ICAC) have been added into this + schema. +- DeviceModel Schema + ◦ Provide general information about a device, and the information is shared across all soft­ + ware versions. + ◦ e.g ProductName, ProductLabel, PartNumber, Commissioning info, etc. +- DeviceSoftwareVersionModel Schema + ◦ Provide software version specific information. + ◦ e.g Release Notes URL, FirmwareInformation, OTA Software Image URL (OtaUrl), etc. +- Compliance / Compliance test result Schema + ◦ Provide compliance and test result data about a software version. +- Device Attestation PKI Revocation Distribution Points + ◦ Provide the distribution points (URLs) for Device Attestation PKI Revocation + +**11.23.2.1. SchemaVersion** + +Each Schema SHALL have a SchemaVersion attribute to indicate the version of the schema. This +helps provide backwards and forwards compatibility when adding new fields to or removing fields +from an existing schema. + +SchemaVersion is a monotonically increasing positive integer indicating the latest available version +of the schema in this specification. + +When the initial version of any schema is published, the value of this field SHALL be 0. For schemas +that have been published prior to the addition of SchemaVersion field, its value SHALL default to 0 +for the purpose of interoperability. + +When a new revision of any schema is published, this value SHALL monotonically increase by 1. + +HardwareVersion and HardwareVersionString are NOT part of the schemas. If there is different +software for a VendorID/ProductID/HardwareVersion, then it SHALL be a new VendorID/ProductID. + +**11.23.3. Vendor Schema** + +Vendor Schema provides contact information associated with the vendor for a given VendorID. +Information in the Vendor schema is populated by the respective vendors as part of onboarding a +vendor account on the DCL. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 997 +``` + +``` +Name Type Constraint Conformance Mutable +VendorID vendor-id all M No +VendorName string max 128 M Yes +CompanyLegal­ +Name +``` +``` +string max 256 M Yes +``` +``` +CompanyPre­ +ferredName +``` +``` +string max 256 O Yes +``` +``` +VendorLanding­ +PageUrl +``` +``` +string max 256 O Yes +``` +``` +SchemaVersion uint16 all M Yes +``` +**11.23.3.1. VendorID** + +This field SHALL uniquely identify this Vendor Schema entry and it SHALL match the Vendor’s +assigned Vendor ID. + +**11.23.3.2. VendorName** + +This field SHALL provide a human readable (displayable) name for the product manufacturer asso­ +ciated with this record. + +**11.23.3.3. CompanyLegalName** + +The CompanyLegalName field SHALL specify the legal name for the product manufacturer. + +**11.23.3.4. CompanyPreferredName** + +The CompanyPreferredName field, if provided, SHALL specify the Preferred Name that MAY be +used for display purposes instead of the CompanyLegalName. + +**11.23.3.5. VendorLandingPageUrl** + +The VendorLandingPageUrl field (when provided) SHALL contain a link to a maintained web page +containing more information about the device manufacturer, such as contact information, address, +etc. During the lifetime of the products of this manufacturer, the specified URL SHOULD resolve to a +maintained web page. The syntax of this field SHALL follow the syntax as specified in RFC 1738 and +SHALL use the https scheme. The maximum length of this field is 256 ASCII characters. + +**11.23.3.6. SchemaVersion** + +The SchemaVersion field value history for this schema is provided below: + +``` +Version Description +0 Initial Release +``` +``` +Page 998 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.23.4. Product Attestation Authority and Intermediate Certificate Schema** + +This schema allows approved Product Attestation Authorities Certificates to be uploaded and made +available via DCL queries. Information in this schema is populated by the respective vendors who +have approved Product Attestation Authorities Certificates. It allows vendors to upload Product +Attestation Intermediate certificate under following conditions: + +- A corresponding Product Attestation Authorities Certificates exists in DCL that has signed the + Product Attestation Intermediate certificate, and +- Both Product Attestation Authorities Certificates and Product Attestation Intermediate certifi­ + cate are associated with the same Vendor ID. + +Note that Matter Operational Root CA Certificates always appear in Matter TLV Certificate format +when they appear in cluster data fields. Careful conversions from PEM to Matter TLV Certificate +format SHOULD be done whenever a comparison is made. + +``` +Name Type Constraint Conformance Mutable +PEMCert string all M No +SerialNumber octstr 20 M No +Issuer string all O No +AuthorityKeyID string all O No +RootSubject string all O No +RootSubjectKeyID string all O No +isRoot boolean all M No +Owner string all M No +Subject string all M No +SubjectKeyID string all M No +GrantApprovals vendor-id all M No +GrantRejects vendor-id all M No +VID vendor-id all M No +SchemaVersion uint16 all M Yes +``` +**11.23.4.1. PEMCert** + +This field uniquely identifies a certificate and SHALL contain the body of a certificate that has been +added in the DCL. It SHALL be encoded in PEM format. The certificate SHALL respect the format +constraints provided for that certificate type. + +**11.23.4.2. SerialNumber** + +The field SHALL be used to identify the serial number field in the Matter certificate structure. A +Matter certificate follows the same limitation on admissible serial numbers as in [RFC 5280], i.e., +that implementations SHALL admit serial numbers up to 20 octets in length, and certificate authori­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 999 +``` + +ties SHALL NOT use serial numbers longer than 20 octets in length. + +**11.23.4.3. Issuer** + +The field SHALL be used to identify the Certificate Authority that issues the certificate. For a PAA +Certificate, this field is OPTIONAL because Issuer and Subject are the same. + +**11.23.4.4. AuthorityKeyID** + +The authority key identifier extension provides a means of identifying the public key correspond­ +ing to the private key used to sign a Matter certificate. This is OPTIONAL for PAA Certificates. + +**11.23.4.5. RootSubject** + +This field SHALL contain the PAA certificate’s Subject field, as defined in PAA in PAA Certificate. +This is OPTIONAL for PAA Certificates. This is encoded as defined in Section 6.1, “Certificate Com­ +mon Conventions”. + +**11.23.4.6. RootSubjectKeyID** + +This field SHALL uniquely identify the PAA certificate’s Subject Key Identifier mandatory exten­ +sion. It is defined in PAA Certificate and Operational Root CA Certificates (RCAC). This is OPTIONAL +for PAA Certificates. This is encoded as defined in Section 6.1, “Certificate Common Conventions”. + +**11.23.4.7. Owner** + +This field uniquely identifies the DCL key that was used to register the certificate in DCL, pursuant +to DCL policies. + +**11.23.4.8. isRoot** + +This field SHALL signify whether the associated certificate is PAA Certificate. + +**11.23.4.9. Subject** + +This field SHALL contain the certificate’s Subject field. This is OPTIONAL for PAA Certificates. This +is encoded as defined in Section 6.1, “Certificate Common Conventions”. + +**11.23.4.10. SubjectKeyID** + +This field SHALL uniquely identify the PAA certificate’s Subject Key Identifier mandatory exten­ +sion. This is encoded as defined in Section 6.1.2, “Key Identifier Extension Constraints”. + +**11.23.4.11. GrantApprovals** + +This field SHALL contain list of DCL Keys that approved the PAA Certificate admission into DCL. +This field SHALL be set only for a PAA Certificate. + +**11.23.4.12. GrantRejects** + +This field SHALL contain list of DCL Keys that rejected the PAA Certificate admission into DCL. This + +``` +Page 1000 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +field SHALL be set only for a PAA Certificate + +**11.23.4.13. VID** + +This field SHALL uniquely identify this Vendor Schema entry and it SHALL match the Vendor’s +assigned Vendor ID. + +**11.23.5. Operational Root and Intermediate Certificate Schema** + +This schema allows Matter Certificates to be uploaded and made available via DCL queries. Infor­ +mation in this schema is populated by the respective vendors who have Matter Certificates. It also +allows vendors to upload Matter Intermediate CA (ICA) Certificate under following conditions: + +- A corresponding Operational Root CA Certificates (RCAC) exists in DCL that has signed the Mat­ + ter Intermediate CA (ICA) Certificate, and +- Both Operational Root CA Certificates (RCAC) and ICAC are associated with the same Vendor ID. + +Note that Matter Operational Root CA Certificates always appear in Matter TLV Certificate format +when they appear in cluster data fields. Careful conversions from PEM to Matter TLV Certificate +format SHOULD be done whenever comparison are made. Each certificate from the this schema +SHALL respect the format constraints provided in Section 6.4.5.3, “Trusted Root CA Certificates” and +Section 6.4.5.2, “Intermediate CA (ICA) Certificate”. + +``` +Name Type Constraint Conformance Mutable +PEMCert string all M No +SerialNumber octstr all M No +Issuer string all O No +AuthorityKeyID string all O No +RootSubject string all O No +RootSubjectKeyID string all O No +isRoot boolean all M No +Owner string all M No +Subject string all M No +SubjectKeyID string all M No +VID vendor-id all M No +SchemaVersion uint16 all M Yes +``` +**11.23.5.1. PEMCert** + +This field uniquely identifies a certificate and SHALL contain the body of a certificate that has been +added in the DCL. It SHALL be encoded in PEM format. The certificate SHALL respect the format +constraints provided for that certificate type. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1001 +``` + +**11.23.5.2. SerialNumber** + +The field SHALL be used to identify the serial number field in the Matter certificate structure. A +Matter certificate follows the same limitation on admissible serial numbers as in [RFC 5280], i.e., +that implementations SHALL admit serial numbers up to 20 octets in length, and certificate authori­ +ties SHALL NOT use serial numbers longer than 20 octets in length. + +**11.23.5.3. Issuer** + +The field SHALL be used to identify the Certificate Authority that issues the certificate. For a +<, this field is OPTIONAL because Issuer and +Subject are the same. + +**11.23.5.4. AuthorityKeyID** + +The authority key identifier extension provides a means of identifying the public key correspond­ +ing to the private key used to sign a Matter certificate. This is OPTIONAL for Operational Root CA +Certificates (RCAC). + +**11.23.5.5. RootSubject** + +This field SHALL contain the PAA certificate’s Subject field, as defined Operational Root CA Certifi­ +cates (RCAC). This is OPTIONAL for Operational Root CA Certificates (RCAC). This is encoded as +defined in Section 6.1, “Certificate Common Conventions”. + +**11.23.5.6. RootSubjectKeyID** + +This field SHALL uniquely identify the PAA certificate’s Subject Key Identifier mandatory exten­ +sion. It is defined in PAA Certificate and Operational Root CA Certificates (RCAC). This is OPTIONAL +for Operational Root CA Certificates (RCAC). This is encoded as defined in Section 6.1, “Certificate +Common Conventions”. + +**11.23.5.7. Owner** + +This field uniquely identifies the DCL key that was used to register the certificate in DCL, pursuant +to DCL policies. + +**11.23.5.8. isRoot** + +This field SHALL signify whether the associated certificates is a Operational Root CA Certificate +(RCAC). + +**11.23.5.9. Subject** + +This field SHALL contain the certificate’s Subject field. This is encoded as defined in Section 6.1, +“Certificate Common Conventions”. + +**11.23.5.10. SubjectKeyID** + +This field SHALL uniquely identify the PAA certificate’s Subject Key Identifier mandatory exten­ +sion. This is encoded as defined in Section 6.1.2, “Key Identifier Extension Constraints”. + +``` +Page 1002 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +### 11.23.5.11. VID + +This field SHALL uniquely identify this Vendor Schema entry and it SHALL match the Vendor’s +assigned Vendor ID. + +**11.23.6. DeviceModel Schema** + +A unique combination of the VendorID and ProductID is used to identify a DeviceModel. The record +schema available to vendors to provide general information shared across all software versions of +a given product is presented below. + +``` +Name Type Constraint Conformance Mutable +VendorID vendor-id all M No +ProductID uint16 all M No +DeviceTypeID devtype-id all M No +ProductName string max 128 M Yes +ProductLabel string max 256 M Yes +PartNumber string max 32 M Yes +DiscoveryCapabili­ +tiesBitmask +``` +``` +map8 0 to 14 desc No +``` +``` +Commissioning­ +CustomFlow +``` +``` +uint8 0 to 2 M No +``` +``` +Commissioning­ +CustomFlowUrl +``` +``` +string max 256 desc Yes +``` +``` +Commissioning­ +ModeInitial­ +StepsHint +``` +``` +map32 desc M Yes +``` +``` +Commissioning­ +ModeInitial­ +StepsInstruction +``` +``` +string max 1024 desc Yes +``` +``` +Commissioning­ +ModeSecondaryS­ +tepsHint +``` +``` +map32 desc M No +``` +``` +Commissioning­ +ModeSecondaryS­ +tepsInstruction +``` +``` +string max 1024 desc Yes +``` +``` +Commissioning­ +FallbackUrl +``` +``` +string max 256 desc Yes +``` +``` +UserManualUrl string max 256 O Yes +SupportUrl string max 256 O Yes +ProductURL string max 256 O Yes +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1003 +``` + +``` +Name Type Constraint Conformance Mutable +LsfUrl string max 256 O Yes +LsfRevision uint16 all desc Yes +SchemaVersion uint16 all M Yes +EnhancedSe­ +tupFlowOptions +``` +``` +map16 desc O Yes +``` +``` +EnhancedSe­ +tupFlowTCUrl +``` +``` +string max 256 desc Yes +``` +``` +EnhancedSe­ +tupFlowTCRevi­ +sion +``` +``` +uint16 all desc Yes +``` +``` +EnhancedSe­ +tupFlowTCDigest +``` +``` +string max 128 desc Yes +``` +``` +EnhancedSe­ +tupFlowTCFileSize +``` +``` +uint32 desc desc Yes +``` +``` +EnhancedSe­ +tupFlowMainte­ +nanceUrl +``` +``` +string desc desc Yes +``` +**11.23.6.1. VendorID** + +This field SHALL identify the vendor of the product by its Vendor ID and SHALL match the Ven­ +dorID field in the Basic Information Cluster of a device running the software referenced by this +DeviceModel/DeviceSoftwareVersionModel record. + +**11.23.6.2. ProductID** + +This field SHALL identify the Product ID of the product instance to which a certification declara­ +tion, and thus a DCL entry, applies. This field SHALL match the ProductID field in the Basic Informa­ +tion Cluster of a device running the software referenced by this DeviceModel/DeviceSoftwareVer­ +sionModel record. + +**11.23.6.3. DeviceTypeID** + +DeviceTypeID is the Primary Device Type identifier for the device. For example, DeviceTypeID is 10 +(0x000A), which is the device type identifier for a Door Lock. + +**11.23.6.4. ProductName** + +This field SHOULD match the ProductName field in the Basic Information Cluster of a device running +the software referenced by this DeviceModel record. + +**11.23.6.5. ProductLabel** + +This field SHOULD match the ProductLabel field in the Basic Information Cluster of a device running + +``` +Page 1004 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +the software referenced by this DeviceModel record. + +**11.23.6.6. PartNumber** + +This field SHALL match the PartNumber field in the Basic Information Cluster of a device running the +software referenced by this DeviceModel record. +Multiple products (and hence PartNumbers) can share a ProductID. For instance, there may be dif­ +ferent packaging (with different PartNumbers) for different regions; also different colors of a prod­ +uct might share the ProductID but may have a different PartNumber. In such cases, the choice of a +single PartNumber out of the available set of PartNumbers using this ProductID SHALL be used to +populate this field. + +**11.23.6.7. DiscoveryCapabilitiesBitmask** + +This field SHALL identify the device’s available technologies for device discovery which SHALL be +encoded as defined in Table 40, “Discovery Capabilities Bitmask”. This field SHALL match the Table +40, “Discovery Capabilities Bitmask” provided in the Section 5.1.3, “QR Code” (if a QR-code is pro­ +vided on or with the product). This field SHALL be populated if the CommissioningFallbackUrl is +populated, and SHOULD be populated for all other products. + +**11.23.6.8. CommissioningCustomFlow** + +This field SHALL identify the device’s commissioning flow with encoding as described in Custom +Flow. + +**11.23.6.9. CommissioningCustomFlowUrl** + +This field SHALL identify a vendor-specific commissioning URL for the device model when the +CommissioningCustomFlow field is set to '2', and MAY be set for other values of CommissioningCus­ +tomFlow. See Custom Commissioning Flow section for how this URL is used. During the lifetime of +the product, the specified URL SHOULD resolve to a maintained web page. The syntax of this field +SHALL follow the syntax as specified in RFC 1738 and SHALL use the https scheme. The maximum +length of this field is 256 ASCII characters. + +**11.23.6.10. CommissioningModeInitialStepsHint** + +This field SHALL identify a hint for the steps that MAY be used to put a device that has not yet been +commissioned into commissioning mode. This field is a bitmap with values defined in the Pairing +Hint Table. For example, a value of 1 (bit 0 is set) indicates that a device that has not yet been com­ +missioned will enter Commissioning Mode upon a power cycle. +Devices that implement Extended Discovery SHALL reflect this value in the Pairing Hint field of +Commissionable Node Discovery when they have not yet been commissioned. + +**11.23.6.11. CommissioningModeInitialStepsInstruction** + +This field SHALL be populated with the appropriate Pairing Instruction for those values of Commis­ +sioningModeInitialStepsHint, for which the Pairing Hint Table indicates a Pairing Instruction (PI) +dependency. +Devices that implement Extended Discovery SHALL reflect this value in the Pairing Instruction field +of Commissionable Node Discovery when they have not yet been commissioned. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1005 +``` + +**11.23.6.12. CommissioningModeSecondaryStepsHint** + +This field SHALL identify a hint for the steps that MAY be used to put a device that has already been +commissioned into commissioning mode. This field is a bitmap with values defined in the Pairing +Hint Table. At least bit 2 SHALL be set, to indicate that a current Administrator can be used to put a +device that has already been commissioned into commissioning mode (see Section 5.6.3, “Enhanced +Commissioning Method (ECM)”). Devices which implement _additional_ mechanisms to put a device +that has already been commissioned into commissioning mode SHALL reflect these mechanism by +setting the corresponding bits in this field. +Devices that implement Extended Discovery SHALL reflect this value in the Pairing Hint field of +Commissionable Node Discovery when they have already been commissioned. + +**11.23.6.13. CommissioningModeSecondaryStepsInstruction** + +This field SHALL be populated with the appropriate Pairing Instruction for those values of Commis­ +sioningModeSecondaryStepsHint, for which the Pairing Hint Table indicates a Pairing Instruction +(PI) dependency. +Devices that implement Extended Discovery SHALL reflect this value in the Pairing Instruction field +of Commissionable Node Discovery when they have already been commissioned. + +**11.23.6.14. CommissioningFallbackUrl** + +This field SHALL identify a vendor-specific commissioning-fallback URL for the device model, +which can be used by a Commissioner in case commissioning fails to direct the user to a manufac­ +turer-provided mechanism to provide resolution to commissioning issues. See Commissioning Fall­ +back section for how this URL is used. + +During the lifetime of the product, the specified URL SHOULD resolve to a maintained web page. +The syntax of this field SHALL follow the syntax as specified in RFC 1738 and SHALL use the https +scheme. The maximum length of this field is 256 ASCII characters. + +**11.23.6.15. UserManualUrl** + +This field (when provided) SHALL identify a product-specific web page containing a user manual +for the device model. During the lifetime of the product, the specified URL SHOULD resolve to a +maintained web page. The syntax of this field SHALL follow the syntax as specified in RFC 1738 and +SHALL use the https scheme. The maximum length of this field is 256 ASCII characters. + +**11.23.6.16. SupportUrl** + +This field (when provided) SHALL identify a product specific support web page. During the lifetime +of the product, the specified URL SHOULD resolve to a maintained web page. The syntax of this +field SHALL follow the syntax as specified in RFC 1738 and SHALL use the https scheme. The maxi­ +mum length of this field is 256 ASCII characters. + +**11.23.6.17. ProductURL** + +This field (when provided) SHALL identify a link to a product specific web page. This field SHALL +match the ProductURL field in the Basic Information Cluster of a device running the software refer­ +enced by this DeviceModel record. During the lifetime of the product, the specified URL SHOULD + +``` +Page 1006 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +resolve to a maintained web page. The syntax of this field SHALL follow the syntax as specified in +RFC 1738 and SHALL use the https scheme. The maximum length of this field is 256 ASCII charac­ +ters. + +**11.23.6.18. LsfUrl** + +This field (when provided) SHALL identify a link to the Localized String File of this product. This +field SHALL NOT have a localized string identifier. During the lifetime of the product, the specified +URL SHOULD resolve to a maintained Localized String File. The syntax of this field SHALL follow +the syntax as specified in RFC 1738 and SHALL use the https scheme. The maximum length of this +field is 256 ASCII characters. + +**11.23.6.19. LsfRevision** + +LsfRevision is a monotonically increasing positive integer indicating the latest available version of +Localized String File. Any client can use this field to check whether it has the latest version of the +Localized String File cached. When the first version of the Localized String File is published, the +value of this field SHOULD be 1. When a new revision of the Localized String File is published, this +value SHALL monotonically increase by 1. When a client of this information finds this to be greater +than its currently stored LSF revision number, it SHOULD download the latest version of the LSF +from the LsfUrl, and update its local value of this field. + +This field SHALL be provided if and only if when LsfUrl is provided. + +**11.23.6.20. SchemaVersion** + +The SchemaVersion field value history for this schema is provided below: + +``` +Version Description +0 Initial Release +``` +**11.23.6.21. EnhancedSetupFlowOptions** + +This field SHALL identify the configuration options for the Enhanced Setup Flow. This field is a +bitmap with values defined in Enhanced Setup Flow Options Table. + +**11.23.6.22. EnhancedSetupFlowTCUrl** + +This field (when provided) SHALL identify a link to the Enhanced Setup Flow Terms and Condition +File for this product. During the lifetime of the product, the specified URL SHOULD resolve to a +maintained Terms and Conditions File. The syntax of this field SHALL follow the syntax as specified +in RFC 1738. The maximum length of this field is 256 ASCII characters. All URLs SHALL use the +https scheme. This field SHALL be present if and only if the EnhancedSetupFlowOptions field has +bit 0 set. + +**11.23.6.23. EnhancedSetupFlowTCRevision** + +This field (when provided) is an increasing positive integer indicating the latest available version of +the Enhanced Setup Flow Terms and Conditions file. When a new revision of the File is published, + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1007 +``` + +this value SHALL increase (and SHOULD increase by 1). This field SHALL be present if and only if +the EnhancedSetupFlowOptions field has bit 0 set. + +**11.23.6.24. EnhancedSetupFlowTCDigest** + +This field (when provided) SHALL contain the digest of the entire contents of the associated file +downloaded from the EnhancedSetupFlowTCUrl field, encoded in base64 string representation and +SHALL be used to ensure the contents of the downloaded file are authentic. The digest SHALL have +been computed using the SHA-256 digest algorithm. This field SHALL be present if and only if the +EnhancedSetupFlowOptions field has bit 0 set. + +**11.23.6.25. EnhancedSetupFlowTCFileSize** + +This field (when provided) SHALL indicate the total size of the Enhanced Setup Flow Terms and +Conditions file in bytes, and SHALL be used to ensure the downloaded file size is within the bounds +of EnhancedSetupFlowTCFileSize. This field SHALL be provided if and only if the EnhancedSe­ +tupFlowTCUrl field is present. + +**11.23.6.26. EnhancedSetupFlowMaintenanceUrl** + +This field (when provided) SHALL identify a link to a vendor-specific URL which SHALL provide a +manufacturer specific means to resolve any functionality limitations indicated by the +TERMS_AND_CONDITIONS_CHANGED status code. This field SHALL be present if the EnhancedSe­ +tupFlowOptions field has bit 0 set. During the lifetime of the product, the specified URL SHOULD +resolve to a maintained web page. The syntax of this field SHALL follow the syntax as specified in +RFC 1738. The maximum length of this field is 256 ASCII characters. All URLs SHALL use the https +scheme. + +**11.23.7. DeviceSoftwareVersionModel Schema** + +A unique combination of the VendorID, ProductID and SoftwareVersion is used to identify a Device­ +SoftwareVersionModel. The record schema available to vendors to provide information specific to a +particular software version for a given product is presented below. + +``` +Name - (Matching +Basic Informa­ +tion Cluster +Field) +``` +``` +Type Constraint Conformance Mutable +``` +``` +VendorID vendor-id all M No +ProductID uint16 all M No +SoftwareVersion uint32 all M No +SoftwareVersion­ +String +``` +``` +string 1 to 64 M No +``` +``` +CDVersionNumber uint16 all M No +FirmwareInforma­ +tion +``` +``` +string max 512 O No +``` +``` +Page 1008 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Name - (Matching +Basic Informa­ +tion Cluster +Field) +``` +``` +Type Constraint Conformance Mutable +``` +``` +SoftwareVersion­ +Valid +``` +``` +boolean all M Yes +``` +``` +OtaUrl string max 256 desc Yes +OtaFileSize uint64 all OtaUrl No +OtaChecksum string max 64 OtaUrl No +OtaChecksumType uint16 desc OtaUrl No +MinApplicable­ +SoftwareVersion +``` +``` +uint32 all M Yes +``` +``` +MaxApplicable­ +SoftwareVersion +``` +``` +uint32 all M Yes +``` +``` +ReleaseNotesUrl string max 256 O Yes +SchemaVersion uint16 all M Yes +SpecificationVer­ +sion +``` +``` +uint32 all M No +``` +**11.23.7.1. VendorID** + +See Section 11.23.6.1, “VendorID”. + +**11.23.7.2. ProductID** + +See Section 11.23.6.2, “ProductID”. + +**11.23.7.3. SoftwareVersion** + +SoftwareVersion SHALL identify the software version number for the device model consistent with +the value found in Section 11.21.2.4.3, “SoftwareVersion field”. The SoftwareVersionNumber value +SHOULD NOT be displayed to an end-user. SoftwareVersion is not editable, but it would be possible +to create a new device model for the same VendorID/ProductID for different versions. Both Soft­ +wareVersion and SoftwareVersionString SHALL be included. This field SHALL match the Software­ +Version field in the Basic Information Cluster of a device running the software certified by this +DeviceModel record. + +**11.23.7.4. SoftwareVersionString** + +This field SHALL match the Software Version String field in the Basic Information Cluster of a +device running the software referenced by this DeviceModel record, including format constraints +on that field. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1009 +``` + +**11.23.7.5. CDVersionNumber** + +CDVersionNumber SHALL identify the CD Version Number of the Certification that applies to this +Software Image. The CDVersionNumber maps to version_number defined in Certification Elements TLV +structure. + +**11.23.7.6. FirmwareInformation** + +The FirmwareInformation field, if present, SHALL match the firmware_information field in attesta­ +tion-elements field included in the Device Attestation response when this Software Image boots on +the device. It is an OPTIONAL field that MAY be present only for devices that meet the requirements +listed in Section 6.3.2, “Firmware Information”. + +**11.23.7.7. SoftwareVersionValid** + +This field SHALL indicate whether this SoftwareVersion is valid. When creating an entry for a new +SoftwareVersion, this typically is set to True. When the manufacturer later finds out there is some +reason that this version should no longer be used (e.g. due to some bugs), the field SHALL be +updated to False. + +### NOTE + +``` +This mechanism is for "withdrawal" of a SoftwareVersion by the manufacturer , not +to be confused with certification revocation by CSA (see SoftwareVersionCertifica­ +tionStatus). +``` +### 11.23.7.8. OTA + +**OtaUrl** + +OtaUrl SHALL identify the URL where to obtain the OTA image. The OtaUrl field SHALL be popu­ +lated unless the device manufacturer provides alternative means to update the product’s firmware. +The specified URL SHOULD be available for the relevant lifetime of the corresponding software. +The syntax of this field SHALL follow the syntax as specified in RFC 1738 and SHALL use the https +scheme. The maximum length of this field is 256 ASCII characters. + +**OtaFileSize** + +OtaFileSize is the total size of the OTA software image in bytes. This field SHALL be provided if the +OtaUrl field is populated. + +**OtaChecksum** + +OtaChecksum SHALL contain the digest of the entire contents of the associated OTA Software +Update Image under the OtaUrl field, encoded in base64 string representation. The digest SHALL +have been computed using the algorithm specified in OtaChecksumType. This field SHALL be provided +if the OtaUrl field is populated. + +**OtaChecksumType** + +OtaChecksumType SHALL identify the type of OtaChecksum. This field SHALL be provided if the +OtaUrl field is populated. + +``` +Page 1010 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The value of this field SHALL be a supported numerical identifier value from the IANA Named +Information Hash Algorithm Registry [https://www.iana.org/assignments/named-information/named-informa­ +tion.xhtml#hash-alg] established as part of RFC 6920. For example, a value of 1 would match the sha- +256 identifier, which maps to the SHA-256 digest algorithm per Section 6.2 of FIPS 180-4. + +The digest algorithm chosen SHALL have a minimum digest length of 256 bits, such as sha-256 (ID 1 +in the registry). + +To increase interoperability, OtaChecksumType SHALL be within the list of [1, 7, 8, 10, 11, 12]. + +**11.23.7.9. MinApplicableSoftwareVersion** + +MinApplicableSoftwareVersion SHALL be equal to the lowest SoftwareVersion for which this image +can be applied. Also see Section 11.21.2.4.6, “MinApplicableSoftwareVersion field”. + +**11.23.7.10. MaxApplicableSoftwareVersion** + +MaxApplicableSoftwareVersion SHALL be equal to the highest SoftwareVersion for which this +image can be applied. Also see Section 11.21.2.4.7, “MaxApplicableSoftwareVersion field”. + +**11.23.7.11. ReleaseNotesUrl** + +ReleaseNotesUrl SHALL identify a product specific web page that contains release notes for the +device model software. The specified URL SHOULD resolve to a maintained web page available for +the lifetime of the corresponding software being relevant. The syntax of this field SHALL follow the +syntax as specified in RFC 1738 and SHALL use the https scheme. The maximum length of this field +is 256 ASCII characters. + +**11.23.7.12. SchemaVersion** + +The SchemaVersion field value history for this schema is provided below: + +``` +Version Description +0 Initial Release +``` +**11.23.7.13. SpecificationVersion** + +SpecificationVersion SHALL identify the specification version applicable to the device model. This +field SHALL match the SpecificationVersion field in the Basic Information Cluster of a device run­ +ning the software certified by this DeviceModel record. + +**11.23.8. DeviceSoftwareCompliance / Compliance test result Schema** + +A unique combination of the VendorID, ProductID and SoftwareVersion is used to identify a Device­ +SoftwareCompliance record. This record schema is available to the CSA to provide information spe­ +cific to certification of a particular software version for a given product is presented below. Note +that this schema is writable and mutable by CSA, not by the manufacturer. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1011 +``` + +``` +Name - (Matching +Basic Informa­ +tion Cluster +Field) +``` +``` +Type Constraint Conformance Mutable +``` +``` +VendorID vendor-id all M No +ProductID uint16 all M No +SoftwareVersion uint32 all M No +SoftwareVersion­ +String +``` +``` +string 1 to 64 M No +``` +``` +CDVersionNumber uint16 all M Yes +SoftwareVersion­ +CertificationStatus +``` +``` +SoftwareVersion­ +CertificationSta­ +tusEnum +``` +``` +all M Yes +``` +``` +CDCertificateID string 19 M Yes +SchemaVersion uint16 all M Yes +``` +For the description of the first five fields, see the corresponding fields in DeviceSoftwareVersion­ +Model Schema. + +**11.23.8.1. SoftwareVersionCertificationStatus** + +This field SHALL have a value from SoftwareVersionCertificationStatusEnum reflecting the current +certification status of this SoftwareVersion. + +**11.23.8.2. SoftwareVersionCertificationStatusEnum Type** + +This data type is derived from enum8 and has its values listed below. + +``` +Value Name Summary Conformance Description +0 dev-test dev-test M used for develop­ +ment and test pur­ +poses (These will +typically not be +placed in DCL) +1 provisional provisional M used for a Soft­ +wareVersion when +going into certifi­ +cation testing +(These might or +might not be +placed in DCL, +depending on CSA +policy and proce­ +dures) +``` +``` +Page 1012 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance Description +2 certified certified M used for a Soft­ +wareVersion +which has been +certified +3 revoked revoked M used for a Soft­ +wareVersion +which has been +revoked +``` +The values 0 through 2 SHALL correspond to the values 0 through 2 used in certification_type in the +Certification Declaration. + +**11.23.8.3. CDCertificateID** + +This field SHALL have the CSA certification’s certificate ID for the Certification that applies to this +record. The value of this field is used in the Certification Declaration's certificate_id field (see Cer­ +tification Elements TLV structure) for products using the VendorID, ProductID and SoftwareVersion +in this schema entry. + +**11.23.8.4. SchemaVersion** + +The SchemaVersion field value history for this schema is provided below: + +``` +Version Description +0 Initial Release +``` +**11.23.9. Device Attestation PKI Revocation Distribution Points Schema** + +The Device Attestation PKI revocation distribution points are used to identify the URL where PAAs +and PAIs provide revocation information for PAIs and DACs, respectively. + +See Section 6.2, “Device Attestation” for more details on the PKI elements discussed in this subsec­ +tion (e.g. PAA, PAI, DAC). + +The schema is presented in the table below: + +``` +Name Type Constraint Conformance Mutable +VendorID vendor-id all M No +ProductID uint16 all desc No +IsPAA bool all M No +Label string max 64 M No +CRLSignerDelega­ +tor +``` +``` +string max 2048 desc Yes +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1013 +``` + +``` +Name Type Constraint Conformance Mutable +CRLSignerCertifi­ +cate +``` +``` +string max 2048 M Yes +``` +``` +IssuerSubjec­ +tKeyID +``` +``` +string max 64 M No +``` +``` +DataUrl string max 256 M Yes +DataFileSize uint64 desc O Yes +DataDigest string max 128 desc Yes +DataDigestType uint32 all desc Yes +RevocationType uint32 desc M No +SchemaVersion uint16 all M Yes +``` +**11.23.9.1. VendorID** + +This field SHALL indicate the VendorID associated with the PAA or PAI whose revocation informa­ +tion is provided. For a non-vendor-scoped PAA, this SHALL be the VendorID associated with the +organization operating the PAA. For vendor-scoped PAA and for PAIs, this field SHALL contain the +VendorID as found in the CRLSignerCertificate (see Section 6.2.2.2, “Encoding of Vendor ID and +Product ID in subject and issuer fields” for encoding). + +**11.23.9.2. ProductID** + +This field is only required when a PAI is making the distribution point available. This field SHALL +only be provided if the IsPAA field is false and if the CRLSignerCertificate field has a ProductID in +its subject (see Section 6.2.2.2, “Encoding of Vendor ID and Product ID in subject and issuer fields” +for encoding). + +**11.23.9.3. IsPAA** + +This field SHALL be set to true if the revocation information distribution point relates to a PAA, oth­ +erwise it SHALL be set to false (i.e. it relates to a PAI, not a PAA)." + +**11.23.9.4. Label** + +This field contains a label to disambiguate multiple revocation information partitions of a particu­ +lar issuer. Uniqueness within the Device Attestation PKI Revocation Distribution Points schema +SHALL be enforced against the tuple containing all of: + +- VendorID +- Label +- IssuerSubjectKeyID + +Therefore, there MAY be multiple entries for the same VendorID and IssuerSubjectKeyID in case +partitioning is done, which are disambiguated by the Label. + +``` +Page 1014 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Enforcement of uniqueness constraints SHALL be done by the Distributed Compliance Ledger’s +block transaction processing and SHALL also be done by clients making use of the information +from this schema. + +**11.23.9.5. CRLSignerDelegator** + +This field SHALL be present and non-empty if all of the following are true: + +- Certificate in CRLSignerCertificate field is not self-signed. +- IsPAA is false. +- CRLSignerCertificate is not a PAI. + +When present, this field SHALL contain the issuer certificate which signed the CRLSignerCertificate, +encoded in X.509v3 PEM format. + +Additional constraints related to the value of this field are specified in Section 11.23.9.6, “CRLSign­ +erCertificate”. + +**11.23.9.6. CRLSignerCertificate** + +This field SHALL contain the issuer certificate who signed the revocation information that is pro­ +vided in the distribution point entry, encoded in X.509v3 PEM format. + +If the RevocationType is 1 (X.509v3 CRL): + +- The certificate’s subject public key SHALL be used to validate the signatureValue of the Certifi­ + cateList object in the CRL (see RFC 5280 sec 5.1.1.3). These checks SHALL be done by the client + making use of the information, since they cannot be done by the Distributed Compliance Ledger + implementation which cannot rely on out-of-ledger records or files. +- The certificate’s SubjectKeyIdentifier mandatory extension SHALL match the Authority Key + Identifier found in the file at the DataUrl. +- The certificate SHALL be checked for correct chaining by the dynamic validation within the Dis­ + tributed Compliance Ledger’s block transaction processing: + ◦ If the certificate is self-signed, it SHALL be considered as a PAA certificate, the IsPAA field + SHALL be true, and the certificate SHALL be found in the list of approved PAA certificates + currently in force in the Distributed Compliance Ledger using exact byte equality. + ◦ If the certificate is not self-signed and the IsPAA field is set to true, it SHALL be considered as + a CRL signer certificate delegated by a PAA. The certificate format SHALL be as specified in + Section 11.23.9.6.1, “PAA-delegated CRLSignerCertificate format”. The certificate SHALL be + validated using the set of approved PAA certificates currently in force in the Distributed + Compliance Ledger and the IssuerSubjectKeyID field SHALL match the SubjectKeyIdentifier + extension value in the matching PAA. Commissioners SHALL verify that the PAA that issued + the CRLSignerCertificate is the same PAA that issued the PAI being checked for revocation. + ◦ If the certificate is not self-signed and the IsPAA field is set to false, it SHALL be considered as + a PAI certificate or a CRL signer certificate delegated by a PAI. The format of a CRL signer + certificate delegated by a PAI SHALL be as specified in Section 11.23.9.6.2, “PAI-delegated + CRLSignerCertificate format”. If the CRL signer certificate is not a PAI certificate but is dele­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1015 +``` + +``` +gated by a PAI, then the PAI certificate SHALL be present in the CRLSignerDelegator field so +that the full certificate chain can be verified. The certification path containing the certificate +SHALL be validated using the set of approved PAA certificates currently in force in the Dis­ +tributed Compliance Ledger as the trust store. Commissioners SHALL verify that either the +CRLSignerCertificate or the CRLSignerDelegator is the same PAI that issued the DAC being +checked for revocation. +``` +**PAA-delegated CRLSignerCertificate format** + +In case the CRLSignerCertificate is a delegate of a PAA for signing CRL for revoking PAI certificates, +then the certificate SHALL follow the following constraints layered on top of the encoding specified +by RFC 5280 within the TBSCertificate structure: + +1. The version field SHALL be set to 2 to indicate v3 certificate. +2. The signature field SHALL contain the identifier for signatureAlgorithm ecdsa-with-SHA256. +3. The issuer field SHALL be a sequence of RelativeDistinguishedName s. +4. The issuer field SHALL match the subject field of the parent PAA certificate. +5. The subject field SHALL be a sequence of RelativeDistinguishedName s. +6. A ProductID value SHALL NOT be present in either the subject or issuer fields. +7. The algorithm field in subjectPublicKeyInfo field SHALL be the object identifier for prime256v1. +8. The certificate SHALL carry the following Extensions: + a.Basic Constraint extension SHALL be marked critical and have the cA field set to FALSE. +b. Key Usage extension SHALL be marked critical. +i. The cRLSign bits SHALL be set in the KeyUsage bitstring +ii.The digitalSignature bit MAY be set in the KeyUsage bitstring +iii.Other bits SHALL NOT be set +c.Subject Key Identifier +9. The certificate MAY also carry the following additional Extensions: + a.Extended Key Usage +b. Authority Key Identifier +c.Any other extension allowed in RFC 5280 where inclusion does not violate size limitations. +These extensions insofar not defined in this specification SHALL be ignored, but MAY be +present to allow flexibility in CA operation. + +**PAI-delegated CRLSignerCertificate format** + +In case the CRLSignerCertificate is a delegate of a PAI for signing CRL for revoking DAC certificates, +then the certificate SHALL follow the following constraints layered on top of the encoding specified +by RFC 5280 within the TBSCertificate structure: + +1. The version field SHALL be set to 2 to indicate v3 certificate. +2. The signature field SHALL contain the identifier for signatureAlgorithm ecdsa-with-SHA256. + +``` +Page 1016 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +3. The issuer field SHALL be a sequence of RelativeDistinguishedName s. +4. The issuer field SHALL match the subject field of the parent PAI certificate. +5. The subject field SHALL be a sequence of RelativeDistinguishedName s. +6. The algorithm field in subjectPublicKeyInfo field SHALL be the object identifier for prime256v1. +7. The certificate SHALL carry the following Extensions: + a. Basic Constraint extension SHALL be marked critical and have the cA field set to FALSE. + b. Key Usage extension SHALL be marked critical + i. The cRLSign bit SHALL be set in the KeyUsage bitstring +ii. The digitalSignature bit MAY be set in the KeyUsage bitstring +iii. Other bits SHALL NOT be set +c. Authority Key Identifier + d. Subject Key Identifier +8. The certificate MAY also carry the following additional Extensions: + a. Extended Key Usage + b. Any other extension allowed in RFC 5280 where inclusion does not violate size limitations. + These extensions insofar not defined in this specification SHALL be ignored, but MAY be + present to allow flexibility in CA operation. + +**11.23.9.7. IssuerSubjectKeyID** + +This field SHALL uniquely identify the PAA or PAI for which this revocation distribution point is +provided, via the certificate’s SubjectKeyIdentifier mandatory extension. This field is provided to +assist queries without requiring additional certificate parsing. This field SHALL provide the subject +key identifier as an even number of uppercase hexadecimal characters ([0-9A-F]), with no white­ +space and no non-hexadecimal characters. + +For example, subject key ID A3:03:13:6D:54:A8:4B:E2:4C:48:87:B3:41:06:6D:C2:70:96:2F:99 (as it +would appear in openssl x509 output, for human consumption) would be recorded as +A303136D54A84BE24C4887B341066DC270962F99. + +When processing revocation information during the device Device Attestation Procedure, clients +SHALL only use entries whose IssuerSubjectKeyID matches a candidate certificate’s Authority Key +Identifier extension. + +**11.23.9.8. DataUrl** + +This field SHALL indicate the URL where to obtain the information in the format indicated by the +RevocationType field. The syntax of this field SHALL follow the syntax as specified in RFC 1738. The +maximum length of this field is 256 ASCII characters. All URLs SHALL use either the http or https +scheme. + +For entries of RevocationType 1 (RFC 5280 CRL): + +- The content located at the DataUrl SHALL be a RFC 5280 Certificate Revocation List document + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1017 +``` + +``` +(see section 5 in the RFC) encoded in DER format. +◦ Note that conformance to the RFC 5280 CRL profile requires at least the AuthorityKeyIdenti­ +fier and CRLNumber extensions to be present in the document. +``` +- If multiple entries exist in the schema, which match in VendorID and IssuerSubjectKeyID, then: + ◦ All entries SHALL have a different Label. + ◦ All entries SHALL have a different DataUrl. + ◦ The content located at the DataURL SHALL have the Issuing Distribution Point critical CRL + extension present (see RFC 5280 section 5.2.5). + ▪ DCL software SHALL validate the uniqueness of Label and DataUrl of each entry. + ▪ Note that the content located at the DataURL will never be accessed or validated by DCL + software which cannot rely on out-of-ledger records or files. + ◦ Based on the Issuing Distribution Point critical CRL extension (see RFC 5280 section 5.2.5), + the following validation SHALL be applied: + ▪ The distributionPoint field of the extension SHALL have a single GeneralName of type + uniformResourceIdentifier. + ▪ The uniformResourceIdentifier SHALL match exactly, byte-for-byte, the value found in + the DataUrl field of this schema entry. + ▪ If the value of the CRLSignerCertificate is a CRL signer certificate delegated by a PAA or + delegated by a PAI, then the indirectCRL field of the extension SHALL be set to true. Oth­ + erwise, the indirectCRL field of the extension SHALL be set to false. + +**11.23.9.9. DataFileSize** + +This field, if present, SHALL indicate the total size in bytes of the file found at the DataUrl. This field +SHALL be omitted if the RevocationType is 1, which refers to a type having built-in signatures. + +**11.23.9.10. DataDigest** + +This field, if present, SHALL contain the digest of the entire contents of the associated file down­ +loaded from the DataUrl field, encoded in base64 string representation. The digest SHALL have been +computed using the algorithm specified in DataDigestType. This field SHALL be present if and only if +the DataFileSize field is present. + +**11.23.9.11. DataDigestType** + +This field, if present, SHALL indicate the type of digest used in the DataDigest field. This field SHALL +be provided if and only if the DataDigest field is present. + +The value of this field SHALL be a supported numerical identifier value from the IANA Named +Information Hash Algorithm Registry [https://www.iana.org/assignments/named-information/named-informa­ +tion.xhtml#hash-alg] established as part of RFC 6920. For example, a value of 1 would match the sha- +256 identifier, which maps to the SHA-256 digest algorithm per Section 6.2 of FIPS 180-4. + +The digest algorithm chosen SHALL have a minimum digest length of 256 bits, such as sha-256 (ID 1 +in the registry). + +``` +Page 1018 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +To increase interoperability, DataDigestType, if present, SHALL be within the list of [1, 7, 8, 10, 11, +12]. + +**11.23.9.12. RevocationType** + +This field SHALL identify the type of file found at the DataUrl for this entry. Values supported are: + +- 0: Undefined. This value SHALL NOT appear +- 1: RFC 5280 Certificate Revocation List (CRL) +- Other: reserved for future use. + +**11.23.9.13. SchemaVersion** + +The SchemaVersion field value history for this schema is provided below: + +``` +Version Description +0 Initial Release +``` +**11.23.10. APIs / CLI** + +The Ledger comes with a set of secure APIs and CLI. More details available here [https://github.com/zig­ +bee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md]. + +**11.24. Joint Fabric Datastore Cluster** + +The Joint Fabric Datastore Cluster is a cluster that provides a mechanism for the Joint Fabric +Administrators to manage the set of Nodes, Groups, and Group membership among Nodes in the +Joint Fabric. + +When an Ecosystem Administrator Node is commissioned onto the Joint Fabric, the Ecosystem +Administrator Node has no knowledge of what Nodes and Groups are present, or what set-up infor­ +mation related to the Joint Fabric is provided by the user. To address lack of knowledge, the Joint +Fabric Datastore provides the information required for all Ecosystem Administrators to maintain a +consistent view of the Joint Fabric including Nodes, Groups, settings and privileges. + +The Joint Fabric Datastore cluster server SHALL only be accessible on a Node which is acting as the +Joint Fabric Anchor Administrator. When not acting as the Joint Fabric Anchor Administrator, the +Joint Fabric Datastore cluster SHALL NOT be accessible. + +The Admin level of access to the Joint Fabric Datastore cluster server SHALL be limited to JF Adminis­ +trator Nodes identified using the Administrator CAT. + +``` +NOTE Support for Joint Fabric Datastore cluster is provisional. +``` +**11.24.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1019 +``` + +``` +Revision Description +1 Initial revision +``` +**11.24.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node JFDS +``` +**11.24.3. Cluster ID** + +``` +ID Name Conformance +0x0752 Joint Fabric Datastore Cluster P +``` +**11.24.4. Usage Requirements** + +This section describes the required flows for Joint Fabric Administrators to perform common +actions related to adding and removing Nodes to a Joint Fabric, and managing Groups and Group +Membership on the Joint Fabric. + +Many flows performed by a Joint Fabric Administrator require commands to be sent to the Datas­ +tore in order to keep the Datastore up-to-date with regard to Nodes and Groups on the Fabric. While +a Joint Fabric Administrator SHALL update the Datastore with changes made to Nodes and Groups, +it MAY complete these configuration and commissioning tasks when the Datastore is unreachable. +If attempts to update the Datastore fail due to temporary conditions (reachability issues, BUSY +response error, RESOURCE_EXHAUSTED error, etc.), the Commissioner SHALL periodically retry the +attempted commands until successful. + +The RESOURCE_EXHAUSTED error MAY be used by the Datastore to indicate that a storage capacity +limit of the Datastore has been reached and SHALL notify the user of this condition using propri­ +etary means outside of this specification (ex. email, screen-based notification, etc.), and SHALL pro­ +vide a means for the user to purge information pertaining to unused Nodes. + +**11.24.4.1. Adding a Node to the Joint Fabric** + +During commissioning of a Node onto a Joint fabric, the Fabric Administrator performing the com­ +missioning first populates the Datastore in order to ensure the new Node can be discovered by any +client on the fabric for which the user has granted access. Specifically, before completing the com­ +missioning process, the Commissioner SHALL invoke the Add Pending Node Command in order to +add a node entry to the Datastore (which will be marked with “pending” status since commission­ +ing of the device has not yet completed), and follow Section 11.24.4.9, “Adding/Removing access +privileges for a Controller” to ensure access privileges are managed consistently across the Joint +Fabric. After completion of commissioning and associated configuration, the Commissioner SHALL +invoke the Refresh Node Command in order to indicate completion of commissioning and to cause +the Datastore to update the Node Information Entry with state read from the Node and mark the +entry as "committed". By performing this work in two steps (first pending status, then committed +status), the design can prevent error scenarios where a node is brought onto a fabric without + +``` +Page 1020 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +appearing in the Datastore. + +Commissioning Flow - Datastore Impact + +1. Regular Flow: Commissioner obtains setup code, discovers device, completes PASE portion of + commissioning. +2. Datastore Step: Commissioner SHALL add a Node Information Entry to the Datastore (see Add + Pending Node Command). +3. Regular Flow: Commissioner finalizes commissioning via CASE. + +If the finalize commissioning step fails, the Commissioner removes the pending node from the +Datastore (see Remove Node Command. + +If the finalize commissioning step succeeds, the Commissioner SHALL indicate completion by call­ +ing the >. + +**11.24.4.2. Removing a Node from the Joint Fabric** + +When removing a Node from the Joint Fabric the following steps SHALL be followed: + +1. The Joint Fabric Administrator SHALL first remove access privileges (see Section 11.24.4.9, + “Adding/Removing access privileges for a Controller”) for the Node. +2. The Node Information Entry SHALL be removed from the Joint Fabric Datastore using the + Remove Node Command. + +**11.24.4.3. Pending Data Cleanup** + +The Datastore SHALL periodically review its data in a Pending and PendingDeletion state and +attempt to reach the corresponding Node in order to apply these updates. Examples of configura­ +tion that may be in such a state include: + +1. Node GroupKey additions and removals. +2. Node Endpoint Group membership additions and removals. +3. Node ACL additions, updates and removals for groups, including changes relating to CAT ver­ + sion updates. +4. Node Binding additions and removals for groups. + +See Refresh Node Command for a detailed description of each step. An Administrator MAY invoke +this command at any time to request that the Datastore perform this operation immediately for a +given Node. + +When a new node entry is left in the pending state, a Joint Fabric Administrator may not be able to +determine whether commissioning completed or failed. In this scenario, the Joint Fabric Adminis­ +trator must continue to monitor and attempt maintenance duties upon the node until the node +entry is removed by another Joint Fabric Administrator or by the user. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1021 +``` + +**11.24.4.4. Adding a Node to a Group** + +When adding a Node to a Group, the Joint Fabric Administrator SHALL use the AddGroupIDToEnd­ +pointForNode Command to update the Node with the KeySet and Group relationship required for +the new Group membership. + +When the Group membership is intended for control of the Node, the Joint Fabric Administrator +SHALL use the AddACLToNode Command to update the Node with the appropriate ACL. + +When the Group membership is intended for control by the Node, the Joint Fabric Administrator +SHALL use the AddBindingToEndpointForNode Command to update the Node with the appropriate +Binding. + +**11.24.4.5. Removing a Node from a Group** + +When the Group membership was used for control of the Node, the Joint Fabric Administrator +SHALL use the RemoveACLFromNode Command to remove the ACL from the Node. + +When the Group membership was used for control by the Node, the Joint Fabric Administrator +SHALL use the RemoveBindingFromEndpointForNode Command to remove the Binding from the +Node. + +When removing a Node from a Group, the Joint Fabric Administrator SHALL use the Remove­ +GroupIDFromEndpointForNode Command to ensure the KeySet and Group relationship is removed +from the Node and the Datastore reflects the new Group membership. + +For groups with access control considerations, the Joint Fabric Administrator SHALL use the +UpdateGroup Command to update the GroupKeySetID and increment the GroupCATVersion. If the +Node is a Controller, then the Joint Fabric Administrator SHALL also update the GroupCATVersion +of the Group. + +**11.24.4.6. Making a Node a Group Controller (eg. Light Switch example)** + +In this example, Node N’s Endpoint E (On/Off Light Switch) should control Group G with Group Key +Set K: + +1. Make sure Node N is in Group G by calling AddGroupIDToEndpointForNode Command with + arguments N, E, and G. +2. Add a binding to Endpoint E on Node N by calling AddBindingToEndpointForNode Command + with arguments N, E, and the desired Binding. + +**11.24.4.7. Adding a Joint Fabric Administrator Node to a Fabric** + +When a Node is a Joint Fabric Administrator, its Group membership does not need to be managed +by the Datastore since it has the ability to monitor the Datastore and issue operational certs for its +own Administrator Nodes at any time. As a result, rather than adding Joint Fabric Administrator +Nodes to the regular NodeList attribute via the AddPendingNode Command, these Nodes SHALL be +added to the AdminList via the AddAdmin Command. + +It’s important to explicitly track the vendor ID of an Joint Fabric Administrator so that the Joint Fab­ + +``` +Page 1022 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +ric Administrator controlling the Root Operational Cert for the fabric can sign intermediate certifi­ +cates which can be used by an Joint Fabric Administrator to issue operational certificates. + +**11.24.4.8. Adding/Updating/Removing a Group** + +When adding a group, a client must create the group information entry before adding membership +associations between the Node and the Group. + +Adding a Group + +Add Group Key Set Entry (if new) using the AddKeySet Command, followed by Group Information +Entry using the AddGroup Command. + +Updating a Group + +Update the Group Key Set Entry (if changing) using the UpdateKeySet Command. Update the Group +Information Entry using the UpdateGroup Command. KeySet and Group updates performed using +these commands will cause the Datastore to attempt to update all Node members of the group with +these changes. Any Node changes that do not complete (for example, if the Node is unreachable) +will result in Pending status on the data in the Node Information Entry. + +Removing a Group + +Remove the Group Information Entry using the UpdateGroup Command. This command will fail if +the Group is in use (and not with PendingDelete Status) by any Nodes. + +Remove the Group Key Set Entry using the RemoveKeySet Command. This command will fail if this +KeySet is in use by any Groups. + +**11.24.4.9. Adding/Removing access privileges for a Controller** + +In order to ensure a consistent approach to access control by Administrators on a Joint Fabric, Joint +Fabric Administrators SHALL use groups in the Datastore for managing access to Nodes. One goal of +this approach is to avoid creating ACL entries on Nodes which reference a single NodeID, which +does not scale as the number of Controller NodeIDs increases. Instead, ACLs can reference the CAT +tag of the group or the GroupID of the group, depending upon the type of access intended. Each +group in the Datastore contains a CAT tag for use in unicast access to group members, and a KeySet +for use in broadcast access to group members. + +In order to add a new access privilege to NodeA by ControllerB, the Joint Fabric Administrator +SHALL identify a group to use for this grant (using Section 11.24.7.4, “AddGroup Command” to cre­ +ate a new one if needed), and call Section 11.24.7.15, “AddGroupIDToEndpointForNode Command” +and Section 11.24.7.19, “AddACLToNode Command” in order to configure NodeA to allow access by +the group. Next, the Administrator SHALL provide a NOC to the controller containing the CAT tag +specified for the given group. + +In order to remove an access privilege grant for ControllerB on NodeA, the Joint Fabric Administra­ +tor SHALL revoke access to the group by ControllerB (see Section 11.24.4.5, “Removing a Node from +a Group”) and in doing so, ensure that the CAT version for the Group Information Entry is incre­ +mented. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1023 +``` + +**11.24.5. Data Types** + +**11.24.5.1. DatastoreStateEnum Type** + +This data type is derived from enum8. + +``` +Value Name Summary Conformance +0 Pending Target device operation +is pending +``` +### M + +``` +1 Committed Target device operation +has been committed +``` +### M + +``` +2 DeletePending Target device delete +operation is pending +``` +### M + +**11.24.5.2. DatastoreStatusEntry Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 State Section +11.24.5.1, +“Datas­ +toreSta­ +teEnum +Type” +``` +``` +Pending R V M +``` +``` +1 Update­ +Time­ +stamp +``` +``` +utc all null R V M +``` +**State Field** + +This field SHALL contain the current state of the target device operation. + +**UpdateTimestamp Field** + +This field SHALL contain the timestamp of the last update. + +**11.24.5.3. Datastore Node Key Entry Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 GroupKey­ +SetID +``` +``` +uint16 all R V M +``` +``` +Page 1024 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Access Quality: Fabric Scoped +1 StatusEn­ +try +``` +``` +Section +11.24.5.2, +“Datas­ +toreSta­ +tusEntry +Type” +``` +### R V M + +**GroupKeySet Field** + +Group Key Set structure containing the list of epoch keys. + +**StatusEntry Field** + +Indicates whether entry in this list is pending, committed, or delete-pending. + +**11.24.5.4. Datastore Group Information Entry Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 GroupID uint64 all R V M +1 Friendly­ +Name +``` +``` +string max 32 R V M +``` +``` +2 GroupKey­ +SetID +``` +``` +uint16 1 to 65535 R V M +``` +``` +3 GroupCAT uint16 1 to 65535 R V M +4 Group­ +CATVer­ +sion +``` +``` +uint16 1 to 65535 R V M +``` +``` +5 GroupPer­ +mission +``` +``` +AccessCon­ +trolEn­ +tryPrivi­ +legeEnum +``` +### R V M + +**GroupID Field** + +The unique identifier for the group. + +**FriendlyName Field** + +The friendly name for the group. + +**GroupKeySetID Field** + +The unique identifier for the group key set. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1025 +``` + +**GroupCAT Field** + +CAT value for this group. This is used for control of individual members of a group (non-broadcast +commands). + +**GroupCATVersion Field** + +Current version number for this CAT. + +**GroupPermission Field** + +The permission level associated with ACL entries for this group. There should be only one Adminis­ +trator group per fabric, and at most one Manage group per Ecosystem (Vendor Entry). + +**Datastore Binding Entry Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ListID uint16 all R V M +1 Binding Target­ +Struct +``` +``` +desc R V M +``` +``` +2 StatusEn­ +try +``` +``` +Section +11.24.5.2, +“Datas­ +toreSta­ +tusEntry +Type” +``` +### R V M + +**ListID Field** + +The unique identifier for the Binding entry in the Datastore’s list of DatastoreBindingEntry. + +**Binding Field** + +The binding target structure. + +**StatusEntry Field** + +Indicates whether entry in this list is pending, committed, or delete-pending. + +**11.24.5.5. Datastore Group ID Entry Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 GroupID group-id all R V M +``` +``` +Page 1026 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Access Quality: Fabric Scoped +1 StatusEn­ +try +``` +``` +Section +11.24.5.2, +“Datas­ +toreSta­ +tusEntry +Type” +``` +### R V M + +**GroupID Field** + +The unique identifier for the group. + +**StatusEntry Field** + +Indicates whether entry in this list is pending, committed, or delete-pending. + +**11.24.5.6. Datastore Endpoint Entry Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 End­ +pointID +``` +``` +endpoint- +id +``` +``` +all R V M +``` +``` +1 NodeID node-id all R V M +2 Friendly­ +Name +``` +``` +string max 32 R V M +``` +``` +3 StatusEn­ +try +``` +``` +Section +11.24.5.2, +“Datas­ +toreSta­ +tusEntry +Type” +``` +### R V M + +``` +4 GroupIDLi +st +``` +``` +DataType­ +List[Sec­ +tion +11.24.5.5, +“Datastore +Group ID +Entry +Type”] +``` +### R V M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1027 +``` + +``` +Access Quality: Fabric Scoped +5 Bind­ +ingList +``` +``` +DataType­ +List[Sec­ +tion +11.24.5.4.7, +“Datastore +Binding +Entry +Type”] +``` +### R V M + +**EndpointID Field** + +The unique identifier for the endpoint. + +**NodeID Field** + +The unique identifier for the node. + +**FriendlyName Field** + +Friendly name for this endpoint which is propagated to nodes. Any changes to Friendly Name or +Group Id List (add/remove entry) must follow the pending→committed workflow with current state +reflected in the Status Entry. + +**StatusEntry Field** + +Indicates whether changes to Friendly Name are pending or committed. + +**GroupIDList Field** + +List of Group IDs that this endpoint is a member of. Any changes to Group Id List (add/remove +entry) must follow the pending→committed workflow with current state reflected in the Status +Entry. + +**BindingList Field** + +List of Binding Targets for this endpoint. Any changes to Binding List (add/remove entry) must fol­ +low the pending→committed workflow with current state reflected in the Status Entry. + +**11.24.5.7. Datastore ACL Entry Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 ListID uint16 all R V M +1 ACLEntry AccessCon­ +trolEntryS­ +truct +``` +### R V M + +``` +Page 1028 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Access Quality: Fabric Scoped +2 StatusEn­ +try +``` +``` +Section +11.24.5.2, +“Datas­ +toreSta­ +tusEntry +Type” +``` +### R V M + +**ListID Field** + +The unique identifier for the ACL entry in the Datastore’s list of DatastoreACLEntry. + +**ACLEntry Field** + +The Access Control Entry structure. + +**StatusEntry Field** + +Indicates whether entry in this list is pending, committed, or delete-pending. + +**11.24.5.8. Datastore Node Information Entry Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 NodeID node-id all R V M +2 Friendly­ +Name +``` +``` +string max 32 R V M +``` +``` +3 Commis­ +sion­ +ingSta­ +tusEntry +``` +``` +Section +11.24.5.2, +“Datas­ +toreSta­ +tusEntry +Type” +``` +### R V M + +``` +4 NodeKey­ +SetList +``` +``` +DataType­ +List[Sec­ +tion +11.24.5.3, +“Datastore +Node Key +Entry +Type”] +``` +### R V M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1029 +``` + +``` +Access Quality: Fabric Scoped +5 ACLList list[Section +11.24.5.7, +“Datastore +ACL Entry +Type”] +``` +### R V M + +``` +6 End­ +pointList +``` +``` +DataType­ +List[Sec­ +tion +11.24.5.6, +“Datastore +Endpoint +Entry +Type”] +``` +### R V M + +**NodeID Field** + +The unique identifier for the node. + +**FriendlyName Field** + +Friendly name for this node which is not propagated to nodes. + +**CommissioningStatusEntry Field** + +Set to pending prior to completing commissioning, and set to completed after commissioning com­ +plete is successful. + +**NodeKeySetList Field** + +List of Key Set information for the given Node. Updates to the Group Key List must follow the pend­ +ing→committed workflow with current state reflected in the Status Entry for the corresponding +entry in the list. + +**ACLList Field** + +List of ACL entries. Group membership for this node is inferred from the ACLs. Client access to a +Node Information Entry will be determined from the ACL List. Any changes to ACL List +(add/remove entry) must follow the pending→committed workflow with current state reflected in +the Status Entry for the corresponding entry in the list. + +**EndpointList Field** + +The list of endpoints for this node. Any changes to Endpoint List (add/remove entry) must follow +the pending→committed workflow with current state reflected in the Status Entry for the corre­ +sponding entry in the list. + +``` +Page 1030 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.24.5.9. Datastore Administrator Information Entry Type** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +1 NodeID node-id all R V M +2 Friendly­ +Name +``` +``` +string max 32 R V M +``` +``` +3 VendorID vendor-id all R V M +4 ICAC octstr max 400 R V M +``` +**NodeID Field** + +The unique identifier for the node. + +**FriendlyName Field** + +Friendly name for this node which is not propagated to nodes. + +**VendorID Field** + +The Vendor ID for the node. + +**ICAC Field** + +The ICAC used to issue the NOC. + +**11.24.6. Attributes** + +``` +Access Quality: Fabric Scoped +ID Name Type Constraint Quality Default Access Confor­ +mance +0 Anchor­ +RootCA +``` +``` +octstr S A R M +``` +``` +1 AnchorN­ +odeID +``` +``` +node-id all S A R M +``` +``` +2 Anchor­ +VendorID +``` +``` +vendor-id all S A R M +``` +``` +3 Friendly­ +Name +``` +``` +string max 32 S A R M +``` +``` +4 GroupKey­ +SetList +``` +``` +DataType­ +List[Group­ +KeySet­ +Struct] +``` +### S A R M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1031 +``` + +``` +Access Quality: Fabric Scoped +5 GroupList DataType­ +List[Sec­ +tion +11.24.5.4, +“Datastore +Group +Informa­ +tion Entry +Type”] +``` +### S A R M + +``` +6 NodeList DataType­ +List[Sec­ +tion +11.24.5.8, +“Datastore +Node +Informa­ +tion Entry +Type”] +``` +### S A R M + +``` +7 AdminList DataType­ +List[Sec­ +tion +11.24.5.9, +“Datastore +Adminis­ +trator +Informa­ +tion Entry +Type”] +``` +### S A R M + +``` +8 StatusEn­ +try +``` +``` +Section +11.24.5.9, +“Datastore +Adminis­ +trator +Informa­ +tion Entry +Type” +``` +### S A R M + +**11.24.6.1. AnchorRootCA Attribute** + +This SHALL indicate the Anchor Root CA used to sign all NOC Issuers in the Joint Fabric. A null +value indicates that the Joint Fabric is not yet formed. + +**11.24.6.2. AnchorNodeID Attribute** + +This SHALL indicate the Node identifier of the Joint Fabric Anchor Root CA. + +``` +Page 1032 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.24.6.3. AnchorVendorID Attribute** + +This SHALL indicate the Vendor identifier of the Joint Fabric Anchor Root CA. + +**11.24.6.4. FriendlyName Attribute** + +Friendly name for this fabric which can be propagated to nodes. + +**11.24.6.5. GroupKeySetList Attribute** + +This SHALL indicate the list of GroupKeySetStruct used in the Joint Fabric. + +This attribute SHALL contain at least one entry, the IPK, which has GroupKeySetID of 0. + +**11.24.6.6. GroupList Attribute** + +This SHALL indicate the list of groups in the Joint Fabric. + +**11.24.6.7. NodeList Attribute** + +This SHALL indicate the list of nodes in the Joint Fabric. + +**11.24.6.8. AdminList Attribute** + +This SHALL indicate the list of administrators in the Joint Fabric. + +Only one Administrator may serve as the Anchor Root CA and Anchor Fabric Administrator and +SHALL have index value 0. All other Joint Fabric Administrators SHALL be referenced at index 1 or +greater. + +A null value or empty list indicates that the Joint Fabric is not yet formed. + +**11.24.6.9. StatusEntry Attribute** + +This SHALL indicate the current state of the Joint Fabric Datastore Cluster. + +The Committed status indicates the DataStore is ready for use. The Pending status indicates that the +DataStore is not yet ready for use. The DeletePending status indicates that the DataStore is in the +process of being transferred to another Joint Fabric Anchor Administrator. + +**11.24.7. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 Section +11.24.7.1, +“AddKeySet +Command” +``` +``` +Client ⇒ ServerY F A M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1033 +``` + +``` +ID Name Direction Response Access Conformance +0x01 Section +11.24.7.2, +“UpdateKey­ +Set Com­ +mand” +``` +``` +Client ⇒ ServerY F A M +``` +``` +0x02 Section +11.24.7.3, +“RemoveKey­ +Set Com­ +mand” +``` +``` +Client ⇒ ServerY F A M +``` +``` +0x03 Section +11.24.7.4, +“AddGroup +Command” +``` +``` +Client ⇒ ServerY F A M +``` +``` +0x04 Section +11.24.7.5, +“UpdateGroup +Command” +``` +``` +Client ⇒ ServerY F A M +``` +``` +0x05 Section +11.24.7.6, +“Remove­ +Group Com­ +mand” +``` +``` +Client ⇒ ServerY F A M +``` +``` +0x06 Section +11.24.7.7, +“AddAdmin +Command” +``` +``` +Client ⇒ ServerY F A M +``` +``` +0x07 Section +11.24.7.8, +“UpdateAd­ +min Com­ +mand” +``` +``` +Client ⇒ ServerY F A M +``` +``` +0x08 Section +11.24.7.9, +“RemoveAd­ +min Com­ +mand” +``` +``` +Client ⇒ ServerY F A M +``` +``` +0x09 Section +11.24.7.10, +“AddPend­ +ingNode Com­ +mand” +``` +``` +Client ⇒ ServerY F A M +``` +Page 1034 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**ID Name Direction Response Access Conformance** + +0x0A **Section +11.24.7.11, +“RefreshNode +Command”** + +``` +Client ⇒ ServerY F A M +``` +0x0B **Section +11.24.7.12, +“UpdateNode +Command”** + +``` +Client ⇒ ServerY F A M +``` +0x0C **Section +11.24.7.13, +“RemoveNode +Command”** + +``` +Client ⇒ ServerY F A M +``` +0x0D **Section +11.24.7.14, +“UpdateEnd­ +pointForNode +Command”** + +``` +Client ⇒ ServerY F A M +``` +0x0E **Section +11.24.7.15, +“AddGroupID­ +ToEndpoint­ +ForNode Com­ +mand”** + +``` +Client ⇒ ServerY F A M +``` +0x0F **Section +11.24.7.16, +“Remove­ +GroupID­ +FromEnd­ +pointForNode +Command”** + +``` +Client ⇒ ServerY F A M +``` +0x10 **Section +11.24.7.17, +“AddBinding­ +ToEndpoint­ +ForNode Com­ +mand”** + +``` +Client ⇒ ServerY F A M +``` +0x11 **Section +11.24.7.18, +“RemoveBind­ +ingFromEnd­ +pointForNode +Command”** + +``` +Client ⇒ ServerY F A M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1035 +``` + +``` +ID Name Direction Response Access Conformance +0x12 Section +11.24.7.19, +“AddACLToN­ +ode Com­ +mand” +``` +``` +Client ⇒ ServerY F A M +``` +``` +0x13 Section +11.24.7.20, +“RemoveACL­ +FromNode +Command” +``` +``` +Client ⇒ ServerY F A M +``` +**11.24.7.1. AddKeySet Command** + +This command SHALL be used to add a KeySet to the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupKey­ +Set +``` +``` +GroupKey­ +SetStruct +``` +### M + +GroupKeySet represents the KeySet to be added to the Joint Fabric Datastore Cluster. + +Upon receipt of this command, the Datastore SHALL: + +1. Ensure there are no KeySets in the KeySetList attribute with the given GroupKeySetID. +2. If a match is found, return CONSTRAINT_ERROR. +3. Add the Epoch Key Entry for the KeySet to the KeySetList attribute. + +**11.24.7.2. UpdateKeySet Command** + +This command SHALL be used to update a KeySet in the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupKey­ +Set +``` +``` +GroupKey­ +SetStruct +``` +### M + +GroupKeySet represents the KeySet to be updated in the Joint Fabric Datastore Cluster. + +Upon receipt of this command, the Datastore SHALL: + +1. Find the Epoch Key Entry for the KeySet in the KeySetList attribute with the given GroupKey­ + +``` +Page 1036 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +SetID, and update any changed fields. +``` +2. If entry is not found, return NOT_FOUND. +3. If any fields are changed as a result of this command: + a. Iterate through each Node Information Entry: + i. If the NodeKeySetList contains an entry with the given GroupKeySetID: + A. Update the Status on the given Section 11.24.5.3, “Datastore Node Key Entry Type” tp + Pending. + B. Update the GroupKeySet on the given Node with the new values. + I. If successful, update the Status on this Section 11.24.5.3, “Datastore Node Key + Entry Type” to Committed. +II. If not successful, the pending change SHALL be applied in a subsequent Node +Refresh. + +**11.24.7.3. RemoveKeySet Command** + +This command SHALL be used to remove a KeySet from the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupKey­ +SetID +``` +``` +uint16 all M +``` +GroupKeySetID represents the unique identifier for the KeySet to be removed from the Joint Fabric +Datastore Cluster. + +Attempt to remove the IPK, which has GroupKeySetID of 0, SHALL fail with response CONSTRAIN­ +T_ERROR. + +Upon receipt of this command, the Datastore SHALL: + +1. If entry is not found, return NOT_FOUND. +2. Ensure there are no Nodes using this KeySet. To do this: + a. Iterate through each Node Information Entry: + i. If the NodeKeySetList list contains an entry with the given GroupKeySetID, and the entry + does NOT have Status DeletePending, then return CONSTRAINT_ERROR. +3. Remove the GroupKeySet for the given GroupKeySetID from the GroupKeySetList attribute. + +**11.24.7.4. AddGroup Command** + +This command SHALL be used to add a group to the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1037 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +1 Friendly­ +Name +``` +``` +string max 32 M +``` +``` +2 GroupKey­ +SetID +``` +``` +uint16 1 to 65535 M +``` +``` +3 GroupCAT uint16 1 to 65535 M +4 Group­ +CATVersion +``` +``` +uint16 1 to 65535 M +``` +``` +5 GroupPer­ +mission +``` +``` +AccessCon­ +trolEn­ +tryPrivi­ +legeEnum +``` +### M + +GroupInformationEntry represents the group to be added to the Joint Fabric Datastore Cluster. + +Upon receipt of this command, the Datastore SHALL: + +1. Ensure there are no Groups in the GroupList attribute with the given GroupID. If a match is + found, return CONSTRAINT_ERROR. +2. Add the DatastoreGroupInformationEntry for the Group with the given GroupID to the Grou­ + pList attribute. + +**11.24.7.5. UpdateGroup Command** + +This command SHALL be used to update a group in the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +1 Friendly­ +Name +``` +``` +string max 32 X M +``` +``` +2 GroupKey­ +SetID +``` +``` +uint16 1 to 65535 X M +``` +``` +3 GroupCAT uint16 1 to 65535 X M +4 Group­ +CATVersion +``` +``` +uint16 1 to 65535 X M +``` +``` +Page 1038 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +5 GroupPer­ +mission +``` +``` +AccessCon­ +trolEn­ +tryPrivi­ +legeEnum +``` +### X M + +GroupID represents the group to be updated in the Joint Fabric Datastore Cluster. NULL values for +the additional parameters will be ignored (not updated). + +Upon receipt of this command, the Datastore SHALL: + +1. If entry is not found, return NOT_FOUND. +2. Update the DatastoreGroupInformationEntry for the Group with the given GroupID to match + the non-NULL fields passed in. +3. If any fields are changed as a result of this command: + a. Iterate through each Node Information Entry: + i. If the GroupKeySetID changed: + I. Add a Section 11.24.5.3, “Datastore Node Key Entry Type” with the new GroupKey­ + SetID, and Status set to Pending. +II. Add this KeySet to the Node. +1. If successful, Set the Status to Committed for this entry in the NodeKeySetList. +2. If not successful, the pending change SHALL be applied in a subsequent Node +Refresh. +A. If the NodeKeySetList list contains an entry with the previous GroupKeySetID: +III. Set the Status set to DeletePending. +IV. Remove this KeySet from the Node. +1. If successful, Remove this entry from the NodeKeySetList. +2. If not successful, the pending change SHALL be applied in a subsequent Node +Refresh. +ii. If the GroupCAT, GroupCATVersion or GroupPermission changed: +A. If the ACLList contains an entry for this Group, update the ACL List Entry in the Data­ +store with the new values and Status Pending, update the ACL attribute on the given +Node with the new values. If the update succeeds, set the Status to Committed on the +ACLList Entry in the Datastore. +iii. If the FriendlyName changed: +A. Iterate through each Endpoint Information Entry: +I. If the GroupIDList contains an entry with the given GroupID: +1. Update the GroupIDList Entry in the Datastore with the new values and Status +Pending + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1039 +``` + +2. Update the Groups on the given Node with the new values. + 1. If the update succeeds, set the Status to Committed on the GroupIDList + Entry in the Datastore. + 2. If not successful, the pending change SHALL be applied in a subsequent + Node Refresh. + +**11.24.7.6. RemoveGroup Command** + +This command SHALL be used to remove a group from the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 GroupID group-id all M +``` +GroupID represents the unique identifier for the group to be removed from the Joint Fabric Datas­ +tore Cluster. + +Upon receipt of this command, the Datastore SHALL: + +1. If entry is not found, return NOT_FOUND. +2. Ensure there are no Nodes in this group. To do this: + a.Iterate through each Node Information Entry: + i. If the GroupIDList contains an entry with the given GroupID, and the entry does NOT + have Status DeletePending, then return CONSTRAINT_ERROR. +3. Remove the DatastoreGroupInformationEntry for the Group with the given GroupID from the + GroupList attribute. + +**11.24.7.7. AddAdmin Command** + +This command SHALL be used to add an admin to the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 AdminInfor­ +mationEn­ +try +``` +``` +Section +11.24.5.9, +“Datastore +Administra­ +tor Informa­ +tion Entry +Type” +``` +### M + +AdminInformationEntry represents the admin to be added to the Joint Fabric Datastore Cluster. + +``` +Page 1040 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.24.7.8. UpdateAdmin Command** + +This command SHALL be used to update an admin in the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all X M +1 Friendly­ +Name +``` +``` +string max 32 X M +``` +``` +2 ICAC octstr max 400 X M +``` +NodeID represents the admin to be updated in the Joint Fabric Datastore Cluster. NULL values for +the additional parameters will be ignored (not updated). + +If entry is not found, return NOT_FOUND. + +**11.24.7.9. RemoveAdmin Command** + +This command SHALL be used to remove an admin from the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all M +``` +NodeID represents the unique identifier for the admin to be removed from the Joint Fabric Datas­ +tore Cluster. + +If entry is not found, return NOT_FOUND. + +**11.24.7.10. AddPendingNode Command** + +The command SHALL be used to add a node to the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all M +1 Friendly­ +Name +``` +``` +string max 32 M +``` +NodeID represents the node to be added to the Joint Fabric Datastore Cluster. + +Upon receipt of this command, the Datastore SHALL: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1041 +``` + +1. Update CommissioningStatusEntry of the Node Information Entry with the given NodeID to + Pending. + +If a Node Information Entry exists for the given NodeID, this command SHALL return INVALID_­ +CONSTRAINT. + +**11.24.7.11. RefreshNode Command** + +The command SHALL be used to request that Datastore information relating to a Node is refreshed. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all M +``` +Upon receipt of this command, the Datastore SHALL: + +1. Confirm that a Node Information Entry exists for the given NodeID, and if not, return NOT_­ + FOUND. +2. Update the CommissioningStatusEntry for the Node Information Entry to Pending. +3. Ensure the Endpoint List for the Node Information Entry with the given NodeID matches End­ + point list on the given Node. This involves the following steps: + a.Read the PartsList of the Descriptor cluster from the Node. +b. For each Endpoint Information Entry in the Endpoint List of the Node Information Entry +that does not match an Endpoint ID in the PartList, remove the Endpoint Information Entry. +c.For each Endpoint Information Entry in the Endpoint List of the Node Information Entry +that matches an Endpoint ID in the PartList: +i. Check that each entry in Node’s Group List occurs in the GroupIDList of the Endpoint +Information Entry. +A. Add any missing entries to the GroupIDList of the Endpoint Information Entry. +B. For any entries in the GroupIDList with Status of Pending: +I. Add the corresponding change to the Node’s Group List. +1. If successful, mark the Status to Committed. +2. If not successful, the pending change SHALL be applied in a subsequent Node +Refresh. +C. For any entries in the GroupIDList with Status of DeletePending: +1. If successful, remove the corresponding entry from the Node’s Group List. +2. If not successful, the pending change SHALL be applied in a subsequent Node +Refresh. +ii.Check that each entry in Node’s Binding List occurs in the BindingList of the Endpoint +Information Entry. + +``` +Page 1042 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +A. Add any missing entries to the BindingList of the Endpoint Information Entry. +B. For any entries in the BindingList with Status of Pending: +I. Add the corresponding change to the Node’s Binding List. +``` +1. If successful, mark the Status to Committed. +2. If not successful, the pending change SHALL be applied in a subsequent Node + Refresh. +C. For any entries in the BindingList with Status of DeletePending: +1. If successful, remove the corresponding entry from the Node’s BindingList. +2. If not successful, the pending change SHALL be applied in a subsequent Node +Refresh. +4. Ensure the GroupKeySetList for the Node Information Entry with the given NodeID matches the +Group Keys on the given Node. This involves the following steps: +a. Read the Group Keys from the Node. +b. For each GroupKeySetEntry in the GroupKeySetList of the Node Information Entry with a +Pending Status: +i. Add the corresponding GroupKeySetStruct to the Node’s Group Key list. +A. If successful, mark the Status to Committed. +B. If not successful, the pending change SHALL be applied in a subsequent Node +Refresh. +c. All remaining entries in the GroupKeySetList should be replaced by the remaining entries +on the Node. +5. Ensure the ACLList for the Node Information Entry with the given NodeID matches the ACL +attribute on the given Node. This involves the following steps: +a. Read the ACL attribute on the Node. +b. For each Section 11.24.5.7, “Datastore ACL Entry Type” in the ACLList of the Node Informa­ +tion Entry with a Pending Status: +i. Add the corresponding DatastoreACLEntry to the Node’s ACL attribute. +A. If successful, mark the Status to Committed. +B. If not successful, the pending change SHALL be applied in a subsequent Node +Refresh. +c. All remaining entries in the ACLList should be replaced by the remaining entries on the +Node. +6. Update the CommissioningStatusEntry for the Node Information Entry to Committed. + +**11.24.7.12. UpdateNode Command** + +The command SHALL be used to update the friendly name for a node in the Joint Fabric Datastore +Cluster. + +The data for this command is as follows: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1043 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all M +1 Friendly­ +Name +``` +``` +string max 32 M +``` +NodeID represents the node to be updated in the Joint Fabric Datastore Cluster. + +If a Node Information Entry does not exist for the given NodeID, this command SHALL return +NOT_FOUND. + +**11.24.7.13. RemoveNode Command** + +This command SHALL be used to remove a node from the Joint Fabric Datastore Cluster. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all M +``` +NodeID represents the unique identifier for the node to be removed from the Joint Fabric Datastore +Cluster. + +If a Node Information Entry does not exist for the given NodeID, this command SHALL return +NOT_FOUND. + +**11.24.7.14. UpdateEndpointForNode Command** + +This command SHALL be used to update the state of an endpoint for a node in the Joint Fabric Data­ +store Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 EndpointID endpoint-id all M +1 NodeID node-id all M +2 Friendly­ +Name +``` +``` +string max 32 M +``` +EndpointID represents the unique identifier for the endpoint to be updated in the Joint Fabric Data­ +store Cluster. + +NodeID represents the unique identifier for the node to which the endpoint belongs. + +If an Endpoint Information Entry does not exist for the given NodeID and EndpointID, this com­ +mand SHALL return NOT_FOUND. + +``` +Page 1044 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.24.7.15. AddGroupIDToEndpointForNode Command** + +This command SHALL be used to add a Group ID to an endpoint for a node in the Joint Fabric Data­ +store Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all M +1 EndpointID endpoint-id all M +2 GroupID group-id all M +``` +GroupID represents the unique identifier for the group to be added to the endpoint. + +EndpointID represents the unique identifier for the endpoint to be updated in the Joint Fabric Data­ +store Cluster. + +NodeID represents the unique identifier for the node to which the endpoint belongs. + +Upon receipt of this command, the Datastore SHALL: + +1. Confirm that an Endpoint Information Entry exists for the given NodeID and EndpointID, and if + not, return NOT_FOUND. +2. Ensure the Group Key List for the Node Information Entry with the given NodeID includes the + KeySet for the given Group ID. If it does not: + a. Add an entry for the KeySet of the given Group ID to the Group Key List. The new entry’s sta­ + tus SHALL be set to Pending. + b. Add a Group Key Entry for this KeySet to the given Node ID. + i. If this succeeds, update the new KeySet entry in the Datastore to Committed. +ii. If not successful, the pending change SHALL be applied in a subsequent Node Refresh. +3. Ensure the Group List for the Endpoint Information Entry with the given NodeID and End­ + pointID includes an entry for the given Group. If it does not: + a. Add a Group entry for the given Group ID to the Group List. The new entry’s status SHALL + be set to Pending. + b. Add this Group entry to the given Endpoint ID on the given Node ID. + i. If this succeeds, update the new Group entry in the Datastore to Committed. +ii. If not successful, the pending change SHALL be applied in a subsequent Node Refresh. + +**11.24.7.16. RemoveGroupIDFromEndpointForNode Command** + +This command SHALL be used to remove a Group ID from an endpoint for a node in the Joint Fab­ +ric Datastore Cluster. + +The data for this command is as follows: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1045 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all M +1 EndpointID endpoint-id all M +2 GroupID group-id all M +``` +GroupID represents the unique identifier for the group to be removed from the endpoint. + +EndpointID represents the unique identifier for the endpoint to be updated in the Joint Fabric Data­ +store Cluster. + +NodeID represents the unique identifier for the node to which the endpoint belongs. + +Upon receipt of this command, the Datastore SHALL: + +1. Confirm that an Endpoint Information Entry exists for the given NodeID and EndpointID, and if + not, return NOT_FOUND. +2. Ensure the Group List for the Endpoint Information Entry with the given NodeID and End­ + pointID does not include an entry for the given Group. If it does: + a.Update the status to DeletePending of the Group entry for the given Group ID in the Group + List. +b. Remove this Group entry for the given Endpoint ID on the given Node ID. +i. If this succeeds, remove the Group entry for the given Group ID in the Group List for this +NodeID and EndpointID in the Datastore. +ii.If not successful, the pending change SHALL be applied in a subsequent Node Refresh. +3. Ensure the Group Key List for the Node Information Entry with the given NodeID does not + include the KeySet for the given Group ID. If it does: + a.Update the status to DeletePending for the entry for the KeySet of the given Group ID in the + Group Key List. +b. Remove the Group Key Entry for this KeySet from the given Node ID. +i. If this succeeds, remove the KeySet entry for the given Node ID. +ii.If not successful, the pending change SHALL be applied in a subsequent Node Refresh. + +**11.24.7.17. AddBindingToEndpointForNode Command** + +This command SHALL be used to add a binding to an endpoint for a node in the Joint Fabric Datas­ +tore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all M +``` +``` +Page 1046 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 EndpointID endpoint-id all M +2 Binding TargetStruct M +``` +Binding represents the binding to be added to the endpoint. + +EndpointID represents the unique identifier for the endpoint to be updated in the Joint Fabric Data­ +store Cluster. + +NodeID represents the unique identifier for the node to which the endpoint belongs. + +Upon receipt of this command, the Datastore SHALL: + +1. Confirm that an Endpoint Information Entry exists for the given NodeID and EndpointID, and if + not, return NOT_FOUND. +2. Ensure the Binding List for the Node Information Entry with the given NodeID includes the + given Binding. If it does not: + a. Add the Binding to the Binding List for the Node Information Entry for the given NodeID. + The new entry’s status SHALL be set to Pending. + b. Add this Binding to the given Node ID. + i. If this succeeds, update the new Binding in the Datastore to Committed. +ii. If not successful, the pending change SHALL be applied in a subsequent Node Refresh. + +**11.24.7.18. RemoveBindingFromEndpointForNode Command** + +This command SHALL be used to remove a binding from an endpoint for a node in the Joint Fabric +Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ListID uint16 all M +1 EndpointID endpoint-id all M +2 NodeID node-id all M +``` +ListID represents the unique identifier for the binding to be removed from the endpoint. + +EndpointID represents the unique identifier for the endpoint to be updated in the Joint Fabric Data­ +store Cluster. + +NodeID represents the unique identifier for the node to which the endpoint belongs. + +Upon receipt of this command, the Datastore SHALL: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1047 +``` + +1. Confirm that an Endpoint Information Entry exists for the given NodeID and EndpointID, and if + not, return NOT_FOUND. +2. Ensure the Binding List for the Node Information Entry with the given NodeID does not include + an entry with the given ListID. If it does: + a.Update the status to DeletePending for the given Binding in the Binding List. +b. Remove this Binding from the given Node ID. +i. If this succeeds, remove the given Binding from the Binding List. +ii.If not successful, the pending change SHALL be applied in a subsequent Node Refresh. + +**11.24.7.19. AddACLToNode Command** + +This command SHALL be used to add an ACL to a node in the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 NodeID node-id all M +1 ACLEntry AccessCon­ +trolEntryS­ +truct +``` +### M + +NodeID represents the unique identifier for the node to which the ACL is to be added. + +ACLEntry represents the ACL to be added to the Joint Fabric Datastore Cluster. + +Upon receipt of this command, the Datastore SHALL: + +1. Confirm that a Node Information Entry exists for the given NodeID, and if not, return NOT_­ + FOUND. +2. Ensure the ACL List for the Node Information Entry with the given NodeID includes the given + ACLEntry. If it does not: + a.Add the ACLEntry to the ACL List for the Node Information Entry for the given NodeID. The + new entry’s status SHALL be set to Pending. +b. Add this ACLEntry to the given Node ID. +i. If this succeeds, update the new ACLEntry in the Datastore to Committed. +ii.If not successful, the pending change SHALL be applied in a subsequent Node Refresh. + +**11.24.7.20. RemoveACLFromNode Command** + +This command SHALL be used to remove an ACL from a node in the Joint Fabric Datastore Cluster. + +The data for this command is as follows: + +``` +Page 1048 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ListID uint16 all M +1 NodeID node-id all M +``` +ListID represents the unique identifier for the ACL to be removed from the Joint Fabric Datastore +Cluster. + +NodeID represents the unique identifier for the node from which the ACL is to be removed. + +Upon receipt of this command, the Datastore SHALL: + +1. Confirm that a Node Information Entry exists for the given NodeID, and if not, return NOT_­ + FOUND. +2. Ensure the ACL List for the Node Information Entry with the given NodeID does not include the + given ACLEntry. If it does: + a. Update the status to DeletePending for the given ACLEntry in the ACL List. + b. Remove this ACLEntry from the given Node ID. + i. If this succeeds, remove the given ACLEntry from the ACL List. +ii. If not successful, the pending change SHALL be applied in a subsequent Node Refresh. + +**11.25. Joint Fabric PKI Cluster** + +An instance of the Joint Fabric PKI Cluster only applies to Joint Fabric Administrator nodes fulfilling +the role of Anchor CA. + +``` +NOTE Support for Joint Fabric PKI Cluster is provisional. +``` +**11.25.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.25.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node JFPKI +``` +**11.25.3. Cluster ID** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1049 +``` + +``` +ID Name Conformance +0x0753 Joint Fabric PKI P +``` +**11.25.4. Data Types** + +**11.25.4.1. ICAC Signing Request Status Enum Type** + +This data type is derived from enum8. + +This enumeration is used by the ICACSRResponse command to convey the detailed outcome of this +cluster’s ICACSRRequest command. + +``` +Value Name Summary Conformance +0 OK No error M +1 InvalidIcaCsrFormat The ICACSR in the +request is not compli­ +ant to PKCS #10 rules +``` +### M + +``` +2 InvalidIcaCsrSigna­ +ture +``` +``` +The ICACSR in the +request has an incor­ +rect signature +``` +### M + +``` +3 FailedDCLVendorId­ +Validation +``` +``` +DCL Vendor ID valida­ +tion failed +``` +### M + +``` +4 NotAnIcac DCL returned certifi­ +cate is not an ICAC +``` +### M + +``` +5 BusyAnchorTransfer Error due to an in +progress Anchor Trans­ +fer +``` +### M + +``` +6 IcaCsrSigningFailed Signing the ICA CSR +failed +``` +### M + +``` +7 IcaCsrRequestNoUser­ +Consent +``` +``` +No user consent M +``` +**11.25.4.2. Transfer Anchor Response Status Enum Type** + +``` +This data type is derived from <>. +``` +This enumeration is used by the TransferAnchorResponse command to convey the detailed out­ +come of this cluster’s TransferAnchorRequest command. + +``` +Value Name Summary Conformance +0 OK No error M +``` +``` +Page 1050 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Value Name Summary Conformance +1 TransferAnchorSta­ +tusDatastoreBusy +``` +``` +Anchor Transfer was +not started due to on- +going Datastore opera­ +tions +``` +### M + +``` +2 TransferAnchorSta­ +tusNoUserConsent +``` +``` +User has not consented +for Anchor Transfer +``` +### M + +**11.25.5. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 ICACSRRe­ +quest +``` +``` +Client ⇒ ServerICACSRRe­ +sponse +``` +### A M + +``` +0x01 ICACSRRe­ +sponse +``` +``` +Server ⇒ ClientN A M +``` +``` +0x02 TransferAn­ +chorRequest +``` +``` +Client ⇒ ServerTransferAn­ +chorResponse +``` +### A M + +``` +0x03 TransferAn­ +chorResponse +``` +``` +Server ⇒ ClientN A M +``` +``` +0x04 TransferAn­ +chorComplete +``` +``` +Client ⇒ ServerY A M +``` +**11.25.5.1. ICACSRRequest Command** + +This command SHALL be generated and executed during the Joint Commissioning Method steps +and subsequently respond in the form of an ICACSRResponse command. + +Check ICA Cross Signing for details about the generation and contents of the ICACSR. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 ICACSR octstr max 400 M +``` +**11.25.5.2. ICACSRResponse Command** + +This command SHALL be generated in response to the ICACSRRequest command. + +Check ICA Cross Signing for details about the generation and contents of ICAC. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StatusCode IcacsrRe­ +questSta­ +tusEnum +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1051 +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +1 ICAC octstr max 400 O +``` +**StatusCode Field** + +This field SHALL contain an ICACSRRequestStatusEnum value representing the status of the Section +11.25.5.1, “ICACSRRequest Command” operation. + +**ICAC Field** + +If present, it SHALL contain the NOC Issuer Certificate in PEM format. + +**11.25.5.3. Transfer Anchor Request Command** + +This command SHALL be sent by a candidate Joint Fabric Anchor Administrator to the current Joint +Fabric Anchor Administrator to request transfer of the Anchor Fabric. + +**11.25.5.4. Transfer Anchor Response Command** + +This command SHALL be generated in response to the Transfer Anchor Request command. + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 StatusCode TransferAn­ +chorRe­ +sponseSta­ +tusEnum +``` +### M + +**11.25.5.5. Transfer Anchor Complete Command** + +This command SHALL indicate the completion of the transfer of the Anchor Fabric to another Joint +Fabric Ecosystem Administrator. + +**11.26. Commissioner Control Cluster** + +The Commissioner Control Cluster supports the ability for clients to request the commissioning of +themselves or other nodes onto a fabric which the cluster server can commission onto. An example +use case is ecosystem to ecosystem Fabric Synchronization setup. + +The generalized flow supported by the Commissioner Control Cluster can be seen in the following +diagram. + +``` +Page 1052 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 103. Commissioner Control Cluster - General Flow_ + +**11.26.1. Revision History** + +The global ClusterRevision attribute value SHALL be the highest revision number in the table +below. + +``` +Revision Description +1 Initial revision +``` +**11.26.2. Classification** + +``` +Hierarchy Role Scope PICS Code +Base Utility Node CCTRL +``` +**11.26.3. Cluster ID** + +``` +ID Name +0x0751 Commissioner Control +``` +**11.26.4. Data Types** + +**11.26.4.1. SupportedDeviceCategoryBitmap Type** + +This data type is derived from map32. + +``` +Bit Name Summary Conformance +0 FabricSynchronization Aggregators which sup­ +port Fabric Synchro­ +nization may be com­ +missioned. +``` +### O + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1053 +``` + +**FabricSynchronization Bit** + +The FabricSynchronization bit SHALL be set to 1 if and only if the server supports commissioning +nodes that support Fabric Synchronization. + +**11.26.5. Attributes** + +``` +ID Name Type Constraint Quality Default Access Confor­ +mance +0x0000 Supported­ +DeviceCat­ +egories +``` +``` +Supported­ +DeviceCat­ +egory­ +Bitmap +``` +``` +all 0 R M M +``` +**11.26.5.1. SupportedDeviceCategories Attribute** + +This attribute SHALL indicate the device categories specified in SupportedDeviceCategoryBitmap +that are supported by this Commissioner Control Cluster server. + +A client SHALL NOT send the RequestCommissioningApproval command if the intended node to be +commissioned does not conform to any of the values specified in SupportedDeviceCategories. + +**11.26.6. Commands** + +``` +ID Name Direction Response Access Conformance +0x00 RequestCom­ +missioningAp­ +proval +``` +``` +client ⇒ server Y M M +``` +``` +0x01 CommissionN­ +ode +``` +``` +client ⇒ server ReverseOpen­ +Commission­ +ingWindow +``` +### M M + +``` +0x02 ReverseOpen­ +Commission­ +ingWindow +``` +``` +server ⇒ client N M +``` +**11.26.6.1. RequestCommissioningApproval Command** + +This command is sent by a client to request approval for a future CommissionNode call. This is +required to be a separate step in order to provide the server time for interacting with a user before +informing the client that the CommissionNode operation may be successful. + +If the command is not executed via a CASE session, the command SHALL fail with a status code of +UNSUPPORTED_ACCESS. + +The server MAY request approval from the user, but it is not required. + +The server SHALL always return SUCCESS to a correctly formatted RequestCommissioningApproval +command, and then generate a CommissioningRequestResult event associated with the command’s + +``` +Page 1054 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +accessing fabric once the result is ready. + +Clients SHOULD avoid using the same RequestID. If the RequestID and client NodeID of a Request­ +CommissioningApproval match a previously received RequestCommissioningApproval and the +server has not returned an error or completed commissioning of a device for the prior request, +then the server SHOULD return FAILURE. + +The parameters for RequestCommissioningApproval command are as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 RequestID uint64 M +1 VendorID vendor-id M +2 ProductID uint16 M +3 Label string max 64 O +``` +**11.26.6.2. RequestID** + +This SHALL be set by the client to be used again in future interactions. + +**11.26.6.3. VendorID / ProductID fields** + +These fields SHALL contain the VendorID and ProductID which match the values in the Device +Attestation Certificate of the device that the client would like to have commissioned in the subse­ +quent ReverseOpenCommissioningWindow command. + +**11.26.6.4. Label** + +The Label field SHOULD be set to a user readable name for the device that the client would like to +have commissioned in the subsequent ReverseOpenCommissioningWindow command. This may be +an ecosystem defined label or user provided name. + +For example, in FabricSynchronization between two ecosystems (E1 as initial commissioner and E2 +as initial commissionee), the label here represents the node on E1 that will be commissioned by E2 +in the reverse commissioning operation after E1 has initially commissioned E2. This enables E2 to +provide the user with a label for the node on E1 prior to completing the reverse commissioning +operation. + +**11.26.6.5. CommissionNode Command** + +This command is sent by a client to request that the server begins commissioning a previously +approved request. + +The server SHALL return FAILURE if the CommissionNode command is not sent from the same +NodeID and on the same fabric as the RequestCommissioningApproval or if the provided RequestID +to CommissionNode does not match the value provided to RequestCommissioningApproval. + +If the command is not executed via a CASE session, the command SHALL fail with a status code of + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1055 +``` + +### UNSUPPORTED_ACCESS. + +Upon receipt, the server SHALL respond with ReverseOpenCommissioningWindow if Commission­ +ingRequestResult was generated with StatusCode of SUCCESS for the matching RequestID field and +NodeID of the client. + +The server SHALL return FAILURE if the CommissionNode command is received after the server +has already responded to a client with ReverseOpenCommissioningWindow for a matching +RequestID field and NodeID of the client unless the client has sent another RequestCommis­ +sioningApproval and received an additional CommissioningRequestResult. + +The parameters for CommissionNode command are as follows: + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 RequestID uint64 M +1 Response­ +TimeoutSec­ +onds +``` +``` +uint16 30 to 120 30 M +``` +**11.26.6.6. RequestID Field** + +This SHALL be set by the client to be the same value provided to RequestCommissioningApproval. + +**11.26.6.7. ResponseTimeoutSeconds Field** + +Timeout in seconds that the client SHALL wait to receive a response before considering the +responses invalid. + +**11.26.6.8. ReverseOpenCommissioningWindow Command** + +When received within the timeout specified by ResponseTimeoutSeconds in the CommissionNode +command, the client SHALL open a commissioning window on a node which matches the VendorID +and ProductID provided in the associated RequestCommissioningApproval command. + +When commissioning this node, the server SHALL check that the VendorID and ProductID fields +provided in the RequestCommissioningApproval command match the VendorID and ProductID +attributes of the Basic Information Cluster which have already been verified during the Device +Attestation Procedure. If they do not match, the server SHALL NOT complete commissioning and +SHOULD indicate an error to the user. + +### NOTE + +``` +This is an alias onto the Open Commissioning Window command within the Admin­ +istrator Commissioning Cluster. Refer to the Open Commissioning Window com­ +mand for a description of the command behavior and parameters. +``` +The parameters for ReverseOpenCommissioningWindow command are as follows: + +``` +Page 1056 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Type Constraint Quality Default Confor­ +mance +0 Commis­ +sioning­ +Timeout +``` +``` +uint16 desc M +``` +``` +1 PAKEPass­ +codeVeri­ +fier +``` +``` +octstr all M +``` +``` +2 Discrimina­ +tor +``` +``` +uint16 max 4095 M +``` +``` +3 Iterations uint32 1000 to +100000 +``` +### M + +``` +4 Salt octstr 16 to 32 M +``` +**11.26.7. Events** + +``` +ID Name Priority Quality Access Conformance +0x00 Commission­ +ingRequestRe­ +sult +``` +### INFO M S M + +**11.26.7.1. CommissioningRequestResult Event** + +This event SHALL be generated by the server following a RequestCommissioningApproval com­ +mand which the server responded to with SUCCESS. + +### NOTE + +``` +The approval is valid for a period determined by the manufacturer and characteris­ +tics of the node presenting the Commissioner Control Cluster. Clients SHOULD send +the CommissionNode command immediately upon receiving a CommissioningRe­ +questResult event. +``` +``` +Access Quality: Fabric-Sensitive +ID Name Type Constraint Quality Default Confor­ +mance +0 RequestID uint64 all M +1 ClientN­ +odeID +``` +``` +node-id all M +``` +``` +2 StatusCode status desc M +``` +**11.26.7.2. RequestID / ClientNodeID Fields** + +The RequestID SHALL match the RequestID provided to RequestCommissioningApproval and the +ClientNodeID shall match the NodeID of the client which generated the RequestCommissioningAp­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1057 +``` + +proval command. + +**11.26.7.3. StatusCode Field** + +The server SHALL set this field to SUCCESS if the server is ready to begin commissioning the +requested device, TIMEOUT if the server timed out due to user inaction or FAILURE for any other +error. + +``` +Page 1058 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 12. Multiple Fabrics** + +**12.1. Introduction** + +The Multiple Fabric feature allows a Node to be commissioned to multiple separately-administered +Fabrics. With this feature a current Administrator can (with user consent) allow the Commissioner +for another fabric to commission that Node within its Fabric. The new Commissioner MUST have +their own Node Operational Certificate (NOC) issued by its Trusted Root Certificate Authority +(TRCA). Once commissioning is completed and the Node is properly configured, Administrators on +the newly joined Fabric have access to the Node and can perform all administrative tasks. + +A Fabric is anchored by its Trusted Root Certificate Authority (TRCA). A TRCA MAY delegate to one +or more Intermediate Certificate Authorities (ICA) which issue NOCs. Multiple vendors or compa­ +nies can use the same CA hierarchy in which case they will be governed under the same Trusted +Root Certificate Authority. + +**12.2. Joint Fabric** + +**12.2.1. Introduction** + +When multiple vendors or companies use the same CA hierarchy, governed under the same Trusted +Root Certificate Authority, they create a Joint Fabric using the Joint Commissioning Method flow. +This flow enables a set of one or more companies to use a single fabric anchored by the Trusted +Root Certificate Authority (TRCA). In the context of JCM, the fabric that is anchored by this TRCA is +known as the Anchor Fabric. + +``` +NOTE Support for Joint Fabric is provisional. +``` +**12.2.2. Node ID Generation** + +Any newly-allocated Node ID SHALL: + +- be greater than 0x0000_0000_0000_0000, but less than 0xFFFF_FFEF_FFFF_FFFF, representing a + value within the Operational NodeID range (see Table 4, “Node Identifier Allocations”); +- be checked to ensure its uniqueness in the NodeList attribute of the Joint Fabric Datastore + +The Node ID SHALL be regenerated if these constraints are not met. + +It is RECOMMENDED to use random allocation within the valid range to avoid having to regenerate +the Node ID. + +**12.2.3. Anchor ICAC requirements** + +Anchor ICAC SHALL be the ICAC corresponding to the Anchor Administrator. Anchor ICAC SHALL +contain the reserved org-unit-name attribute from the Table 64, “Standard DN Object Identifiers” +with value jf-anchor-icac in its Subject DN. The Anchor CA SHALL NOT place the reserved org- +unit-name attribute jf-anchor-icac value into any Node that is not the Anchor Administrator. The + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1059 +``` + +Anchor CA SHALL place the reserved org_unit-name attribute jf-anchor-icac value into the Anchor +ICAC. + +**12.2.4. Joint Fabric ACL Architecture** + +A set of CASE Authenticated Tags defined to be used in the context of Joint Fabric. In combination +with the Anchor ICAC, these CATs can provide a greater level of security. + +**12.2.4.1. Administrator CAT** + +The Administrator CAT is meant to simplify management of the group of Administrator Nodes as +opposed to managing a list of subject Node IDs. All devices participating in Joint Fabric SHALL con­ +tain an ACL entry granting Administer privilege to CaseSubjectAdmin set to the Administrator CAT. +During commissioning of any Node onto the Joint Fabric the CaseAdminSubject field SHALL be set to +the Administrator CAT upon invoking the AddNOC command. + +Any Node advertising as a Joint Fabric Administrator SHALL contain the Administrator CAT in its +NOC. A NOC containing the Administrator CAT MAY be issued by any Joint Fabric Administrator. + +Any client that discovers the Administrator Node with DNS-SD and connects to the Node via CASE +SHALL check if the Administrator CAT is present in the NOC of the Node as part of the CASE hand­ +shake. This SHALL be required in order to verify that the Node is authorized to act as an Adminis­ +trator in the Joint Fabric. + +If the Administrator CAT is already in use in a fabric that wants to participate in the Joint Fabric +then its Administrator first needs to take the required steps for updating it with a non-overlapping +Administrator CAT. This may involve updating ACLs and NOCs on the Nodes wishing to participate +in the Joint Fabric. + +Concern for its use in gaining unauthorized Administer access is mitigated by the fact that the +Administrator CAT is a special subject distinguished name within the NOC and that the NOC must +be issued by an Administrator and not self-issued. + +User initiated and granted revocation of an Administrator to administer nodes SHALL be achieved +by updating the Administrator CAT. The Joint Fabric Anchor Administrator SHALL increment the +version number of the Administrator CAT to a value higher than its current value (e.g., from 0x0000 +to 0x0001), update the existing credentials (NOC) for all Administrator Nodes that are NOT being +revoked with the new version of the Administrator CAT, and update the ACL entry of all Nodes +whose subject list contains the prior version of the Administrator CAT with the new version of the +Administrator CAT. This has the effect of revoking the Administer access of any Administrator Nodes +that did not receive updated credentials (NOC) with the new version of the Administrator CAT. Com­ +pleting this operation requires visiting all the nodes in the Joint Fabric, a task which might take a +long time to complete or might never complete if some Nodes are permanently offline or otherwise +unreachable. However, any Nodes that are permanently offline are probably not at risk due to the +no longer trusted Administrator Node because they are inaccessible to it. + +**12.2.4.2. Anchor CAT** + +Any Node advertising as a Joint Fabric Anchor SHALL contain the Anchor CAT in its NOC. A NOC +containing the Anchor CAT SHALL be issued only by the Joint Fabric Anchor ICAC. + +``` +Page 1060 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Any client that discovers a Anchor Node with DNS-SD and connects to the Node via CASE SHALL +check if the Anchor CAT or the Anchor/Datastore CAT is present in the NOC of the Node and the NOC +chains up to the Anchor ICAC. + +If the Node also has the role of a Datastore then the Anchor/Datastore CAT SHALL be used instead. + +**12.2.4.3. Datastore CAT** + +A NOC containing the Datastore CAT SHALL be issued by any Joint Fabric Administrator. + +Any client that discovers a Datastore Node with DNS-SD and connects to the Node via CASE SHALL +check if the Datastore CAT or the Anchor/Datastore CAT is present in the NOC of the NODE as part of +the CASE handshake. This SHALL be required in order to verify that the Node is authorized to act as +a Datastore in the Joint Fabric. + +If the Node is also a Joint Fabric Anchor then the Anchor/Datastore CAT SHALL be used instead. + +**12.2.4.4. Anchor/Datastore CAT** + +A NOC containing the Anchor/Datastore CAT SHALL be issued only by the Anchor ICAC. + +Any client that discovers an Anchor/Datastore Node with DNS-SD and connects to the Node via +CASE SHALL check the Anchor/Datastore CAT is present in the NOC of the Node as part of the CASE +handshake. This SHALL be required in order to verify that the Node is authorized to act as an +Anchor and Datastore in the Joint Fabric. + +**12.2.5. Joint Commissioning Method (JCM)** + +``` +NOTE Support for Joint Commissioning Method is provisional. +``` +This method SHALL be implemented for Commissioners and Administrators that support Joint Fab­ +ric. Given a pre-existing Matter fabric Fabric A managed by an Ecosystem A with its own adminis­ +trator nodes and commissioner nodes, a Joint Fabric can be created with another Ecosystem B such +that all devices of Ecosystem A and Ecosystem B can communicate using a single operational root of +trust and devices can be added to the new joint fabric by either Ecosystem. + +The joint operation ensures that ICA’s from both Fabric A and Fabric B are signed by the Anchor CA +(the Root CA of the fabric selected to become the Anchor Fabric), establishing a common trust +between all devices of the original Fabric A and Fabric B and all newly added devices to the “Joint +Fabric”. + +The Joint Fabric contains multiple ecosystems whose ICACs are cross-signed by the Anchor CA. +Therefore, all ecosystems participating in the Joint Fabric SHALL use an ICAC to sign NOCs. Signing +NOCs with a Root CA different than the Anchor CA is not permitted in the Joint Fabric. + +The following steps describe JCM. In the figure below, Ecosystem A with Fabric A acts as the Anchor +Fabric and Ecosystem B with Fabric B as joining fabric to create a Joint Fabric between the two +Ecosystems. + +1. Commission an Administrator from the Ecosystem B (Eco B Admin) using either ECM or BCM + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1061 +``` + +``` +triggered by one Commissioner device from Ecosystem A (Eco A Commissioner). When Ecosys­ +tem B Administrator advertises its presence over DNS-SD (as a result of Open Commissioning +Window) it SHALL also advertise the correct JF TXT key. +``` +2. Once ECM or BCM is over, Ecosystem B Administrator SHALL check that the NOC belonging to + Ecosystem A Administrator (responder NOC field of the sigma-2-tbsdata) contains either an + Anchor CAT or an Anchor/Datastore CAT. +3. User Consent must be obtained on Ecosystem B before proceeding with the next steps. +4. Ecosystem B Administrator SHALL use ec-pub-key, pub-key-algo and ec-curve-id of Eco A RCAC + together with Ecosystem A VendorID as input parameters for RCAC based Vendor ID validation. +5. Ecosystem B Administrator SHALL check that the returned certificate is a RCAC (Basic Con­ + straint extension SHALL be marked critical and have the cA field set to TRUE). +6. Ecosystem B Administrator requests an Administrator from Ecosystem A to sign its ICA by + invoking the ICACSR Request command of the Joint Fabric PKI Cluster, as described in ICA Cross + Signing. +7. Ecosystem A Administrator performs the steps in ICA Cross Signing on the request from the + Ecosystem B Administrator. +8. Cross-signed ICAC is returned to Ecosystem B Administrator using ICACSR Response command. +9. Ecosystem B Administrator SHALL use following commands from Node Operational Credentials + cluster to update each node in the Fabric B to join the Joint Fabric: + a.Update TrustedRootCertificates by using AddTrustedRootCertificate +b. Update Node Operational Credentials using AddNOC. Subject DN of the issued NOCs encodes +a matter-fabric-id attribute whose value SHALL be identical with the value of the matter- +fabric-id attribute from the cross-signed ICAC. +c.Remove the old Trusted Root CA Certificate and the associated fabric using the RemoveFab­ +ric command + +Upon successful completion of JCM, all nodes from Fabric B will be part of the Joint Fabric anchored +by the Ecosystem A. + +``` +Page 1062 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 104. Joint Commissioning Steps_ + +**12.2.5.1. Scope of User Consent** + +Before commissioning a Joint Fabric Administrator, the user SHALL be asked for consent to enable +Joint Fabric functionality between ecosystems. Each ecosystem joining the Joint Fabric SHALL inde­ +pendently ask the user for consent. + +**12.2.5.2. Discovery** + +The user SHALL be able to enable JCM through an appropriate interface of the devices on that +ecosystem. For example, a mobile application, a web configuration, or an on-device interface. + +**12.2.5.3. Vendor ID Validation** + +The Joint Fabric requires that the fabrics participating in a Joint Fabric perform mutual Vendor ID +validation so that they can be sure of the authenticity of the Vendor ID being asserted. Vendor ID +validation SHALL be achieved by using the VendorID Validation Procedure. + +**12.2.5.4. ICA Cross Signing** + +As described in the Joint Commissioning Method, an Ecosystem Administrator, different than the +Joint Fabric Anchor Administrator, SHALL have the ability to issue NOCs chaining up to the Anchor +CA. To obtain this ability it SHALL receive an ICAC issued by the Joint Fabric Anchor Administrator. +Cross-signing means that the SubjectPublicKey of the ICAC chaining up to the Anchor CA is identical +to the SubjectPublicKey of the pre-installed ICAC (chaining up to that particular Ecosystem Adminis­ +trator RCAC). + +The Ecosystem Administrator that needs to obtain a cross-signed ICAC SHALL create a Certificate +Signing Request (ICA CSR) as described in PKCS #10: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1063 +``` + +1. ICA CSR SHALL include a signature (see RFC 2986 section 4.2, SignatureAlgorithm) generated + using the Private Key of its pre-installed ICAC. +2. The Public Key associated with the Private Key used to sign the ICA CSR SHALL appear in the + SubjectPublicKey of the ICA CSR. +3. Minimum attributes that SHALL be present are shown in the image below. Note that the subject + DN SHALL encode a matter-fabric-id attribute. The attribute’s value SHALL be identical to the + Fabric ID of the Anchor Fabric. +4. Once the ICA CSR is created it SHALL be sent in a DER-encoded string inside the ICACSR parame­ + ter of the ICACSRRequest command. + +_ICACSR_ + +``` +Certificate Request: +Data: +Version: 1 (0x0) +Subject: 1.3.6.1.4.1.37244.1.5 = Fabric ID of the Anchor Fabric +Subject Public Key Info: +Public Key Algorithm: id-ecPublicKey +Public-Key: (256 bit) +pub: +04:12:3b:90:f5:....... +ASN1 OID: prime256v1 +NIST CURVE: P-256 +Attributes: +Requested Extensions: +Signature Algorithm: ecdsa-with-SHA256 +30:46:02:21:00:95:ff:...... +``` +The ICA cross signing requires a Joint Fabric Anchor Administrator to receive and validate a Certifi­ +cate Signing Request by following these steps: + +1. Check that User Consent has been obtained previously or ask for User Consent. + a.If User Consent is not obtained, error status SHALL be IcaCsrRequestNoUserConsent. +2. Check that the ICA CSR follows the encoding and rules from PKCS #10. + a.Otherwise, error status SHALL be InvalidIcaCsrFormat. +3. Check that the signature can be validated using the Public Key of the ICA CSR. + a.Otherwise, error status SHALL be InvalidIcaCsrSignature. +4. Convert the Subject Public Key Info of the ICA CSR’s to the equivalent Matter certificate TLV val­ + ues by using the specific rules for ec-pub-key, pub-key-algo and ec-curve-id. +5. Perform ICAC based Vendor ID validation using as input parameters the ec-pub-key, pub-key- + algo, ec-curve-id and the Vendor ID associated with the Administrator requesting the ICA CSR + Signing: + +``` +Page 1064 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +a. If the output of the validation is an empty list, error SHALL be FailedDCLVendorIdValidation +b. Check that the DCL returned certificate is an ICAC (Basic Constraints extension SHALL be +marked critical and have the cA field set to FALSE). +i. If not an ICAC, error status SHALL be NotAnIcac. +``` +6. Upon success, ICA’s certificate SHALL be signed by the RCAC of the Joint Fabric Anchor Adminis­ + trator. + a. If signing fails, error status SHALL be IcaCsrSigningFailed. +7. ICAC SHALL be returned in a PEM format inside the ICAC field of the ICACSRResponse com­ + mand. + +If any of the above validation checks fail, the server SHALL immediately respond to the client with +an ICACSRResponse command. The StatusCode SHALL be set to the error status value specified in +the above validation checks. + +**12.2.6. Anchor Administrator Selection** + +The Joint Fabric design allows devices to communicate with one another regardless of which com­ +missioner was used to commission devices. Similarly, devices participating in Joint Fabric can be +removed without impacting the remaining devices. If all devices commissioned using a particular +commissioner are deleted, the devices remaining in the Joint Fabric will typically continue to func­ +tion. + +User SHALL provide consent when an Anchor Administrator is removed and a new Anchor CA is +chosen. In the example below, the Anchor Administrator is removed from the Joint Fabric and the +user has selected a candidate Administrator to be promoted to Anchor Administrator. For clarity, +Joint Fabric Anchor Administrator A is being replaced with the candidate Joint Fabric Administrator +B. + +User consent SHALL be mutual: + +- on Administrator A side, User provides consent that transfer of the Anchor role to Administrator + B is allowed. +- on Administrator B side, User provides consent that receipt of the Anchor role from Administra­ + tor A is allowed. + +Flow for Anchor Transfer is as follows: + +1. Administrator B SHALL: + a. send TransferAnchorRequest to Administrator A to set itself as Joint Fabric Anchor Adminis­ + trator. + b. obtain user consent prior to sending the TransferAnchorRequest command. +2. Administrator A SHALL: + a. check that the NOC used by Administrator B during the CASE session contains an Adminis­ + trator CAT. + b. check that user provided consent that allows the transfer of the Anchor role to a different + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1065 +``` + +``` +Administrator. If not, then TransferAnchorResponse command with StatusCode set to Trans­ +ferAnchorStatusNoUserConsent SHALL be sent and the procedure stopped here. +c.check all the Datastore entries of type DatastoreStatusEntry. If any of these entries has a +value that equals to Pending or to DeletePending then TransferAnchorResponse command +with StatusCode set to TransferAnchorStatusDatastoreBusy SHALL be sent and the proce­ +dure stopped here. +d. put Joint Fabric Datastore in read only state by setting the Datastore StatusEntry to Delete­ +Pending. +e. stop DNS SD advertising of the Administrator, Anchor and Datastore capability inside the JF +TXT key. +f. set BusyAnchorTransfer error status for the ICACSRResponse in case an ICA Cross Signing is +in progress. +``` +3. All other Joint Fabric Administrators SHALL: + a.stop commissioning of any new devices into the Joint Fabric once it detects that Datastore + StatusEntry equals DeletePending. +4. Administrator B SHALL: + a.copy (through attribute read, BDX) Joint Fabric Datastore from Administrator A. +b. set the Datastore StatusEntry to Committed. +c.set the value of the Datastore AnchorNodeId attribute to the value of its Node ID. +d. increase Administrator CAT version. +e. use following commands from Node Operational Credentials cluster on the other Joint Fab­ +ric Administrators: +i. update TrustedRootCertificates by using AddTrustedRootCertificate. +ii.update Node Operational Credentials using AddNOC. NOCs SHALL contain an updated +version of the Administrator CAT. +f. issue itself a new NOC with the updated version of the Anchor/Datastore CAT. +g. set itself as the new Datastore provider and Anchor Administrator by advertising the Admin­ +istrator, Anchor and Datastore capabilities inside the JF TXT key. +h. send TransferAnchorComplete to Administrator A to announce that transition to Anchor +Administrator is complete. +5. All other Joint Fabric Administrators SHALL: + a.subscribe to the new Datastore provider (Administrator B) having discovered the new Datas­ + tore capability via Service Discovery of the JF TXT key. +b. check that the NOC used by the new Datastore provider (Administrator B) during the first +CASE session contains an Anchor/Datastore CAT and that the NOC chains up to the Anchor +ICAC. +c.request ICA Cross Signing from the new Joint Fabric Anchor Administrator discovered via +Service Discovery (Administrator and Anchor flags are set in JF TXT key). +d. remove devices from the fabric governed by the old Anchor CA using the RemoveFabric com­ + +Page 1066 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +``` +mand. +e. start commissioning devices onto the Joint Fabric using the new ICAC for NOC issuance. +``` +**12.2.7. Administrator Removal** + +Since Joint Fabric has multiple Intermediate NOC Certificate Authorities trusted by Joint Fabric +Anchor CA, the following steps SHALL be taken to remove an Intermediate NOC Certificate Author­ +ity from a Joint Fabric. + +The RemoveFabric section outlines a Warning that SHALL apply here for removing a Joint Fabric +Administrator. + +1. Joint Fabric Anchor Administrator SHALL send a RemoveFabric command to a Joint Fabric + Admin that user has consented to remove. +2. Joint Fabric Administrator SHALL remove the outgoing Administrator from the Joint Fabric + Datastore. +3. The outgoing Administrator SHALL remove the given Fabric and **delete all associated fabric-** + **scoped data**. +4. Joint Fabric Anchor Administrator SHALL increase Administrator CAT version and issue itself a + new NOC. +5. Administrator B SHALL set new NOC for all the Joint Fabric Administrators. + +**12.2.7.1. Security Consideration** + +Matter does not currently include any method for a Trusted Root Certificate to revoke an ICAC pre­ +viously issued. Thus, to ensure proper fail proof removal of a Joint Fabric Administrator from a +Joint Fabric, the Anchor Administrator SHOULD trigger a transition to a new Trusted Root Certifi­ +cate as described in the Anchor Administrator Selection section. In this case, the new Anchor can be +run by the same ecosystem as the old Anchor but the new Trusted Root Certificate will not issue an +ICAC to the Joint Fabric Administrator that is to be removed. + +**12.3. User Consent** + +A user who wishes to have an already commissioned Node join another Fabric (and therefore +another Security Domain) provides consent by instructing an existing Administrator, which SHALL +put the Node into commissioning mode by using steps outlined in Section 5.6.4, “Open Commission­ +ing Window”. Administrators SHALL provide a mechanism for the user to thus instruct them. + +**12.4. Administrator-Assisted Commissioning Method** + +Administrators SHALL support opening a commissioning window on a Node using the mandatory +method described in Section 5.6.3, “Enhanced Commissioning Method (ECM)”. All Nodes SHALL +support having a commissioning window opened using the mandatory method described in Section +5.6.3, “Enhanced Commissioning Method (ECM)”. + +An Administrator MAY open a commissioning window on a Node using the optional method + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1067 +``` + +described in Section 5.6.2, “Basic Commissioning Method (BCM)”, if the Node supports the method. + +**12.5. Node Behavior** + +The Node SHALL host an Section 11.19, “Administrator Commissioning Cluster”. The Cluster +exposes commands which enable the entry into commissioning mode for a prescribed time, and +which SHALL be invoked over a CASE secure channel. See Section 11.19.8.1, “OpenCommissioning­ +Window Command” and Section 11.19.8.2, “OpenBasicCommissioningWindow Command”. During +such a commissioning window, the Node SHALL maintain its existing configuration, such as its +operational network connection and identities, and SHOULD allow normal interactions from other +Nodes. + +**12.6. Fabric Synchronization** + +**12.6.1. Introduction** + +The Fabric Synchronization feature enables commissioning of devices from one fabric to another +without requiring user intervention for every device. It defines mechanisms that can be used by +multiple ecosystems/controllers to communicate with one another to simplify the experience for +users. + +The following diagram shows how two ecosystems/controllers would communicate after a single +setup sequence. + +_Figure 105. Example of two synchronized fabrics_ + +**12.6.2. Terminology** + +A component within an ecosystem which supports Fabric Synchronization will be referred to as a +**Fabric Synchronizing Administrator**. This includes the Aggregator and Fabric Administrator +node(s). + +A device which is being synchronized between ecosystems will be referred to as a **Synchronized +Device**. + +``` +Page 1068 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**12.6.3. Fabric Synchronization Composition** + +Fabric Synchronization is present when an Aggregator satisfies the FabricSynchronization condi­ +tion or one or more Bridged Nodes satisfy the FabricSynchronizedNode condition. (See Device +Library, _Aggregator_ and _Bridged Node_ .) + +_Figure 106. Composition of a device supporting Fabric Synchronization._ + +An Aggregator supporting Fabric Synchronization SHALL be composed of the following compo­ +nents. + +**12.6.3.1. Matter Fabric Administrator Node** + +The device providing the Aggregator SHALL be able to commission nodes on its fabric. + +**12.6.3.2. Aggregator Node** + +When Fabric Synchronization is supported, the Aggregator with FabricSynchronization condition +(see Device Library, _Aggregator_ ) SHALL be met on an endpoint with the following endpoints in the +Descriptor cluster PartsList. + +**Commissioner Control Cluster** + +The Commissioner Control Cluster enables another device which supports Fabric Synchronization +to set up a bidirectional synchronization relationship without the user having to scan a QR code or +enter a Manual Pairing Code (as used in ECM flow) for a device. + +Fabric Synchronization SHALL be supported when the SupportedDeviceCategories attribute in the +Commissioner Control Cluster has the FabricSynchronization bit set. + +**Bridged Node Endpoint(s)** + +Every Bridged Node endpoint presented that conforms to the FabricSynchronizedNode condition +(see Device Library, _Bridged Node_ ) represents a device that can be synchronized (A Synchronized +Device). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1069 +``` + +The Bridged Node with FabricSynchronizedNode condition enables the synchronization of devices +between fabrics by the following: + +- The Bridged Node SHALL include the Ecosystem Information Cluster. (Enables discovery and + directory synchronization.) +- The Bridged Node SHALL include the Administrator Commissioning Cluster when the user con­ + sents to share a device. (Enables synchronization of devices between fabrics.) +- The Bridged Node SHOULD support the BridgedICDSupport feature in the Bridged Device Basic + Information Cluster if the Synchronized Device is an Intermittently Connected Device (ICD). + (Enables communication with ICDs.) + +**12.6.4. Preventing Device Duplication** + +A Fabric Synchronizing Administrator SHOULD NOT commission devices onto the same fabric that +they are already on. To avoid this, the Fabric Synchronizing Administrator SHOULD examine the +UniqueID of a potential Synchronized Device’s Bridged Device Basic Information Cluster and +SHOULD examine the VendorID and ProductID fields if they are present in the Bridged Device Basic +Information Cluster. If all of the provided values for UniqueID, ProductID, and VendorID match a +known device that is already on the Fabric Synchronizing Administrator’s fabric, then it SHOULD +NOT attempt to commission the device. + +**12.6.4.1. Missing UniqueID** + +The UniqueID field in the Basic Information Cluster became mandatory after the initial release of +this specification. Therefore, the following must be performed to support devices without +UniqueIDs. + +When a Fabric Synchronizing Administrator commissions a Synchronized Device, it SHALL persist +and maintain an association with the UniqueID in the Bridged Device Basic Information Cluster +exposed by another Fabric Synchronizing Administrator. + +If a Fabric Synchronizing Administrator exposes a Synchronized Device which does not have a +UniqueID in its Basic Information Cluster, then the Fabric Synchronizing Administrator SHALL gen­ +erate and persist a new UniqueID to be used in the Bridged Device Basic Information Cluster. + +**12.6.4.2. Unifying Generated UniqueID** + +When a Fabric Synchronizing Administrator establishes a PASE session to a Synchronized Device +for the purposes of commissioning, the Fabric Synchronizing Administrator SHOULD verify that the +device is not already present on the intended fabric as follows: + +- The Fabric Synchronizing Administrator MAY check if the UniqueID is present in the Basic + Information Cluster. If the UniqueID is present, the Fabric Synchronizing Administrator can + skip the below check. +- If the UniqueID is not present or not checked, the Fabric Synchronizing Administrator SHOULD + check if the intended fabric is already present in the Fabric Table. + ◦ If it is present, the Fabric Synchronizing Administrator SHOULD NOT complete commission­ + ing and SHOULD avoid attempting to commission the device (or establish PASE sessions) in + +``` +Page 1070 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +the future by persisting the UniqueID exposed by the other Fabric Synchronizing Adminis­ +trator’s Bridged Device Basic Information Cluster. (If the Fabric Synchronizing Administra­ +tor exposes the device through a Bridged Node endpoint, then the Fabric Synchronizing +Administrator SHOULD expose the UniqueID through its Bridged Device Basic Information +Cluster.) +◦ If it is not present, the Fabric Synchronizing Administrator MAY continue the commissioning +process. +``` +To avoid the potential for getting stuck in a loop of checking the device and updating UniqueIDs in +the Bridged Device Basic Information Cluster, a caching and tie-breaker policy is required. If a Fab­ +ric Synchronizing Administrator updated its Bridged Device Basic Information Cluster as a result of +a duplication detected when checking the Fabric Table during a PASE session, then it SHOULD per­ +form the following: + +- The Fabric Synchronizing Administrator SHOULD create a cache of prior known UniqueIDs + scoped to the NodeID of the Synchronized Device. The cache SHOULD have space for at least 5 + entries per NodeID. +- If a Fabric Synchronizing Administrator (hereafter denoted A) receives a UniqueID from + another Fabric Synchronizing Administrator’s (hereafter denoted B) Bridged Device Basic Infor­ + mation Cluster that matches an entry in the cache, but is not the entry currently presented in + the Bridged Device Basic Information Cluster of the client Fabric Synchronizing Administrator + (A), then the Fabric Synchronizing Administrator (A) SHOULD set the UniqueID in its Bridged + Device Basic Information Cluster to the value stored in the cache which is lexicographically + smaller than all other entries. + +**12.6.5. Changes to device and locations of Synchronized Devices** + +A fabric administrator typically has information on topology or logical grouping of the Synchro­ +nized Devices, which can be of use to the user when shared with other administrators. + +For example, consider a fabric with 50 lights. If the locations (such as rooms) and device naming +are not present, the user would just see a list of 50 lights on their synchronized controller and +would not know which of those lights would be in which location. + +Typically, the user has some means (e.g. a Manufacturer-provided app) to assign names to the Syn­ +chronized Devices, or names could be assigned automatically by the administrator. Sometimes +these names are written to the Basic Information Cluster on the device, while other times the +administrator does not write these names to the Basic Information Cluster. + +A Fabric Synchronizing Administrator SHOULD expose such names in the Ecosystem Information +Cluster on the associated endpoint. A Fabric Synchronizing Administrator MAY expose such names +in the Basic Information Cluster on the associated endpoint. + +If a Fabric Synchronizing Administrator exposes such names in the Basic Information Cluster for a +Synchronized Device, then the same associated names SHALL be exposed in the Ecosystem Infor­ +mation Cluster. + +Similarly, the user typically has some means to assign and change the location (e.g. room/zone) +names. The grouping MAY also be applied automatically by the administrator. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1071 +``` + +A Fabric Synchronizing Administrator SHOULD expose such grouping using the Ecosystem Informa­ +tion Cluster as described above. + +Nodes that wish to be notified of a change in such a name or location SHOULD monitor changes of +the Ecosystem Information Cluster. + +A Fabric Synchronizing Administrator MAY make it possible (e.g. through a Manufacturer’s app) for +its users to restrict whether all or some of the Ecosystem Information Cluster is exposed to the Fab­ +ric. + +**12.6.6. Changes to the set of Synchronized Devices** + +Matter Devices can be added to or removed from the set of Synchronized Devices through Adminis­ +trator-specific means. For example, the user can use a Manufacturer-provided app to disable syn­ +chronization of specific devices. When an update to the set of synchronized Devices occurs, the Fab­ +ric Synchronizing Administrator SHALL: + +- Update the PartsList attribute on the Descriptor clusters of the Root Node Endpoint and of the + endpoint which holds the Aggregator device type. +- Update the exposed endpoints and their descriptors according to the new set of Synchronized + Devices + +Nodes that wish to be notified of added/removed devices SHOULD monitor changes of the PartsList +attribute in the Descriptor cluster on the Root Node Endpoint and the endpoint which holds the +Aggregator device type. + +Allocation of endpoints for Synchronized Devices SHALL be performed as described in Dynamic +Endpoint allocation. + +**12.6.7. Fabric Synchronized Relationships** + +Each Client ecosystem to a Fabric Synchronizing Administrator (possibly multiple unique clients +per ecosystem) will use the client ecosystem’s fabric to commission the Aggregator. The client +ecosystems will each have their own dedicated, isolated fabric that is separate from the fabric used +by the Aggregator to interact with the Matter devices. + +This relationship can be seen in the overview figure. In that figure, Ecosystem E1 can directly +access all devices and the Aggregator of Ecosystem E2 from Ecosystem E1’s fabric. This is done with­ +out requiring Ecosystem E2 to have any access granted on Ecosystem E1’s fabric. + +**12.6.8. Setup flow for Fabric Synchronization** + +This section will cover generic setup sequences, which ecosystems MAY extend to provide the +desired level of configuration options. + +**12.6.8.1. Fabric Synchronization Mutual Authentication** + +As a precondition to enabling the Fabric Synchronization feature, ecosystems MAY wait until the +complete bi-directional commissioning of both ecosystems has been completed before exposing any + +``` +Page 1072 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Bridged Nodes. At this point, both ecosystems have received the device attestation from the other. + +**12.6.8.2. Scope of User Consent** + +Before or after commissioning a Fabric Synchronizing Administrator, the user SHALL be asked for +consent to enable Fabric Synchronization functionality between ecosystems. This matches the exist­ +ing single-device Administrator-Assisted Commissioning consent model that requires user consent +when Matter devices are shared. + +Each ecosystem SHALL independently ask the user for consent. This can be done before or after +commissioning the device. + +Similar to the Multi-Admin flow, after the share operation has been completed, the second Admin +can now perform additional sharing operations with the device and/or data according to consent +the user has given the second ecosystem. + +**12.6.8.3. Starting Condition** + +For the purpose of demonstrating the setup process, consider two ecosystems that provide Fabric +Synchronization. These may have existing Matter devices commissioned on their independent fab­ +rics. + +_Figure 107. Fabric Synchronization Setup - Example Starting Condition._ + +**12.6.8.4. Enabling Fabric Synchronization Between Two Ecosystems** + +**User Action Summary (Informational)** + +To initiate the setup of Fabric Synchronization, the manufacturer-specific setup SHOULD include +the following steps: + +1. Scan a QR code or enter the Manual Pairing Code of the Commissionee Fabric Synchronizing + Administrator. This is similar to the current Administrator-Assisted Commissioning of Matter + devices. +2. Consent and configure relationships on both ecosystems. (The Commissionee ecosystem MAY + provide a configuration step prior to providing the QR code or Manual Pairing Code.) + +If full bi-directional Fabric Synchronization is enabled, the end result of the setup process will + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1073 +``` + +resemble the Introductory Example. + +**Initiating Discovery** + +The user SHALL be able to enable the administrator-assisted commissioning of an ecosystem’s Fab­ +ric Synchronization feature through an appropriate interface of the devices on that ecosystem. For +example, a mobile application, a web configuration, or an on-device interface. + +The Fabric Synchronizing Administrator that advertises its presence over DNS-SD will be desig­ +nated the Commissionee. The Fabric Synchronizing Administrator that performs service discovery +will be designated the Commissioner. + +The Commissionee SHALL provide the user with Manual Pairing Code and MAY provide the user +with a QR code to initiate commissioning of the Commissionee by the Commissioner. + +**Discovery** + +The Commissionee SHALL advertise its presence over DNS-SD (see Section 5.4.2.7, “Using Existing +IP-bearing Network” and Commissionable Node Discovery.) + +A Commissioner MAY discover the Commissionee device and provide the user with a notification +prior to additional user action. + +_Figure 108. Fabric Synchronization Setup - Commissioner Relationship Established._ + +**Forward Commissioning** + +The user SHALL then be able to initiate commissioning on another administrator with the Fabric +Synchronization feature using the provided QR code or manual pairing code from the Commis­ +sioner. + +The Commissioner SHALL commission the Commissionee using the steps outlined in the Concur­ +rent connection commissioning flow. + +After commissioning is complete, the Commissionee Fabric Synchronizing Administrator’s Aggrega­ +tor will now be accessible on the Fabric administrated by the Commissioner. + +``` +Page 1074 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 109. Fabric Synchronization Setup - Forward Commissioning Complete._ + +**Reverse Commissioning** + +After the Commissioner has finished commissioning the Commissionee, the Commissioner SHOULD +initiate Reverse Commissioning using the Commissioner Control Cluster. + +### NOTE + +``` +A Commissionee Fabric Synchronizing Administrator MAY choose to require +reverse commissioning before enabling Fabric Synchronization. +``` +_Figure 110. Fabric Synchronization Setup - Reverse Commissioning Complete._ + +**Fabric Synchronization Configuration** + +After or before commissioning (and optionally Reverse Commissioning,) the device-appropriate +interfaces for the Fabric Synchronization feature SHALL ask the user for consent to synchronize +devices between fabrics according to Scope Of User Consent. + +The following are example configurable options: + +- The Fabric Synchronization feature MAY ask the user for consent for all Synchronized Devices + or consent for smaller subsets independently. +- The Fabric Synchronization feature MAY ask the user for consent to perform this operation + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1075 +``` + +``` +automatically when new Synchronized Devices are commissioned. +``` +- The Fabric Synchronization feature MAY ask the user for consent to share Synchronized Device + metadata such as device names and locations. + +**Fabric Synchronization** + +Once commissioning and configuration are complete, the ecosystems are now ready to synchronize +their fabrics. + +The Fabric Synchronizing Administrator SHALL commission the synchronized devices as config­ +ured by the user. + +Commissioning of Matter devices SHALL be performed by: + +1. Discover available Synchronized Devices to commission by identifying endpoints specified in + the PartsList of the Aggregator within the Fabric Synchronizing Administrator. +2. Identify if the Synchronized Device supports the BridgedICDSupport feature in the Bridged + Device Basic Information Cluster by presence of the BridgedICDSupport feature. + a.If the BridgedICDSupport feature is present, the client MAY use the BridgedICDSupport fea­ + ture to ensure the device is active. +3. Initiate commissioning by sending an Open Commissioning Window command to the Adminis­ + trator Commissioning Cluster exposed on the endpoint with the Bridged Node device type speci­ + fied in the PartsList and the Administrator Commissioning Cluster present. +4. Complete commissioning using the Enhanced Commissioning Method. + +_Figure 111. Fabric Synchronization Setup - Setup Complete._ + +**Device Interaction Summary** + +The below sequence diagram summarizes the interactions between the Fabric Synchronizing +Administrator described in the steps above. + +``` +Page 1076 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 112. Fabric Synchronization Setup - Example Complete Flow._ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1077 +``` + +Page 1078 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 13. Security Requirements** + +**13.1. Overview** + +Each Matter security and privacy requirement references the underlying countermeasure (CM) and +threat (T) in the Threat Model that motivated the need for the requirement. The requirements are +grouped by topic. Unless stated otherwise, these requirements typically address all Devices and +Nodes (i.e. all implementations of Matter functionality). Some requirements are called out specifi­ +cally for a particular group of implementations, or Roles. + +**13.2. Device vs. Node** + +For some requirements, we need to differentiate between a Node (the entity which supports the +Matter protocol stack) and a Device (a piece of equipment containing one or more Nodes). + +- If the Node contains all of the Matter functionality, nevertheless it will probably rely on some + security features of the Device. +- If the Node uses Matter functionality provided by the Device, the requirements obviously hold + for both the Node and the Device. + +**13.3. Commissioning** + +``` +a. Nodes SHALL stop both commissioning and unsecured rendezvous actions after a specified time +period from the beginning of the commissioning mode when commissioning has not been con­ +cluded, unless allowed for other purposes such as Commissionable Node Discovery. The time +period for commissioning and unsecured rendezvous announcements SHALL follow require­ +ments as specified in Section 5.5, “Commissioning Flows” and Section 5.4.2.3, “Announcement +Duration” respectively. [CM8 for T5, T7] +b. Nodes SHALL utilize multiple hash iterations in PBKDF, as required by definitions in Section 3.9, +“Password-Based Key Derivation Function (PBKDF)”. Nodes SHALL validate the bounds of the +iteration count for PBKDF, to respect the minimum and maximum values stated in the cryptog­ +raphy primitives section (see Section 3.9, “Password-Based Key Derivation Function (PBKDF)”). +[CM99 in T102] +c. Nodes SHALL exit commissioning mode after 20 failed commission attempts (see Section 5.5, +“Commissioning Flows”). [CM100 for T101, T112] +d. Devices SHALL include a Device Attestation Certificate and private key, unique to that Device. +[CM23 for T22, T24, T34, T86] +e. When the setup code is not permanently attached to a device, for example, it is removable or +only found in the device setup guide, the device SHALL NOT deliver the Onboarding Payload +using an NFC tag [CM4 for T90]. +f. If an NFC Tag is used to convey the Onboarding Payload from a device to a Commissioner, +depending on how the NFC tag is associated with the device (e.g. device package, attached to the +device, connected to the device...), the NFC Tag SHALL only allow the alteration of the Onboard­ +ing Payload and the reading thereof in ways and in device states attackers cannot exploit to illic­ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1079 +``` + +``` +itly onboard the device (e.g., the alteration of the NFC Tag Onboarding Payload SHALL only be +possible while being manufactured, the NFC tag read-out SHALL NOT be possible when the +device is still in the packaging, the NFC Tag read-out SHALL only be allowed during the enabled +commissioning window). [CM4 for T90] +g. After initial Commissioning of a Device, subsequent Commissioning SHALL only be triggered by +an Administrator or an equivalent entity where the user gives administrative consent. [CM2 for +T1] +``` +**13.4. Factory Reset** + +``` +a.Devices and Nodes SHALL have a factory reset capability. [CM15 for T16, T17, T79, T82] +b. Factory reset SHALL remove from the Node all security- and privacy-related data and key mate­ +rial created during or after commissioning except data explicitly required to persist across +resets. [CM35 for T16, T17, T79, T82] +``` +See the following sections for detailed factory reset requirements. + +- Section 6.4.3, “Node Operational Identifier Composition” +- Section 6.4.11, “Security Considerations” +- Section 6.6.3, “Access Control List Examples” +- Section 7.12.1, “Persistence” +- Section 7.14, “Event” +- Section 11.12, “General Diagnostics Cluster” +- Section 11.20.4.2, “Image Verification” +- NOCs +- Fabrics +- CommissionedFabrics +- TrustedRootCertificates + +**13.5. Firmware** + +``` +a.Nodes SHALL support OTA firmware updates, either using Matter-provided means (see Section +11.20, “Over-the-Air (OTA) Software Update”) or proprietary means. [CM58 for T59, T226] +b. Nodes SHALL validate the authenticity and integrity of the firmware prior to installation, such +as through cryptographic means (see Section 11.20.4.2, “Image Verification”). [CM58 for T59, +T226] +c.Nodes SHOULD validate configuration and input for length, and acceptable values and ranges +before applying them. This validation is dependent on the configuration or input being applied +(see Section 9.10, “Access Control Cluster”). Configuration and input validation is explicitly +defined in relevant sections of the specification. [CM46 for T55] +``` +``` +Page 1080 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**13.6. Security Best Practices** + +This section describes best practices that Matter implementors SHOULD implement. Matter imple­ +menters SHALL indicate whether they comply or not to the best practices. Matter certification will +not itself test that these requirements have been met. + +**13.6.1. Cryptography** + +``` +a. Devices and Nodes SHOULD include protection (if it exists) against known remote attacks that +can be used to extract or infer cryptographic key material. [CM107 for T94] +b. Devices SHOULD protect the confidentiality of attestation (DAC) private keys. The level and +nature of protection for these keys may vary depending on the nature of the Device. [CM77 for +T22] +c. Nodes SHOULD protect the confidentiality of Node Operational Private Keys. The level and +nature of protection for these keys may vary depending on the nature of the Nodes. [CM87 for +T87, T110, T120] +d. Cryptographic keys SHALL be randomly chosen using a cryptographically secure random num­ +ber generator in accordance with algorithms defined in Section 3.1, “Deterministic Random Bit +Generator (DRBG)”. [CM39 for T39] +e. Devices SHALL use non-repeating initialization vectors for a given session key. [CM78 for T81] +``` +**13.6.2. Commissioning and Administration** + +``` +a. Manufacturers SHOULD control the number of DACs issued under their Vendor ID. [CM24 for +T23, T34] +b. Where practical, the setup code SHOULD NOT be photograph-able or visible when installed (e.g., +QR code hidden with a flap). [CM89 for T90] +c. Uncommissioned Devices SHOULD only be available to be commissioned with some form of +physical proximity user interaction (e.g. power cycle or button press). [CM3 for T15, T90, T92] +d. For Devices subject to physical tampering (e.g. doorbell, camera, door lock, devices designed for +outdoor use cases), the physical interaction to initiate commissioning and/or the setup code (QR +code, NFC Tag or Manual code) SHOULD NOT be accessible to a physical attacker. E.g. setup code +is removable or not on the device, the button used to initiate commissioning for the lock is +inside the house. [CM4 for T3, T84] +e. A Commissioner or Administrator SHOULD only add Root Certificates that it trusts to a Node. +[CM36 for T153] +f. A device manufacturer SHOULD implement Basic Commissioning Method only for devices that +adequately secure the Passcode. [CM154 for T173] +g. Commissioners and Administrators SHOULD carefully control which Nodes get Administer, +Manage, or Operate privilege, especially for safety-critical systems like Door Locks and Smoke +CO Alarms. [CM244 for T17, T20, T59, T94, T230] +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1081 +``` + +**13.6.3. Firmware** + +``` +a.Vendors of Matter implementations (including their suppliers of Matter functionality) SHOULD +have a public vulnerability reporting mechanism and policy and actively monitor, identify and +rectify in a timely manner security vulnerabilities throughout the publicly stated security life- +cycle policy of the product. Typical responsible disclosure guidelines allow vendors from 60 to +120 days to patch a vulnerability, but the implementation of such a program is at each vendor’s +discretion. [CM59 for T9, T226] +b. Devices SHOULD have a verified boot based in an immutable root of trust to verify the authen­ +ticity of firmware. Commissioners SHOULD only be loaded on a computing platform that has +such a verified boot. If devices cannot support verified boot, devices SHOULD perform verifica­ +tion on any firmware update before applying the new firmware. [CM22 for T16, T20, T226] +c.The private part of the code signing key (used to sign firmware) SHOULD be strongly protected +against disclosure or misuse. For example, it could be stored in an HSM on a secure server out­ +side the factory with very restricted access to only a small number of Device Manufacturer +employees. [CM28 for T72] +``` +**13.6.4. Manufacturing** + +``` +a.Fusing of Devices in production SHOULD be done to limit unintended access to hardware com­ +ponents. For example, vendors may disable debug interfaces, and program trust anchors for +secure boot. There are multiple options to secure fusing on the factory floor (e.g., physically +securing the fusing station, pre-fusing the silicon, etc). [CM113 for T117] +``` +**13.6.5. Resiliency** + +``` +a.Matter implementations SHOULD implement resiliency features (e.g., responding to secure boot +failures with recovery or error signaling mode) to detect and handle compromise. [CM57 for +T59, T226] +``` +**13.6.6. Battery Powered Devices** + +``` +a.Battery powered Devices SHOULD respond to excessive queries by rate limiting (even limiting +the rate to zero if desired). [CM51 for T52, T53] +``` +**13.6.7. Tamper Resistance** + +``` +a.Protection against physical attacks (especially those that impact cybersecurity) MAY be needed +for some Devices, as determined by the manufacturer. [CM62 for T60] +``` +**13.6.8. Bridging** + +``` +a.Admins SHOULD only grant privileges to a Bridge or Bridged Device (sending commands from +that Bridged Device towards a Matter node) that the User is comfortable implicitly granting to +all other Bridged Devices exposed by that Bridge. Background: Matter’s ACL mechanism does +not provide a way to grant privileges to only a single endpoint (Bridged Device) from a node +(the Bridge). [CM149 for T162, T165, and T167] +``` +``` +Page 1082 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**13.6.9. Distributed Compliance Ledger** + +``` +a. Vendors SHOULD avail themselves of the DCL store-and-forward functionality so that they can +control posting of data about their products to the DCL. [CM160 for T170] +b. Access to Validator Nodes SHOULD be restricted (e.g., with VPN that only permits Validator +Nodes, Observer Nodes, and authenticated clients with write access). [CM163 for T169, T177, +T180, T183, T186] +c. Vendors SHOULD run and use their own Observer Nodes and restrict access to it to make sure +that it stays available to the vendors' DCL clients. [CM166 for T180, T182] +d. Vendors SHOULD protect DCL private keys in Hardware Security Module (HSM) equipped +servers. [CM167 for T168, T186] +e. All parameters passed in transactions and queries to the DCL SHALL pass input validation +checks done by the implementation of the DCL. [CM169 for T185] +``` +**13.6.10. Safety** + +``` +a. Safety-relevant Devices SHOULD revert to a safe state before performing operations that will +result in an outage (e.g., restart or firmware update) and, if possible, when an outage is +detected. Safety-relevant Devices are Devices whose operation may have a safety or physical +impact. The definitions of "safety-relevant" and "safe state" may vary depending on the kind of +Device and on that Device’s usage. [CM263 for T249] +b. Vendors SHOULD implement controls to ensure that safety-relevant Devices remain safe and +can enter a failsafe state. Any settings that could lead to a safety or physical impact and which +can be modified via Matter clusters, SHOULD be vetted and ignored if outside safe limits. For +example, maximum temperature of Water Heaters should remain at factory setting and never +change during the lifetime of the device. [CM269 for T55] +c. Energy Management SHOULD NOT make automated decisions based on unauthenticated data. +When using such data, it should treat it as advisory only. Examples include weather data that is +pulled in from online resources or tariff and grid event data provided by Utilities. [CM254 to +T239] +``` +**13.7. Threats and Countermeasures** + +This section lists identified threats to Matter and countermeasures to mitigate those threats. This +section is meant to be informational and not as normative requirements. + +Table 103, “Threats” describes the threats, the agent involved in the threat as well as evaluates the +consequences. This includes the severity, impact and likelihood of the threat being exploited. + +_Table 103. Threats_ + +``` +Threat Description Threat Evaluation Counter­ +measure +ID Description Threat Agent Impact/Consequence Severity ID +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1083 +``` + +``` +Threat Description Threat Evaluation Counter­ +measure +T1 Commission an +already Commis­ +sioned Node for +control that may +be difficult to +detect (e.g., IP +Camera to stream +video) +``` +``` +Malicious house +guest (brief physi­ +cal access). +``` +``` +Silent control of Node +and access to sensitive +Node data (e.g. IP Cam­ +era traffic). If only 1 +commissioning is +allowed, user would +detect issue later +if/when they try to use +Node. +``` +``` +High CM2 +``` +``` +T3 Reset Device and +Commission for +silent control (e.g. +IP Camera to +stream video). +``` +``` +Malicious house +guest (brief physi­ +cal access). +``` +``` +Silent control of Node +and access to sensitive +Node data (e.g. IP Cam­ +era traffic). If only 1 +commissioning is +allowed, user would +detect issue later +if/when they try to use +Node. +``` +``` +High CM4 +``` +``` +T5 IoT device adver­ +tises information +that can be used to +identify vulnera­ +bilities. +``` +``` +Malicious device +or person with +local network +access. +``` +``` +Use information about +the Device to exploit a +(known) vulnerability. +``` +``` +High CM6, CM7, +CM8 +``` +``` +T7 IoT device adver­ +tises information +that can be used to +identify, profile, or +target a home or a +user. +``` +``` +Malicious device +or person with +local network +access. +``` +``` +Use information about +available accessories to +target a given home or +user (e.g. to rob). +``` +``` +Medium CM6, CM7, +CM8, +CM183 +``` +``` +T9 Exploit vulnerabil­ +ity in the Device to +gain arbitrary con­ +trol over Device. +``` +``` +Any. Unexpected control of +Device to gain access to +home data, instill fear, +etc. +``` +``` +High CM21, +CM22, +CM57, +CM58, +CM59, +CM110, +CM112, +CM259 +T15 Commission an +uncommissioned +Node without +physical access to +Device +``` +``` +Malicious neigh­ +bor or other +nearby active +attacker +``` +``` +Silent control of Node +and access to sensitive +Node data (e.g. IP Cam­ +era traffic). +``` +``` +High CM3 +``` +Page 1084 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Threat Description Threat Evaluation Counter­ +measure** + +T16 Seller of an Device +(most likely a used +one) intentionally +leaves malicious +software or config­ +uration on the +Device to compro­ +mise future traffic. + +``` +Malicious Device +seller. +``` +``` +Control or access sensi­ +tive data of Device. +``` +``` +Medium CM15, +CM16, +CM17, +CM21, +CM22, +CM35 +``` +T17 Device buyer or +trash picker +dumps memory to +find previous +owner’s Device +keys, group keys, +and network cre­ +dentials. + +``` +Malicious Device +buyer or trash +picker. +``` +``` +Access to sensitive data +and ability to inject +trusted data or even +commands. +``` +``` +Medium CM15, +CM16, +CM17, +CM35, +CM244 +``` +T20 Firmware (any +software on +Device that can be +modified) is modi­ +fied by attacker in +factory (or +remotely through +factory) + +``` +Worker at factory +or programming +location or remote +attacker +``` +1. Local network +behavior issues +2. Infected Nodes lead­ +ing to data breach, mal­ +function, denial of ser­ +vice, or attacks by this +Node on other Nodes + +``` +Medium CM21, +CM22, +CM244 +``` +T22 Cloned Device pro­ +duced (with identi­ +cal credentials to a +proper Device). + +``` +Anyone with phys­ +ical access to a +Device from which +they can extract +Device Attestation +credentials. +``` +1. Brand damage if +Device is of lower qual­ +ity. +2. Loss of revenue. +3. Lack of function or +interoperability if +Device does not func­ +tion properly. +4. Lack of security if +Device does not have +proper security mea­ +sures. +5. Lack of support from +manufacturer for +cloned Devices. + +``` +Medium CM23, +CM77 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1085 +``` + +``` +Threat Description Threat Evaluation Counter­ +measure +T23 Counterfeit Device +produced (with +unique but appar­ +ently authorized +credentials) +``` +``` +Worker at factory +or programming +location +``` +1. Brand damage if +Device is of lower qual­ +ity. +2. Loss of revenue. +3. Lack of function or +interoperability if +Device does not func­ +tion properly. +4. Lack of security if +Device does not have +proper security mea­ +sures. +5. Lack of support from +manufacturer for +cloned Devices. + +``` +Medium CM24 +``` +``` +T24 Factory provi­ +sioned keys cap­ +tured in factory, +transit, or store +(e.g., with fault +injection or other +tampering). +``` +1. Worker in sup­ +ply chain. +2. Attacker who +goes to retail store + +``` +Control of Device and +access to sensitive +Device data (e.g. IP +Camera traffic). +``` +``` +Medium CM23, +CM113 +``` +``` +T34 Cloned Device +enters the net­ +work. +``` +``` +Manufacturer sell­ +ing cloned +Devices. +``` +``` +Loss of revenue or +brand issues for origi­ +nal manufacturer. +``` +``` +Low CM23, +CM24 +``` +``` +T39 Guessing security +keys via brute +force attack. +``` +``` +Attacker within +radio range, cap­ +tures encrypted +network packets. +``` +``` +Control or access sensi­ +tive data of Device. +Even control entire net­ +work if the private key +for the Operational Cer­ +tificate of a Controller +can be guessed. +``` +``` +High CM39 +``` +``` +T52 Malicious Device +off the network +causes battery +powered Device to +wake too often. +``` +``` +Attacker using a +Device on the net­ +work. +``` +``` +Shortened battery life +of nearby Devices. +``` +``` +Medium CM44, +CM51 +``` +Page 1086 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Threat Description Threat Evaluation Counter­ +measure** + +T53 Malicious Device +off the network +interrupts battery +powered messages +too often and +greatly reduces +battery life. + +``` +Attacker using a +Device on the net­ +work. +``` +``` +Shortened battery life +of nearby Devices. +``` +``` +Medium CM44, +CM51 +``` +T55 Device reconfig­ +ured improperly. + +``` +Attacker using a +Device on the net­ +work. +``` +``` +Device could be config­ +ured such that it does +not properly behave. +``` +``` +Medium CM45, +CM46, +CM47, +CM269 +``` +T59 Maliciously +crafted message +exploits Device +vulnerability, +causing Device +compromise. + +``` +Attacker using a +Device on the net­ +work. +``` +``` +Trusted Device could +be hijacked. +``` +``` +High CM57, +CM58, +CM244 +``` +T60 Physical tamper­ +ing with Device +permits compro­ +mise. + +``` +Attacker with +physical access to +Device. +``` +``` +Trusted Device could +be hijacked. +``` +``` +Medium CM62 +``` +T72 Code signing key +copied, permitting +signing of unau­ +thorized code. + +``` +Attacker gets +administrative +access to code +signing server. +``` +1. Bad images could be +installed on many +Devices +2. Devices could be +destroyed or hijacked, +even invisibly and +irreparably. + +``` +High CM28 +``` +T79 Device marked for +destruction reused +in network. + +``` +Installer or return +agent. +``` +``` +Damaged or obsolete +Devices may re-enter +the network. +``` +``` +Low CM15, +CM16, +CM20, +CM35 +``` +T81 Attacker uses pre­ +dictable Initializa­ +tion Vectors to +derive crypto keys. + +``` +Attacker able to +observe network +traffic from the +Device. +``` +``` +Attacker discovery of +Device crypto keys and +other secrets, which +can lead to control of +other Devices if the +Device has such privi­ +leges. +``` +``` +High CM78 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1087 +``` + +``` +Threat Description Threat Evaluation Counter­ +measure +T82 Device buyer +dumps memory to +find previous +owner’s user data. +``` +``` +Malicious Device +buyer or dumpster +diver. +``` +``` +User data may be +leaked. +``` +``` +Medium CM15, +CM35 +``` +``` +T84 Person with physi­ +cal access to +already installed +Device resets +Device then scans +QR code to gain +access. +``` +``` +Attacker with +physical access to +Device. +``` +``` +Control of Device and +access to sensitive +Device data (e.g. IP +Camera traffic). +``` +``` +Medium CM4 +``` +``` +T86 Leak certificate or +Device identity +private key to +appear as valid +Device. +``` +``` +Physical or locally +compromised +attacker. +``` +``` +Device appears as valid +Device. +``` +``` +Low CM23 +``` +``` +T87 Malicious Device +or party poses as +valid Matter Node +using operational +credentials +``` +``` +Attacker on the +local network or +remotely control­ +ling a Node on the +local network +``` +``` +Group keys and sensi­ +tive data revealed to an +invalid Node +``` +``` +Medium CM87 +``` +``` +T90 Long range cam­ +era captures QR +code at Commis­ +sioning time or +otherwise. +``` +``` +Malicious neigh­ +bor, robber, or +other nearby +active attacker. +``` +``` +Attacker manages to +connect Device to their +gateway or account. +``` +``` +Medium CM3, +CM89 +``` +``` +T92 Microphone in the +house can capture +person speaking +the setup code and +use that to MITM +Commissioning. +``` +``` +Malicious neigh­ +bor, robber, or +other nearby +active attacker +``` +``` +Attacker manages to +connect the Node to +their gateway or +account +``` +``` +Medium CM3 +``` +``` +T94 Remote attack +used to extract +keys and other +secrets. +``` +``` +Attacker able to +access the Device +remotely or over +local network. +``` +``` +Attacker discovery of +Device crypto keys and +other secrets, which +can lead to control of +other Devices if the +Device has such privi­ +leges. +``` +``` +High CM107, +CM244 +``` +Page 1088 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Threat Description Threat Evaluation Counter­ +measure** + +T101 Malicious Device +or person with +local network +access attempts to +guess setup code +via online brute +force attack. + +``` +Attacker on the +local network. +``` +``` +Control of Device and +access to sensitive +Device data (e.g. IP +Camera traffic). +``` +``` +High CM5, +CM100 +``` +T102 Malicious Device +or person with +knowledge of +passcode verifier +uses offline brute +force attack to +derive setup code. + +``` +Attacker with +remote access. +``` +``` +Control of Device and +access to sensitive +Device data (e.g. IP +Camera traffic). +``` +``` +High CM5, +CM99 +``` +T110 Malicious device +or party poses as +valid Matter +Administrative +Node using opera­ +tional credentials + +``` +Attacker on the +local network or +remotely control­ +ling a Node on the +local network +``` +``` +Control of Node and +access to sensitive Node +data (e.g., IP camera +traffic) +``` +``` +High CM87 +``` +T112 Malicious +Device(s) or per­ +son(s) with local +network access +attempts to guess +setup code of +many Devices via +online brute force +attack. + +``` +Attackers on the +local network. +``` +``` +Control of Device and +access to sensitive +Device data (e.g. IP +Camera traffic). +``` +``` +Medium CM5, +CM100 +``` +T117 Incorrect fusing of +production +Devices. + +``` +Contract manufac­ +turer, factory +worker. +``` +``` +Device assets are vul­ +nerable, security poli­ +cies including secure +boot might not be +enforceable, etc. +``` +``` +High CM113 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1089 +``` + +``` +Threat Description Threat Evaluation Counter­ +measure +T120 Data from Matter +Nodes is shared +with non-Matter +or unauthorized +entities (e.g. data +leakage to adja­ +cent non-Matter +Nodes) +``` +``` +Any adversarial +process running in +the node that has +enough privileges +to modify ACLs. +Secure boot is not +sufficient protec­ +tion if the device +boots rarely and +the malicious +process was +spawned post-boot +up. +``` +``` +Matter data may be +used in inappropriate +or unauthorized ways +potentially harming the +owner. +``` +``` +High CM87 +``` +``` +T153 Commis­ +sioner/Administra­ +tor adds untrust­ +worthy Root CA to +Node. +``` +``` +Malicious, com­ +promised, or +poorly advised +Commis­ +sioner/Administra­ +tor. +``` +``` +Attacker can create +NOCs that enable +impersonation and +MITM of Secure Chan­ +nels. +``` +``` +High CM36 +``` +``` +T162 Compromise of +Bridged Device. +Bridged device +can have lower +security than Mat­ +ter device. +(Applicable to +bridged devices +controlling Matter +device or exposing +data to Matter +devices. Not +applicable to +bridged devices +being controlled +from Matter +devices.) +``` +``` +Attacker who can +compromise a +bridged device. +``` +``` +Control of Matter-side +Devices and access to +sensitive Device data. +Control Camera, unlock +door. +``` +``` +High CM149 +``` +Page 1090 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Threat Description Threat Evaluation Counter­ +measure** + +T165 Privilege Escala­ +tion. Bridged +device is able to +impersonate +higher privileged +bridged device. +Unlock door on +presence. +(Applicable to +bridged devices +controlling Matter +device or exposing +data to Matter +devices. Not +applicable to +bridged devices +being controlled +from Matter +devices.) + +``` +Attacker that con­ +trols Bridged +Device can use +that device to +impersonate other +Bridged Devices +(potentially ones +that have more +access to the Mat­ +ter network.) +``` +``` +Control of all interac­ +tions between Matter +and bridged devices. +This can include con­ +trol of Matter devices. +``` +``` +High CM149 +``` +T167 Attacker with priv­ +ileges on Bridged +Ecosystem + +``` +Attacker has no +privileges on Mat­ +ter fabrics but +does have privi­ +leges on Bridged +Ecosystems. +``` +``` +Control of all interac­ +tions between Matter +and bridged devices. +This can include con­ +trol of Matter devices. +``` +``` +High CM149 +``` +T168 DCL Private Key +Exfiltration. + +``` +Attacker obtains +one or more pri­ +vate keys of a com­ +pany with DCL +writer privilege. +``` +``` +Attacker can add to the +block chain on behalf +of the company. Can +change the OtaUrl to +point to old and +known-vulnerable +firmware or prevent an +update from being +installed. +``` +``` +High CM163 +``` +T169 DoS/DDoS of Val­ +idators Nodes. + +``` +Attack can direct a +DoS attack or +resource exhaus­ +tion attack against +validators. +Attacker only +needs to DoS 1/3+1 +of validators to +DoS consensus. +``` +``` +New blocks cannot be +added. +``` +``` +High CM163 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1091 +``` + +``` +Threat Description Threat Evaluation Counter­ +measure +T170 Unintended or +premature expo­ +sure of informa­ +tion. +``` +``` +Company or certi­ +fication lab posts +device details to +the chain and it is +validated. +``` +``` +Immutability of block +chain means the infor­ +mation is permanently +on the chain. +``` +``` +High CM160 +``` +``` +T173 Malicious Device +or person with +local network +access and knowl­ +edge of the pass­ +code attempts to +pair with a com­ +missioned device +when someone +else opens the +commissioning +window using Sec­ +tion 5.6.2, “Basic +Commissioning +Method (BCM)” +and the device’s +Passcode. +``` +``` +Attacker on the +local network +``` +``` +Control of Device and +access to sensitive +Device data (e.g. IP +Camera traffic) +``` +``` +Medium CM41, +CM152, +CM154 +``` +``` +T174 Malicious Device +gains knowledge +of the Passcode on +an uncommis­ +sioned Device, +commissions the +Device, and then +puts it back into +commissioning +mode with the +same Passcode +using Section 5.6.2, +“Basic Commis­ +sioning Method +(BCM)” or Section +5.6.3, “Enhanced +Commissioning +Method (ECM)” to +avoid detection. +``` +``` +Attacker on the +local network +``` +``` +Control of Device and +access to sensitive +Device data (e.g. IP +Camera traffic) +``` +``` +Medium CM41, +CM152 +``` +Page 1092 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Threat Description Threat Evaluation Counter­ +measure** + +T175 Malicious Device +with knowledge of +the Passcode com­ +missions an +uncommissioned +Device and then +puts it back into +commissioning +mode with the +same Passcode +using Section 5.6.2, +“Basic Commis­ +sioning Method +(BCM)” or Section +5.6.3, “Enhanced +Commissioning +Method (ECM)” to +avoid detection. + +``` +Attacker on the +local network +``` +``` +Control of Device and +access to sensitive +Device data (e.g. IP +Camera traffic) +``` +``` +Medium CM41, +CM152 +``` +T177 Attacker exploits a +vulnerability that +is common to most +or all of the Valida­ +tor Node software. + +``` +Attacker with +some sort of DCL +access (maybe just +read, which is +open to all). +``` +``` +Many Validator Nodes +misbehave (e.g., +approving adding or +revoking a PAA or +changing an OtaURL). +``` +``` +High CM163 +``` +T180 Attacker accesses +Observer Node or +Validator Node +with unauthenti­ +cated READ CLI +protocol, mounts a +DoS or DDoS +attack. + +``` +Attacker that can +send network +messages to a DCL +Observer Node or +Validator Node. +``` +``` +DCL capacity dimin­ +ished or eliminated. +Unable to communicate +important things like +revocation of PAA. +``` +``` +High CM163, +CM166 +``` +T182 DoS/DDoS of +Observers Nodes. + +``` +Attack can direct a +DoS attack or +resource exhaus­ +tion attack against +Observer Nodes. If +enough Observer +Nodes are +impacted by a DoS +attack, the DCL +may become +unavailable. +``` +``` +DCL unavailable High CM166 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1093 +``` + +``` +Threat Description Threat Evaluation Counter­ +measure +T183 DoS on Trustees' +approval process. +``` +``` +Submit many PRO­ +POSE_ADD_AC­ +COUNT requests. +The Trustees can +be overwhelmed +with illegitimate +requests. Requires +compromise of a +Trustee, although +replay is possible. +``` +``` +Trustees overloaded Medium CM163 +``` +``` +T185 DCL Denial of Ser­ +vice. Attacker +writes a value to +the ledger that is +very large or out +of bounds. +``` +``` +Authorized +attacker sends a +write request with +very large para­ +meter payload. +``` +``` +Very large ledger +blocks added to ledger. +This could cause valida­ +tion problems. DOS on +Observer Nodes if +response is very large. +``` +``` +High CM169 +``` +``` +T186 Test House posts +incorrect informa­ +tion about a ven­ +dor’s product. +``` +``` +Authorized test +house. +``` +``` +False product info in +ledger +``` +``` +High CM163, +CM167 +``` +``` +T226 False information +is provided by a +compromised, vul­ +nerable, or mali­ +cious device. +``` +``` +Attacker that is +able to compro­ +mise an existing +vulnerable device +or introduce a +new malicious +device +``` +``` +Impacts may include +triggering an action +(e.g., unlocking a door +due to a false report of +a person detected in +the home) or tricking +the user into thinking +configuring the wrong +device (e.g., changing +the NodeLabel of a +device to impersonate +another device). +``` +``` +High CM21, +CM22, +CM57, +CM58, +CM59 +``` +``` +T230 Spurious com­ +mands are sent to +a Device, leading +the consumer to +disable it. +``` +``` +Attacker autho­ +rized by ACL to +send commands to +Device. +``` +``` +Consumer frustration +with and distrust of +Device leading con­ +sumer to disable Device +``` +``` +High CM244 +``` +Page 1094 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Threat Description Threat Evaluation Counter­ +measure** + +T231 An attacker +remotely starts a +household appli­ +ance that belongs +to a device type +which may cause +harm without +attended confir­ +mation. + +``` +Attacker that is +able to access the +device remotely +``` +``` +Cause a flood or a fire +or electric overload in a +home +``` +``` +High CM245 +``` +T232 CA or other parties +failing to meet +obligations laid +out in the Certifi­ +cate Policy + +``` +Attacker able to +exploit unad­ +dressed Certificate +Policy rules and/or +absence of techni­ +cal and opera­ +tional controls +associated with +the identity infor­ +mation, key gener­ +ation, distribution, +revocation, and +administration of +certificates +``` +``` +Loss of relying party +trust +``` +``` +High CM24, +CM101, +CM117 +``` +T233 Malicious +PAA/PAI/DAC revo­ +cation request ini­ +tiated by DCL +observer node + +``` +Attacker able to +compromise or +control a DCL +observer node +able to corrupt +revocation infor­ +mation to clients +``` +``` +Illegitimate revocation +information shared to +clients +``` +``` +High CM199 +``` +T234 Malicious pro­ +posal and revoca­ +tion of +PAA/PAI/DAC using +compromised Ven­ +dor’s DCL Account +and its associated +Key + +``` +Attacker able to +compromise or +control a DCL +account and its +associated key +(Vendor, Trustee, +NodeAdmin, Cert­ +Center) able to +propose and/or +revoke certificates +``` +``` +Denial of Service High CM76, +CM167 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1095 +``` + +``` +Threat Description Threat Evaluation Counter­ +measure +T239 Ability to influ­ +ence many devices +with large electric +load in a small +geographic area +could permit an +attack to increase +or decrease load +simultaneously +and impact the +power grid +``` +``` +Influence Energy +Management deci­ +sion making +``` +``` +Damage to power grid High CM254 +``` +``` +T240 Ability to perform +phishing exploits +using a compro­ +mised Commis­ +sionee Device or +Video content +sharing App +``` +``` +Client uses Screen +Sharing and Mes­ +saging feature to +trick the customer +into thinking a +message comes +from a different +source. User +responds thinking +this is the TV or +Content App ask­ +ing +``` +``` +Loss of relying party +trust. Display of false +information, including +malicious instructions +``` +``` +High CM248 +``` +``` +T241 Exposure of data +in transit using +MITM, remote +code execution +and adversary lat­ +eral movement +exploiting WebRTC +communication +protocol +``` +``` +Some clusters uti­ +lize WebRTC. By +default, the +WebRTC commu­ +nication is poten­ +tially vulnerable +to eavesdropping +and MITM +``` +``` +Denial of Service High CM249 +``` +Page 1096 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Threat Description Threat Evaluation Counter­ +measure** + +T242 Lack of traceabil­ +ity and identifica­ +tion of Commis­ +sionees (Video +content sharing +apps) temporarily +using the TV for +Video content- +sharing + +``` +Airbnb/Hoteling +scenario - Renter +commissions a +device as a mes­ +sage source using +the on-screen flow. +Homeowner +returns and does +not know which +actual device is +sending messages +to their TV. Maybe +the device is hid­ +den in a closet +``` +``` +Loss of relying party +trust. Display of false +information, including +malicious instructions +``` +``` +High CM248, +CM250 +``` +T243 Lack of mecha­ +nisms to establish +parental control +requirements as +per prevailing +standards and +regional regula­ +tions + +``` +Customer uses +Content Control +feature to set +Parental Controls +on TV to limit +access to content +with rating N, +child opens an +app, app allows +child to access +content with rat­ +ing N +``` +``` +Regulatory and compli­ +ance risk - Loss of cus­ +tomer trust or brand +issues for original man­ +ufacturer +``` +``` +High CM251 +``` +T244 Unknown commis­ +sioned node acting +maliciously (ex. +Video content +sharing app from +a client device) + +``` +Unrecognized +NodeId. Adversary +hijacked client or +phone app sends +commands or +eavesdrops on net­ +work traffic - Ex: a +UDC/CDC message +indicating PIN +code dialog is +requested. +Attacker leverages +a hijacked camera +to see PIN code +displayed on TV +screen +``` +``` +Loss of relying party +trust. Display of false +information, including +malicious instructions +``` +``` +High CM248, +CM250, +CM253 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1097 +``` + +``` +Threat Description Threat Evaluation Counter­ +measure +T245 Adversary exploits +TV static passcode +/ PIN feature to +request that the +TV generate and +display a Passcode +``` +``` +TV reuses the +same Passcode +code every time +(no dynamic pass­ +code). Vulnerable +to brute-forcing +SPAKE2 (during +PASE) +``` +``` +Denial of Service High CM252 +``` +``` +T246 Adversary eaves­ +drops on network +traffic and +sees/sends +UDC/CDC messages +exploiting a device +vulnerability that +allows adversary +to use information +for discovering +available apps and +push prompts on +the TV +``` +``` +Attacker uses UDC +to mount a DoS by +continually send­ +ing messages to +the TV to request +commissioning, +allows UDC flow to +partially complete +(performs com­ +missionable node +discovery) and +times out, effec­ +tively blocking any +other client from +using this feature +``` +``` +Denial of Service High CM253 +``` +``` +T249 Attacker triggers +Device outage +while Device is in +an unsafe state +``` +``` +Attacker able to +cause Device out­ +age (e.g., through +Denial of Service) +``` +``` +Attacker can keep +Device in unsafe state +indefinitely, potentially +leading to damage +``` +``` +Medium CM263 +``` +Table 104, “Countermeasures” describes the various countermeasures to the threats listed in Table +103, “Threats”. + +_Table 104. Countermeasures_ + +``` +ID Description +CM2 After initial Commissioning of a Device, subsequent Commissioning can only be +triggered by an Administrator or an equivalent entity where the user gives +administrative consent. +CM3 Commissioning is started with some form of physical user interaction (e.g. power +cycle or button press). +CM4 For Devices subject to physical tampering (e.g. doorbell, camera, door lock, +devices designed for outdoor use cases), the physical interaction to initiate com­ +missioning and/or the setup code is not accessible to a physical attacker. E.g. setup +Passcode is removable or not on the device, the button for the lock is inside the +house. +``` +``` +Page 1098 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**ID Description** + +CM5 All Devices include a randomly generated setup passcode and a corresponding +passcode verifier derived from the setup passcode via a PBKDF. The setup code +includes at least 27 bits of entropy compliant with a recognized standard (e.g., +NIST SP 800-90B). + +CM6 Unsecured rendezvous are enabled by a user action and, upon time-out or com­ +missioning failure, will cause deletion of any state information. Examples of "user +actions" are pressing a physical button, power-cycling a Device, and leveraging a +previously commissioned account. + +CM7 Minimize OS and other version information advertised during discovery. + +CM8 Both commissioning and unsecured rendezvous actions time-out after at most 15 +minutes from the beginning of the commissioning mode when commissioning has +not been concluded. + +CM15 Devices have a physical button or trigger for factory reset. + +CM16 Devices rotate keys at specified triggers (e.g. Factory Device Reset). + +CM17 Devices implement Perfect Forward secrecy key agreement protocols that give +assurances that session keys will not be compromised even if long-term secrets +used in the session key exchange are compromised. + +CM20 Revoke Device credentials and privileges when the Device is removed from the +home. + +CM21 Devices have cryptographically signed firmware, including all firmware and soft­ +ware on the Device. + +CM22 Devices have a verified boot based in an immutable root of trust to verify the +authenticity of firmware. + +CM23 All Devices include a Device Attestation Certificate and private key, unique to that +Device. + +CM24 Manufacturers control the number of DACs issued under their Vendor ID. + +CM28 Private part of code signing key is strongly protected against disclosure or misuse. +For example, it could be stored in an HSM on a secure server outside the factory +with very restricted access to only a small number of Device Manufacturer +employees. + +CM35 Factory reset removes all local data and key material created during or after com­ +missioning except data explicitly required to persist across resets. + +CM36 A Commissioner / Administrator only adds Root Certificates that it trusts to a +node. + +CM39 Cryptographic keys are randomly chosen using the strong entropy separately +required and the cryptographic algorithms and key lengths specified by Matter. + +CM41 Administrators can view the set of Fabrics on each Device (i.e., Attributes for the +Node Operational Credentials Cluster). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1099 +``` + +``` +ID Description +CM44 Administrator responds to reported or detected attacks and malfunctions (e.g., by +adding Devices to a denylist, notifying the user, changing group keys, or hopping +channels). +CM45 Configuration for secure channel protocol is carefully negotiated and validated by +both parties. +CM46 Devices validate configuration and input changes for length, character type, and +acceptable values and ranges before applying them. This validation is dependent +on the configuration or input being applied (e.g. ACL entries). Configuration and +input validation is explicitly defined in relevant sections of the specification. +CM47 Device management service uses a secure communication mechanism for recon­ +figuration. +CM51 Battery powered Devices respond to excessive queries by rate limiting (even limit­ +ing the rate to zero if desired). +CM57 Devices implement resiliency features (e.g., responding to secure boot failures +with recovery or error signaling mode) to detect and handle compromise. +CM58 Devices support OTA firmware updates. Devices validate the authenticity and +integrity of the firmware prior to installation. +CM59 Manufacturers monitor newly discovered vulnerabilities and provide software +updates to address them. +CM62 Protection against physical attacks (especially those that impact cybersecurity) is +needed for some Devices, as determined by the manufacturer. +CM76 All DCL writers constantly watch for DCL changes that relate to them and com­ +plain about them if they are unauthorized. +CM77 All Devices protect the confidentiality of attestation (DAC) private keys. The level +and nature of protection for these keys may vary depending on the nature of the +Device. +CM78 Devices use random initialization vectors. +CM87 All Nodes protect the confidentiality of operational credential private keys. The +level and nature of protection for these keys may vary depending on the nature of +the Nodes. +CM89 The setup code is not photographable (e.g., NFC) or not visible when installed (e.g., +QR code hidden with a flap). +CM99 Devices utilize multiple hashes in PBKDF. +CM100 Device exits commissioning mode after 20 failed commissioning attempts. +CM101 Use PKI best practices for all CAs, including secure backup of private key, use of +an HSM, four eyes principle, etc. These are described in the PKI CP. +CM107 Devices include protection (if it exists) against known remote attacks that can be +used to extract or infer cryptographic key material. +``` +Page 1100 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**ID Description** + +CM110 Devices support remote Firmware attestation with trusted root of measurement +to allow local and cloud agents to validate the cryptographic identity of the Device +firmware and refuse to perform actions on behalf of or by relying to information +acquired by known compromised versions. Firmware attestation is performed at +initial commissioning and when revocation lists get updated. + +CM112 ACLs restrict access granted to Nodes. + +CM113 Fusing of Production Devices is done correctly. For example, disabling debug +interfaces, and programming trust anchors for secure boot. There are multiple +options to secure fusing on the factory floor (e.g., physically securing the fusing +station, pre-fusing the silicon, etc). + +CM117 Design, implement, and operate the PAI and associated infrastructure so that +unauthorized Devices cannot be created with proper credentials. + +CM149 Administrators only grant privileges to a Bridge if the Administrator is comfort­ +able granting those same privileges to all Bridged Devices behind that Bridge. + +CM152 Device manufacturers provide a way to secure a static Passcode after initial com­ +missioning so that it is not available for unauthorized agents. + +CM154 A device manufacturer implements Section 5.6.2, “Basic Commissioning Method +(BCM)” only for devices that adequately secure the Passcode. + +CM160 Vendors sign off on some other entity posting data about their products to the +DCL. + +CM163 Tightly restrict access to Validator Nodes (e.g., with VPN that only permits Valida­ +tor Nodes, Observer Nodes, and authenticated clients with write access). + +CM166 Matter vendors run and use their own Observer Node and restrict access to it to +make sure that it stays available to that company’s DCL clients. + +CM167 Matter vendors protect DCL private keys in HSM equipped servers. + +CM169 All parameters passed in transactions and queries to the DCL pass input valida­ +tion checks. + +CM183 VID & PID are not advertised before Commissioning. + +CM199 Light client cryptographically verifies responses received from nodes. + +CM244 Commissioners and Administrators carefully control which Nodes get Administer, +Manage, or Operate privilege, especially for safety-critical systems like Door Locks +and Smoke CO Alarms. + +CM245 Device manufacturers consider carefully whether their products that support +remotely starting its operation could do harm to the end user; if so, require some +additional operations (e.g. attended confirmation for remote start). + +CM248 Devices with content launching features require source of content origin and per­ +form verification of origin information and display human-friendly information +before sharing Video content and/or commands to perform sharing of content + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1101 +``` + +``` +ID Description +CM249 The Screen device and content sharing client support implementing the minimum +required WebRTC security requirements as stated in w3c and webrtc-security +WebRTC security requirements (see https://www.w3.org/TR/webrtc/#privacy-and- +security-considerations and https://webrtc-security.github.io) +CM250 The commissioner require utilizing ACL or similar access control mechanisms for +uniquely identifying and controlling access by Video content-sharing clients so +that access control can be managed and revoked without impacting the primary +device admin account +CM251 Devices supporting content control functionality will enforce the required +parental controls specific to the content being shared and inform the user of limi­ +tations of this control, for example, when these settings do not apply to content +provided by Content Apps on the TV +CM252 The Screen device provide access using dynamic passcode or user-defined +passphrase (similar to other casting protocols) with options to reset frequently +CM253 Detect and surface to the user suspicious behavior by unauthenticated network +clients and provide the user with the option to disable any information or func­ +tionality exposed to unauthenticated clients +CM254 Treat unauthenticated data as advisory only +CM259 Include the ability to revoke an Operational Certificate +CM263 Device reverts to safe state before performing unsafe operations and in case of +outage +CM269 Device vets settings that could lead to a safety or physical impact and ignores if +outside safe limits. +``` +Page 1102 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Appendix A: Tag-length-value (TLV)** + +**Encoding Format** + +**A.1. Scope & Purpose** + +The Matter TLV ( _Tag-Length-Value_ ) format is a generalized encoding method for simple structured +data, used throughout this specification. + +Values in the Matter TLV format are encoded as _TLV elements_. Each TLV element has a type. Ele­ +ment types fall into two categories: _primitive types_ and _container types_. Primitive types convey fun­ +damental data values such as integers and strings. Container types convey collections of elements +that themselves are either primitives or containers. The Matter TLV format supports three different +container types: structures, arrays and lists. + +All valid _TLV encodings_ consist of a single top-level element. This value can be either a primitive +type or a container type. + +**A.2. Tags** + +A TLV element includes an optional numeric tag that identifies its purpose. A TLV element without +a tag is called an _anonymous_ element. For elements with tags, two categories of tags are defined: +_profile-specific_ and _context-specific_. + +**A.2.1. Profile-Specific Tags** + +Profile-specific tags identify elements globally. A profile-specific tag is a 64-bit number composed of +the following fields: + +- 16-bit Vendor ID +- 16-bit profile number +- 32-bit tag number + +Profile-specific tags are defined either by Matter or by vendors. Additionally the Matter Common +Profile includes a set of predefined profile-specific tags that can be used across organizations. + +**A.2.2. Context-Specific Tags** + +Context-specific tags identify elements within the context of a containing structure element. A con­ +text-specific tag consists of a single 8-bit tag number. The meaning of a context-specific tag derives +from the structure it resides in, implying that the same tag number may have different meanings in +the context of different structures. Effectively, the interpretation of a context-specific tag depends +on the tag attached to the containing element. Because structures themselves can be assigned con­ +text-specific tags, the interpretation of a context-specific tag may ultimately depend on a nested +chain of such tags. + +Context-specific tags can only be assigned to elements that are immediately within a structure. This + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1103 +``` + +implies that an element with a context-specific tag cannot appear as the outermost element of a TLV +encoding. + +**A.2.3. Anonymous Tags** + +A special "anonymous tag" is used to denote TLV elements that lack a tag value. Such a TLV element +is referred to as an anonymous element. + +**A.2.4. Canonical Ordering of Tags** + +Where a distinguished ordering of tags is required (e.g. for the purposes of generating a hash or +cryptographic signature of elements within a structure), the following ordering rules SHALL be +used: + +- Anonymous tags SHALL be ordered before all other tags. +- Context-specific tags SHALL be ordered before profile-specific tags. +- Context-specific tags with numerically lower tag values SHALL be ordered before those with + higher tag values. +- Profile-specific tags with numerically lower Vendor IDs SHALL be ordered before those with + higher Vendor IDs. +- Profile-specific tags with the same Vendor ID, but numerically lower profile numbers SHALL be + ordered before those with higher profile numbers. +- Profile-specific tags with the same Vendor ID and the same profile numbers but numerically + lower tag numbers SHALL be ordered before those with higher tag numbers. + +The ordering rules SHALL apply to elements at the same level within a container. + +**A.3. Lengths** + +Depending on its type, a TLV element may contain a length field that gives the length, in octets, of +the element’s value field. A length field is only present for string types (character and octet strings). +Other element types either have a predetermined length or are encoded with a marker that identi­ +fies their end. + +**A.4. Primitive Types** + +The Matter TLV format supports the following primitive types: + +- Signed integers +- Unsigned integers +- UTF-8 Strings +- Octet Strings +- Single or double-precision floating point numbers (following IEEE 754-2019) +- Booleans + +``` +Page 1104 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- Nulls + +Of the primitive types, integers, floating point numbers, booleans and nulls have a predetermined +length specified by their type. Octet strings and UTF-8 strings include a length field that gives their +lengths in octets. + +**A.5. Container Types** + +The Matter TLV format supports the following container types: + +- Structures +- Arrays +- Lists + +Each of the container types is a form of element collection that can contain primitive types and/or +other container types. The elements appearing immediately within a container type are called its +_members_. A container type can contain any number of member elements, including none. Con­ +tainer types can be nested to any depth and in any combination. The end of a container type is +denoted by a special element called the ‘end-of-container’ element. Although encoded as a member, +conceptually the end-of-container element is not included in the members of the containing type. + +**A.5.1. Structures** + +A structure is a collection of member elements that each have a distinct meaning. All member ele­ +ments within a structure SHALL have a unique tag as compared to the other members of the struc­ +ture. Member elements without tags (anonymous elements) are not allowed in structures. The +encoded ordering of members in a structure may or may not be important depending on the intent +of the sender or the expectations of the receiver. For example, in some situations, senders and +receivers may agree on a particular ordering of elements to make encoding and decoding easier. + +Where a distinguished ordering of members is required (for example, for the purposes of generat­ +ing a hash or cryptographic signature of the structure), the members of the structure SHALL be +encoded as specified in Section A.2.4, “Canonical Ordering of Tags”. + +**A.5.2. Arrays** + +An array is an ordered collection of member elements that either do not have distinct meanings, or +whose meanings are implied by their encoded positions in the array. An array can contain any type +of element, including other arrays. All member elements of an array SHALL be anonymous ele­ +ments – that is, they SHALL be encoded with an anonymous tag. + +**A.5.3. Lists** + +A list is an ordered collection of member elements, each of which may be encoded with a tag. The +meanings of member elements in a list are denoted by their position within the list in conjunction +with any associated tag value they may have. + +A list can contain any type of element, including other lists. The members of a list may be encoded + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1105 +``` + +with any form of tag, including an anonymous tag. The tags within a list do not need to be unique +with respect to other members of the list. + +**A.6. Element Encoding** + +A TLV element is encoded a single control octet, followed by a sequence of tag, length and value +octets. Depending on the nature of the element, any of the tag, length or value fields may be omit­ +ted. + +``` +Control Octet Tag Length Value +1 octet 0 to 8 octets 0 to 8 octets Variable +``` +**A.7. Control Octet Encoding** + +The control octet specifies the type of a TLV element and how its tag, length and value fields are +encoded. The control octet consists of two subfields: an _element type field_ which occupies the lower +5 bits, and a _tag control field_ which occupies the upper 3 bits. + +**A.7.1. Element Type Field** + +The element type field encodes the element’s type as well as how the corresponding length and +value fields are encoded. In the case of Booleans and the Null value, the element type field also +encodes the value itself. + +``` +Control Octet Description +Tag Control Element Type +7 6 5 4 3 2 1 0 +x x x 0 0 0 0 0 Signed Integer, 1-octet value +x x x 0 0 0 0 1 Signed Integer, 2-octet value +x x x 0 0 0 1 0 Signed Integer, 4-octet value +x x x 0 0 0 1 1 Signed Integer, 8-octet value +x x x 0 0 1 0 0 Unsigned Integer, 1-octet value +x x x 0 0 1 0 1 Unsigned Integer, 2-octet value +x x x 0 0 1 1 0 Unsigned Integer, 4-octet value +x x x 0 0 1 1 1 Unsigned Integer, 8-octet value +x x x 0 1 0 0 0 Boolean False +x x x 0 1 0 0 1 Boolean True +x x x 0 1 0 1 0 Floating Point Number, 4-octet value +x x x 0 1 0 1 1 Floating Point Number, 8-octet value +x x x 0 1 1 0 0 UTF-8 String, 1-octet length +``` +``` +Page 1106 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Control Octet Description +x x x 0 1 1 0 1 UTF-8 String, 2-octet length +x x x 0 1 1 1 0 UTF-8 String, 4-octet length +x x x 0 1 1 1 1 UTF-8 String, 8-octet length +x x x 1 0 0 0 0 Octet String, 1-octet length +x x x 1 0 0 0 1 Octet String, 2-octet length +x x x 1 0 0 1 0 Octet String, 4-octet length +x x x 1 0 0 1 1 Octet String, 8-octet length +x x x 1 0 1 0 0 Null +x x x 1 0 1 0 1 Structure +x x x 1 0 1 1 0 Array +x x x 1 0 1 1 1 List +0 0 0 1 1 0 0 0 End of Container +x x x 1 1 0 0 0 Reserved (where xxx are not 000 ) +x x x 1 1 0 0 1 Reserved +x x x 1 1 0 1 0 Reserved +x x x 1 1 0 1 1 Reserved +x x x 1 1 1 0 0 Reserved +x x x 1 1 1 0 1 Reserved +x x x 1 1 1 1 0 Reserved +x x x 1 1 1 1 1 Reserved +``` +For both signed and unsigned integer types the bottom two bits of the element type field signal the +width of the corresponding field as follows: + +- 00 — 1 octet +- 01 — 2 octets +- 10 — 4 octets +- 11 — 8 octets + +For UTF-8 and octet string types the bottom two bits of the element type field signal the width of the +length field as follows: + +- 00 — 1 octet +- 01 — 2 octets +- 10 — 4 octets +- 11 — 8 octets + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1107 +``` + +For end of container element type the tag control bits are set to 0. Any other combination of the tag +control bits for this element type only is reserved. See Section A.10, “End of Container Encoding”. + +**A.7.2. Tag Control Field** + +The tag control field identifies the form of tag assigned to the element (including none) as well as +the encoding of the tag octets. + +``` +Control Octet Description +Tag Control Element Type +7 6 5 4 3 2 1 0 +0 0 0 x x x x x Anonymous Tag Form, 0 octets +0 0 1 x x x x x Context-specific Tag Form, 1 octet +0 1 0 x x x x x Common Profile Tag Form, 2 octets +0 1 1 x x x x x Common Profile Tag Form, 4 octets +1 0 0 x x x x x Implicit Profile Tag Form, 2 octets +1 0 1 x x x x x Implicit Profile Tag Form, 4 octets +1 1 0 x x x x x Fully-qualified Tag Form, 6 octets +1 1 1 x x x x x Fully-qualified Tag Form, 8 octets +``` +**A.8. Tag Encoding** + +Tags are encoded in 0, 1, 2, 4, 6 or 8 octet widths as specified by the tag control field. Tags consist of +up to three numeric fields: a _Vendor ID field_ , a _profile number field_ , and a _tag number field_. All fields +are encoded in little-endian order. The tag fields are ordered as follows: + +``` +Vendor ID Profile Number Tag Number +0 or 2 octets 0 or 2 octets 1, 2, or 4 octets +``` +**A.8.1. Fully-Qualified Tag Form** + +A profile-specific tag can be encoded in _fully-qualified tag form_ , where the encoding includes all +three tag components (Vendor ID, profile number and tag number). Two variants of this form are +supported, one with a 16-bit tag number and one with a 32-bit tag number. The 16-bit variant +SHALL be used with tag numbers < 65536, while the 32-bit variant SHALL be used with tag num­ +bers >= 65536. + +``` +Tag Control Vendor ID Size Profile Number +Size +``` +``` +Tag Number Size +``` +``` +110b 2 octets 2 octets 2 octets For tag numbers < +65536 +``` +``` +Page 1108 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Tag Control Vendor ID Size Profile Number +Size +``` +``` +Tag Number Size +``` +``` +111b 2 octets 2 octets 4 octets For tag numbers +>= 65536 +``` +**A.8.2. Implicit Profile Tag Form** + +A profile-specific tag can also be encoded in _implicit profile tag form_ , where the encoding includes +only the tag number, and the Vendor ID and profile number are inferred from the protocol context +in which the TLV encoding is communicated. This form also has two variants based on the magni­ +tude of the tag number. + +``` +Tag Control Tag Number Size +100b 2 octets For tag numbers < 65536 +101b 4 octets For tag numbers >= 65536 +``` +**A.8.3. Common Profile Tag Form** + +A special encoding exists for profile-specific tags that are defined by the Matter Common Profile. +These are encoded in the same manner as implicit profile tags except that they are identified as +common profile tags, rather than implicit profile tags in the tag control field. + +``` +Tag Control Tag Number Size +010b 2 octets For tag numbers < 65536 +011b 4 octets For tag numbers >= 65536 +``` +**A.8.4. Context-Specific Tag Form** + +Context-specific tags are encoded as a single octet conveying the tag number. + +``` +Tag Control Tag Number Size +001b 1 octets All tag numbers 0 - 255 +``` +**A.8.5. Anonymous Tag Form** + +Anonymous elements do not encode any tag octets. + +``` +Tag Control Tag Size +000b 0 octets No data encoded +``` +**A.9. Length Encoding** + +Length fields are encoded in 0, 1, 2, 4 or 8 octet widths, as specified by the element type field. +Length fields of more than one octet are encoded in little-endian order. The choice of width for the + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1109 +``` + +length field is up to the discretion of the sender, implying that a sender can choose to send more +length octets than strictly necessary to encode the value. + +**A.10. End of Container Encoding** + +The end of a container type is marked with a special element called the end-of-container element. +The end-of-container element is encoded as a single control octet with the value 18h. The tag con­ +trol bits within the control octet SHALL be set to zero, implying that end-of-container element can +never have a tag. + +``` +Control Octet +1 octet +``` +**A.11. Value Encodings** + +**A.11.1. Integers** + +An integer element is encoded as follows: + +``` +Control Octet Tag Value +1 octet 0 to 8 octets 1, 2, 4 or 8 octets +``` +The number of octets in the value field is indicated by the element type field within the control +octet. The choice of value octet count is at the sender’s discretion, implying that a sender is free to +send more octets than strictly necessary to encode the value. Within the value octets, the integer +value is encoded in little-endian format (two’s complement format for signed integers). + +**A.11.2. UTF-8 and Octet Strings** + +UTF-8 and octet strings are encoded as follows: + +``` +Control Octet Tag Length Value +1 octet 0 to 8 octets 1 to 8 octets 0 to 2^64 -1 octets +``` +The length field of a UTF-8 or octet string encodes the number of octets (not characters) present in +the value field. The number of octets in the length field is implied by the type specified in the ele­ +ment type field (within the control octet). + +For octet strings, the value can be any arbitrary sequence of octets. For UTF-8 strings, the value +octets SHALL encode a valid UTF-8 character (code points) sequence. Senders SHALL NOT include a +terminating null character to mark the end of a string. + +**A.11.3. Booleans** + +Boolean elements are encoded as follows: + +``` +Page 1110 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Control Octet Tag +1 octet 0 to 8 octets +``` +The value of a Boolean element (true or false) is implied by the type indicated in the element type +field. + +**A.11.4. Arrays, Structures and Lists** + +Array, structure and list elements are encoded as follows: + +``` +Control Octet Tag Value End-of-Container +1 octet 0 to 8 octets Variable 1 octet +``` +The value field of an array/structure/list element is a sequence of encoded TLV elements that consti­ +tute the members of the element, followed by an end-of-container element. The end-of-container +element SHALL always be present, even in cases where the end of the array/structure/list element +could be inferred by other means (e.g. the length of the packet containing the TLV encoding). + +**A.11.5. Floating Point Numbers** + +A floating point number is encoded as follows: + +``` +Control Octet Tag Value +1 octet 0 to 8 octets 4 or 8 octets +``` +The value field of a floating point element contains an IEEE 754-2019 single or double precision +floating point number encoded in little-endian format (specifically, the reverse of the order +described in External Data Representation, RFC 4506). The choice of precision is implied by the type +specified in the element type field (within the control octet). The sender is free to choose either pre­ +cision at their discretion. + +**A.11.6. Nulls** + +A Null value is encoded as follows: + +``` +Control Octet Tag +1 octet 0 to 8 octets +``` +**A.12. TLV Encoding Examples** + +In order to better ground the TLV concepts, this subsection provides a set of sample encodings. In +the tables below, type and values column uses a decimal representation for all number whereas the +encoding is represented with hexadecimal numbers. + +Table 105, “Sample encoding of primitive types” shows sample encodings for primitive types. All +examples in the table below are encoded as anonymous elements. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1111 +``` + +_Table 105. Sample encoding of primitive types_ + +``` +Type and Value Encoding (hex) +Boolean false^08 +Boolean true^09 +Signed Integer, 1-octet, value 42 00 2a +Signed Integer, 1-octet, value -17 00 ef +Unsigned Integer, 1-octet, value 42U 04 2a +Signed Integer, 2-octet, value 42 01 2a 00 +Signed Integer, 4-octet, value -170000 02 f0 67 fd ff +Signed Integer, 8-octet, value 40000000000 03 00 90 2f 50 09 00 00 00 +UTF-8 String, 1-octet length, "Hello!" 0c 06 48 65 6c 6c 6f 21 +UTF-8 String, 1-octet length, "Tschüs" 0c 07 54 73 63 68 c3 bc 73 +Octet String, 1-octet length, octets 00 01 02 03 04 10 05 00 01 02 03 04 +Null^14 +Single precision floating point 0.0 0a 00 00 00 00 +Single precision floating point (1.0 / 3.0) 0a ab aa aa 3e +Single precision floating point 17.9 0a 33 33 8f 41 +Single precision floating point infinity (∞) 0a 00 00 80 7f +Single precision floating point negative infinity +(-∞) +``` +``` +0a 00 00 80 ff +``` +``` +Double precision floating point 0.0 0b 00 00 00 00 00 00 00 00 +Double precision floating point (1.0 / 3.0) 0b 55 55 55 55 55 55 d5 3f +Double precision floating point 17.9 0b 66 66 66 66 66 e6 31 40 +Double precision floating point infinity (∞) 0b 00 00 00 00 00 00 f0 7f +Double precision floating point negative infinity +(-∞) +``` +``` +0b 00 00 00 00 00 00 f0 ff +``` +Table 106, “Sample encoding of containers” shows sample encodings for container types. In each of +the examples below, the outermost container is encoded as an anonymous element. + +_Table 106. Sample encoding of containers_ + +``` +Type and Value Encoding (hex) +Empty Structure, {} 15 18 +Empty Array, [] 16 18 +Empty List, [] 17 18 +Structure, two context specific tags, Signed Inte­ +ger, 1 octet values, {0 = 42, 1 = -17} +``` +``` +15 20 00 2a 20 01 ef 18 +``` +``` +Page 1112 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Type and Value Encoding (hex) +Array, Signed Integer, 1-octet values, [0, 1, 2, +3, 4] +``` +### 16 00 00 00 01 00 02 00 03 00 04 18 + +``` +List, mix of anonymous and context tags, Signed +Integer, 1 octet values, [[1, 0 = 42, 2, 3, 0 = +-17]] +``` +``` +17 00 01 20 00 2a 00 02 00 03 20 00 ef 18 +``` +``` +Array, mix of element types, [42, -170000, {}, +17.9, "Hello!"] +``` +``` +16 00 2a 02 f0 67 fd ff 15 18 0a 33 33 8f 41 +0c 06 48 65 6c 6c 6f 21 18 +``` +Table 107, “Sample encoding of different tag types” shows sample encoding of a value with differ­ +ent associated tags, using Vendor ID = : 65522 (0xFFF2), one of the Vendor IDs allocated for testing +purposes. + +_Table 107. Sample encoding of different tag types_ + +``` +Type and Value Encoding (hex) +Anonymous tag, Unsigned Integer, 1-octet value, +42U +``` +``` +04 2a +``` +``` +Context tag 1 , Unsigned Integer, 1-octet value, 1 += 42U +``` +``` +24 01 2a +``` +``` +Common profile tag 1 , Unsigned Integer, 1-octet +value, Matter::1 = 42U +``` +``` +44 01 00 2a +``` +``` +Common profile tag 100000 , Unsigned Integer, 1- +octet value, Matter::100000 = 42U +``` +``` +64 a0 86 01 00 2a +``` +``` +Fully qualified tag, Vendor ID 0xFFF1/ 65521 , pro­ +file number 0xDEED/ 57069 , 2-octet tag 1 , Unsigned +Integer, 1-octet value 42, 65521::57069:1 = 42U +``` +``` +c4 f1 ff ed de 01 00 2a +``` +``` +Fully qualified tag, Vendor ID 0xFFF1/ 65521 , pro­ +file number 0xDEED/ 57069 , 4-octet tag +0xAA55FEED/2857762541, Unsigned Integer, 1-octet +value 42, 65521::57069:2857762541 = 42U +``` +``` +e4 f1 ff ed de ed fe 55 aa 2a +``` +``` +Structure with the fully qualified tag, Vendor ID +0xFFF1/ 65521 , profile number 0xDEED/ 57069 , 2- +octet tag 1. The structure contains a single ele­ +ment labeled using a fully qualified tag under +the same profile, with 2-octet tag 0xAA55/43605. +65521::57069:1 = {65521::57069:43605 = 42U} +``` +``` +d5 f1 ff ed de 01 00 c4 f1 ff ed de 55 aa 2a +18 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1113 +``` + +Page 1114 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Appendix B: Tag-length-value (TLV) Schema** + +**Definitions** + +**B.1. Introduction** + +A TLV Schema provides a simple textual description of the structure of data encoded in the Matter +TLV format. A single TLV Schema MAY define the structure of multiple different TLV-encoded pay­ +loads. This section describes the syntax one can use to define a TLV Schema. + +**B.1.1. Basic Structure** + +A TLV Schema takes the form of a series of definitions. Each definition describes some construct, +such as a data type. Each definition has an associated human readable name separated from the +definition with a ⇒ symbol. As a mnemonic device, it is useful to read the ⇒ symbol as “is a”. For +example, the following definition defines a data type that MAY be used to represent a sensor sam­ +ple: + +_Example_ + +``` +/** Sensor sample structure */ +sensor-sample => STRUCTURE +{ +timestamp [1] : UNSIGNED INTEGER [ range 32-bits ], +value [2] : FLOAT64, +} +``` +This example would be read as " _sensor-sample_ is a structure containing a _timestamp_ and _value_ ". + +A TLV Schema MAY contain multiple definitions. The order of definitions within a TLV Schema is +unimportant. + +**B.1.2. Keywords** + +TLV Schemas employ various keywords when describing a construct. These keywords (e.g. STRUC­ +TURE, SIGNED INTEGER, and range) are an inherent part of the schema language. Keywords in TLV +Schemas are always case-insensitive. However, by convention, keywords associated with types and +other high-level constructs are capitalized for emphasis in text-only contexts. + +**B.1.3. Naming** + +Each definition in a TLV Schema assigns a human-readable name to the construct being defined. +This name serves both as a descriptive title as well as a means to refer to the construct from else­ +where in the schema. + +Names in TLV Schemas are limited to ASCII alphanumeric characters, plus dash (-) and underscore +(_). Additionally, all names SHALL begin with either an alphabetic character or an underscore. In + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1115 +``` + +general, any name conforming to these rules MAY be used, as long as it does not collide with a key­ +word used by the schema language. + +**B.1.4. Namespaces** + +The name assigned to a schema construct SHALL be unique relative to all other named constructs +in the same scope. To facilitate this, TLV Schemas support a namespacing mechanism similar to that +provided in languages like C++. + +The names of constructs defined within a namespace definition are only required to be unique +within the given namespace. Namespaces themselves MAY be nested to any depth. + +Constructs defined in other namespaces MAY be referenced using a name that gives the enclosing +namespaces, plus the construct name, each separated by dots (.). Such a multi-part name is called a +_scoped name_. For example: + +_Namespaces Example_ + +``` +namespace a +{ +x => STRING, +other-x => b.x +} +``` +``` +namespace b +{ +x => SIGNED INTEGER +} +``` +See namespace-def for further details. + +**B.1.5. Qualifiers** + +Constructs within a TLV Schema MAY be annotated with additional information using a _qualifier_. +Qualifiers appear within square brackets ([...]) immediately following the construct they affect. In +most cases the use of qualifiers is optional, but there are some situations where the schema syntax +requires a qualifier. + +Often qualifiers are used to place restrictions on the form or range of values that a construct can +assume. For example a length qualifier MAY be used to constrain the length of a STRING type: + +``` +international-standard-book-number => STRING [length 13] +``` +Multiple qualifiers MAY appear within the square brackets, and SHALL be separated by commas. + +See Section B.5, “Qualifiers” for further details. + +``` +Page 1116 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**B.1.6. Tagging** + +In a TLV Schema, tag numbers appear as qualifiers attached to a particular named construct, such +as a field within a structure. This association reflects the tag’s role as an alias for the textual name +in the TLV encoding. The syntax for tag qualifiers is defined in tag. For example: + +_Tagging Example_ + +``` +certificate [my-protocol:1] => STRUCTURE +{ +serial-num [1] : OCTET STRING, +... +} +``` +**B.2. Definitions** + +A Matter TLV Schema consists of a set of one or more definitions. The definitions that MAY appear +within a schema are: + +- type-def +- field-group-def +- namespace-def +- protocol-def +- vendor-def + +**B.2.1. Type Definition (type-def )** + +_Type Definition Syntax_ + +``` +type-name [ qualifier ] => type-or-ref +``` +``` +type-or-ref: +type +type-ref +``` +``` +type: +ANY +ARRAY +ARRAY OF +BOOLEAN +CHOICE OF +FLOAT32 +FLOAT64 +LIST +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1117 +``` + +### LIST OF + +### NULL + +### OCTET STRING + +### SIGNED INTEGER + +### STRING + +### STRUCTURE + +### UNSIGNED INTEGER + +``` +type-ref: +type-name +scoped-type-name +``` +``` +qualifier: +tag +``` +A type definition associates a name (type-name) with a schema construct representing a TLV type or +pseudo-type. The given name serves as a descriptive title for the type, as well as a means to refer to +the type from elsewhere in the schema. + +Type definitions (type-def) are often used to describe TLV types that appear directly in some form +of communication. For example, a type definition MAY define the structure of data carried within +the payload of a message. Some type definitions may be used to define general purpose TLV con­ +structs which are then employed in the definitions of other types. + +The type (type-name) associated with a type definition MAY be any one of the available TLV types or +pseudo-type. Alternatively, a type definition MAY contain a scoped type (scoped-type-name) referring +to another type definition appearing elsewhere in the schema. This form is referred to as a type ref­ +erence (type-ref). The ordering of type definitions and type references within a schema is unimpor­ +tant, implying that a type reference MAY refer to a type that is defined later in the schema. + +A tag qualifier MAY be applied to the name within a type definition to associate a default tag with +that name. The default tag will be used in an encoding of the type whenever an explicit tag has not +been given. + +**B.2.2. FIELD GROUP Definition (field-group-def )** + +_FIELD GROUP Definition Syntax_ + +``` +field-group-name => FIELD GROUP { field-group-members } +``` +``` +field-group-members: +field-group-member +field-group-members, field-group-member +``` +``` +field-group-member: +identifier [ id-qualifier ] : type-or-ref // field definition +``` +``` +Page 1118 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +includes field-group-name // field group include +``` +``` +id-qualifier: +tag // SHALL be present +optional +``` +FIELD GROUP declares a collection of fields that MAY be included in a TLV Structure. A FIELD GROUP is +never directly encoded in a TLV encoding. A FIELD GROUP is used with includes statement to define +common patterns of fields such that they MAY be reused across different STRUCTURE definitions. + +A FIELD GROUP definition (field-group-def) contains a list of field definitions, each of which gives the +type of the field, its tag, and an associated textual name. The field type MAY be either a fundamen­ +tal type, a CHOICE OF pseudo-type, an ANY pseudo-type, or a reference to one of these types defined +outside the FIELD GROUP definition. + +A FIELD GROUP definition MAY also contain one or more includes statements. Each such statement +identifies another FIELD GROUP whose fields are to be included within the referencing FIELD GROUP. +Such nested inclusion MAY be specified to any depth. + +The rules governing the names and tags associated with fields within a FIELD GROUP are the same as +those defined for STRUCTURE. + +_FIELD GROUP Definition Examples_ + +``` +common-sensor-sample-fields => FIELD GROUP +{ +timestamp [1] : UNSIGNED INTEGER [ range 32-bits ], +} +``` +``` +temperature-sensor-sample => STRUCTURE [tag-order] +{ +includes common-sensor-sample-fields, +``` +``` +value [2] : FLOAT64, +} +``` +``` +humidity-sensor-sample => STRUCTURE [tag-order] +{ +includes common-sensor-sample-fields, +``` +``` +value [2] : UNSIGNED INTEGER [ range 64-bits ], +} +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1119 +``` + +**B.2.3. Namespace Definition (namespace-def )** + +_Namespace Definition Syntax_ + +``` +namespace ns-name { ns-scoped-defs } +``` +``` +ns-name: +name +scoped-name +``` +``` +ns-scoped-defs: +ns-scoped-def +ns-scoped-defs, ns-scoped-def +``` +``` +ns-scoped-def: +type-def +field-group-def +protocol-def +namespace-def +``` +namespace introduces a new naming scope. Definitions that appear within the braces of a name­ +space definition are scoped to that namespace, such that their names need only be unique within +the bounds of the enclosing scope. The namespace scoped definitions SHALL be separated by com­ +mas. + +In general, four forms of definitions MAY appear within a namespace: type definitions (type-def), +FIELD GROUP definitions (field-group-def), protocol definitions (protocol-def) and further namespace +definitions (namespace-def). Namespace definitions MAY be nested to any level. Protocol defini­ +tions, however, are restricted such that they SHALL NOT be nested. Thus a namespace can only con­ +tain a protocol definition if the namespace itself is not located, at any level, within another protocol +definition. + +The name used in a namespace definition MAY be either a simple name, such as a, or a scoped-name, +such as a.b.c. When a scoped-name is used, the effect is exactly as if multiple nested namespaces had +been declared, each named after a part of the scoped name. + +It is legal to have multiple namespace definitions, each with the same name, defined within the +same scope. The effect is as if there were only a single namespace definition containing a union of +the enclosed definitions. Thus, a namespace definition with the same name as a preceding defini­ +tion MAY be seen as a kind of continuation of the earlier one. + +_Namespace Definition Examples_ + +``` +namespace abc +{ +property => FLOAT32 [ range 0..50 ], +``` +``` +Page 1120 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +point => STRUCTURE +{ +day [0] : UNSIGNED INTEGER, +prop [1] : property +} +} +``` +``` +namespace matter.protocols.aaa +{ +config => STRUCTURE +{ +points [0] : ARRAY OF abc.point, +... +} +} +``` +**B.2.4. PROTOCOL Definition (protocol-def )** + +_PROTOCOL Definition Syntax_ + +``` +name => PROTOCOL [ qualifier ] { protocol-scoped-defs } +``` +``` +qualifier: +id +``` +``` +protocol-scoped-defs: +protocol-scoped-def +protocol-scoped-defs, protocol-scoped-def +``` +``` +protocol-scoped-def: +type-def +field-group-def +namespace-def +``` +PROTOCOL defines a Matter protocol. A Matter protocol is a group of logically related Matter TLV con­ +structs that together serve a common purpose. + +Similar to a namespace definition, a PROTOCOL definition introduces a new naming scope in which fur­ +ther definitions may appear. The names of definitions appearing within the braces of a PROTOCOL are +scoped in exactly the same way as if they had appeared within a namespace definition. Likewise, con­ +structs outside the PROTOCOL definition MAY refer to definitions within the protocol by using a +scoped name that includes the protocol name. The PROTOCOL scoped definitions SHALL be separated +by commas. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1121 +``` + +PROTOCOL definitions MAY appear at the global naming scope, or within a namespace definition. +However, PROTOCOL definitions SHALL NOT be nested within other PROTOCOL definitions at any depth. + +Every PROTOCOL definition SHALL include an id qualifier giving the id of the protocol, that uniquely +identifies the protocol among all other protocols. The id given in a PROTOCOL definition SHALL be +unique relative to all other PROTOCOL definitions in a schema. However, it is legal to have multiple +PROTOCOL definitions with the same protocol id, provided that they also have the same name and +appear within the same naming scope. The effect of this is as if there were only a single PROTOCOL +definition containing a union of the enclosed definitions. This makes it possible to break up a PROTO­ +COL definition across multiple schema files. + +_PROTOCOL Definition Example_ + +``` +namespace some.names { +``` +``` +my-protocol => PROTOCOL [ VENDOR:0x0008 ] +{ +laser-transducer-metadata [1] => STRUCTURE +{ +serial-num [1] : OCTET STRING, +... +}, +``` +``` +optics-array [2] => ARRAY OF optical-specification +} +``` +``` +} +``` +**B.2.5. VENDOR Definition (vendor-def )** + +_VENDOR Definition Syntax_ + +``` +name => VENDOR [ qualifier ] +``` +``` +qualifier: +id +``` +VENDOR associates a name with a Vendor ID. VENDOR definition SHALL include an id qualifier giving +the id of the vendor. + +In a TLV Schema that includes a VENDOR definition, the vendor name MAY be used elsewhere in the +schema as a stand-in for the associated Vendor ID. One such place where a vendor name may +appear is within the id qualifier of a PROTOCOL definition. + +VENDOR definitions MAY only appear at the global name scope, implying they SHALL NOT be placed +within the body of a namespace or PROTOCOL definition. + +``` +Page 1122 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Both the name and id value used in a VENDOR definition SHALL be unique across all such definitions. +However, for convenience, a VENDOR definition MAY be repeated provided that the name and id are +the same. + +The Matter vendor (0x00000) is implicitly defined in all schemas, although it MAY be explicitly +defined as well: + +_VENDOR Definition Example_ + +``` +Matter => VENDOR [ 0x0000 ] +``` +**B.3. Types** + +The TLV format supports 10 fundamental types: integers (signed and unsigned), floats, booleans, +UTF-8 strings, octet strings, structures, arrays, lists and nulls. Accordingly, a TLV Schema MAY use +one of the following type constructs to constrain an encoding to be one of these fundamental types. + +**B.3.1. ARRAY / ARRAY OF** + +_ARRAY Syntax_ + +``` +ARRAY [ qualifier ] OF type-or-ref // uniform array +ARRAY [ qualifier ] { type-pattern } // pattern array +``` +``` +qualifier (optional): +length +nullable +``` +``` +type-pattern: +type-pattern-item +type-pattern, type-pattern-item +``` +``` +type-pattern-item: +type-or-ref quantifier // unnamed item +identifier : type-or-ref quantifier // named item +``` +``` +quantifier (optional): +* // zero or more ++ // one or more +{ count } // exactly count +{ min..max } // between min and max +{ min.. } // at least min +``` +ARRAY and ARRAY OF declare an element that is encoded as a TLV Array. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1123 +``` + +ARRAY OF declares an array where all the items in the array are of the same fundamental type, or +taken from the same set of possible types. This form of array is called a _uniform array_ , and is gener­ +ally used to represent ordered collections of values. + +ARRAY declares an array where the types of the array items follow a particular pattern. In this form, +known as a _pattern array_ ; the allowed type for an item depends on its position in the array. The +overall pattern of types allowed in the array is declared using a schema construct called a linear +type pattern, which is similar to a regular expression (see below). Pattern arrays are typically used +to represent vectors, tuples or paths. + +A length qualifier on an array MAY be used to constraint the minimum and maximum number of +items in the array. For a pattern array, the given length constraint SHALL be consistent with (i.e. fall +within) the minimum and maximum number of items implied by the type pattern. In cases where +the length qualifier places a narrower constraint on the length of an array than that implied by the +type pattern, the length qualifier constraint takes precedence. + +A nullable qualifier MAY be used to indicate that a TLV Null MAY be encoded in place of the ARRAY or +ARRAY OF. Note that an array that has been replaced by a Null is distinct in terms of its encoding +from an array that has no items. + +**B.3.1.1. Linear Type Patterns** + +A linear type pattern describes the sequence of TLV types that MAY appear in a TLV Array or List +element. In its simplest form, a linear type pattern is a list of type definitions, or references to +defined types, where each item constrains the TLV type that appears at the corresponding position +in the collection. The type pattern is always anchored at the start of the collection, with the first +type constraining the first item in the collection. Any type or pseudo-type MAY appear within a lin­ +ear type pattern. + +More complex type patterns can be created by using a quantifier. Quantifiers appear after a type in +a type pattern and specify the number of times the associated type MAY appear at that position in +the collection. Quantifiers borrow common regular expression notation to denote repetition, with * +meaning zero or more, + meaning one or more, and { } expressing specific counts. Using quanti­ +fiers, one can express complex sequences of types, including some that require arbitrary look- +ahead to match. + +**B.3.1.2. Item Names** + +Items or groups of items in a pattern array MAY be given textual names. These names do not affect +the encoding of the array, but serve as user documentation, or as input to code generation tools. +Item names within a pattern array SHALL be unique. + +Per the rules for encoding TLV arrays, array items SHALL NOT have tags. Thus the tag qualifier +SHALL NOT be applied to an item name with a pattern array. + +_ARRAY Example_ + +``` +supported-country-codes => ARRAY [ length 0..10 ] OF STRING [ length 2 ] +``` +``` +Page 1124 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +weather-tuple => ARRAY +{ +timestamp : UNSIGNED INTEGER [ range 32-bits ], +temperature : FLOAT64, +relative-humidity : UNSIGNED INTEGER [ range 0..100 ], +precipitation : UNSIGNED INTEGER [ range 0..100 ], +} +``` +``` +named-vector => ARRAY +{ +name : STRING, +FLOAT64 *, +} +``` +**B.3.2. BOOLEAN** + +_BOOLEAN Syntax_ + +``` +BOOLEAN [ qualifier ] +``` +``` +qualifier (optional): +nullable +``` +BOOLEAN declares an element that SHALL be encoded as a TLV Boolean. + +If the nullable qualifier is given, a TLV Null MAY be encoded in its place. + +_BOOLEAN Example_ + +``` +pathlight-enabled => BOOLEAN +``` +**B.3.3. FLOAT32 / FLOAT64** + +_FLOAT Syntax_ + +``` +FLOAT32 [ qualifier ] +FLOAT64 [ qualifier ] +``` +``` +qualifier (optional): +range +nullable +``` +FLOAT32 declares an element that SHALL be encoded as a TLV floating point number with the ele­ +ment type indicating a 4-octet IEEE 754-2019 single-precision value. Correspondingly, FLOAT64 +declares a TLV element that SHALL be encoded as a TLV floating point number with the element + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1125 +``` + +type indicating an 8-octet IEEE 754-2019 double-precision value. + +If the nullable qualifier is given, a TLV Null MAY be encoded in place of the number. + +The allowed range of values can be constrained using the range qualifier. If omitted, the value is +constrained by what the relevant TLV type can represent. + +_FLOAT Example_ + +``` +set-value => FLOAT32 [ range 0..50 ] +``` +**B.3.4. SIGNED INTEGER / UNSIGNED INTEGER** + +_Integer Syntax_ + +``` +SIGNED INTEGER [ qualifier ] { enum } +UNSIGNED INTEGER [ qualifier ] { enum } +``` +``` +qualifier (optional): +range +nullable +``` +``` +enum: +identifier = int-value +``` +SIGNED INTEGER declares an element that SHALL be encoded as a TLV integer with the element type +indicating the integer is signed. Correspondingly, UNSIGNED INTEGER declares a TLV element that +SHALL be encoded as a TLV integer with the element type indicating the integer is unsigned. + +If the nullable qualifier is given, a TLV Null MAY be encoded in place of the integer. + +The allowed range of values MAY be constrained using the range qualifier. If omitted, the value is +constrained by what the relevant TLV type can represent. + +SIGNED INTEGER and UNSIGNED INTEGER definitions MAY include a set of enumerated values (enum), +each of which associates a textual name (identifier) with a constant integer value (int-value). Each +value SHALL conform to the allowed range of values for the SIGNED INTEGER definition as given by +its sign and any range qualifier. The presence of enumerated values SHALL NOT restrict senders to +only encoding those values. Rather, enumerations merely give symbolic names to particular note­ +worthy values. + +_Integer Examples_ + +``` +sensor-value => SIGNED INTEGER [ range -100..100 ] +``` +``` +counter => UNSIGNED INTEGER [ range 32-bits ] +``` +``` +Page 1126 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**B.3.5. LIST / LIST OF** + +_LIST Syntax_ + +``` +LIST [ list-qualifier ] OF type-or-ref // uniform list +LIST [ list-qualifier ] { type-pattern } // pattern list +``` +``` +list-qualifier (optional): +length +nullable +``` +``` +type-pattern: +type-or-ref quantifier // unnamed item +identifier [ qualifier ] : type-or-ref quantifier // named item +``` +``` +quantifier (optional): +* // zero or more ++ // one or more +{ count } // exactly count +{ min..max } // between min and max +{ min.. } // at least min +``` +``` +qualifier (optional): +tag +``` +LIST and LIST OF declare an element that is encoded as a TLV List. LIST and LIST OF declare the +same fundamental type, but differ based on how the allowed types of their items are expressed. + +LIST OF declares a list where all the items in the list are of the same fundamental type, or taken +from the same set of possible types. This form of list is called a _uniform list_. Uniform lists are gener­ +ally used to represent ordered collections of values where the tags differentiate the semantic mean­ +ing of the value. + +LIST declares a _pattern list_ where the types of the items in the list follow a particular pattern. In this +form, the allowed type(s) for an item depends on its position in the array. Pattern lists are typically +used to represent path-like constructs. + +The overall pattern of types allowed in a pattern list is declared using a schema construct called a +linear type pattern. The syntax and interpretation of linear type patterns for pattern lists are the +same as those for pattern arrays (see Section B.3.1.1, “Linear Type Patterns”). + +The length qualifier MAY be used to constraint the minimum and maximum number of items in the +list. For a pattern list, the given length constraint SHALL be consistent with (i.e. fall within) the min­ +imum and maximum number of items implied by the type pattern. In cases where the length quali­ +fier places a narrower constraint on the length of a list than that implied by the type pattern, the +length qualifier constraint takes precedence. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1127 +``` + +A nullable qualifier MAY be used to indicate that a TLV Null MAY be encoded in place of the LIST or +LIST OF. Note that a list that has been replaced by a Null is distinct (in terms of its encoding) from a +list that has no items. + +**B.3.5.1. Item Names** + +As with the ARRAY type, items or groups of items in a pattern list MAY be given textual names to dis­ +tinguish their purposes. Item names within a pattern list SHALL be unique. + +**B.3.5.2. Item Tags** + +Items within a pattern list can have a tag qualifier that specifies a particular tag value that SHALL +be encoded with the item. The specific tag can be protocol-specific or context-specific, or the anony­ +mous tag. The assigned tag values are not required to be unique among the items in a pattern list. + +When no explicit tag qualifier is given (which is always the case for uniform lists) the items in a list +automatically assume the default tag of their underlying types, if such a tag is provided. This can +occur in two situations: 1) when the underlying type is a reference to a type definition that declares +a default tag, and 2) when the underlying type is a CHOICE OF whose alternates declare default tags. +See default tag for further information. + +If no tag qualifier is given, and no default tag is available, an encoder is allowed to encode list items +with any tag of their choosing. + +**B.3.6. OCTET STRING** + +_OCTET STRING Syntax_ + +``` +OCTET STRING [ qualifier ] +``` +``` +qualifier (optional): +length +nullable +``` +OCTET STRING declares an element that is encoded as a TLV Octet String, and in particular with the +element type indicating it’s an Octet String. + +The minimum and maximum number of bytes can be constrained using the length qualifier. + +_OCTET STRING Example_ + +``` +address => OCTET STRING [ length 8 ] +``` +**B.3.7. NULL** + +_NULL Syntax_ + +``` +NULL +``` +``` +Page 1128 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +NULL declares an element that SHALL be encoded as a TLV Null. There are no qualifiers that can be +associated with a NULL type. + +_NULL Example_ + +``` +serial-num => CHOICE OF { STRING, UNSIGNED INTEGER, NULL } +``` +**B.3.8. STRING** + +_STRING Syntax_ + +``` +STRING [ qualifier ] +``` +``` +qualifier (optional): +length +nullable +``` +STRING declares an element that is encoded as a TLV UTF-8 String, and in particular with the ele­ +ment type indicating it’s a UTF-8 String. + +If the nullable qualifier is given, a TLV Null MAY be encoded in place of the string. + +The minimum and maximum length of the string can be constrained using the length qualifier. + +_STRING Example_ + +``` +name-field => STRING [ length 0..32 ] +``` +**B.3.9. STRUCTURE** + +_STRUCTURE Syntax_ + +``` +STRUCTURE [ structure-qualifier ] { structure-fields } +``` +``` +structure-qualifier (optional): +extensible +order +nullable +``` +``` +structure-fields: +structure-field +structure-fields, structure-field +``` +``` +structure-field: +identifier [ id-qualifier ] : type-or-ref // field definition +includes field-group-name // field group include +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1129 +``` + +``` +id-qualifier: +tag +optional +``` +STRUCTURE declares an element that is encoded as a TLV Structure. The STRUCTURE fields SHALL be +separated by commas. + +A STRUCTURE definition declares the list of fields that MAY appear within the corresponding TLV +Structure. Each field definition gives the type of the field, its tag, and an associated textual name. +The field type MAY be either a fundamental type, a CHOICE OF pseudo-type, an ANY pseudo-type, or a +reference to one of these types defined outside the STRUCTURE definition. + +A STRUCTURE definition MAY also contain one or more includes statements. Each such statement +identifies a FIELD GROUP definition whose fields are to be included within the TLV Structure as if +they had been declared within the STRUCTURE definition itself (see Includes FIELD GROUP below). + +An extensible qualifier MAY be used to declare that a structure can be extended at encoding time by +the inclusion of fields not listed in the STRUCTURE definition. + +The order qualifiers (any-order, schema-order and tag-order) MAY be used to specify a particular +order for the encoding of fields within a TLV Structure. + +A nullable qualifier MAY be used to indicate that a TLV Null MAY be encoded in place of the STRUC­ +TURE. + +**B.3.9.1. Fields** + +Fields within a STRUCTURE are assigned textual names to distinguish them from one another. Each +such name SHALL be distinct from all other field names defined within the STRUCTURE or included +via a includes statement. Fields names do not affect the encoding of the resultant TLV, but MAY +serve as either user documentation or input to code generation tools. + +Per the rules of TLV, all fields within a TLV Structure SHALL be encoded with a distinct TLV tag. +Field tags are declared by placing a tag qualifier on the field name. Both protocol-specific and con­ +text-specific tags are allowed on the fields in a STRUCTURE definition. + +For a given field if the tag qualifier is missing then the underlying type SHALL provide a default tag. +This can occur in two situations: + +1. the underlying type is a reference to a type definition that provides a default tag +2. the underlying type is a CHOICE OF pseudo-type whose alternates provide default tags. + +The tags associated with includes fields are inherited from the target FIELD GROUP definition. + +All tags associated with the fields of a TLV Structure SHALL be unique. This is true not only for tags +declared directly within the STRUCTURE definition, but also for any tags associated with fields that are +incorporated via an includes statement. + +The anonymous tag SHALL NOT be used as the tag for a field within a STRUCTURE definition. + +``` +Page 1130 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +The optional qualifier MAY be used to declare a field which can be omitted from the structure +encoding under some circumstances. + +**B.3.9.2. CHOICE OF Fields** + +A field within a STRUCTURE definition MAY be defined to be a CHOICE OF (either directly within the +STRUCTURE definition or via a type reference). Over the wire, such a field is encoded as one of the +alternate types given in the CHOICE OF definition. For example, the user-id field in the following +STRUCTURE MAY be encoded as either a TLV UTF-8 String or an Unsigned Integer. + +_STRUCTURE with CHOICE OF Field Example_ + +``` +user-information => STRUCTURE [ extensible ] +{ +user-id [1] : CHOICE OF +{ +UNSIGNED INTEGER, +STRING +} +} +``` +If a tag qualifier is given for a CHOICE OF field (e.g. [1] as shown above), that tag SHALL be used in +the encoding of the field for all possible alternates. On the other hand, if a tag qualifier is _not_ given, +then the default tag associated with the selected CHOICE OF alternate SHALL be used in the encoding. +For example, in the following structure, a context-tag of 1 will be encoded if the user-id field is an +Unsigned Integer, or 2 if the field is a String. + +_STRUCTURE with CHOICE OF Field with Default Tag Example_ + +``` +user-information => STRUCTURE [ extensible ] +{ +user-id : CHOICE OF +{ +id [1] : UNSIGNED INTEGER, +name [2] : STRING +} +} +``` +Note that, in all cases, the tag or tags associated with a CHOICE OF field SHALL be unique within the +context of the containing STRUCTURE. + +**B.3.9.3. Includes FIELD GROUP** + +A includes statement MAY be used within a STRUCTURE definition to incorporate the fields of a FIELD +GROUP defined outside the STRUCTURE. The fields of the FIELD GROUP are included in the STRUCTURE as if +they had been listed within the STRUCTURE definition itself. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1131 +``` + +A particular FIELD GROUP SHALL NOT be included more than once within a given STRUCTURE. + +The names assigned to fields within an included FIELD GROUP SHALL be distinct with respect to all +other fields contained within the enclosing STRUCTURE, whether defined directly within the STRUCTURE +itself, or included from another FIELD GROUP. + +Likewise, tags assigned to fields within an included FIELD GROUP SHALL be distinct with respect to +all other fields within the enclosing STRUCTURE. + +**B.4. Pseudo-Types** + +Pseudo-types are type-like constructs that provide flexibility in schema definitions. Some pseudo- +types, like CHOICE OF and ANY, allow for variance in the fundamental TLV types that may appear in +an encoding. Others make it easier to reuse schema constructs in multiple contexts. + +**B.4.1. ANY** + +_ANY Syntax_ + +``` +ANY +``` +ANY declares an element that can be encoded as any fundamental TLV type. Note that ANY is not a +fundamental TLV type itself, but rather a pseudo-type that identifies a range of possible encodings. +An ANY type serves a shorthand for (and is exactly equivalent to) a CHOICE OF all possible fundamen­ +tal types. + +There are no qualifiers that can be associated with an ANY type. + +_ANY Example_ + +``` +app-defined-metadata => ANY +``` +**B.4.2. CHOICE OF** + +_CHOICE OF Syntax_ + +``` +CHOICE [ qualifier ] OF { alternates } +``` +``` +qualifier (optional): +nullable +``` +``` +alternates: +alternate +alternates, alternate +``` +``` +alternate: +type-or-ref // unnamed alternate +``` +``` +Page 1132 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +identifier [ id-qualifier ] : type-or-ref // named alternate +``` +``` +id-qualifier: +tag +``` +CHOICE OF declares an element that MAY be any of a set of TLV types. CHOICE OF is considered a +pseudo-type, rather than a fundamental type, in that the CHOICE OF itself doesn’t have a representa­ +tion in the final TLV encoding. + +The allowed TLV types for a CHOICE OF, known as alternates, are given in the body of the definition. +An alternate MAY be any of the fundamental TLV types, an ANY pseudo-type, or another CHOICE OF +definition (more on this below). Additionally, an alternate MAY be a type reference (in the form of a +scoped type name) referring to a type defined outside of the CHOICE OF definition. + +A nullable qualifier MAY be used to indicate that a TLV Null can be encoded in place of the CHOICE +OF. This is exactly the same as if NULL had been listed as one of the alternates. + +**B.4.2.1. Alternate Names and Tags** + +Alternates MAY be assigned textual names to distinguish them from one another. Each such name +SHALL be unique within the particular CHOICE OF definition. Alternate names do not affect the +encoding of the resultant TLV. Rather, alternate names serve as user documentation, or as input to +code generation tools. + +Named CHOICE OF alternates MAY include at tag qualifier assigning a particular tag value to the +alternate. When qualified in this way, the given tag value serves as a default tag for the alternate +whenever the CHOICE OF appears in a context that doesn’t otherwise specify a tag. The tags assigned +within a CHOICE OF do not need to be unique, although see the discussion of Ambiguous Alternates +below. + +Both protocol-specific and context-specific tags are allowed on the alternates of a CHOICE OF defini­ +tion. + +**B.4.2.2. Nested CHOICE OF and CHOICE OF Merging** + +It is legal for an alternate within a CHOICE OF to be another CHOICE OF definition, or a type reference +to such. In this case, the effect is exactly as if the alternates of the inner CHOICE OF definition had +been declared directly with the outer definition. This merging of CHOICE OF alternates occurs to any +level of nesting, and MAY be used as a means of declaring multiple CHOICE OF that are supersets of +other CHOICE OF. + +When alternates are merged, their names are preserved. In cases where the same name appears in +nested CHOICE OF definitions, the name of the outer alternate is prepended to that of the inner alter­ +nate, separated by a dot, to form a unique name for the merged alternate. In these cases, the outer +alternate SHALL have a name in the schema, to ensure uniqueness. + +An example of invalid CHOICE OF syntax, which results in a name conflict when alternates are +merged: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1133 +``` + +_CHOICE OF Invalid Alternates Merge Example_ + +``` +CHOICE OF { +CHOICE OF { +foo: STRING, +bar: UNSIGNED INTEGER +}, +CHOICE OF { +foo: BOOLEAN, +bar: FLOAT64 +} +} +``` +The example below shows how a valid schema should look to avoid conflict: + +_CHOICE OF Valid Alternates Merge Example_ + +``` +CHOICE OF { +alt1: CHOICE OF { +foo: STRING, +bar: UNSIGNED INTEGER +}, +alt2: CHOICE OF { +foo: BOOLEAN, +bar: FLOAT64 +} +} +``` +**B.4.2.3. Ambiguous Alternates** + +A CHOICE OF MAY contain multiple alternates having the same fundamental TLV type (e.g. two alter­ +nates that are both SIGNED INTEGER). If these alternates are also encoded using the same tag, their +encoded forms are effectively indistinguishable from one another. Such alternates are referred to +as ambiguous alternates. + +Ambiguous alternates MAY occur due to the merging of nested CHOICE OF definitions (see above). +They MAY also arise in cases where the tags associated with the alternates are overridden by a tag +qualifier in an outer context; e.g. when a STRUCTURE incorporates a CHOICE OF field that has a specific +tag qualifier assigned to the field. + +Ambiguous alternates are legal in TLV Schemas. However, care SHALL be taken when introducing +ambiguous alternates to ensure that a decoder can correctly interpret the resulting encoding. This +can be achieved, for example, by signaling the appropriate interpretation via a data value (e.g. an +enumerated integer) contained elsewhere in the encoding. + +``` +Page 1134 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**B.5. Qualifiers** + +Qualifiers are annotations that provide additional information regarding the use or interpretation +of a schema construct. Often qualifiers are used to place restrictions on the form or range of values +that the construct can assume. + +**B.5.1. any-order / schema-order / tag-order** + +_Order Qualifiers Syntax_ + +``` +STRUCTURE [ any-order ] +STRUCTURE [ schema-order ] +STRUCTURE [ tag-order ] +``` +The any-order, schema-order and tag-order qualifiers MAY be used to specify a particular order for +the encoding of fields within a STRUCTURE. + +The any-order qualifier specifies that the encoder of a TLV structure is free to encode the fields of +the structure in any desired order. + +The schema-order qualifier specifies that the fields of a structure SHALL be encoded in the order +given within the associated STRUCTURE definition. If the STRUCTURE definition contains one or more +includes statements, the fields of the referenced FIELD GROUPs SHALL be encoded in the order given +in the respective FIELD GROUP definition, and at the position of the includes statement relative to +other fields within the STRUCTURE. + +The tag-order qualifier specifies that the fields of a structure SHALL be encoded in the order speci­ +fied by their tags, as defined in Section A.2.4, “Canonical Ordering of Tags”. + +Only a single ordering qualifier MAY be applied to a given STRUCTURE type. + +In the absence of an order qualifier, fields within TLV structure MAY generally be encoded in any +order. However, the author of a STRUCTURE definition MAY choose to impose custom ordering con­ +straints on some or all of the fields if so desired. Such constraints SHALL be clearly described in the +prose documentation for the schema. + +**B.5.2. extensible** + +_extensible Qualifier Syntax_ + +``` +STRUCTURE [ extensible ] +``` +The extensible qualifier is only allowed on STRUCTURE types, and declares that the structure MAY be +extended by the inclusion of fields not listed in its definition. When a structure is extended in this +way, any new fields that are included SHALL use tags that are distinct from any of those associated +with defined or included fields. + +Absent the extensible qualifier, a structure encoding SHALL NOT include fields beyond those given + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1135 +``` + +in the STRUCTURE definition. + +_extensible Qualifier Example_ + +``` +user-information => STRUCTURE [ extensible ] +{ +user-id [1] : UNSIGNED INTEGER, +first-name [2] : STRING, +last-name [3] : STRING, +email-address [4] : STRING, +} +``` +**B.5.3. id** + +_id Qualifier Syntax_ + +``` +vendor-name => VENDOR [ id uint-value ] +``` +``` +protocol-name => PROTOCOL [ id uint-value ] +``` +``` +protocol-name => PROTOCOL [ id uint-value:uint-value ] +``` +``` +protocol-name => PROTOCOL [ id vendor-name:uint-value ] +``` +The id qualifier is used to specify an identifying number associated with a VENDOR or PROTOCOL defini­ +tion. + +When applied to a VENDOR definition, the id value is a 16-bit unsigned integer specifying the Protocol +Vendor ID, which uniquely identify an organization or company. VENDOR ids are used to scope other +identifiers (e.g. PROTOCOL ids) such that organizations can independently mint these identifiers with­ +out fear of collision. + +When applied to a PROTOCOL definition, the id value MAY take three forms: + +- 32-bit unsigned integer, which is composed of a Protocol Vendor ID in the high 16-bits and a + protocol id in the low 16-bits +- two 16-bit unsigned integers (separated by a colon) specifying the Protocol Vendor ID and proto­ + col id +- vendor-name and 16-bit protocol id (separated by a colon). The vendor-name definition SHALL exist + elsewhere in the schema + +_id Qualifier Examples_ + +``` +MATTER-VENDOR-AB => VENDOR [ 0x00AB ] +``` +``` +// Equivalent definitions of the protocol introduced by MATTER-VENDOR-AB +``` +``` +Page 1136 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +vendor-ab-prot8 => PROTOCOL [ 0x00AB0008 ] +vendor-ab-prot8 => PROTOCOL [ 0x00AB:0x0008 ] +vendor-ab-prot8 => PROTOCOL [ MATTER-VENDOR-AB:8 ] +``` +**B.5.4. length** + +_length Qualifier Syntax_ + +``` +type [ length count ] // exactly count +type [ length min..max ] // between min and max (inclusive) +type [ length min.. ] // at least min +``` +The length qualifier MAY be used to constrain the number of elements in a collection type, such as +an ARRAY or LIST, or the number of bytes in a STRING or OCTET STRING type. + +**B.5.5. nullable** + +_nullable Qualifier Syntax_ + +``` +type [ nullable ] +``` +The nullable qualifier is used with ARRAY, LIST, STRUCTURE, STRING, OCTET STRING, BOOLEAN, SIGNED INTE­ +GER, UNSIGNED INTEGER, FLOAT32, FLOAT64 types. The nullable qualifier declares that a TLV Null MAY be +substituted for a value of the specified type at a particular point in an encoding. For example, in the +following sensor-sample structure, a null value MAY be encoded for the value field (e.g. in the case +the sensor was off-line at the sample time): + +_nullable Qualifier Example_ + +``` +sensor-sample => STRUCTURE +{ +timestamp [1] : UNSIGNED INTEGER, +value [2] : FLOAT64 [ nullable ], +} +``` +Applying a nullable qualifier to a type is exactly the same as defining a CHOICE OF type with alter­ +nates for the primary and NULL. For example, the sensor sample structure could also be defined as +follows: + +_nullable Qualifier Example_ + +``` +sensor-sample => STRUCTURE +{ +timestamp [1] : UNSIGNED INTEGER, +value [2] : CHOICE OF +{ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1137 +``` + +### FLOAT64, + +### NULL + +### } + +### } + +**B.5.6. optional** + +_optional Qualifier Syntax_ + +``` +... +field-name [ optional ] : type-or-ref, +... +``` +The optional qualifier declares that a field within a STRUCTURE or FIELD GROUP is optional, and MAY +be omitted by an encoder. The optional qualifier MAY only appear on the name portion of a field +definition within either a STRUCTURE or FIELD GROUP. + +Note that an optional field is distinct, both semantically and in terms of encoding, from a field +whose type has been declared nullable. In the former case the field MAY be omitted from the encod­ +ing altogether. In the latter case the field SHALL appear within the encoding, however its value +MAY be encoded as a TLV Null. It is legal to declare a field that is both optional and nullable. + +The conditions under which an optional field can be omitted depend on the semantics of the struc­ +ture. In some cases, fields MAY be omitted entirely at the discretion of the sender. In other cases, +omission of a field MAY be contingent on the value present in another field. In all cases, prose docu­ +mentation associated with the field definition SHALL make clear the rules for when the field may +be omitted. + +Optional fields are allowed within FIELD GROUP and retain their optionality when included within +STRUCTURE. + +_optional Qualifier Example_ + +``` +user-information => STRUCTURE [ extensible ] +{ +user-id [1] : UNSIGNED INTEGER, +first-name [2] : STRING, +middle-name [3, optional] : STRING, // MIGHT be omitted +last-name [4] : STRING, +email-address [5, optional] : STRING, // MIGHT be omitted +} +``` +**B.5.7. range** + +``` +Page 1138 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_range Qualifier Syntax_ + +``` +integer-type [ range min..max ] // explicit constraint (inclusive) +integer-type [ range 8-bits ] // width constraint +integer-type [ range 16-bits ] +integer-type [ range 32-bits ] +integer-type [ range 64-bits ] +``` +The range qualifier MAY be used to constrain the range of values for a numeric type such as SIGNED +INTEGER, UNSIGNED INTEGER, FLOAT32, or FLOAT64. Two forms are supported: _explicit constraints_ and +_width constraints_. Only one form MAY be applied to a given type. + +An _explicit constraint_ gives specific minimum and maximum (inclusive) values for the type. These +MAY be any value that is legal for the underlying type. + +A _width constraint_ constrains the value to fit within a specific number of bytes. Any of the width +constraints (8-bits, 16-bits, 32-bits or 64-bits) MAY be applied to SIGNED INTEGER and UNSIGNED INTEGER +types, where 8-bits, 16-bits, 32-bits and 64-bits constraints correspond to 1-octet, 2-octet, 4-octet and +8-octet element type respectively; only 32-bits constraint MAY be applied to FLOAT32 type and only +64-bits constraint MAY be applied to FLOAT64 type. + +Note that a width constraint range qualifier does not obligate an encoder to always encode the spec­ +ified number of bits. Per the TLV encoding rules, senders are always free to encode integer and +floating point values in any encoding size, bigger or smaller, that will accommodate the value. + +_range Qualifier Example_ + +``` +system-status-event => STRUCTURE +{ +timestamp [1] : UNSIGNED INTEGER [ range 32-bits ], +num-processes [2] : UNSIGNED INTEGER [ range 16-bits ], +percent-busy [3] : UNSIGNED INTEGER [ range 0..100 ], +} +``` +**B.5.8. tag** + +_tag Qualifier Syntax_ + +``` +identifier [ tag-num ] // context-specific tag +identifier [ protocol-id:tag-num ] // protocol-specific tag +identifier [ protocol-name:tag-num ] // protocol-specific tag +identifier [ *:tag-num ] // protocol-specific tag (cur. protocol) +identifier [ anonymous ] // no tag +``` +The tag qualifier is allowed on type names, field names within a STRUCTURE (STRUCTURE Fields) or +FIELD GROUP, item names within a LIST (LIST Item Tags), alternate names within a CHOICE OF (CHOICE + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1139 +``` + +OF Fields). + +The tag qualifier specifies a numeric tag value to be used when encoding a particular value. For +brevity, the tag keyword SHALL be omitted when specifying a tag qualifier. As a special case, the +keyword anonymous MAY be used to signal a value that SHALL be encoded without a tag. + +Matter TLV supports two forms of tags: Protocol-Specific Tags and Context-Specific Tags. A protocol- +specific tag is a colon-separated tuple containing a protocol-id and a tag-num. Protocol ids MAY also +be specified indirectly, by giving the name of a PROTOCOL definition (protocol-name) located else­ +where in the schema. An asterisk (*) MAY be used as a shorthand to refer to the id of the PROTOCOL +definition in which the tag qualifier appears. This protocol is referred to as the _current protocol_. + +**B.5.8.1. Explicit Tags** + +A tag qualifier that appears on a field within a STRUCTURE or FIELD GROUP, or on an item within a LIST, +specifies the exact tag to be used when encoding the associated field/item. Such a tag is called an +explicit tag, and MAY be either a context-specific, protocol-specific or anonymous (for LIST) tag. + +If a field or item lacks a tag qualifier, then the encoding will use a default tag associated with the +underlying field type, if such a tag has been specified. + +**B.5.8.2. Default Tags** + +A tag qualifier that appears on a type definition, or on an alternate within a CHOICE OF, serves as a +default tag. A default tag is used to encode a value when an explicit tag has not been given in the +schema. + +For example, a field within a STRUCTURE that refers to a type with a default tag will use that tag if no +tag qualifier has been specified on the field itself. Similarly, tag qualifiers that appear on the alter­ +nates of a CHOICE OF serve as default tags to be used when no other tag has been specified. + +Both context-specific and protocol-specific tags MAY be used as default tags. 'anonymous` tag +SHALL NOT be used as default tag. + +_Default Tag Qualifier Example_ + +``` +vendor-ab-prot8 => PROTOCOL [ id 0x00AB0008 ] +{ +ec-pub-key [0x00AB0008:1] => OCTET STRING, // default protocol-specific tag using +// a numeric protocol id +``` +``` +ec-priv-key [vendor-ab-prot8:2] => STRUCTURE // default protocol-specific +// tag using a name +{ +priv-key [1] : OCTET STRING, // explicit context-specific tag +``` +``` +pub-key [2, optional] : ec-pub-key // explicit tag overrides default tag on +// ec-pub-key +``` +``` +Page 1140 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +curve : CHOICE OF // tag depends on choice of id or name +{ +id [3] : UNSIGNED INTEGER, // default tag if id chosen +name [4] : STRING // default tag if name chosen +} +}, +``` +``` +ecdsa-sig [*:3] => STRUCTURE // shorthand for vendor-ab-prot8:3 +{ +r [1] : OCTET STRING, +s [2] : OCTET STRING +} +} // end vendor-ab-prot8 PROTOCOL +``` +**B.5.9. Documentation and Comments** + +TLV Schemas MAY include inline annotations that support the automatic generation of reference +documentation and the production of documented code. TLV Schemas follow the Javadoc style of +annotation wherein documentation is wrapped in the special multi-line comment markers /** and +*/. + +_Documentation and Comments Example_ + +``` +/** Sensor sample structure */ +sensor-sample => STRUCTURE +{ +timestamp [1] : UNSIGNED INTEGER, +value [2] : FLOAT64, +} +``` +In certain cases, documentation MAY also be placed after a construct, using /**< and */. + +_Documentation and Comments for a Construct Example_ + +``` +/** Sensor sample structure */ +sensor-sample => STRUCTURE +{ +timestamp [1] : UNSIGNED INTEGER, /**< Unix timestamp */ +value [2] : FLOAT64, /**< Sensor value */ +} +``` +Postfix annotations are allowed on STRUCTURE and FIELD GROUP members, ARRAY and LIST items, +CHOICE OF alternates, SIGNED INTEGER and UNSIGNED INTEGER enumerated values. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1141 +``` + +Non-documentation comments follow the standard C++ commenting style. + +_Documentation and Comments C++ Style Example_ + +``` +user-information => STRUCTURE [ extensible ] +{ +user-id [1] : UNSIGNED INTEGER, // 0 = Unknown user id +first-name [2] : STRING, +last-name [3] : STRING, +email-address [4] : STRING, +``` +``` +/* TODO: additional fields to be added later */ +} +``` +``` +Page 1142 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Appendix C: Tag-length-value (TLV) Payload** + +**Text Representation Format** + +**C.1. Introduction** + +This section describes a means by which to depict TLV payloads in a more user-friendly, textual rep­ +resentation. + +**C.2. Format Specification** + +**C.2.1. Tag/Value** + +TLV elements are tag/value pairs. As such, their general textual representation is as follows: + +``` +tag = value +``` +**C.2.2. Context-Specific Tags** + +The basic representation of a context-specific tag is a single scalar number. + +TLV entries using context-specific tags MAY use the basic representation alone: + +``` +2 = "hello" +``` +If the tag has a name from an associated schema, it MAY be represented using that name. The basic +representation MAY also be appended in parentheses ("(", ")"): + +``` +name (2) = "hello" +``` +**C.2.3. Protocol-Specific Tags** + +The basic representation of a protocol-specific tag SHALL be fully-qualified with "::" separating the +vendor id and the protocol number and ":" separating the protocol number and tag number. The +vendor id, protocol number and tag number are each represented using a single scalar number +represented in hexadecimal notation. + +``` +0x0000::0x0000:0x01 = 10 +``` +If the tag has a name from an associated schema, it MAY be represented using that name. The basic +representation MAY also be appended in parentheses ("(", ")"): + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1143 +``` + +``` +SmartSensorsCompany::SensingProtocol:Extension (0x00ef::0x00aa:0x01) = 10 +``` +**C.2.4. Anonymous Tags** + +TLV entries using anonymous tags SHALL display the value alone: + +``` +"hello" +``` +**C.2.5. Primitive Types** + +Signed Integer: + +``` +duration = 20 +``` +Unsigned Integer: + +``` +duration = 20U +``` +If the value is a defined constant, or enumerated value, then the string literal MAY be provided as +well: + +``` +mode = FAST (20U) +``` +UTF-8 string: + +``` +name = "Jonah" +``` +Octet String (listed as 8-bit hex digits): + +``` +data = 2f 2a fd 11 33 e2 ... +``` +Floats: + +``` +temp = 20.234 +``` +Booleans: + +``` +isOn = false +``` +``` +isOn = true +``` +``` +Page 1144 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Null: + +``` +temp = null +``` +**C.2.6. Complex Types: Structure** + +Braces ({ ... }) SHALL be used to convey the start and end of structure scope, with the members +separated by commas (,): + +``` +user-record = { +name = "Jonah", +pin = 1122 +} +``` +**C.2.7. Complex Types: Arrays** + +Square brackets ([ ... ]) SHALL be used to convey array scope, with elements in the array sepa­ +rated by commas (,). Since elements in the array are required to be anonymous, each element +SHALL display the value alone: + +``` +temp-samples = [20, 30, 40] +``` +**C.2.8. Complex Types: List** + +Double square brackets ([[ ... ]]) SHALL be used to convey list scope, with elements in the list sep­ +arated by commas (,). Since a diversity of tag types can be used in a list (including duplicates), the +tags SHALL always be present and explicitly stated: + +``` +AttributePath = [[ EndpointId = 20, ClusterId = 40 ]] +``` +**C.3. Examples** + +**C.3.1. TLV Schema** + +This is a sample TLV schema that will be used to define example TLV payloads. + +``` +temp-sample => STRUCTURE +{ +timestamp [1] : UNSIGNED INTEGER [ range 32-bits ], +temperature [2] : FLOAT64, +} +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1145 +``` + +``` +accel-sample => STRUCTURE +{ +x [1] : SIGNED INTEGER [ range 16-bits ], +y [2] : SIGNED INTEGER [ range 16-bits ], +z [3] : SIGNED INTEGER [ range 16-bits ] +} +``` +``` +temp-features-enum => UNSIGNED INTEGER [ range 0...3 ] +{ +HAS_TEMP_COMPENSATION = 1, +SUPPORTS_THRESHOLD_TRIGGERS = 2 +} +``` +``` +accel-features-enum => UNSIGNED INTEGER [ range 0...3 ] +{ +SUPPORTS_HIGH_SAMPLING = 1, +SUPPORTS_THRESHOLD_TRIGGERS = 2 +} +``` +``` +sensor-state => STRUCTURE +{ +temperature-samples [1] : ARRAY OF temperature-sample, +accel-samples [2] : ARRAY OF accel-sample, +manufacturer-name [3]: STRING, +``` +``` +// List of lists. If present, one or more of the feature lists will be present. +feature-map [4,optional] : LIST {temp-features[1]: ARRAY OF temp-features-enum, +accel-features[2]: ARRAY OF accel-features-enum}, +``` +``` +supports-idle [5] : BOOLEAN, +``` +``` +num-power-modes[6]: UNSIGNED INTEGER [ range 8-bits ], +``` +``` +supported-extensions[7] : LIST OF STRING +} +``` +**C.3.2. TLV Payloads** + +**C.3.2.1. Temperature Sample** + +``` +temperature-sample-example = +{ +``` +``` +Page 1146 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +timestamp (1) = 2023423U, +temperature (2) = 72.0 +} +``` +**C.3.2.2. Accelerometer Sample** + +``` +accelerometer-sample-example = +{ +x (1) = 10, +y (2) = 20, +z (3) = 30 +} +``` +**C.3.2.3. Sensor State** + +``` +sensor-state-example = +{ +temperature-samples (1) = +[ +{ +timestamp (1) = 2023423U, +temperature (2) = 72.0 +}, +{ +timestamp (1) = 2023U, +temperature (2) = 69.2 +}, +], +``` +``` +accel-samples (2) = +[ +{ +x (1) = 10, +y (2) = 20, +z (3) = 30, +}, +{ +x (1) = 1, +y (2) = 2, +z (3) = 3, +}, +], +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1147 +``` + +``` +manufacturer-name (3) = "SmartSensors Ltd", +``` +``` +feature-map (4) = +[[ +temp-features (1) = +[ +HAS_TEMP_COMPENSATION (1), +SUPPORTS_THRESHOLD_TRIGGERS (2) +], +``` +``` +accel-features (2) = +[ +SUPPORTS_THRESHOLD_TRIGGERS (2) +] +]], +``` +``` +supports-idle (5) = false, +``` +``` +num-power-modes (6) = 2U, +``` +``` +supported-extensions (7) = +[[ +SMARTSENSORS::SensingProtocol:Extension (0x00ef::0x00aa:0x01) = +"SUPPORTS_SMART_AVERAGING" +]] +} +``` +Page 1148 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Appendix D: Status Report Messages** + +**D.1. Overview** + +The StatusReport is a core message that encapsulates the result of an operation which a responder +sends as a reply for requests sent from an initiator, using a common message of the Secure Channel +Protocol (Protocol ID = PROTOCOL_ID_SECURE_CHANNEL). + +This section details the standard Status Report message format encoding as Matter Message Format +payloads. + +**D.2. Status Report elements** + +A Status Report message describes a protocol-specific operation result or status. + +The Status Report message SHALL have the following message header values (some of which may +be omitted within protocol messages, as per header flag rules), no matter which protocol actually +generated the status report: + +- A Protocol Vendor ID set to 0 (Matter common Vendor ID) +- A Protocol ID set to 0x0000 (PROTOCOL_ID_SECURE_CHANNEL) +- A Protocol Opcode set to 0x40 (StatusReport) + +The report message’s Application Payload SHALL consist of: + +- A mandatory _GENERAL CODE_ field, providing a general description of the status being reported. +- A mandatory _PROTOCOL SPECIFIC STATUS_ field, providing additional details +- An **optional** protocol-specific data section that MAY include any additional information that a + protocol requires + ◦ Individual protocols define the contents of this data section and how it is handled + +**D.3. Message Format** + +``` +Length Octets 0 1 +Structure, little-endian +2 octets GeneralCode +4 octets ProtocolId of Protocol-Specific Status +``` +... +2 octets ProtocolCode of Protocol-Specific Status +Variable Optional ProtocolData for protocol-specific additional details, MAY be empty + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1149 +``` + +**D.3.1. General status codes (** GeneralCode **)** + +General status codes conveyed in the GeneralCode field are uniform codes that convey both success +and failures. + +The following general status codes are defined: + +``` +Code Numeric +Value +``` +``` +Description +``` +``` +SUCCESS 0 Operation completed successfully. +FAILURE 1 Generic failure, additional details may be included in +the protocol specific status. +BAD_PRECONDITION 2 Operation was rejected by the system because the sys­ +tem is in an invalid state. +OUT_OF_RANGE 3 A value was out of a required range +BAD_REQUEST 4 A request was unrecognized or malformed +UNSUPPORTED 5 An unrecognized or unsupported request was received +UNEXPECTED 6 A request was not expected at this time +RESOURCE_EXHAUSTED 7 Insufficient resources to process the given request +BUSY 8 Device is busy and cannot handle this request at this +time +TIMEOUT 9 A timeout occurred +CONTINUE 10 Context-specific signal to proceed +ABORTED 11 Failure, may be due to a concurrency error. +INVALID_ARGUMENT 12 An invalid/unsupported argument was provided +NOT_FOUND 13 Some requested entity was not found +ALREADY_EXISTS 14 The sender attempted to create something that already +exists +PERMISSION_DENIED 15 The sender does not have sufficient permissions to exe­ +cute the requested operations. +DATA_LOSS 16 Unrecoverable data loss or corruption has occurred. +MESSAGE_TOO_LARGE 17 Message size is larger than the recipient can handle. +``` +If none of the specific codes above fits for application usage, a protocol SHALL use _FAILURE_ and +provide more information encoded in the ProtocolId and ProtocolCode subfields. + +**D.3.2. Protocol-specific codes (** ProtocolId **and** ProtocolCode **)** + +The protocol-specific portion of StatusReport messages is composed of a fully-qualified ProtocolId +which qualifies the subsequent ProtocolCode space. + +The ProtocolId is encoded as a 32 bit value of Protocol Vendor ID (upper 16 bits) and Protocol ID + +``` +Page 1150 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +under that Protocol Vendor ID (lower 16 bits), similarly to how message Protocol ID and Protocol +Vendor ID are encoded in the Protocol Header. + +The following rules apply to the encoding of the ProtocolCode protocol-specific field: + +- ProtocolCode value 0x0000 SHALL be reserved for use as success placeholder when either a Gen­ + eralCode of _SUCCESS_ (0) or _CONTINUE_ (10) are present. +- ProtocolCode value 0xFFFF SHALL be reserved to indicate that no additional protocol-specific + status code is available. +- When the GeneralCode is _FAILURE_ , the ProtocolCode value of 0xFFFF SHOULD NOT be used, since + the conveyance of specific error codes assists in troubleshooting. +- ProtocolCode values 0x0001 through 0xFFFE SHALL be used to convey protocol-specific status + indications. + +Since protocol-specific status reports are meant to convey more information than generic codes, it +is RECOMMENDED to always use a specific ProtocolCode value, rather than 0xFFFF, unless there are +no additional details to convey. + +**D.3.3. Protocol-specific data (** ProtocolData **)** + +The ProtocolData portion of the StatusReport message is composed of all data beyond the Protocol­ +Code field. If a StatusReport message of size N octets is received, the first 8 octets of payload encode +the GeneralCode, ProtocolId and ProtocolCode, while the remaining N - 8 bytes represent the proto­ +col-specific ProtocolData. + +Encoding of the ProtocolData portion of the payload depends on the ProtocolId and potentially Pro­ +tocolCode. To decode this data, the ProtocolId has to be examined and decoding SHALL be done +according to that protocol specification. For example: + +- A vendor-specific protocol would encode additional custom error metadata in the ProtocolData. +- The Bulk transfer (BDX) protocol does not require additional error information and will always + have ProtocolData empty. + +**D.4. Presenting** StatusReport **messages in protocol** + +**specifications** + +In order to simplify referring to StatusReport messages, the following mnemonic encoding will be +used in the descriptive text for a given protocol. + +References to StatusReport messages take one of the following forms: + +- No ProtocolData present: + ◦ StatusReport(GeneralCode: , ProtocolId: , ProtocolCode: ) + ▪ Example 1: StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: + START_OFFSET_NOT_SUPPORTED) + ▪ Encodes as: 01 00 02 00 00 00 52 00 + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1151 +``` + +``` +▪ Example 2: StatusReport(GeneralCode: SUCCESS, ProtocolId: {VendorID=0xFFF1, Proto­ +colId=0xAABB}, ProtocolCode: 0) +▪ Encodes as: 00 00 BB AA F1 FF 00 00 +``` +- Additional ProtocolData present: + ◦ StatusReport(GeneralCode: , ProtocolId: , ProtocolCode: , Protocol­ + Data: ) + ▪ Example: StatusReport(GeneralCode: FAILURE, ProtocolId: {VendorID=0xFFF1, Proto­ + colId=0xAABB}, ProtocolCode: 9921, ProtocolData: [0x55, 0x66, 0xEE, 0xFF]) + ▪ Encodes as: 01 00 BB AA F1 FF C1 26 55 66 EE FF + +Page 1152 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Appendix E: Matter-Specific ASN.1 Object** + +**Identifiers (OIDs)** + +Matter defines custom ASN.1 OID values, which are listed in the table below under the +1.3.6.1.4.1.37244 private arc. These OID values are assigned by the Connectivity Standards Alliance +for use with Matter. + +_Table 108. ASN.1 Matter-Specific Object Identifiers_ + +``` +Dot Notation ASN.1 Notation Description +1.3.6.1.4.1.37244.1.1 iso(1) org(3) dod(6) internet(1) pri­ +vate(4) enterprise(1) zigbee(37244) +matter-op-cert(1) node-id(1) +``` +``` +Matter Operational Certificate DN +attribute for node identifier +``` +``` +1.3.6.1.4.1.37244.1.2 iso(1) org(3) dod(6) internet(1) pri­ +vate(4) enterprise(1) zigbee(37244) +matter-op-cert(1) firmware-signing- +id(2) +``` +``` +Matter Operational Certificate DN +attribute for firmware signing iden­ +tifier +``` +``` +1.3.6.1.4.1.37244.1.3 iso(1) org(3) dod(6) internet(1) pri­ +vate(4) enterprise(1) zigbee(37244) +matter-op-cert(1) ica-id(3) +``` +``` +Matter Operational Certificate DN +attribute for Intermediate CA (ICA) +identifier +1.3.6.1.4.1.37244.1.4 iso(1) org(3) dod(6) internet(1) pri­ +vate(4) enterprise(1) zigbee(37244) +matter-op-cert(1) root-ca-id(4) +``` +``` +Matter Operational Certificate DN +attribute for Root Certificate Author­ +ity (CA) identifier +1.3.6.1.4.1.37244.1.5 iso(1) org(3) dod(6) internet(1) pri­ +vate(4) enterprise(1) zigbee(37244) +matter-op-cert(1) fabric-id(5) +``` +``` +Matter Operational Certificate DN +attribute for fabric identifier +``` +``` +1.3.6.1.4.1.37244.1.6 iso(1) org(3) dod(6) internet(1) pri­ +vate(4) enterprise(1) zigbee(37244) +matter-op-cert(1) case-authenticated- +tag(6) +``` +``` +Matter Operational Certificate DN +attribute for CASE Authenticated Tag +``` +``` +1.3.6.1.4.1.37244.2.1 iso(1) org(3) dod(6) internet(1) pri­ +vate(4) enterprise(1) zigbee(37244) +matter-att-cert(2) vid(1) +``` +``` +Matter Device Attestation Certificate +DN attribute for the Vendor ID (VID) +``` +``` +1.3.6.1.4.1.37244.2.2 iso(1) org(3) dod(6) internet(1) pri­ +vate(4) enterprise(1) zigbee(37244) +matter-att-cert(2) pid(2) +``` +``` +Matter Device Attestation Certificate +DN attribute for the Product ID (PID) +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1153 +``` + +Page 1154 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Appendix F: Cryptographic test vectors for** + +**some procedures** + +**F.1. Certification Declaration CMS test vector** + +This subsection contains worked examples of encoding a Certification Declaration, which is con­ +veyed by the Attestation Information payload during the Device Attestation Procedure. + +The CSA CD signing certificate and associated private key which are provided in the vectors are +only for exemplary purposes and are not official CD signing material. + +The first example Certification Declaration has the following qualities: + +- Both dac_origin_vendor_id and dac_origin_product_id are absent +- The product_id_array contains a single PID + +The content of this first example is shown below: + +``` +===== Algorithm inputs ===== +-> format_version = 1 +-> vendor_id = 0xFFF1 +-> product_id_array = [ 0x8000 ] +-> device_type_id = 0x1234 +-> certificate_id = "ZIG20141ZB330001-24" +-> security_level = 0 +-> security_information = 0 +-> version_number = 0x2694 +-> certification_type = 0 +-> dac_origin_vendor_id is not present +-> dac_origin_product_id is not present +-> authorized_paa_list is not present +``` +``` +-> Sample CSA CD Signing Certificate: +-----BEGIN CERTIFICATE----- +MIIBszCCAVqgAwIBAgIIRdrzneR6oI8wCgYIKoZIzj0EAwIwKzEpMCcGA1UEAwwg +TWF0dGVyIFRlc3QgQ0QgU2lnbmluZyBBdXRob3JpdHkwIBcNMjEwNjI4MTQyMzQz +WhgPOTk5OTEyMzEyMzU5NTlaMCsxKTAnBgNVBAMMIE1hdHRlciBUZXN0IENEIFNp +Z25pbmcgQXV0aG9yaXR5MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEPDmJIkUr +VcrzicJb0bykZWlSzLkOiGkkmthHRlMBTL+V1oeWXgNrUhxRA35rjO3vyh60QEZp +T6CIgu7WUZ3suqNmMGQwEgYDVR0TAQH/BAgwBgEB/wIBATAOBgNVHQ8BAf8EBAMC +AQYwHQYDVR0OBBYEFGL6gjNZrPqplj4c+hQK3fUE83FgMB8GA1UdIwQYMBaAFGL6 +gjNZrPqplj4c+hQK3fUE83FgMAoGCCqGSM49BAMCA0cAMEQCICxUXOTkV9im8NnZ +u+vW7OHd/n+MbZps83UyH8b6xxOEAiBUB3jodDlyUn7t669YaGIgtUB48s1OYqdq +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1155 +``` + +``` +58u5L/VMiw== +-----END CERTIFICATE----- +``` +``` +-> Sample CSA CD Signing Private Key: +-----BEGIN EC PRIVATE KEY----- +MHcCAQEEIK7zSEEW6UgexXvgRy30G/SZBk5QJK2GnspeiJgC1IB1oAoGCCqGSM49 +AwEHoUQDQgAEPDmJIkUrVcrzicJb0bykZWlSzLkOiGkkmthHRlMBTL+V1oeWXgNr +UhxRA35rjO3vyh60QEZpT6CIgu7WUZ3sug== +-----END EC PRIVATE KEY----- +``` +``` +===== Intermediate outputs ===== +-> Encoded TLV of sample Certification Declaration (54 bytes): +00000000 15 24 00 01 25 01 f1 ff 36 02 05 00 80 18 25 03 |.$..%...6.....%.| +00000010 34 12 2c 04 13 5a 49 47 32 30 31 34 31 5a 42 33 |4.,..ZIG20141ZB3| +00000020 33 30 30 30 31 2d 32 34 24 05 00 24 06 00 25 07 |30001-24$..$..%.| +00000030 94 26 24 08 00 18 |.&$...| +00000036 +``` +``` +===== Algorithm outputs ===== +-> Encoded CMS SignedData of Certification Declaration (235 bytes): +00000000 30 81 e8 06 09 2a 86 48 86 f7 0d 01 07 02 a0 81 |0....*.H........| +00000010 da 30 81 d7 02 01 03 31 0d 30 0b 06 09 60 86 48 |.0.....1.0...`.H| +00000020 01 65 03 04 02 01 30 45 06 09 2a 86 48 86 f7 0d |.e....0E..*.H...| +00000030 01 07 01 a0 38 04 36 15 24 00 01 25 01 f1 ff 36 |....8.6.$..%...6| +00000040 02 05 00 80 18 25 03 34 12 2c 04 13 5a 49 47 32 |.....%.4.,..ZIG2| +00000050 30 31 34 31 5a 42 33 33 30 30 30 31 2d 32 34 24 |0141ZB330001-24$| +00000060 05 00 24 06 00 25 07 94 26 24 08 00 18 31 7c 30 |..$..%..&$...1|0| +00000070 7a 02 01 03 80 14 62 fa 82 33 59 ac fa a9 96 3e |z.....b..3Y....>| +00000080 1c fa 14 0a dd f5 04 f3 71 60 30 0b 06 09 60 86 |........q`0...`.| +00000090 48 01 65 03 04 02 01 30 0a 06 08 2a 86 48 ce 3d |H.e....0...*.H.=| +000000a0 04 03 02 04 46 30 44 02 20 43 a6 3f 2b 94 3d f3 |....F0D. C.?+.=.| +000000b0 3c 38 b3 e0 2f ca a7 5f e3 53 2a eb bf 5e 63 f5 |<8../.._.S*..^c.| +000000c0 bb db c0 b1 f0 1d 3c 4f 60 02 20 4c 1a bf 5f 18 |...... format_version = 1 +-> vendor_id = 0xFFF2 +-> product_id_array = [ 0x8001, 0x8002 ] +-> device_type_id = 0x1234 +-> certificate_id = "ZIG20142ZB330002-24" +-> security_level = 0 +-> security_information = 0 +-> version_number = 0x2694 +-> certification_type = 0 +-> dac_origin_vendor_id = 0xFFF1 +-> dac_origin_product_id = 0x8000 +-> authorized_paa_list = [ 78:5c:e7:05:b8:6b:8f:4e:6f:c7:93:aa:60:cb:43:ea:69:68:82:d5 +] +``` +``` +-> Sample CSA CD Signing Certificate: +-----BEGIN CERTIFICATE----- +MIIBszCCAVqgAwIBAgIIRdrzneR6oI8wCgYIKoZIzj0EAwIwKzEpMCcGA1UEAwwg +TWF0dGVyIFRlc3QgQ0QgU2lnbmluZyBBdXRob3JpdHkwIBcNMjEwNjI4MTQyMzQz +WhgPOTk5OTEyMzEyMzU5NTlaMCsxKTAnBgNVBAMMIE1hdHRlciBUZXN0IENEIFNp +Z25pbmcgQXV0aG9yaXR5MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEPDmJIkUr +VcrzicJb0bykZWlSzLkOiGkkmthHRlMBTL+V1oeWXgNrUhxRA35rjO3vyh60QEZp +T6CIgu7WUZ3suqNmMGQwEgYDVR0TAQH/BAgwBgEB/wIBATAOBgNVHQ8BAf8EBAMC +AQYwHQYDVR0OBBYEFGL6gjNZrPqplj4c+hQK3fUE83FgMB8GA1UdIwQYMBaAFGL6 +gjNZrPqplj4c+hQK3fUE83FgMAoGCCqGSM49BAMCA0cAMEQCICxUXOTkV9im8NnZ +u+vW7OHd/n+MbZps83UyH8b6xxOEAiBUB3jodDlyUn7t669YaGIgtUB48s1OYqdq +58u5L/VMiw== +-----END CERTIFICATE----- +``` +``` +-> Sample CSA CD Signing Private Key: +-----BEGIN EC PRIVATE KEY----- +MHcCAQEEIK7zSEEW6UgexXvgRy30G/SZBk5QJK2GnspeiJgC1IB1oAoGCCqGSM49 +AwEHoUQDQgAEPDmJIkUrVcrzicJb0bykZWlSzLkOiGkkmthHRlMBTL+V1oeWXgNr +UhxRA35rjO3vyh60QEZpT6CIgu7WUZ3sug== +-----END EC PRIVATE KEY----- +``` +``` +===== Intermediate outputs ===== +-> Encoded TLV of sample Certification Declaration (90 bytes): +00000000 15 24 00 01 25 01 f2 ff 36 02 05 01 80 05 02 80 |.$..%...6.......| +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1157 +``` + +``` +00000010 18 25 03 34 12 2c 04 13 5a 49 47 32 30 31 34 32 |.%.4.,..ZIG20142| +00000020 5a 42 33 33 30 30 30 32 2d 32 34 24 05 00 24 06 |ZB330002-24$..$.| +00000030 00 25 07 94 26 24 08 00 25 09 f1 ff 25 0a 00 80 |.%..&$..%...%...| +00000040 36 0b 10 14 78 5c e7 05 b8 6b 8f 4e 6f c7 93 aa |6...x\...k.No...| +00000050 60 cb 43 ea 69 68 82 d5 18 18 |`.C.ih....| +0000005a +``` +``` +===== Algorithm outputs ===== +-> Encoded CMS SignedData of Certification Declaration (273 bytes): +00000000 30 82 01 0d 06 09 2a 86 48 86 f7 0d 01 07 02 a0 |0.....*.H.......| +00000010 81 ff 30 81 fc 02 01 03 31 0d 30 0b 06 09 60 86 |..0.....1.0...`.| +00000020 48 01 65 03 04 02 01 30 69 06 09 2a 86 48 86 f7 |H.e....0i..*.H..| +00000030 0d 01 07 01 a0 5c 04 5a 15 24 00 01 25 01 f2 ff |.....\.Z.$..%...| +00000040 36 02 05 01 80 05 02 80 18 25 03 34 12 2c 04 13 |6........%.4.,..| +00000050 5a 49 47 32 30 31 34 32 5a 42 33 33 30 30 30 32 |ZIG20142ZB330002| +00000060 2d 32 34 24 05 00 24 06 00 25 07 94 26 24 08 00 |-24$..$..%..&$..| +00000070 25 09 f1 ff 25 0a 00 80 36 0b 10 14 78 5c e7 05 |%...%...6...x\..| +00000080 b8 6b 8f 4e 6f c7 93 aa 60 cb 43 ea 69 68 82 d5 |.k.No...`.C.ih..| +00000090 18 18 31 7d 30 7b 02 01 03 80 14 62 fa 82 33 59 |..1}0{.....b..3Y| +000000a0 ac fa a9 96 3e 1c fa 14 0a dd f5 04 f3 71 60 30 |....>........q`0| +000000b0 0b 06 09 60 86 48 01 65 03 04 02 01 30 0a 06 08 |...`.H.e....0...| +000000c0 2a 86 48 ce 3d 04 03 02 04 47 30 45 02 20 4a e9 |*.H.=....G0E. J.| +000000d0 c9 b7 f8 aa 68 61 0a dd 84 e4 12 91 fc 8f 4d c5 |....ha........M.| +000000e0 33 fc a2 9d c1 ff f2 25 3c 09 cd 32 f7 75 02 21 |3......%<..2.u.!| +000000f0 00 9c 0a 5f de f9 e0 08 d1 cc 8b b7 c3 95 9c db |..._............| +00000100 65 c4 61 25 cb 72 95 08 1e 47 b5 c1 31 e4 d1 f4 |e.a%.r...G..1...| +00000110 8c |.| +00000111 +``` +**F.2. Device Attestation Response test vector** + +This subsection contains a worked example of the Attestation Information to be generated in the +AttestationResponse Command when executing the Device Attestation Procedure. + +The Device Attestation key pair shown is an example, not to be reused in implementations. + +``` +NOTE This test vector does NOT contain the optional Firmware Information payload. It is +omitted. +``` +``` +===== Algorithm inputs ===== +-> AttestationNonce (example): +e0:42:1b:91:c6:fd:cd:b4:0e:2a:4d:2c:f3:1d:b2:b4:e1:8b:41:1b:1d:3a:d4:d1:2a:9d:90:aa:8e +:52:fa:e2 +``` +``` +Page 1158 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +-> Attestation challenge (example): 7a:49:53:05:d0:77:79:a4:94:dd:39:a0:85:1b:66:0d + +-> Device attestation private key (example): +38:f3:e0:a1:f1:45:ba:1b:f3:e4:4b:55:2d:ef:65:27:3d:1d:8e:27:6a:a3:14:ac:74:2e:b1:28:93 + +:3b:a6:4b + +-----BEGIN EC PRIVATE KEY----- + +MHcCAQEEIDjz4KHxRbob8+RLVS3vZSc9HY4naqMUrHQusSiTO6ZLoAoGCCqGSM49 +AwEHoUQDQgAEzlz477BdTu55DQpx1cARu3RyQNuiFFiEXTPjSwr2ZRYzBjqASy/4 + +XcqyAZoKtvVZV3X+jYX716B8joN9pNWouQ== + +-----END EC PRIVATE KEY----- + +-> Device attestation public key (example): +04:ce:5c:f8:ef:b0:5d:4e:ee:79:0d:0a:71:d5:c0:11:bb:74:72:40:db:a2:14:58:84:5d:33:e3:4b +:0a:f6:65:16:33:06:3a:80:4b:2f:f8:5d:ca:b2:01:9a:0a:b6:f5:59:57:75:fe:8d:85:fb:d7:a0:7 +c:8e:83:7d:a4:d5:a8:b9 + +-----BEGIN PUBLIC KEY----- + +MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEzlz477BdTu55DQpx1cARu3RyQNui + +FFiEXTPjSwr2ZRYzBjqASy/4XcqyAZoKtvVZV3X+jYX716B8joN9pNWouQ== +-----END PUBLIC KEY----- + +-> Desired timestamp: 2021-06-15T20:15:57Z +-> Desired timestamp in epoch-s: 677103357 +-> vendor specific [0xfff1:0x3e:0x1] = +73:61:6d:70:6c:65:5f:76:65:6e:64:6f:72:5f:72:65:73:65:72:76:65:64:31 + +("sample_vendor_reserved1") +-> vendor specific [0xfff1:0x3e:0x3] = +76:65:6e:64:6f:72:5f:72:65:73:65:72:76:65:64:33:5f:65:78:61:6d:70:6c:65 + +("vendor_reserved3_example") + +===== Intermediate outputs ===== + +-> attestation_elements_message: + +00000000 15 31 01 11 01 30 82 01 0d 06 09 2a 86 48 86 f7 |.1...0.....*.H..| +00000010 0d 01 07 02 a0 81 ff 30 81 fc 02 01 03 31 0d 30 |.......0.....1.0| + +00000020 0b 06 09 60 86 48 01 65 03 04 02 01 30 69 06 09 |...`.H.e....0i..| + +00000030 2a 86 48 86 f7 0d 01 07 01 a0 5c 04 5a 15 24 00 |*.H.......\.Z.$.| +00000040 01 25 01 f2 ff 36 02 05 01 80 05 02 80 18 25 03 |.%...6........%.| + +00000050 34 12 2c 04 13 5a 49 47 32 30 31 34 32 5a 42 33 |4.,..ZIG20142ZB3| + +00000060 33 30 30 30 32 2d 32 34 24 05 00 24 06 00 25 07 |30002-24$..$..%.| + +00000070 94 26 24 08 00 25 09 f1 ff 25 0a 00 80 36 0b 10 |.&$..%...%...6..| +00000080 14 78 5c e7 05 b8 6b 8f 4e 6f c7 93 aa 60 cb 43 |.x\...k.No...`.C| + +00000090 ea 69 68 82 d5 18 18 31 7d 30 7b 02 01 03 80 14 |.ih....1}0{.....| + +000000a0 62 fa 82 33 59 ac fa a9 96 3e 1c fa 14 0a dd f5 |b..3Y....>......| +000000b0 04 f3 71 60 30 0b 06 09 60 86 48 01 65 03 04 02 |..q`0...`.H.e...| + +000000c0 01 30 0a 06 08 2a 86 48 ce 3d 04 03 02 04 47 30 |.0...*.H.=....G0| + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1159 +``` + +``` +000000d0 45 02 20 4a e9 c9 b7 f8 aa 68 61 0a dd 84 e4 12 |E. J.....ha.....| +000000e0 91 fc 8f 4d c5 33 fc a2 9d c1 ff f2 25 3c 09 cd |...M.3......%<..| +000000f0 32 f7 75 02 21 00 9c 0a 5f de f9 e0 08 d1 cc 8b |2.u.!..._.......| +00000100 b7 c3 95 9c db 65 c4 61 25 cb 72 95 08 1e 47 b5 |.....e.a%.r...G.| +00000110 c1 31 e4 d1 f4 8c 30 02 20 e0 42 1b 91 c6 fd cd |.1....0. .B.....| +00000120 b4 0e 2a 4d 2c f3 1d b2 b4 e1 8b 41 1b 1d 3a d4 |..*M,......A..:.| +00000130 d1 2a 9d 90 aa 8e 52 fa e2 26 03 fd c6 5b 28 d0 |.*....R..&...[(.| +00000140 f1 ff 3e 00 01 00 17 73 61 6d 70 6c 65 5f 76 65 |..>....sample_ve| +00000150 6e 64 6f 72 5f 72 65 73 65 72 76 65 64 31 d0 f1 |ndor_reserved1..| +00000160 ff 3e 00 03 00 18 76 65 6e 64 6f 72 5f 72 65 73 |.>....vendor_res| +00000170 65 72 76 65 64 33 5f 65 78 61 6d 70 6c 65 18 |erved3_example.| +0000017f +``` +``` +-> attestation_tbs := attestation_elements_message || attestation_challenge +-> attestation_tbs (NOT sent over the wire): +00000000 15 31 01 11 01 30 82 01 0d 06 09 2a 86 48 86 f7 |.1...0.....*.H..| +00000010 0d 01 07 02 a0 81 ff 30 81 fc 02 01 03 31 0d 30 |.......0.....1.0| +00000020 0b 06 09 60 86 48 01 65 03 04 02 01 30 69 06 09 |...`.H.e....0i..| +00000030 2a 86 48 86 f7 0d 01 07 01 a0 5c 04 5a 15 24 00 |*.H.......\.Z.$.| +00000040 01 25 01 f2 ff 36 02 05 01 80 05 02 80 18 25 03 |.%...6........%.| +00000050 34 12 2c 04 13 5a 49 47 32 30 31 34 32 5a 42 33 |4.,..ZIG20142ZB3| +00000060 33 30 30 30 32 2d 32 34 24 05 00 24 06 00 25 07 |30002-24$..$..%.| +00000070 94 26 24 08 00 25 09 f1 ff 25 0a 00 80 36 0b 10 |.&$..%...%...6..| +00000080 14 78 5c e7 05 b8 6b 8f 4e 6f c7 93 aa 60 cb 43 |.x\...k.No...`.C| +00000090 ea 69 68 82 d5 18 18 31 7d 30 7b 02 01 03 80 14 |.ih....1}0{.....| +000000a0 62 fa 82 33 59 ac fa a9 96 3e 1c fa 14 0a dd f5 |b..3Y....>......| +000000b0 04 f3 71 60 30 0b 06 09 60 86 48 01 65 03 04 02 |..q`0...`.H.e...| +000000c0 01 30 0a 06 08 2a 86 48 ce 3d 04 03 02 04 47 30 |.0...*.H.=....G0| +000000d0 45 02 20 4a e9 c9 b7 f8 aa 68 61 0a dd 84 e4 12 |E. J.....ha.....| +000000e0 91 fc 8f 4d c5 33 fc a2 9d c1 ff f2 25 3c 09 cd |...M.3......%<..| +000000f0 32 f7 75 02 21 00 9c 0a 5f de f9 e0 08 d1 cc 8b |2.u.!..._.......| +00000100 b7 c3 95 9c db 65 c4 61 25 cb 72 95 08 1e 47 b5 |.....e.a%.r...G.| +00000110 c1 31 e4 d1 f4 8c 30 02 20 e0 42 1b 91 c6 fd cd |.1....0. .B.....| +00000120 b4 0e 2a 4d 2c f3 1d b2 b4 e1 8b 41 1b 1d 3a d4 |..*M,......A..:.| +00000130 d1 2a 9d 90 aa 8e 52 fa e2 26 03 fd c6 5b 28 d0 |.*....R..&...[(.| +00000140 f1 ff 3e 00 01 00 17 73 61 6d 70 6c 65 5f 76 65 |..>....sample_ve| +00000150 6e 64 6f 72 5f 72 65 73 65 72 76 65 64 31 d0 f1 |ndor_reserved1..| +00000160 ff 3e 00 03 00 18 76 65 6e 64 6f 72 5f 72 65 73 |.>....vendor_res| +00000170 65 72 76 65 64 33 5f 65 78 61 6d 70 6c 65 18 7a |erved3_example.z| +00000180 49 53 05 d0 77 79 a4 94 dd 39 a0 85 1b 66 0d |IS..wy...9...f.| +0000018f +``` +``` +-> SHA-256 of attestation_tbs used for signature (NOT sent over the wire): +``` +Page 1160 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +1d:f1:05:b1:30:84:c3:cc:13:19:9e:df:07:b8:76:9e:be:2e:26:0d:84:8f:27:a6:ca:b6:6d:d9:a5 + +:8c:ea:b1 + +-> Fixed K for sample signature of attestation_tbs: +c5:35:83:3f:47:86:4f:cb:d8:b5:e3:2e:fb:a8:84:35:c0:fb:0c:9f:db:0f:00:34:98:0a:41:84:cc + +:f0:52:4d + +-> Attestation signature: +79:82:53:5d:24:cf:e1:4a:71:ab:04:24:cf:0b:ac:f1:e3:45:48:7e:d5:0f:1a:c0:bc:25:9e:cc:fb +:39:08:1e:d7:a7:52:18:8d:9f:76:f9:06:37:03:eb:24:0f:9c:d1:4b:0a:43:e7:41:fe:60:ef:2a:8 +1:63:5a:ea:5b:48:4d + +===== Algorithm outputs ===== + +-> AttestationElements field of AttestationResponse (len 383 bytes): +00000000 15 31 01 11 01 30 82 01 0d 06 09 2a 86 48 86 f7 |.1...0.....*.H..| + +00000010 0d 01 07 02 a0 81 ff 30 81 fc 02 01 03 31 0d 30 |.......0.....1.0| + +00000020 0b 06 09 60 86 48 01 65 03 04 02 01 30 69 06 09 |...`.H.e....0i..| +00000030 2a 86 48 86 f7 0d 01 07 01 a0 5c 04 5a 15 24 00 |*.H.......\.Z.$.| + +00000040 01 25 01 f2 ff 36 02 05 01 80 05 02 80 18 25 03 |.%...6........%.| + +00000050 34 12 2c 04 13 5a 49 47 32 30 31 34 32 5a 42 33 |4.,..ZIG20142ZB3| + +00000060 33 30 30 30 32 2d 32 34 24 05 00 24 06 00 25 07 |30002-24$..$..%.| +00000070 94 26 24 08 00 25 09 f1 ff 25 0a 00 80 36 0b 10 |.&$..%...%...6..| + +00000080 14 78 5c e7 05 b8 6b 8f 4e 6f c7 93 aa 60 cb 43 |.x\...k.No...`.C| + +00000090 ea 69 68 82 d5 18 18 31 7d 30 7b 02 01 03 80 14 |.ih....1}0{.....| +000000a0 62 fa 82 33 59 ac fa a9 96 3e 1c fa 14 0a dd f5 |b..3Y....>......| + +000000b0 04 f3 71 60 30 0b 06 09 60 86 48 01 65 03 04 02 |..q`0...`.H.e...| + +000000c0 01 30 0a 06 08 2a 86 48 ce 3d 04 03 02 04 47 30 |.0...*.H.=....G0| + +000000d0 45 02 20 4a e9 c9 b7 f8 aa 68 61 0a dd 84 e4 12 |E. J.....ha.....| +000000e0 91 fc 8f 4d c5 33 fc a2 9d c1 ff f2 25 3c 09 cd |...M.3......%<..| + +000000f0 32 f7 75 02 21 00 9c 0a 5f de f9 e0 08 d1 cc 8b |2.u.!..._.......| + +00000100 b7 c3 95 9c db 65 c4 61 25 cb 72 95 08 1e 47 b5 |.....e.a%.r...G.| +00000110 c1 31 e4 d1 f4 8c 30 02 20 e0 42 1b 91 c6 fd cd |.1....0. .B.....| + +00000120 b4 0e 2a 4d 2c f3 1d b2 b4 e1 8b 41 1b 1d 3a d4 |..*M,......A..:.| + +00000130 d1 2a 9d 90 aa 8e 52 fa e2 26 03 fd c6 5b 28 d0 |.*....R..&...[(.| + +00000140 f1 ff 3e 00 01 00 17 73 61 6d 70 6c 65 5f 76 65 |..>....sample_ve| +00000150 6e 64 6f 72 5f 72 65 73 65 72 76 65 64 31 d0 f1 |ndor_reserved1..| + +00000160 ff 3e 00 03 00 18 76 65 6e 64 6f 72 5f 72 65 73 |.>....vendor_res| + +00000170 65 72 76 65 64 33 5f 65 78 61 6d 70 6c 65 18 |erved3_example.| +0000017f + +-> AttestationSignature field of AttestationResponse (len 64 bytes): +00000000 79 82 53 5d 24 cf e1 4a 71 ab 04 24 cf 0b ac f1 |y.S]$..Jq..$....| + +00000010 e3 45 48 7e d5 0f 1a c0 bc 25 9e cc fb 39 08 1e |.EH~.....%...9..| + +00000020 d7 a7 52 18 8d 9f 76 f9 06 37 03 eb 24 0f 9c d1 |..R...v..7..$...| + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1161 +``` + +``` +00000030 4b 0a 43 e7 41 fe 60 ef 2a 81 63 5a ea 5b 48 4d |K.C.A.`.*.cZ.[HM| +00000040 +``` +**F.3. Node Operational CSR Response test vector** + +This subsection contains a worked example of the NOCSR Information to be generated in the CSR­ +Response Command when executing the Node Operational CSR Procedure. + +The CSR shown is valid for the provided Node Operational public key. + +The Device Attestation key pair shown is an example, not to be reused in implementations. + +``` +===== Algorithm inputs ===== +-> CSRNonce: +81:4a:4d:4c:1c:4a:8e:bb:ea:db:0a:e2:82:f9:91:eb:13:ac:5f:9f:ce:94:30:93:19:aa:94:09:6c +:8c:d4:b8 +-> Attestation challenge (example): 7a:49:53:05:d0:77:79:a4:94:dd:39:a0:85:1b:66:0d +``` +``` +-> Device attestation private key (example): +38:f3:e0:a1:f1:45:ba:1b:f3:e4:4b:55:2d:ef:65:27:3d:1d:8e:27:6a:a3:14:ac:74:2e:b1:28:93 +:3b:a6:4b +-----BEGIN EC PRIVATE KEY----- +MHcCAQEEIDjz4KHxRbob8+RLVS3vZSc9HY4naqMUrHQusSiTO6ZLoAoGCCqGSM49 +AwEHoUQDQgAEzlz477BdTu55DQpx1cARu3RyQNuiFFiEXTPjSwr2ZRYzBjqASy/4 +XcqyAZoKtvVZV3X+jYX716B8joN9pNWouQ== +-----END EC PRIVATE KEY----- +``` +``` +-> Device attestation public key (example): +04:ce:5c:f8:ef:b0:5d:4e:ee:79:0d:0a:71:d5:c0:11:bb:74:72:40:db:a2:14:58:84:5d:33:e3:4b +:0a:f6:65:16:33:06:3a:80:4b:2f:f8:5d:ca:b2:01:9a:0a:b6:f5:59:57:75:fe:8d:85:fb:d7:a0:7 +c:8e:83:7d:a4:d5:a8:b9 +-----BEGIN PUBLIC KEY----- +MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEzlz477BdTu55DQpx1cARu3RyQNui +FFiEXTPjSwr2ZRYzBjqASy/4XcqyAZoKtvVZV3X+jYX716B8joN9pNWouQ== +-----END PUBLIC KEY----- +``` +``` +===== Intermediate outputs ===== +-> Candidate Operational Private Key: +1c:18:82:e8:7f:80:d8:1a:25:9a:62:b6:ea:02:db:08:17:e2:10:68:46:84:2b:eb:3a:ab:c2:53:86 +:a9:1e:89 +-----BEGIN EC PRIVATE KEY----- +MHcCAQEEIBwYguh/gNgaJZpituoC2wgX4hBoRoQr6zqrwlOGqR6JoAoGCCqGSM49 +AwEHoUQDQgAEXKJ542aCwtRs59TPiWeEZwi1ufhbnNr9jKiFJhLLDwx6cTFOyNyc +ljTd7v7p9j8Oi9faz8O2pFMqrdiallHNbg== +-----END EC PRIVATE KEY----- +``` +``` +Page 1162 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +-> Candidate Operational Public Key: +04:5c:a2:79:e3:66:82:c2:d4:6c:e7:d4:cf:89:67:84:67:08:b5:b9:f8:5b:9c:da:fd:8c:a8:85:26 +:12:cb:0f:0c:7a:71:31:4e:c8:dc:9c:96:34:dd:ee:fe:e9:f6:3f:0e:8b:d7:da:cf:c3:b6:a4:53:2 + +a:ad:d8:9a:96:51:cd:6e + +-----BEGIN PUBLIC KEY----- + +MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXKJ542aCwtRs59TPiWeEZwi1ufhb +nNr9jKiFJhLLDwx6cTFOyNycljTd7v7p9j8Oi9faz8O2pFMqrdiallHNbg== + +-----END PUBLIC KEY----- + +Certificate Request: + +Data: + +Version: 1 (0x0) + +Subject: O = CSA +Subject Public Key Info: + +Public Key Algorithm: id-ecPublicKey + +Public-Key: (256 bit) +pub: + +04:5c:a2:79:e3:66:82:c2:d4:6c:e7:d4:cf:89:67: + +84:67:08:b5:b9:f8:5b:9c:da:fd:8c:a8:85:26:12: + +cb:0f:0c:7a:71:31:4e:c8:dc:9c:96:34:dd:ee:fe: +e9:f6:3f:0e:8b:d7:da:cf:c3:b6:a4:53:2a:ad:d8: + +9a:96:51:cd:6e + +ASN1 OID: prime256v1 +NIST CURVE: P-256 + +Attributes: + +Requested Extensions: + +Signature Algorithm: ecdsa-with-SHA256 +30:45:02:20:0e:67:5e:e1:b3:bb:fe:15:2a:17:4a:f5:35:e2: + +2d:55:ce:10:c1:50:ca:c0:1b:31:18:de:05:e8:fd:9f:10:48: + +02:21:00:d8:8c:57:cc:6e:74:f0:e5:48:8a:26:16:7a:07:fd: +6d:be:f1:aa:ad:72:1c:58:0b:6e:ae:21:be:5e:6d:0c:72 + +-> CSR bytes DER: + +00000000 30 81 da 30 81 81 02 01 00 30 0e 31 0c 30 0a 06 |0..0.....0.1.0..| +00000010 03 55 04 0a 0c 03 43 53 41 30 59 30 13 06 07 2a |.U....CSA0Y0...*| + +00000020 86 48 ce 3d 02 01 06 08 2a 86 48 ce 3d 03 01 07 |.H.=....*.H.=...| + +00000030 03 42 00 04 5c a2 79 e3 66 82 c2 d4 6c e7 d4 cf |.B..\.y.f...l...| + +00000040 89 67 84 67 08 b5 b9 f8 5b 9c da fd 8c a8 85 26 |.g.g....[......&| +00000050 12 cb 0f 0c 7a 71 31 4e c8 dc 9c 96 34 dd ee fe |....zq1N....4...| + +00000060 e9 f6 3f 0e 8b d7 da cf c3 b6 a4 53 2a ad d8 9a |..?........S*...| + +00000070 96 51 cd 6e a0 11 30 0f 06 09 2a 86 48 86 f7 0d |.Q.n..0...*.H...| +00000080 01 09 0e 31 02 30 00 30 0a 06 08 2a 86 48 ce 3d |...1.0.0...*.H.=| + +00000090 04 03 02 03 48 00 30 45 02 20 0e 67 5e e1 b3 bb |....H.0E. .g^...| + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1163 +``` + +``` +000000a0 fe 15 2a 17 4a f5 35 e2 2d 55 ce 10 c1 50 ca c0 |..*.J.5.-U...P..| +000000b0 1b 31 18 de 05 e8 fd 9f 10 48 02 21 00 d8 8c 57 |.1.......H.!...W| +000000c0 cc 6e 74 f0 e5 48 8a 26 16 7a 07 fd 6d be f1 aa |.nt..H.&.z..m...| +000000d0 ad 72 1c 58 0b 6e ae 21 be 5e 6d 0c 72 |.r.X.n.!.^m.r| +000000dd +``` +``` +-> Sample vendor_reserved1: +73:61:6d:70:6c:65:5f:76:65:6e:64:6f:72:5f:72:65:73:65:72:76:65:64:31 +-> Sample vendor_reserved3: +76:65:6e:64:6f:72:5f:72:65:73:65:72:76:65:64:33:5f:65:78:61:6d:70:6c:65 +-> nocsr_elements_message: +00000000 15 30 01 dd 30 81 da 30 81 81 02 01 00 30 0e 31 |.0..0..0.....0.1| +00000010 0c 30 0a 06 03 55 04 0a 0c 03 43 53 41 30 59 30 |.0...U....CSA0Y0| +00000020 13 06 07 2a 86 48 ce 3d 02 01 06 08 2a 86 48 ce |...*.H.=....*.H.| +00000030 3d 03 01 07 03 42 00 04 5c a2 79 e3 66 82 c2 d4 |=....B..\.y.f...| +00000040 6c e7 d4 cf 89 67 84 67 08 b5 b9 f8 5b 9c da fd |l....g.g....[...| +00000050 8c a8 85 26 12 cb 0f 0c 7a 71 31 4e c8 dc 9c 96 |...&....zq1N....| +00000060 34 dd ee fe e9 f6 3f 0e 8b d7 da cf c3 b6 a4 53 |4.....?........S| +00000070 2a ad d8 9a 96 51 cd 6e a0 11 30 0f 06 09 2a 86 |*....Q.n..0...*.| +00000080 48 86 f7 0d 01 09 0e 31 02 30 00 30 0a 06 08 2a |H......1.0.0...*| +00000090 86 48 ce 3d 04 03 02 03 48 00 30 45 02 20 0e 67 |.H.=....H.0E. .g| +000000a0 5e e1 b3 bb fe 15 2a 17 4a f5 35 e2 2d 55 ce 10 |^.....*.J.5.-U..| +000000b0 c1 50 ca c0 1b 31 18 de 05 e8 fd 9f 10 48 02 21 |.P...1.......H.!| +000000c0 00 d8 8c 57 cc 6e 74 f0 e5 48 8a 26 16 7a 07 fd |...W.nt..H.&.z..| +000000d0 6d be f1 aa ad 72 1c 58 0b 6e ae 21 be 5e 6d 0c |m....r.X.n.!.^m.| +000000e0 72 30 02 20 81 4a 4d 4c 1c 4a 8e bb ea db 0a e2 |r0. .JML.J......| +000000f0 82 f9 91 eb 13 ac 5f 9f ce 94 30 93 19 aa 94 09 |......_...0.....| +00000100 6c 8c d4 b8 30 03 17 73 61 6d 70 6c 65 5f 76 65 |l...0..sample_ve| +00000110 6e 64 6f 72 5f 72 65 73 65 72 76 65 64 31 30 05 |ndor_reserved10.| +00000120 18 76 65 6e 64 6f 72 5f 72 65 73 65 72 76 65 64 |.vendor_reserved| +00000130 33 5f 65 78 61 6d 70 6c 65 18 |3_example.| +0000013a +``` +``` +-> nocsr_tbs (NOT sent over the wire): +00000000 15 30 01 dd 30 81 da 30 81 81 02 01 00 30 0e 31 |.0..0..0.....0.1| +00000010 0c 30 0a 06 03 55 04 0a 0c 03 43 53 41 30 59 30 |.0...U....CSA0Y0| +00000020 13 06 07 2a 86 48 ce 3d 02 01 06 08 2a 86 48 ce |...*.H.=....*.H.| +00000030 3d 03 01 07 03 42 00 04 5c a2 79 e3 66 82 c2 d4 |=....B..\.y.f...| +00000040 6c e7 d4 cf 89 67 84 67 08 b5 b9 f8 5b 9c da fd |l....g.g....[...| +00000050 8c a8 85 26 12 cb 0f 0c 7a 71 31 4e c8 dc 9c 96 |...&....zq1N....| +00000060 34 dd ee fe e9 f6 3f 0e 8b d7 da cf c3 b6 a4 53 |4.....?........S| +00000070 2a ad d8 9a 96 51 cd 6e a0 11 30 0f 06 09 2a 86 |*....Q.n..0...*.| +00000080 48 86 f7 0d 01 09 0e 31 02 30 00 30 0a 06 08 2a |H......1.0.0...*| +``` +Page 1164 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +00000090 86 48 ce 3d 04 03 02 03 48 00 30 45 02 20 0e 67 |.H.=....H.0E. .g| + +000000a0 5e e1 b3 bb fe 15 2a 17 4a f5 35 e2 2d 55 ce 10 |^.....*.J.5.-U..| + +000000b0 c1 50 ca c0 1b 31 18 de 05 e8 fd 9f 10 48 02 21 |.P...1.......H.!| +000000c0 00 d8 8c 57 cc 6e 74 f0 e5 48 8a 26 16 7a 07 fd |...W.nt..H.&.z..| + +000000d0 6d be f1 aa ad 72 1c 58 0b 6e ae 21 be 5e 6d 0c |m....r.X.n.!.^m.| + +000000e0 72 30 02 20 81 4a 4d 4c 1c 4a 8e bb ea db 0a e2 |r0. .JML.J......| +000000f0 82 f9 91 eb 13 ac 5f 9f ce 94 30 93 19 aa 94 09 |......_...0.....| + +00000100 6c 8c d4 b8 30 03 17 73 61 6d 70 6c 65 5f 76 65 |l...0..sample_ve| + +00000110 6e 64 6f 72 5f 72 65 73 65 72 76 65 64 31 30 05 |ndor_reserved10.| + +00000120 18 76 65 6e 64 6f 72 5f 72 65 73 65 72 76 65 64 |.vendor_reserved| +00000130 33 5f 65 78 61 6d 70 6c 65 18 7a 49 53 05 d0 77 |3_example.zIS..w| + +00000140 79 a4 94 dd 39 a0 85 1b 66 0d |y...9...f.| + +0000014a + +-> SHA-256 of nocsr_tbs used for signature (NOT sent over the wire): +e2:62:65:69:65:2b:49:e1:5b:6e:d5:b2:42:92:bf:28:e8:e0:e9:5d:e4:25:14:e1:03:a4:30:30:18 + +:16:cf:3f + +-> Fixed K for sample signature of nocsr_tbs: +a9:c0:d7:f2:b5:1f:51:e3:75:05:3d:c7:0e:53:f5:4e:b1:86:59:c7:d2:99:47:94:f6:8d:b5:08:bb + +:53:05:5f + +-> Attestation signature: +87:8e:46:cf:fa:83:c8:32:96:eb:27:2e:bc:37:1c:1f:ef:ee:6d:69:54:f3:78:9f:d3:d2:27:e1:64 +:13:d3:d4:75:a6:2f:d0:12:b9:19:d9:95:8b:c7:3d:7c:63:b3:cc:1e:f2:b6:2c:18:e0:cc:10:2e:d +1:ba:4d:ac:85:fe:ea + +===== Algorithm outputs ===== +-> NOCSRElements field of CSRResponse (len 314 bytes): + +00000000 15 30 01 dd 30 81 da 30 81 81 02 01 00 30 0e 31 |.0..0..0.....0.1| + +00000010 0c 30 0a 06 03 55 04 0a 0c 03 43 53 41 30 59 30 |.0...U....CSA0Y0| + +00000020 13 06 07 2a 86 48 ce 3d 02 01 06 08 2a 86 48 ce |...*.H.=....*.H.| +00000030 3d 03 01 07 03 42 00 04 5c a2 79 e3 66 82 c2 d4 |=....B..\.y.f...| + +00000040 6c e7 d4 cf 89 67 84 67 08 b5 b9 f8 5b 9c da fd |l....g.g....[...| + +00000050 8c a8 85 26 12 cb 0f 0c 7a 71 31 4e c8 dc 9c 96 |...&....zq1N....| +00000060 34 dd ee fe e9 f6 3f 0e 8b d7 da cf c3 b6 a4 53 |4.....?........S| + +00000070 2a ad d8 9a 96 51 cd 6e a0 11 30 0f 06 09 2a 86 |*....Q.n..0...*.| + +00000080 48 86 f7 0d 01 09 0e 31 02 30 00 30 0a 06 08 2a |H......1.0.0...*| +00000090 86 48 ce 3d 04 03 02 03 48 00 30 45 02 20 0e 67 |.H.=....H.0E. .g| + +000000a0 5e e1 b3 bb fe 15 2a 17 4a f5 35 e2 2d 55 ce 10 |^.....*.J.5.-U..| + +000000b0 c1 50 ca c0 1b 31 18 de 05 e8 fd 9f 10 48 02 21 |.P...1.......H.!| + +000000c0 00 d8 8c 57 cc 6e 74 f0 e5 48 8a 26 16 7a 07 fd |...W.nt..H.&.z..| +000000d0 6d be f1 aa ad 72 1c 58 0b 6e ae 21 be 5e 6d 0c |m....r.X.n.!.^m.| + +000000e0 72 30 02 20 81 4a 4d 4c 1c 4a 8e bb ea db 0a e2 |r0. .JML.J......| + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1165 +``` + +``` +000000f0 82 f9 91 eb 13 ac 5f 9f ce 94 30 93 19 aa 94 09 |......_...0.....| +00000100 6c 8c d4 b8 30 03 17 73 61 6d 70 6c 65 5f 76 65 |l...0..sample_ve| +00000110 6e 64 6f 72 5f 72 65 73 65 72 76 65 64 31 30 05 |ndor_reserved10.| +00000120 18 76 65 6e 64 6f 72 5f 72 65 73 65 72 76 65 64 |.vendor_reserved| +00000130 33 5f 65 78 61 6d 70 6c 65 18 |3_example.| +0000013a +-> AttestationSignature field of CSRResponse (len 64 bytes): +00000000 87 8e 46 cf fa 83 c8 32 96 eb 27 2e bc 37 1c 1f |..F....2..'..7..| +00000010 ef ee 6d 69 54 f3 78 9f d3 d2 27 e1 64 13 d3 d4 |..miT.x...'.d...| +00000020 75 a6 2f d0 12 b9 19 d9 95 8b c7 3d 7c 63 b3 cc |u./........=|c..| +00000030 1e f2 b6 2c 18 e0 cc 10 2e d1 ba 4d ac 85 fe ea |...,.......M....| +00000040 +``` +**F.4. Check-In Protocol test vectors** + +This subsection contains worked examples of the Check-In Protocol encryption and decryption. + +**Test 1** + +``` +===== Encryption algorithm inputs ===== +-> Symmetric Key: d9:0e:13:18:0d:00:ba:ad:d2:0c:f5:ed:49:13:d3:ff +-> Server counter: 0c:00:00:00 +-> Application data : '' +``` +``` +===== Intermediate outputs ===== +-> generated Nonce: 45:80:d2:c6:f1:31:0d:c4:eb:64:f1:f8:e8 +-> Ciphertext: bd:c2:1f:b5 +-> Tag: 19:5d:74:7d:d2:87:9b:2b:0d:43:ce:5b:1c:56:50:78 +``` +``` +===== Encryption algorithm outputs ===== +-> Check-in message payload : +45:80:d2:c6:f1:31:0d:c4:eb:64:f1:f8:e8:bd:c2:1f:b5:19:5d:74:7d:d2:87:9b:2b:0d:43:ce:5b +:1c:56:50:78 +``` +``` +===== Decryption algorithm inputs ===== +-> Check-in message payload : +45:80:d2:c6:f1:31:0d:c4:eb:64:f1:f8:e8:bd:c2:1f:b5:19:5d:74:7d:d2:87:9b:2b:0d:43:ce:5b +:1c:56:50:78 +-> Symmetric Key: d9:0e:13:18:0d:00:ba:ad:d2:0c:f5:ed:49:13:d3:ff +-> Client counter: 0b:00:00:00 +``` +``` +===== Decryption algorithm outputs ===== +-> Received counter: 0c:00:00:00 +``` +``` +Page 1166 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +-> Application data : '' +-> Valid Check-In message +``` +**Test 2** + +``` +===== Encryption algorithm inputs ===== +-> Symmetric Key: 18:fd:bc:ea:ef:01:95:5b:0e:c8:75:ed:a3:ae:6e:e8 +-> Server counter: 0f:00:00:00 +-> Application data : 'This' +``` +``` +===== Intermediate outputs ===== +-> generated Nonce: 9b:02:ed:21:ee:0c:7b:49:19:85:50:2e:37 +-> Ciphertext: 2d:bd:7b:3f:8b:4f:8e:3c +-> Tag: 5a:d9:94:19:38:9f:41:a8:d6:09:93:8c:67:a8:6d:65 +``` +``` +===== Encryption algorithm outputs ===== +-> Check-in message payload : +9b:02:ed:21:ee:0c:7b:49:19:85:50:2e:37:2d:bd:7b:3f:8b:4f:8e:3c:5a:d9:94:19:38:9f:41:a8 +:d6:09:93:8c:67:a8:6d:65 +``` +``` +===== Decryption algorithm inputs ===== +-> Check-in message payload : +9b:02:ed:21:ee:0c:7b:49:19:85:50:2e:37:2d:bd:7b:3f:8b:4f:8e:3c:5a:d9:94:19:38:9f:41:a8 +:d6:09:93:8c:67:a8:6d:65 +-> Symmetric Key: 18:fd:bc:ea:ef:01:95:5b:0e:c8:75:ed:a3:ae:6e:e8 +-> Client counter: 0b:00:00:00 +``` +``` +===== Decryption algorithm outputs ===== +-> Received counter: 0f:00:00:00 +-> Application data : 'This' +-> Valid Check-In message +``` +**Test 3** + +``` +===== Encryption algorithm inputs ===== +-> Symmetric Key: d9:0e:13:18:0d:00:ba:ad:d2:0c:f5:ed:49:13:d3:ff +-> Server counter: 0b:00:00:00 +-> Application data : 'This is a' +``` +``` +===== Intermediate outputs ===== +-> generated Nonce: aa:84:bc:60:88:6a:63:a8:47:5d:5d:be:b5 +-> Ciphertext: 6d:63:5f:a9:52:85:ae:33:62:66:13:c7:63 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1167 +``` + +``` +-> Tag: 6c:e3:e3:b2:a8:b1:3a:8c:89:be:f7:68:91:e8:e2:96 +``` +``` +===== Encryption algorithm outputs ===== +-> Check-in message payload : +aa:84:bc:60:88:6a:63:a8:47:5d:5d:be:b5:6d:63:5f:a9:52:85:ae:33:62:66:13:c7:63:6c:e3:e3 +:b2:a8:b1:3a:8c:89:be:f7:68:91:e8:e2:96 +``` +``` +===== Decryption algorithm inputs ===== +-> Check-in message payload : +aa:84:bc:60:88:6a:63:a8:47:5d:5d:be:b5:6d:63:5f:a9:52:85:ae:33:62:66:13:c7:63:6c:e3:e3 +:b2:a8:b1:3a:8c:89:be:f7:68:91:e8:e2:96 +-> Symmetric Key: d9:0e:13:18:0d:00:ba:ad:d2:0c:f5:ed:49:13:d3:ff +-> Client counter: 0b:00:00:00 +``` +``` +===== Decryption algorithm outputs ===== +-> Received counter: 0b:00:00:00 +-> Application data : 'This is a' +-> Invalid Check-In message - Received counter has already been used +``` +**Test 4** + +``` +===== Encryption algorithm inputs ===== +-> Symmetric Key: ca:67:d4:1f:f7:11:29:10:fd:d1:8a:1b:f9:9e:a9:74 +-> Server counter: 0b:00:00:00 +-> Application data : 'This is a longer' +``` +``` +===== Intermediate outputs ===== +-> generated Nonce: 7a:97:72:24:3c:97:c8:7d:5f:3a:31:c4:e6 +-> Ciphertext: db:bc:1a:a5:66:c4:43:c2:05:86:06:6b:42:7b:fc:aa:ad:78:da:4a +-> Tag: 10:5a:13:42:ad:bf:3f:47:98:cd:81:b9:ef:97:bb:b7 +``` +``` +===== Encryption algorithm outputs ===== +-> Check-in message payload : +7a:97:72:24:3c:97:c8:7d:5f:3a:31:c4:e6:db:bc:1a:a5:66:c4:43:c2:05:86:06:6b:42:7b:fc:aa +:ad:78:da:4a:10:5a:13:42:ad:bf:3f:47:98:cd:81:b9:ef:97:bb:b7 +``` +``` +===== Decryption algorithm inputs ===== +-> Check-in message payload +:7a:97:72:24:3c:97:c8:7d:5f:3a:31:c4:e6:db:bc:1a:a5:66:c4:43:c2:05:86:06:6b:42:7b:fc:a +a:ad:78:da:4a:10:5a:13:42:ad:bf:3f:47:98:cd:81:b9:ef:97:bb:b7 +-> Symmetric Key: ca:67:d4:1f:f7:11:29:10:fd:d1:8a:1b:f9:9e:a9:74 +-> Client counter: 0f:00:00:00 +``` +``` +Page 1168 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +===== Decryption algorithm outputs ===== +-> Received counter: 0b:00:00:00 +-> Application data : 'This is a longer' +-> Invalid Check-In message - Received counter has already been used +``` +**Test 5** + +This test only had decryption processing because it tests the nonce validation that only applies to +the decryption process. + +``` +===== Decryption algorithm inputs ===== +-> Check-in message payload : +f9:34:67:6e:a6:e0:70:7b:7a:d7:81:4f:f8:2e:5b:18:d1:9a:23:b2:e4:fa:df:82:92:53:51:7f:f3 +:c9:1d:8d:47:84:31:5a:1e:32:08:b8:ec:f6:11:8b:02:1a:5a:4c:d4:e9:d4:13:8d:ff:29:71 +-> Symmetric Key: ca:67:d4:1f:f7:11:29:10:fd:d1:8a:1b:f9:9e:a9:74 +-> Client counter: 0b:00:00:00 +``` +``` +===== Decryption algorithm outputs ===== +-> Failed to decrypt Check-In message. +``` +**Test 6** + +This test only had decryption processing because it tests the nonce validation that only applies to +the decryption process. + +``` +===== Decryption algorithm inputs ===== +-> Check-in message payload : +06:34:67:6e:a6:e0:70:7b:7a:d7:81:4f:f8:29:5b:18:d1:9a:23:b2:e4:fa:df:82:92:53:51:7f:f3 +:c9:1d:8d:47:84:2e:41:02:3c:03:ad:66:ac:4d:ca:72:47:e0:e4:c6:6b:d9:d3:99:13:e2:3d:82:3 +2:b9:61:fa:92:26 +-> Symmetric Key: ca:67:d4:1f:f7:11:29:10:fd:d1:8a:1b:f9:9e:a9:74 +-> Client counter: 0f:00:00:00 +``` +``` +===== Decryption algorithm outputs ===== +-> Received counter: 0b:00:00:00 +-> Application data : 'This is a longer longer string' +-> Invalid Check-In message - Nonce and received counter do not match. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1169 +``` + +Page 1170 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Appendix G: Minimal Resource** + +**Requirements** + +This is a list of various resources required by a Node implementation, along with references to +where the minimal requirements for each resource type are defined. + +``` +Resource Minimal requirement definition +Fabric Section 11.18.5, “Attributes” +Operational Certificate Section 11.18.5, “Attributes” +ACL Entry ACL +ACL Entry subject AccessControlEntryStruct +ACL Entry target AccessControlEntryStruct +Scene "Maximum Number of Scenes" in Scenes Man­ +agement cluster in the Cluster Library +Binding Section 9.6.1, “Binding Mutation” +Group Section 2.11.1.2, “Group Limits” +Group key Section 2.11.1.2, “Group Limits” +Group peer state entries Section 4.18.2, “Group Peer State” +Read path Section 2.11.2.1, “Read Interaction Limits” +Subscription Section 2.11.2.2, “Subscribe Interaction Limits” +Subscription path Section 2.11.2.2, “Subscribe Interaction Limits” +IPv6 multicast group Section 2.11.1.2, “Group Limits” +IPv6 Prefix Section 4.2.2, “Matter Node Behavior” +IPv6 route Section 4.2.2, “Matter Node Behavior” +IPv6 neighbor cache entry Section 4.2.2, “Matter Node Behavior” +CASE session Section 4.14.2.8, “Minimal Number of CASE Ses­ +sions”. +ICD Check-In registered clients ClientsSupportedPerFabric +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1171 +``` + diff --git a/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_DEVICE_SPEC.md b/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_DEVICE_SPEC.md new file mode 100644 index 000000000..c124aa7ee --- /dev/null +++ b/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_DEVICE_SPEC.md @@ -0,0 +1,9150 @@ +# Matter Device Library Specification + +# Version 1.4. + +``` +Document: 23-27351-006_Matter-1.4.1-Device-Library-Specification.pdf +March 17, 2025 +Sponsored by: Connectivity Standards Alliance +Accepted by: This document has been accepted for release by the Connectivity +Standards Alliance Board of Directors on March 17, 2025 +Abstract: The Matter Device Library Specification defines fundamental +requirements for Matter Device Types. +Keywords: Referenced in Chapter 1. +``` +Copyright © 2022-2025 Connectivity Standards Alliance, Inc. +508 Second Street, Suite 109B Davis, CA 95616 - USA +[http://www.csa-iot.org](http://www.csa-iot.org) +All rights reserved. + +Permission is granted to members of the Connectivity Standards Alliance to reproduce this +document for their own use or the use of other Connectivity Standards Alliance members only, +provided this notice is included. All other rights reserved. Duplication for sale, or for commercial or +for-profit use is strictly prohibited without the prior written consent of the Connectivity Standards +Alliance. + + + +# Matter Device Library + +``` +Version 1.4.1, 2025-03-12 06:42:16 -0700: Approved +``` + + +**Copyright Notice, License and Disclaimer** + +Copyright © Connectivity Standards Alliance (2021-2023). All rights reserved. The information +within this document is the property of the Connectivity Standards Alliance and its use and disclo­ +sure are restricted, except as expressly set forth herein. + +Connectivity Standards Alliance hereby grants you a fully-paid, non-exclusive, nontransferable, +worldwide, limited and revocable license (without the right to sublicense), under Connectivity Stan­ +dards Alliance’s applicable copyright rights, to view, download, save, reproduce and use the docu­ +ment solely for your own internal purposes and in accordance with the terms of the license set +forth herein. This license does not authorize you to, and you expressly warrant that you shall not: +(a) permit others (outside your organization) to use this document; (b) post or publish this docu­ +ment; (c) modify, adapt, translate, or otherwise change this document in any manner or create any +derivative work based on this document; (d) remove or modify any notice or label on this docu­ +ment, including this Copyright Notice, License and Disclaimer. The Connectivity Standards Alliance +does not grant you any license hereunder other than as expressly stated herein. + +Elements of this document may be subject to third party intellectual property rights, including +without limitation, patent, copyright or trademark rights, and any such third party may or may not +be a member of the Connectivity Standards Alliance. Connectivity Standards Alliance members +grant other Connectivity Standards Alliance members certain intellectual property rights as set +forth in the Connectivity Standards Alliance IPR Policy. Connectivity Standards Alliance members +do not grant you any rights under this license. The Connectivity Standards Alliance is not responsi­ +ble for, and shall not be held responsible in any manner for, identifying or failing to identify any or +all such third party intellectual property rights. Please visit [http://www.csa-iot.org](http://www.csa-iot.org) for more information +on how to become a member of the Connectivity Standards Alliance. + +This document and the information contained herein are provided on an “AS IS” basis and the Con­ +nectivity Standards Alliance DISCLAIMS 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 INTELLEC­ +TUAL PROPERTY RIGHTS INCLUDING PATENT, COPYRIGHT OR TRADEMARK RIGHTS); OR (B) ANY +IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR +NONINFRINGEMENT. IN NO EVENT WILL THE CONNECTIVITY STANDARDS ALLIANCE BE LIABLE +FOR ANY LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF BUSI­ +NESS, OR FOR ANY OTHER DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTAL, 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 in this document may be trademarks that are the sole prop­ +erty of their respective owners. + +This notice and disclaimer must be included on all copies of this document. + +Connectivity Standards Alliance +508 Second Street, Suite 206 +Davis, CA 95616, USA + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1 +``` + +Page 2 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Revision History** + +``` +Revision Date Details Editor +1 September 23, 2022 Version 1.0 Robert Szewczyk +2 May 17, 2023 Version 1.1 Robert Szewczyk +3 October 18, 2023 Version 1.2 Robert Szewczyk +4 April 17, 2024 Version 1.3 Robert Szewczyk +5 November 4, 2024 Version 1.4 Robert Szewczyk +6 March 17, 2024 Version 1.4.1 Robert Szewczyk +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 3 +``` + +Page 4 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +## Table of Contents + + + + + + + + + + + + +- Copyright Notice, License and Disclaimer.   +- Revision History.   + - References.   + - CSA Reference Documents.   + - Provisional.   + - List of Provisional Items.   +- 1. Base Device Type.   + - 1.1. Base Device Type.   + - 1.1.1. Revision History.   + - 1.1.2. Overview.   + - 1.1.3. Conditions.   + - 1.1.4. Common Capability Conditions.   + - 1.1.5. Device Type Class Conditions.   + - 1.1.6. Endpoint Type Class Conditions.   + - 1.1.7. Cluster Requirements.   + - 1.1.8. Element Requirements.   +- 2. Utility Device Types.   + - 2.1. Root Node.   + - 2.1.1. Revision History.   + - 2.1.2. Classification.   + - 2.1.3. Conditions.   + - 2.1.4. Device Type Requirements.   + - 2.1.5. Cluster Requirements.   + - 2.1.6. Element Requirements.   + - 2.1.7. Endpoint Composition.   + - 2.2. Power Source.   + - 2.2.1. Classification.   + - 2.2.2. Revision History.   + - 2.2.3. Cluster Requirements.   + - 2.3. OTA Requestor.   + - 2.3.1. Revision History.   + - 2.3.2. Classification.   + - 2.3.3. Cluster Requirements.   + - 2.4. OTA Provider.   + - 2.4.1. Revision History.   + - 2.4.2. Classification.   + - 2.4.3. Cluster Requirements.   + - 2.5. Bridged Node.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 2.5.1. Revision History.   + - 2.5.2. Classification.   + - 2.5.3. Conditions.   + - 2.5.4. Device Type Requirements.   + - 2.5.5. Cluster Requirements.   + - 2.5.6. Endpoint Composition.   + - 2.6. Electrical Sensor.   + - 2.6.1. Revision History.   + - 2.6.2. Classification.   + - 2.6.3. Device Type Requirements.   + - 2.6.4. Cluster Requirements.   + - 2.7. Device Energy Management.   + - 2.7.1. Revision History.   + - 2.7.2. Classification.   + - 2.7.3. Conditions.   + - 2.7.4. Cluster Requirements.   + - 2.7.5. Element Requirements.   + - 2.8. Secondary Network Interface.   + - 2.8.1. Revision History.   + - 2.8.2. Classification.   + - 2.8.3. Cluster Requirements.   + - 2.9. Joint Fabric Administrator.   + - 2.9.1. Joint Fabric Architecture.   + - 2.9.2. Revision History.   + - 2.9.3. Classification.   + - 2.9.4. Cluster Requirements.   +- 3. Application Device Types.   +- 4. Lighting Device Types.   + - 4.1. On/Off Light.   + - 4.1.1. Revision History.   + - 4.1.2. Classification.   + - 4.1.3. Conditions.   + - 4.1.4. Cluster Requirements.   + - 4.1.5. Element Requirements.   + - 4.2. Dimmable Light   + - 4.2.1. Revision History.   + - 4.2.2. Classification.   + - 4.2.3. Conditions.   + - 4.2.4. Cluster Requirements.   + - 4.2.5. Element Requirements.   + - 4.3. Color Temperature Light   + - 4.3.1. Revision History.   + - 4.3.2. Classification.   + - 4.3.3. Conditions.   + - 4.3.4. Cluster Requirements.   + - 4.3.5. Element Requirements.   + - 4.4. Extended Color Light.   + - 4.4.1. Revision History.   + - 4.4.2. Classification.   + - 4.4.3. Conditions.   + - 4.4.4. Cluster Requirements.   + - 4.4.5. Element Requirements.   +- 5. Smart Plugs/Outlets and other Actuators.   + - 5.1. On/Off Plug-in Unit.   + - 5.1.1. Revision History.   + - 5.1.2. Classification.   + - 5.1.3. Conditions.   + - 5.1.4. Cluster Requirements.   + - 5.1.5. Element Requirements.   + - 5.2. Dimmable Plug-In Unit.   + - 5.2.1. Revision History.   + - 5.2.2. Classification.   + - 5.2.3. Conditions.   + - 5.2.4. Cluster Requirements.   + - 5.2.5. Element Requirements.   + - 5.3. Mounted On/Off Control.   + - 5.3.1. Revision History.   + - 5.3.2. Classification.   + - 5.3.3. Conditions.   + - 5.3.4. Cluster Requirements.   + - 5.3.5. Element Requirements.   + - 5.4. Mounted Dimmable Load Control.   + - 5.4.1. Revision History.   + - 5.4.2. Classification.   + - 5.4.3. Conditions.   + - 5.4.4. Cluster Requirements.   + - 5.4.5. Element Requirements.   + - 5.5. Pump.   + - 5.5.1. Revision History.   + - 5.5.2. Classification.   + - 5.5.3. Conditions.   + - 5.5.4. Cluster Requirements.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 5.5.5. Cluster Restrictions.   + - 5.6. Water Valve Device Type.   + - 5.6.1. Revision History.   + - 5.6.2. Classification.   + - 5.6.3. Conditions.   + - 5.6.4. Cluster Requirements.   + - 5.6.5. Device implementation recommendations   +- 6. Switches and Controls Device Types.   + - 6.1. On/Off Light Switch.   + - 6.1.1. Revision History.   + - 6.1.2. Classification.   + - 6.1.3. Conditions.   + - 6.1.4. Cluster Requirements.   + - 6.2. Dimmer Switch.   + - 6.2.1. Revision History.   + - 6.2.2. Classification.   + - 6.2.3. Conditions.   + - 6.2.4. Cluster Requirements.   + - 6.3. Color Dimmer Switch.   + - 6.3.1. Revision History.   + - 6.3.2. Classification.   + - 6.3.3. Conditions.   + - 6.3.4. Cluster Requirements.   + - 6.4. Control Bridge.   + - 6.4.1. Revision History.   + - 6.4.2. Classification.   + - 6.4.3. Conditions.   + - 6.4.4. Cluster Requirements.   + - 6.5. Pump Controller.   + - 6.5.1. Revision History.   + - 6.5.2. Classification.   + - 6.5.3. Cluster Requirements.   + - 6.6. Generic Switch.   + - 6.6.1. Revision History.   + - 6.6.2. Classification.   + - 6.6.3. Conditions.   + - 6.6.4. Cluster Requirements.   + - 6.6.5. Relation with other Switch device types (informative).   +- 7. Sensor Device Types.   + - 7.1. Contact Sensor Device Type.   + - 7.1.1. Revision History.   + - 7.1.2. Classification.   + - 7.1.3. Conditions.   + - 7.1.4. Cluster Requirements.   +- 7.2. Light Sensor.   + - 7.2.1. Revision History.   + - 7.2.2. Classification.   + - 7.2.3. Conditions.   + - 7.2.4. Cluster Requirements.   +- 7.3. Occupancy Sensor Device Type.   + - 7.3.1. Revision History.   + - 7.3.2. Classification.   + - 7.3.3. Conditions.   + - 7.3.4. Cluster Requirements.   + - 7.3.5. Multi-modality sensors.   +- 7.4. Temperature Sensor.   + - 7.4.1. Revision History.   + - 7.4.2. Classification.   + - 7.4.3. Conditions.   + - 7.4.4. Cluster Requirements.   +- 7.5. Pressure Sensor.   + - 7.5.1. Revision History.   + - 7.5.2. Classification.   + - 7.5.3. Conditions.   + - 7.5.4. Cluster Requirements.   +- 7.6. Flow Sensor.   + - 7.6.1. Revision History.   + - 7.6.2. Classification.   + - 7.6.3. Conditions.   + - 7.6.4. Cluster Requirements.   +- 7.7. Humidity Sensor.   + - 7.7.1. Revision History.   + - 7.7.2. Classification.   + - 7.7.3. Conditions.   + - 7.7.4. Cluster Requirements.   +- 7.8. On/Off Sensor.   + - 7.8.1. Revision History.   + - 7.8.2. Classification.   + - 7.8.3. Conditions.   + - 7.8.4. Cluster Requirements.   +- 7.9. Smoke CO Alarm.   + - 7.9.1. Revision History.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 7.9.2. Classification.   + - 7.9.3. Conditions.   + - 7.9.4. Device Type Requirements.   + - 7.9.5. Cluster Requirements.   + - 7.10. Air Quality Sensor.   + - 7.10.1. Revision History.   + - 7.10.2. Classification.   + - 7.10.3. Conditions.   + - 7.10.4. Cluster Requirements   + - 7.11. Water Freeze Detector Device Type.   + - 7.11.1. Revision History.   + - 7.11.2. Classification.   + - 7.11.3. Conditions.   + - 7.11.4. Cluster Requirements   + - 7.11.5. Element Requirements.   + - 7.12. Water Leak Detector Device Type.   + - 7.12.1. Revision History.   + - 7.12.2. Classification.   + - 7.12.3. Conditions.   + - 7.12.4. Cluster Requirements   + - 7.12.5. Element Requirements.   + - 7.13. Rain Sensor Device Type.   + - 7.13.1. Revision History.   + - 7.13.2. Classification.   + - 7.13.3. Conditions.   + - 7.13.4. Cluster Requirements   + - 7.13.5. Element Requirements.   +- 8. Closure Device Types.   + - 8.1. Door Lock Device Type.   + - 8.1.1. Revision History.   + - 8.1.2. Classification.   + - 8.1.3. Conditions.   + - 8.1.4. Cluster Requirements.   + - 8.1.5. Element Requirements.   + - 8.2. Door Lock Controller Device Type.   + - 8.2.1. Revision History.   + - 8.2.2. Classification.   + - 8.2.3. Conditions.   + - 8.2.4. Cluster Requirements.   + - 8.3. Window Covering.   + - 8.3.1. Revision History.   + - 8.3.2. Classification.   + - 8.3.3. Conditions.   + - 8.3.4. Cluster Requirements.   + - 8.3.5. Element Requirements.   + - 8.4. Window Covering Controller.   + - 8.4.1. Revision History.   + - 8.4.2. Classification.   + - 8.4.3. Conditions.   + - 8.4.4. Cluster Requirements.   + - 8.4.5. Element Requirements.   +- 9. HVAC Device Types.   + - 9.1. Thermostat.   + - 9.1.1. Revision History.   + - 9.1.2. Classification.   + - 9.1.3. Conditions.   + - 9.1.4. Cluster Requirements.   + - 9.1.5. Element Requirements.   + - 9.2. Fan.   + - 9.2.1. Revision History.   + - 9.2.2. Classification.   + - 9.2.3. Conditions.   + - 9.2.4. Device Type Requirements.   + - 9.2.5. Cluster Requirements.   + - 9.2.6. Cluster Restrictions.   + - 9.2.7. Element Requirements.   + - 9.3. Air Purifier.   + - 9.3.1. Revision History.   + - 9.3.2. Classification.   + - 9.3.3. Conditions.   + - 9.3.4. Device Type Requirements.   + - 9.3.5. Cluster Requirements.   + - 9.3.6. Cluster Restrictions.   + - 9.3.7. Element Requirements.   +- 10. Media Device Types.   + - 10.1. Video Player Architecture.   + - 10.1.1. Introduction.   + - 10.1.2. Clients of a Casting Video Player.   + - 10.1.3. Endpoint Composition for Content Apps of a Casting Video Player.   + - 10.1.4. Commissioning.   + - 10.1.5. Determining Context.   + - 10.1.6. Basic Video Player Features.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 10.1.7. Content Launching Features.   + - 10.2. Basic Video Player.   + - 10.2.1. Revision History.   + - 10.2.2. Classification.   + - 10.2.3. Conditions.   + - 10.2.4. Cluster Requirements.   + - 10.3. Casting Video Player.   + - 10.3.1. Revision History.   + - 10.3.2. Classification.   + - 10.3.3. Conditions.   + - 10.3.4. Cluster Requirements.   + - 10.3.5. Element Requirements.   + - 10.4. Speaker.   + - 10.4.1. Revision History.   + - 10.4.2. Classification.   + - 10.4.3. Conditions.   + - 10.4.4. Cluster Requirements.   + - 10.5. Content App.   + - 10.5.1. Revision History.   + - 10.5.2. Classification.   + - 10.5.3. Conditions.   + - 10.5.4. Cluster Requirements.   + - 10.5.5. Element Requirements.   + - 10.5.6. Endpoint Composition.   + - 10.5.7. Disambiguation.   + - 10.6. Casting Video Client.   + - 10.6.1. Revision History.   + - 10.6.2. Classification.   + - 10.6.3. Conditions.   + - 10.6.4. Cluster Requirements.   + - 10.7. Video Remote Control.   + - 10.7.1. Revision History.   + - 10.7.2. Classification.   + - 10.7.3. Conditions.   + - 10.7.4. Cluster Requirements.   +- 11. Generic Device Types.   + - 11.1. Mode Select.   + - 11.1.1. Revision History.   + - 11.1.2. Classification.   + - 11.1.3. Conditions.   + - 11.1.4. Cluster Requirements.   + - 11.2. Aggregator.   + - 11.2.1. Revision History.   + - 11.2.2. Classification.   + - 11.2.3. Conditions.   + - 11.2.4. Cluster Requirements.   + - 11.2.5. Endpoint Composition.   + - 11.2.6. Disambiguation.   +- 12. Robotic Device Types.   + - 12.1. Robotic Vacuum Cleaner Device Type.   + - 12.1.1. Revision History.   + - 12.1.2. Classification.   + - 12.1.3. Conditions.   + - 12.1.4. Cluster Requirements.   + - 12.1.5. Cluster Usage.   +- 13. Appliances Device Types.   + - 13.1. Laundry Washer.   + - 13.1.1. Revision History.   + - 13.1.2. Classification.   + - 13.1.3. Conditions.   + - 13.1.4. Cluster Requirements.   + - 13.1.5. Cluster Restrictions.   + - 13.1.6. Element Requirements.   + - 13.2. Refrigerator.   + - 13.2.1. Refrigerator Architecture.   + - 13.2.2. Revision History.   + - 13.2.3. Classification.   + - 13.2.4. Conditions.   + - 13.2.5. Device Type Requirements.   + - 13.2.6. Cluster Requirements.   + - 13.2.7. Element Requirements.   + - 13.3. Room Air Conditioner.   + - 13.3.1. Room Air Conditioner Architecture.   + - 13.3.2. Revision History.   + - 13.3.3. Classification.   + - 13.3.4. Conditions.   + - 13.3.5. Device Type Requirements.   + - 13.3.6. Cluster Requirements.   + - 13.3.7. Cluster Restrictions.   + - 13.3.8. Element Requirements.   + - 13.4. Temperature Controlled Cabinet.   + - 13.4.1. Revision History.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 13.4.2. Classification.   + - 13.4.3. Conditions.   + - 13.4.4. Cluster Requirements.   + - 13.4.5. Element Requirements.   +- 13.5. Dishwasher.   + - 13.5.1. Revision History.   + - 13.5.2. Classification.   + - 13.5.3. Conditions.   + - 13.5.4. Cluster Requirements.   + - 13.5.5. Cluster Restrictions.   + - 13.5.6. Element Requirements.   +- 13.6. Laundry Dryer.   + - 13.6.1. Revision History.   + - 13.6.2. Classification.   + - 13.6.3. Conditions.   + - 13.6.4. Cluster Requirements.   + - 13.6.5. Cluster Restrictions.   + - 13.6.6. Element Requirements.   +- 13.7. Cook Surface.   + - 13.7.1. Revision History.   + - 13.7.2. Classification.   + - 13.7.3. Conditions.   + - 13.7.4. Cluster Requirements.   + - 13.7.5. Cluster Restrictions.   + - 13.7.6. Element Requirements.   +- 13.8. Cooktop.   + - 13.8.1. Revision History.   + - 13.8.2. Classification.   + - 13.8.3. Conditions.   + - 13.8.4. Device Type Requirements.   + - 13.8.5. Cluster Requirements.   + - 13.8.6. Cluster Restrictions.   + - 13.8.7. Element Requirements.   +- 13.9. Oven.   + - 13.9.1. Oven Architecture.   + - 13.9.2. Revision History.   + - 13.9.3. Classification.   + - 13.9.4. Conditions.   + - 13.9.5. Device Type Requirements.   + - 13.9.6. Cluster Requirements.   +- 13.10. Extractor Hood.   + - 13.10.1. Revision History.   + - 13.10.2. Classification.   + - 13.10.3. Conditions.   + - 13.10.4. Device Type Requirements   + - 13.10.5. Cluster Requirements.   + - 13.10.6. Element Requirements.   + - 13.11. Microwave Oven.   + - 13.11.1. Microwave Oven Architecture.   + - 13.11.2. Revision History.   + - 13.11.3. Classification.   + - 13.11.4. Conditions.   + - 13.11.5. Device Type Requirements   + - 13.11.6. Cluster Requirements.   + - 13.11.7. Element Requirements.   + - 13.11.8. Cluster Usage.   +- 14. Energy Device Types.   + - 14.1. EVSE Device Type.   + - 14.1.1. EVSE Architecture.   + - 14.1.2. Revision History.   + - 14.1.3. Classification.   + - 14.1.4. Conditions.   + - 14.1.5. Device Type Requirements.   + - 14.1.6. Cluster Requirements.   + - 14.2. Water Heater Device Type.   + - 14.2.1. Water Heater Architecture.   + - 14.2.2. Revision History.   + - 14.2.3. Classification.   + - 14.2.4. Conditions.   + - 14.2.5. Device Type Requirements.   + - 14.2.6. Cluster Requirements.   + - 14.2.7. Element Requirements.   + - 14.3. Solar Power Device Type.   + - 14.3.1. Solar Power Architecture.   + - 14.3.2. Revision History.   + - 14.3.3. Classification.   + - 14.3.4. Conditions.   + - 14.3.5. Device Type Requirements.   + - 14.3.6. Cluster Requirements.   + - 14.4. Battery Storage Device Type.   + - 14.4.1. Battery Storage Architecture.   + - 14.4.2. Revision History.   + - Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page + - 14.4.3. Classification.   + - 14.4.4. Conditions.   + - 14.4.5. Device Type Requirements.   + - 14.4.6. Cluster Requirements.   + - 14.5. Heat Pump Device Type.   + - 14.5.1. Heat Pump Architecture.   + - 14.5.2. Revision History.   + - 14.5.3. Classification.   + - 14.5.4. Conditions.   + - 14.5.5. Device Type Requirements.   + - 14.5.6. Cluster Requirements.   +- 15. Network Infrastructure Device Types.   + - 15.1. Introduction.   + - 15.2. Network Infrastructure Manager Device Type.   + - 15.2.1. Revision History.   + - 15.2.2. Classification.   + - 15.2.3. Conditions.   + - 15.2.4. Cluster Requirements.   + - 15.2.5. Root Node Element Requirements.   + - 15.2.6. Other Requirements.   + - 15.3. Thread Border Router Device Type.   + - 15.3.1. Revision History.   + - 15.3.2. Classification.   + - 15.3.3. Conditions.   + - 15.3.4. Device Type Requirements.   + - 15.3.5. Cluster Requirements.   + - 15.3.6. Other Requirements.   + - 15.3.7. Usage.   + + +**References** + +The following standards and specifications contain provisions, which through reference in this doc­ +ument constitute provisions of this specification. All the standards and specifications listed are nor­ +mative references. At the time of publication, the editions indicated were valid. All standards and +specifications are subject to revision, and parties to agreements based on this specification are +encouraged to investigate the possibility of applying the most recent editions of the standards and +specifications indicated below. + +**CSA Reference Documents** + +``` +Reference Reference Location/URL Description +[MatterCore] https://github.com/CHIP- +Specifications/connected­ +homeip-spec/raw/build-sam­ +ple/pdf/main.pdf +``` +``` +Matter Core Specification - Under development +``` +``` +[CSA-PNP] https://groups.csa-iot.org/wg/ +members/document/21624 +``` +``` +Organizational Processes and Procedures, 13-0625, +revision 8, November 2021 +``` +**Provisional** + +Per [CSA-PNP], when a specification is completed there may be sections of specification text (or +smaller pieces of a section) that are not certifiable at this stage. These sections (or smaller pieces of +a section) are marked as provisional prior to publishing the specification. This specification uses +well-defined notation to mark Provisional Conformance (see [MatterCore], Section 7.3) or notes a +section of text with the term "provisional". + +**List of Provisional Items** + +The following is a list of provisional items. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 17 +``` + +Page 18 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 1. Base Device Type** + +This chapter describes the base device type. + +**1.1. Base Device Type** + +**1.1.1. Revision History** + +This is the revision history for this document. Because this document defines common require­ +ments for all device types, changes to this document may affect many device types. Therefore, each +device type definition affected by a change here, SHALL have its revision number incremented, +with a new entry added to its history with a description that matches the description here. + +``` +Revision Description +1 Initial revision +2 Duplicate condition replaces Multiple condition +``` +**1.1.2. Overview** + +This defines common conformance for all device types depending on, but not limited to: + +- Certification programs (e.g. Zigbee, Matter, etc.) +- Underlying protocol stack (e.g. 802.15.4, Wi-Fi, Thread, Zigbee PRO, IPv6, TCP/IP) +- Regional regulations +- Interfaces (UI, cloud, etc.) +- Scale (e.g. residential vs commercial) +- Other common limitations or capabilities (e.g. battery powered or sleepy nodes). +- etc. + +**1.1.3. Conditions** + +Each section below is a category of conditions, each defining a list of conformance condition names +and unique tags. The separation into categories is for reading purposes only. + +**1.1.3.1. Certification Program Conditions** + +At the time of the first publication of this document, many certification programs have terminated, +or only allow re-certification, such as the Zigbee Home Automation standard. + +``` +Certification Program Tag Description +Zigbee Home Automation ZHA Zigbee Home Automation stan­ +dard +Zigbee Smart Energy ZSE Zigbee Smart Energy standard +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 19 +``` + +``` +Certification Program Tag Description +Green Power GP Zigbee Green Power standard +Zigbee Zigbee Zigbee standard +SuZi SuZi Zigbee PRO Sub-GHz standard +Matter Matter Matter standard +``` +**1.1.3.2. Protocol Conditions** + +``` +Protocol Tag +Ethernet +Wi-Fi +Thread +TCP +UDP +IP +IPv4 +IPv6 +``` +**1.1.3.3. Interface Conditions** + +``` +Interface Tag Description +LanguageLocale The node supports localization for conveying +text to the user +TimeLocale The node supports localization for conveying +time to the user +UnitLocale The node supports localization for conveying +units of measure to the user +``` +Note that "supports localization" in the table above refers to supporting update of localization via +cluster interactions. + +**1.1.4. Common Capability Conditions** + +This category is for common limitations or capabilities of a node. + +``` +Capability Tag Description +SIT The node is a short idle time intermittently con­ +nected device +LIT The node is a long idle time intermittently con­ +nected device +``` +``` +Page 20 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Capability Tag Description +Active The node is always able to communicate +``` +**1.1.5. Device Type Class Conditions** + +This category is for classifications of device type. Some of these classifications are dependent on +other conditions. + +``` +Class Tag Summary +Node the device type is classified as a Node device +type (see Data Model specification) +App the device type is classified as an Application +device type (see Data Model specification) +Simple the device type is classified as a Simple device +type (see Data Model specification) +Dynamic the device type is classified as a Dynamic device +type (see Data Model specification) +Composed the device type is composed of 2 or more device +types (see System Model specification) +``` +**1.1.6. Endpoint Type Class Conditions** + +This category is for classifications of endpoints. Some of these classifications are dependent on +other conditions. + +``` +Class Tag Summary +Client there exists a client application cluster on the +endpoint +Server there exists a server application cluster on the +endpoint +Duplicate see Duplicate Condition +BridgedPowerSourceInfo the endpoint represents a Bridged Device, for +which information about the state of its power +source is available to the Bridge +``` +**1.1.6.1. Duplicate Condition** + +The endpoint and at least one of its sibling endpoints have an overlap in application device type(s), +as defined in the "Disambiguation" section in the System Model specification. This condition trig­ +gers requirements for providing additional information about the endpoints in order to disam­ +biguate between the endpoints (see "Disambiguation" section in the System Model specification). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 21 +``` + +**1.1.7. Cluster Requirements** + +Each Matter device type implementation SHALL include these clusters, as a minimum set, based on +the conformance defined below. This conformance table SHALL assume the Matter conformance +condition is TRUE (in Conformance column). + +``` +ID Cluster Client/Server Quality Conformance +0x001D Descriptor Server M +0x001E Binding Server Simple & Client +0x0040 Fixed Label Server O +0x0041 User Label Server O +``` +**1.1.8. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +entry means no change. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x001D Descriptor Feature TagList Duplicate +``` +``` +Page 22 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 2. Utility Device Types** + +This chapter describes the utility device types. The utility device types are summarized in the table +below: + +``` +Device ID Device name +0x0016 Root Node +0x0011 Power Source +0x0012 OTA Requestor +0x0014 OTA Provider +0x0013 Bridged Node +0x0510 Electrical Sensor +0x050D Device Energy Management +0x0019 Secondary Network Interface +0x0130 Joint Fabric Administrator +``` +**2.1. Root Node** + +This defines conformance for a root node endpoint (see System Model specification). This endpoint +is akin to a "read me first" endpoint that describes itself and the other endpoints that make up the +node. + +- Device types with Endpoint scope SHALL NOT be supported on the same endpoint as this device + type. +- Clusters with an Application role SHALL NOT be supported on the same endpoint as this device + type. +- Other device types with Node scope MAY be supported on the same endpoint as this device type. + +**2.1.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Added Power Source to device type; Deprecated +Power Source Configuration +3 Added restriction on Managed Device feature of +Access Control cluster +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 23 +``` + +**2.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0016 Root Node Node Node +``` +**2.1.3. Conditions** + +``` +Condition Description +CustomNetworkConfig The node only supports out-of-band-configured +networking (e.g. rich user interface, manufac­ +turer-specific means, custom commissioning +flows, or future IP-compliant network technol­ +ogy not yet directly supported by NetworkCommis­ +sioning cluster). +ManagedAclAllowed The node has at least one endpoint where some +Device Type present on the endpoint has a +Device Library element requirement table entry +that sets this condition to true. +``` +Please see the Base Device Type definition for additional conformance tags. + +**2.1.4. Device Type Requirements** + +The table lists other device types to be implemented along with this device type based on confor­ +mance. + +``` +ID Name Constraint Conformance +0x0011 Power Source O +``` +**2.1.5. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0028 Basic Information Server I M +0x001F Access Control Server I M +0x002E Power Source Con­ +figuration +``` +``` +Server I O, D +``` +``` +0x0038 Time Synchroniza­ +tion +``` +``` +Server I O +``` +``` +0x003F Group Key Man­ +agement +``` +``` +Server I M +``` +``` +Page 24 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0030 General Commis­ +sioning +``` +``` +Server I M +``` +``` +0x0031 Network Commis­ +sioning +``` +``` +Server !CustomNetwork­ +Config +0x003C Administrator +Commissioning +``` +``` +Server I M +``` +``` +0x003E Node Operational +Credentials +``` +``` +Server I M +``` +``` +0x002B Localization Con­ +figuration +``` +``` +Server I LanguageLocale +``` +``` +0x002C Time Format +Localization +``` +``` +Server I TimeLocale +``` +``` +0x002D Unit Localization Server I UnitLocale +0x0033 General Diagnos­ +tics +``` +``` +Server I M +``` +``` +0x0032 Diagnostic Logs Server I O +0x0034 Software Diagnos­ +tics +``` +``` +Server I O +``` +``` +0x0037 Ethernet Network +Diagnostics +``` +``` +Server [Ethernet] +``` +``` +0x0036 Wi-Fi Network +Diagnostics +``` +``` +Server [Wi-Fi] +``` +``` +0x0035 Thread Network +Diagnostics +``` +``` +Server [Thread] +``` +``` +0x0046 ICD Management Server I SIT | LIT +``` +### NOTE + +``` +The Network Diagnostics clusters present on the Root Node SHALL serve the pri­ +mary network interface as specified in the Network Commissioning cluster if it +exists, or the out-of-band-configured networking interfaces. +``` +**2.1.6. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x001F Access Con­ +trol +``` +``` +Feature MNGD desc [ManagedA­ +clAllowed] +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 25 +``` + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0046 ICD Manage­ +ment +``` +``` +Feature LongIdle­ +TimeSupport +``` +### LIT + +**2.1.6.1. Access Control MNGD Conformance** + +The MNGD (Managed Device) feature of the Access Control Cluster on the device’s Root Node end­ +point is restricted to devices that contain an Application Endpoint type that explicitly permits its +use, such as the Network Infrastructure Manager device type (Device Type ID 0x0090). + +**2.1.7. Endpoint Composition** + +A Root Node endpoint’s Descriptor cluster PartsList attribute SHALL contain a list of all other end­ +points on the node, i.e. the full-family pattern defined in the System Model specification. + +**2.2. Power Source** + +**2.2.1. Classification** + +``` +ID Device Name Superset Class Scope +0x0011 Power Source Utility Node +``` +**2.2.2. Revision History** + +``` +Rev +i­ +sio +n +``` +``` +Description +``` +``` +1 Initial revision +``` +**2.2.3. Cluster Requirements** + +This device SHALL support the clusters listed in the following table. + +``` +ID ClusterName Client/Server Quality Conformance +0x002F Power Source Server M +``` +**2.3. OTA Requestor** + +An OTA Requestor is a device that is capable of receiving an OTA software update. + +**2.3.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is + +``` +Page 26 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**2.3.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0012 OTA Requestor Utility Node +``` +**2.3.3. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x002A OTA Software +Update Requestor +``` +``` +Server M +``` +``` +0x0029 OTA Software +Update Provider +``` +``` +Client M +``` +**2.4. OTA Provider** + +An OTA Provider is a node that is capable of providing an OTA software update to other nodes on +the same fabric. + +**2.4.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**2.4.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0014 OTA Provider Utility Node +``` +**2.4.3. Cluster Requirements** + +Each node supporting this device type SHALL include these clusters based on the conformance +defined below. A node SHALL only ever have, at most, one instance of the OTA Provider’s required +clusters. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 27 +``` + +``` +ID Cluster Client/Server Quality Conformance +0x002A OTA Software +Update Requestor +``` +``` +Client O +``` +``` +0x0029 OTA Software +Update Provider +``` +``` +Server M +``` +**2.5. Bridged Node** + +This defines conformance for a Bridged Node root endpoint. This endpoint is akin to a "read me +first" endpoint that describes itself and any other endpoints that make up the Bridged Node. A +Bridged Node endpoint represents a device on a foreign network, but is not the root endpoint of the +bridge itself. + +**2.5.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Added Power Source to device type; Deprecated +Power Source Configuration +3 Added Ecosystem Information Cluster and Fab­ +ricSynchronizedNode Condition. +``` +**2.5.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0013 Bridged Node Utility Endpoint +``` +**2.5.3. Conditions** + +This device type MAY support the following conformance conditions as defined below. + +``` +Condition Description +FabricSynchronizedNode See description below. +``` +Please see the Base Device Type definition for additional conformance tags. + +**2.5.3.1. FabricSynchronizedNode Condition** + +The FabricSynchronizedNode condition applies to a Bridged Node endpoint when all of the follow­ +ing are true: + +- There is a Commissioner Control Cluster on an Aggregator which has this endpoint as a descen­ + +``` +Page 28 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +dant. +``` +- The Commissioner Control Cluster has a SupportedDeviceCategories attribute with the Fabric­ + Synchronization bit set. +- The bridged node is a Matter Node. + +**2.5.4. Device Type Requirements** + +This device type SHALL only be indicated on endpoints which are listed in the Descriptor cluster +PartsList of another endpoint with an Aggregator device type. + +The table lists other device types to be implemented along with this device type based on confor­ +mance. + +``` +ID Name Constraint Conformance +0x0011 Power Source O +``` +**2.5.5. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0039 Bridged Device +Basic Information +``` +``` +Server M +``` +``` +0x002E Power Source Con­ +figuration +``` +``` +Server BridgedPower­ +SourceInfo, D +0x002F Power Source Server BridgedPower­ +SourceInfo +0x0750 Ecosystem Infor­ +mation +``` +``` +Server FabricSynchro­ +nizedNode, O +0x003C Administrator +Commissioning +``` +``` +Server FabricSynchro­ +nizedNode +``` +**2.5.6. Endpoint Composition** + +- A Bridged Node endpoint SHALL support one of the following composition patterns: + ◦ Separate Endpoints: All application device types are supported on separate endpoints, and + not on the Bridged Node endpoint. The Bridged Node endpoint’s Descriptor cluster PartsList + attribute SHALL indicate a list of all endpoints representing the functionality of the bridged + device, including the endpoints supporting the application device types, i.e. the full-family + pattern defined in the System Model specification. + ◦ One Endpoint: Both the Bridged Node and one or more application device types are sup­ + ported on the same endpoint (following application device type rules). Endpoint composi­ + tion SHALL conform to the application device type(s) definition. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 29 +``` + +**2.6. Electrical Sensor** + +An Electrical Sensor device measures the electrical power and/or energy being imported and/or +exported. + +**2.6.1. Revision History** + +``` +Revision Description +1 Initial revision +``` +**2.6.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0510 Electrical Sensor Utility Endpoint +``` +**2.6.3. Device Type Requirements** + +Electrical measurements made by either the Electrical Power Measurement cluster, the Electrical +Energy Measurement cluster, or both SHALL apply to the endpoints indicated by the Power Topol­ +ogy cluster. + +**2.6.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x009C Power Topology Server M +0x0090 Electrical Power +Measurement +``` +``` +Server O.a+ +``` +``` +0x0091 Electrical Energy +Measurement +``` +``` +Server O.a+ +``` +**2.7. Device Energy Management** + +A Device Energy Management device provides reporting and optionally adjustment of the electrical +power planned on being consumed or produced by the device. + +**2.7.1. Revision History** + +``` +Revision Description +1 Initial revision +2 Updated description of when DEM Mode is to be +included +``` +``` +Page 30 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**2.7.2. Classification** + +``` +ID Device Name Superset Class Scope +0x050D Device Energy +Management +``` +``` +Utility Endpoint +``` +**2.7.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +``` +Condition Description +ControllableESA The DEM cluster on this endpoint accepts com­ +mands to adjust its energy operation. +``` +A ControllableESA device is one that allows a client to request either a change in power (PowerAd­ +justment feature), a change in the start time (StartTimeAdjustment feature), to be paused and +resumed (Pausable feature), or to have its power or state forecast adjusted (ForecastAdjustment or +ConstraintBasedAdjustment features). + +Simple reporting of the Forecast as a single capability on its own (PowerForecastReporting or State­ +ForecastReporting feature support) does not require the ControllableESA condition. + +**2.7.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0098 Device Energy +Management +``` +``` +Server M +``` +``` +0x009F Device Energy +Management +Mode +``` +``` +Server ControllableESA, O +``` +**2.7.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0098 Device +Energy Man­ +agement +``` +``` +Feature PowerAd­ +justment +``` +``` +Control­ +lableESA.a+ +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 31 +``` + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0098 Device +Energy Man­ +agement +``` +``` +Feature StartTimeAd­ +justment +``` +``` +Control­ +lableESA.a+ +``` +``` +0x0098 Device +Energy Man­ +agement +``` +``` +Feature Pausable Control­ +lableESA.a+ +``` +``` +0x0098 Device +Energy Man­ +agement +``` +``` +Feature ForecastAd­ +justment +``` +``` +Control­ +lableESA.a+ +``` +``` +0x0098 Device +Energy Man­ +agement +``` +``` +Feature Constraint­ +BasedAdjust­ +ment +``` +``` +Control­ +lableESA.a+ +``` +**2.8. Secondary Network Interface** + +A Secondary Network Interface device provides an additional network interface supported by the +Node, supplementing the primary interface hosted by the Root Node endpoint. + +A Node supporting multiple network interfaces SHALL include the primary interface on the Root +Node endpoint, along with secondary interfaces on other endpoints. The priorities of these network +interfaces are determined by the order of their endpoints, where interfaces with smaller endpoint +numbers are higher priority. + +**2.8.1. Revision History** + +``` +Revision Description +1 Initial revision +``` +**2.8.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0019 Secondary Net­ +work Interface +``` +``` +Utility Endpoint +``` +**2.8.3. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0031 Network Commis­ +sioning +``` +``` +Server M +``` +``` +Page 32 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Client/Server Quality Conformance +0x0037 Ethernet Network +Diagnostics +``` +``` +Server [Ethernet] +``` +``` +0x0036 Wi-Fi Network +Diagnostics +``` +``` +Server [Wi-Fi] +``` +``` +0x0035 Thread Network +Diagnostics +``` +``` +Server [Thread] +``` +``` +NOTE The Network Diagnostics cluster present in this device type SHALL serve the sec­ +ondary network interface as specified in the Network Commissioning cluster. +``` +**2.9. Joint Fabric Administrator** + +A Joint Fabric Administrator device provides capabilities to manage the Joint Fabric Datastore and +issue an ICAC signed by the Joint Fabric Anchor Root CA. + +A client wanting to access the capabilities of the Joint Fabric Administrator MAY use the Joint Com­ +missioning Method to be commissioned onto the Joint Fabric. Once commissioned, a client MAY +access the capabilities of the Joint Fabric Administrator. + +**2.9.1. Joint Fabric Architecture** + +See Joint Fabric. + +**2.9.2. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**2.9.3. Classification** + +``` +ID Device Name Superset Class Scope +0x0130 Joint Fabric +Administrator +``` +``` +Utility Endpoint +``` +**2.9.4. Cluster Requirements** + +Each endpoint supporting the Joint Fabric Administrator device type SHALL include these clusters +based on the conformance defined below. + +``` +ID Name Client/Server Quality Conformance +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 33 +``` + +``` +0x0752 Joint Fabric Datas­ +tore +``` +``` +Server M +``` +``` +0x0753 Joint Fabric PKI Server M +``` +Page 34 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 3. Application Device Types** + +The following chapters list the application device types defined in this version of the Device +Library. They are grouped per functional area in a chapter and are summarized in the table below: + +``` +Device ID Device name +lighting +0x0100 On/Off Light +0x0101 Dimmable Light +0x010C Color Temperature Light +0x010D Extended Color Light +smart plugs/outlets and other actuators +0x010A On/Off Plug-in Unit +0x010B Dimmable Plug-In Unit +0x010F Mounted On/Off Control +0x0110 Mounted Dimmable Load Control +0x0303 Pump +0x0042 Water Valve +switches and controls +0x0103 On/Off Light Switch +0x0104 Dimmer Switch +0x0105 Color Dimmer Switch +0x0840 Control Bridge +0x0304 Pump Controller +0x000F Generic Switch +sensors +0x0015 Contact Sensor +0x0106 Light Sensor +0x0107 Occupancy Sensor +0x0302 Temperature Sensor +0x0305 Pressure Sensor +0x0306 Flow Sensor +0x0307 Humidity Sensor +0x0850 On/Off Sensor +0x0076 Smoke CO Alarm +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 35 +``` + +``` +Device ID Device name +0x002C Air Quality Sensor +0x0041 Water Freeze Detector +0x0043 Water Leak Detector +0x0044 Rain Sensor +closures +0x000A Door Lock +0x000B Door Lock Controller +0x0202 Window Covering +0x0203 Window Covering Controller +HVAC +0x0301 Thermostat +0x002B Fan +0x002D Air Purifier +media +0x0028 Basic Video Player +0x0023 Casting Video Player +0x0022 Speaker +0x0024 Content App +0x0029 Casting Video Client +0x002A Video Remote Control +generic +0x0027 Mode Select +0x000E Aggregator +robotic devices +0x0074 Robotic Vacuum Cleaner +appliances +0x0070 Refrigerator +0x0071 Temperature Controlled Cabinet +0x0072 Room Air Conditioner +0x0073 Laundry Washer +0x0075 Dishwasher +0x0077 Cook Surface +0x0078 Cooktop +``` +Page 36 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Device ID Device name** + +0x0079 Microwave Oven + +0x007A Extractor Hood + +0x007B Oven + +0x007C Laundry Dryer + +``` +energy +``` +0x050C EVSE + +0x050F Water Heater + +0x0017 Solar Power + +0x0018 Battery Storage + +0x0309 Heat Pump + +``` +network infrastructure +``` +0x0090 Network Infrastructure Manager + +0x0091 Thread Border Router + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 37 +``` + +Page 38 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 4. Lighting Device Types** + +**4.1. On/Off Light** + +The On/Off Light is a lighting device that is capable of being switched on or off by means of a bound +controller device such as an On/Off Light Switch or a Dimmer Switch. In addition, an on/off light is +also capable of being switched by means of a bound occupancy sensor. + +**4.1.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**4.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0100 On/Off Light Simple Endpoint +``` +**4.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**4.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 1. On/Off Light Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server M +0x0062 Scenes Manage­ +ment +``` +``` +Server P, M +``` +``` +0x0006 On/Off Server M +0x0008 Level Control Server O +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +The inclusion of the Level Control cluster on this device is recommended to provide a consistent + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 39 +``` + +user experience when the device is grouped with additional dimmable lights and the “with on/off ” +commands are used. For this device, since its only states are on or off, if the Level Control cluster is +implemented, it SHALL NOT have any effect on the actual light level except for those commands +that cause an on/off state change, that is, the “with on/off ” commands. In addition, if the Level Con­ +trol cluster is implemented, the device SHALL accept and process Level Control cluster commands, +adjusting the value of the CurrentLevel attribute accordingly and, where necessary, adjusting the +On/Off cluster OnOff attribute. + +**4.1.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0003 Identify Command TriggerEffect M +0x0062 Scenes Man­ +agement +``` +``` +Command CopyScene P, M +``` +``` +0x0006 On/Off Feature Lighting M +0x0008 Level Con­ +trol +``` +``` +Feature OnOff M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Feature Lighting M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute CurrentLevel 1 to 254 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MinLevel 1 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MaxLevel 254 +``` +As the TriggerEffect command of the Identify cluster and the OffWithEffect command of the On/Off +cluster specify light effects that require dimming of the light output, and such is not possible on this +device type, the specified light effects MAY be replaced by pure on/off light effects. + +**4.2. Dimmable Light** + +A Dimmable Light is a lighting device that is capable of being switched on or off and the intensity of +its light adjusted by means of a bound controller device such as a Dimmer Switch or a Color Dim­ +mer Switch. In addition, a Dimmable Light device is also capable of being switched by means of a +bound occupancy sensor or other device(s). + +**4.2.1. Revision History** + +``` +Page 40 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**4.2.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0101 Dimmable Light On/Off Light Simple Endpoint +``` +**4.2.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**4.2.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 2. Dimmable Light Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server M +0x0062 Scenes Manage­ +ment +``` +``` +Server P, M +``` +``` +0x0006 On/Off Server M +0x0008 Level Control Server M +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +**4.2.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0003 Identify Command TriggerEffect M +0x0062 Scenes Man­ +agement +``` +``` +Command CopyScene P, M +``` +``` +0x0006 On/Off Feature Lighting M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 41 +``` + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0008 Level Con­ +trol +``` +``` +Feature Lighting M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Feature OnOff M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute CurrentLevel 1 to 254 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MinLevel 1 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MaxLevel 254 +``` +**4.3. Color Temperature Light** + +A Color Temperature Light is a lighting device that is capable of being switched on or off, the inten­ +sity of its light adjusted, and its color temperature adjusted by means of a bound controller device +such as a Color Dimmer Switch. + +**4.3.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Added optional occupancy sensing +4 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**4.3.2. Classification** + +``` +ID Device Name Superset Class Scope +0x010C Color Tempera­ +ture Light +``` +``` +Dimmable Light Simple Endpoint +``` +**4.3.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**4.3.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +Page 42 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Table 3. Color Temperature Light Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server M +0x0062 Scenes Manage­ +ment +``` +``` +Server P, M +``` +``` +0x0006 On/Off Server M +0x0008 Level Control Server M +0x0300 Color Control Server M +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +**4.3.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0003 Identify Command TriggerEffect M +0x0062 Scenes Man­ +agement +``` +``` +Command CopyScene P, M +``` +``` +0x0006 On/Off Feature Lighting M +0x0008 Level Con­ +trol +``` +``` +Feature OnOff M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Feature Lighting M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute CurrentLevel1 to 254 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MinLevel 1 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MaxLevel 254 +``` +``` +0x0300 Color Con­ +trol +``` +``` +Feature ColorTem­ +perature +``` +### M + +``` +0x0300 Color Con­ +trol +``` +``` +Attribute Remaining­ +Time +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 43 +``` + +**4.4. Extended Color Light** + +An Extended Color Light is a lighting device that is capable of being switched on or off, the intensity +of its light adjusted, and its color adjusted by means of a bound controller device such as a Color +Dimmer Switch or Control Bridge. The device supports adjustment of color by means of hue/satura­ +tion, enhanced hue, color looping, XY coordinates, and color temperature. In addition, the extended +color light is also capable of being switched by means of a bound occupancy sensor. + +**4.4.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation; integrate +DM CCB 3501 +3 Added optional occupancy sensing +4 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**4.4.2. Classification** + +``` +ID Device Name Superset Class Scope +0x010D Extended Color +Light +``` +``` +Color Tempera­ +ture Light +``` +``` +Simple Endpoint +``` +**4.4.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**4.4.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 4. Extended Color Light Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server M +0x0062 Scenes Manage­ +ment +``` +``` +Server P, M +``` +``` +0x0006 On/Off Server M +0x0008 Level Control Server M +0x0300 Color Control Server M +``` +``` +Page 44 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +**4.4.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0003 Identify Command TriggerEffect M +0x0062 Scenes Man­ +agement +``` +``` +Command CopyScene P, M +``` +``` +0x0006 On/Off Feature Lighting M +0x0008 Level Con­ +trol +``` +``` +Feature OnOff M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Feature Lighting M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute CurrentLevel1 to 254 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MinLevel 1 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MaxLevel 254 +``` +``` +0x0300 Color Con­ +trol +``` +``` +Feature HueSatura­ +tion +``` +### O + +``` +0x0300 Color Con­ +trol +``` +``` +Feature Enhanced­ +Hue +``` +### O + +``` +0x0300 Color Con­ +trol +``` +``` +Feature ColorLoop O +``` +``` +0x0300 Color Con­ +trol +``` +``` +Feature XY M +``` +``` +0x0300 Color Con­ +trol +``` +``` +Feature ColorTem­ +perature +``` +### M + +``` +0x0300 Color Con­ +trol +``` +``` +Attribute Remaining­ +Time +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 45 +``` + +Page 46 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 5. Smart Plugs/Outlets and other** + +**Actuators** + +**5.1. On/Off Plug-in Unit** + +An On/Off Plug-in Unit is a device that provides power to another device that is plugged into it, and +is capable of switching that provided power on or off. + +**5.1.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**5.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x010A On/Off Plug-in +Unit +``` +``` +Simple Endpoint +``` +**5.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**5.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 5. On/Off Plug-in Unit Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server M +0x0062 Scenes Manage­ +ment +``` +``` +Server P, M +``` +``` +0x0006 On/Off Server M +0x0008 Level Control Server O +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 47 +``` + +The inclusion of the Level Control cluster on this device is recommended to provide a consistent +user experience when the device is grouped with additional dimmable lights and the “with on/off ” +commands are used. For this device, since its only states are on or off, if the Level Control cluster is +implemented, it SHALL NOT have any effect on the actual light level except for those commands +that cause an on/off state change, that is, the “with on/off ” commands. In addition, if the Level Con­ +trol cluster is implemented, the device SHALL accept and process Level Control cluster commands, +adjusting the value of the CurrentLevel attribute accordingly and, where necessary, adjusting the +On/Off cluster OnOff attribute. + +**5.1.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0003 Identify Command TriggerEffect M +0x0062 Scenes Man­ +agement +``` +``` +Command CopyScene P, M +``` +``` +0x0006 On/Off Feature Lighting M +0x0008 Level Con­ +trol +``` +``` +Feature OnOff M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Feature Lighting M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute CurrentLevel 1 to 254 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MinLevel 1 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MaxLevel 254 +``` +As the TriggerEffect command of the Identify cluster and the OffWithEffect command of the On/Off +cluster specify light effects that require dimming of the light output, and such is not possible on this +device type, the specified light effects MAY be replaced by pure on/off light effects. + +**5.2. Dimmable Plug-In Unit** + +A Dimmable Plug-In Unit is a device that provides power to another device that is plugged into it, +and is capable of being switched on or off and have its level adjusted. The Dimmable Plug-in Unit is +typically used to control a conventional non-communicating light through its mains connection +using phase cutting. + +``` +Page 48 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**5.2.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Added optional occupancy sensing +4 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**5.2.2. Classification** + +``` +ID Device Name Superset Class Scope +0x010B Dimmable Plug-In +Unit +``` +``` +Simple Endpoint +``` +**5.2.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**5.2.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 6. Dimmable Plug-In Unit Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server M +0x0062 Scenes Manage­ +ment +``` +``` +Server P, M +``` +``` +0x0006 On/Off Server M +0x0008 Level Control Server M +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +**5.2.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 49 +``` + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0003 Identify Command TriggerEffect M +0x0062 Scenes Man­ +agement +``` +``` +Command CopyScene P, M +``` +``` +0x0006 On/Off Feature Lighting M +0x0008 Level Con­ +trol +``` +``` +Feature OnOff M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Feature Lighting M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute CurrentLevel 1 to 254 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MinLevel 1 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MaxLevel 254 +``` +**5.3. Mounted On/Off Control** + +A Mounted On/Off Control is a fixed device that provides power to another device that is plugged +into it, and is capable of switching that provided power on or off. + +**5.3.1. Revision History** + +``` +Revision Description +1 Initial release +``` +**5.3.2. Classification** + +``` +ID Device Name Superset Class Scope +0x010F Mounted On/Off +Control +``` +``` +Simple Endpoint +``` +**5.3.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**5.3.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 7. Mounted On/Off Control Cluster Requirements_ + +``` +Page 50 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server M +0x0062 Scenes Manage­ +ment +``` +``` +Server P, M +``` +``` +0x0006 On/Off Server M +0x0008 Level Control Server O +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +The inclusion of the Level Control cluster on this device is recommended to provide a consistent +user experience when the device is grouped with additional dimmable lights and the “with on/off ” +commands are used. For this device, since its only states are on or off, if the Level Control cluster is +implemented, it SHALL NOT have any effect on the actual light level except for those commands +that cause an on/off state change, that is, the “with on/off ” commands. In addition, if the Level Con­ +trol cluster is implemented, the device SHALL accept and process Level Control cluster commands, +adjusting the value of the CurrentLevel attribute accordingly and, where necessary, adjusting the +On/Off cluster OnOff attribute. + +**5.3.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0003 Identify Command TriggerEffect M +0x0062 Scenes Man­ +agement +``` +``` +Command CopyScene P, M +``` +``` +0x0006 On/Off Feature Lighting M +0x0008 Level Con­ +trol +``` +``` +Feature OnOff M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Feature Lighting M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute CurrentLevel1 to 254 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MinLevel 1 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MaxLevel 254 +``` +As the TriggerEffect command of the Identify cluster and the OffWithEffect command of the On/Off + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 51 +``` + +cluster specify light effects that require dimming of the light output, and such is not possible on this +device type, the specified light effects MAY be replaced by pure on/off light effects. + +**5.4. Mounted Dimmable Load Control** + +A Mounted Dimmable Load Control is a fixed device that provides power to another device that is +plugged into it, and is capable of being switched on or off and have its level adjusted. The Mounted +Dimmable Load Control is typically used to control a conventional non-communicating light +through its mains connection using phase cutting. + +**5.4.1. Revision History** + +``` +Revision Description +1 Initial release +``` +**5.4.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0110 Mounted Dimma­ +ble Load Control +``` +``` +Simple Endpoint +``` +**5.4.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**5.4.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 8. Mounted Dimmable Load Control Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server M +0x0062 Scenes Manage­ +ment +``` +``` +Server P, M +``` +``` +0x0006 On/Off Server M +0x0008 Level Control Server M +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +**5.4.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank + +``` +Page 52 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0003 Identify Command TriggerEffect M +0x0062 Scenes Man­ +agement +``` +``` +Command CopyScene P, M +``` +``` +0x0006 On/Off Feature Lighting M +0x0008 Level Con­ +trol +``` +``` +Feature OnOff M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Feature Lighting M +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute CurrentLevel1 to 254 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MinLevel 1 +``` +``` +0x0008 Level Con­ +trol +``` +``` +Attribute MaxLevel 254 +``` +**5.5. Pump** + +A Pump device is a pump that may have variable speed. It may have optional built-in sensors and a +regulation mechanism. It is typically used for pumping fluids like water. + +**5.5.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**5.5.2. Classification** + +``` +ID Device name Superset Class Scope +0x0303 Pump Simple Endpoint +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 53 +``` + +**5.5.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**5.5.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 9. Pump Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0006 On/Off Server M +0x0200 Pump Configura­ +tion and Control +``` +``` +Server M +``` +``` +0x0003 Identify Server M +0x0008 Level Control Server O +0x0004 Groups Server O +0x0062 Scenes Manage­ +ment +``` +``` +Server P, O +``` +``` +0x0402 Temperature Mea­ +surement +``` +``` +Server O +``` +``` +0x0403 Pressure Measure­ +ment +``` +``` +Server O +``` +``` +0x0404 Flow Measure­ +ment +``` +``` +Server O +``` +``` +0x0402 Temperature Mea­ +surement +``` +``` +Client O +``` +``` +0x0403 Pressure Measure­ +ment +``` +``` +Client O +``` +``` +0x0404 Flow Measure­ +ment +``` +``` +Client O +``` +``` +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +**5.5.5. Cluster Restrictions** + +**5.5.5.1. On/Off Cluster (Server) Clarifications** + +The actions carried out by a Pump device on receipt of commands are shown in the following. + +_Table 10. Pump Actions on Receipt for On/Off Commands_ + +``` +Page 54 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Command Action on Receipt +Off If the pump is powered on, store the current +level then immediately power it off. +On If the pump is powered off, power it on and +move immediately to the level stored by a previ­ +ous Off command. If no such level has been +stored, move immediately to the maximum level +allowed for the pump. +Toggle If the pump is powered on, proceed as for the +Off command. If the device is powered off, pro­ +ceed as for the On command. +``` +**5.5.5.2. Level Control Cluster (Server) Clarifications** + +The Level Control cluster SHALL allow controlling the pump setpoints. However, the transition time +is always ignored. + +The setpoint of the pump is a percentage related to the level according to the following table. + +_Table 11. Relationship between Level and Setpoint_ + +``` +Level Setpoint Meaning +0 N/A Pump is stopped. +1–200 Level / 2 (0.5–100.0%) Pump setpoint in percent. +201–255 100.0% Pump setpoint is 100.0% +``` +**5.6. Water Valve Device Type** + +This defines conformance to the Water Valve device type. + +**5.6.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**5.6.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0042 Water Valve Simple Endpoint +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 55 +``` + +**5.6.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**5.6.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +0x0081 Valve Configura­ +tion and Control +``` +``` +Server M +``` +``` +0x0404 Flow Measure­ +ment +``` +``` +Server O +``` +``` +0x0404 Flow Measure­ +ment +``` +``` +Client O +``` +**5.6.4.1. Identify Cluster** + +This cluster is used to identify the device. + +**5.6.4.2. Valve Configuration and Control Cluster** + +This cluster is used to configure and control (Open/Close) the valve. + +**5.6.4.3. Flow Measurement Cluster** + +The cluster server, if present, SHALL be used to report the measured flow through the valve. + +The cluster client, if present, MAY be used via binding to close a control loop of flow through the +valve. + +**5.6.5. Device implementation recommendations** + +**5.6.5.1. Start Up Behavior** + +The start up behavior of a device with this device type, is currently not specified and is considered +manufacturer specific. This means that the start up behavior and what is considered the "safe +state", most suitable for the specific device, is defined by the manufacturer. + +**5.6.5.2. Firmware Update** + +When a device with this device type needs to update its firmware (or restart for another reason), it +is strongly recommended to only perform the update/restart when the valve is in its closed state, as +well as ignoring any open request during this update/restart, given the chance a valve can uninten­ +tionally be left in the open state, for longer periods of time. + +``` +Page 56 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 6. Switches and Controls Device** + +**Types** + +This Chapter specifies a number of "controller" device types like On/Off Light Switch and Dimmer +Switch. Some products implementing these device types are intended to replace legacy switches or +dimmers that directly control the power to a load. For such products, manufacturers are encour­ +aged to implement an additional endpoint on the same product holding an "actuator" device type +like an On/Off Light (or On/Off Plug-in Unit) or Dimmable Light (or Dimmable Plug-in Unit), consis­ +tent with the type of control it can provide to the load. In case product can control multiple loads +separately, multiple such endpoints to each hold a device type for each load. + +Additionally, having a central control function allows much richer automation triggered by a press +of a switch. In such case, a switch works more like a sensor. For this, the Generic Switch device type +is defined. See Section 6.6, “Generic Switch”. Manufacturers are encouraged to implement the +Generic Switch device type as well in products that are generically referred to as switches. See Sec­ +tion 6.6.5, “Relation with other Switch device types (informative)” for examples how these device +types can be combined. + +**6.1. On/Off Light Switch** + +An On/Off Light Switch is a controller device that, when bound to a lighting device such as an +On/Off Light, is capable of being used to switch the device on or off. + +**6.1.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**6.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0103 On/Off Light +Switch +``` +``` +Simple Endpoint +``` +**6.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**6.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 57 +``` + +defined below. + +_Table 12. On/Off Light Switch Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0003 Identify Client M +0x0004 Groups Client O +0x0006 On/Off Client M +0x0062 Scenes Manage­ +ment +``` +``` +Client P, O +``` +**6.2. Dimmer Switch** + +A Dimmer Switch is a controller device that, when bound to a lighting device such as a Dimmable +Light, is capable of being used to switch the device on or off and adjust the intensity of the light +being emitted. + +**6.2.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**6.2.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0104 Dimmer Switch On/Off Light +Switch +``` +``` +Simple Endpoint +``` +**6.2.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**6.2.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 13. Dimmer Switch Cluster Requirements_ + +``` +Page 58 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0003 Identify Client M +0x0004 Groups Client O +0x0062 Scenes Manage­ +ment +``` +``` +Client P, O +``` +``` +0x0006 On/Off Client M +0x0008 Level Control Client M +``` +**6.3. Color Dimmer Switch** + +A Color Dimmer Switch is a controller device that, when bound to a lighting device such as an +Extended Color Light, is capable of being used to adjust the color of the light being emitted. + +**6.3.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**6.3.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0105 Color Dimmer +Switch +``` +``` +Dimmer Switch Simple Endpoint +``` +**6.3.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**6.3.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 14. Color Dimmer Switch Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0003 Identify Client M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 59 +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0004 Groups Client O +0x0062 Scenes Manage­ +ment +``` +``` +Client P, O +``` +``` +0x0006 On/Off Client M +0x0008 Level Control Client M +0x0300 Color Control Client M +``` +**6.4. Control Bridge** + +A Control Bridge is a controller device that, when bound to a lighting device such as an Extended +Color Light, is capable of being used to switch the device on or off, adjust the intensity of the light +being emitted and adjust the color of the light being emitted. In addition, a Control Bridge device is +capable of being used for setting scenes. + +**6.4.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**6.4.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0840 Control Bridge Simple Endpoint +``` +**6.4.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**6.4.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 15. Control Bridge Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0003 Identify Client M +0x0004 Groups Client M +``` +``` +Page 60 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0062 Scenes Manage­ +ment +``` +``` +Client P, M +``` +``` +0x0006 On/Off Client M +0x0008 Level Control Client M +0x0300 Color Control Client M +0x0400 Illuminance Mea­ +surement +``` +``` +Client O +``` +``` +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +**6.5. Pump Controller** + +A Pump Controller device is capable of configuring and controlling a Pump device. + +**6.5.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +4 Remove Binding client as a result of review of +CCB4058 +``` +**6.5.2. Classification** + +``` +ID Device name Superset Class Scope +0x0304 Pump Controller Simple Endpoint +``` +**6.5.3. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 16. Pump Controller Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0006 On/Off Client M +0x0200 Pump Configura­ +tion and Control +``` +``` +Client M +``` +``` +0x0003 Identify Server M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 61 +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Client O +0x0004 Groups Client O +0x0008 Level Control Client O +0x0062 Scenes Manage­ +ment +``` +``` +Client P, O +``` +``` +0x0402 Temperature Mea­ +surement +``` +``` +Client O +``` +``` +0x0403 Pressure Measure­ +ment +``` +``` +Client O +``` +``` +0x0404 Flow Measure­ +ment +``` +``` +Client O +``` +**6.6. Generic Switch** + +This defines conformance for the Generic Switch device type. + +**6.6.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Removed requirement for Fixed Label cluster +(can use TagList which was added in Descriptor +cluster) +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**6.6.2. Classification** + +``` +ID Device Name Superset Class Scope +0x000F Generic Switch Simple Endpoint +``` +**6.6.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**6.6.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +Page 62 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x003B Switch Server M +``` +**6.6.4.1. Instantaneous reporting** + +The generic mechanism for subscriptions and events might not ensure that detected interactions +with the switch will be delivered "instantaneously" to the Switch client cluster in the interested +party (they might be sent only after some time, e.g. due to batching of events and the Min Interval +behavior for subscriptions). In order to achieve a good user experience, a device of this device type +SHALL send updates of attributes and events defined in the Switch cluster without delay to sub­ +scribed parties. + +**6.6.4.2. Labeling for multi-switch devices** + +A Node which contains multiple switches will need to expose multiple endpoints each hosting an +instance of this device type and the associated Switch cluster. This means the Duplicate condition in +Matter base device requirements applies, so a TagList SHALL be included in the Descriptor cluster +on each such endpoint. The tag(s) in this TagList are used to indicate orientation (e.g. left and right +for a two-button switch) or labeling (e.g. "dim up" and "dim down" icons printed on the buttons) rel­ +evant to the user. A client SHOULD use these tags to convey such information to the user (e.g. show­ +ing it in a user interface), to help the user identify which endpoint maps to a certain orientation or +labeling. + +For the case where a server indicates tags from the Common Number Namespace, and the client +presents entities related to the endpoints (e.g. icons for the various switches), it SHOULD present +them in numerical order as indicated by the tags from the Common Number Namespace. + +For a Node which has only one endpoint hosting an instance of this device type and the associated +Switch cluster, a TagList MAY be used. This can be beneficial in cases where the switch has some +user-recognizable labeling. + +The TagList can contain a combination of tags from the namespaces defined in the Matter Semantic +Tag Namespaces, including the namespace for switches (section 12 of that document) as well as tags +from a manufacturer-specific namespace. + +In case the buttons have an intended function (e.g. engraved icon), the semantic tags from the +Switches Namespace (section 12) SHALL be used where applicable. If there is no corresponding tag, +a manufacturer-specific tag with a string Label SHOULD be used (see Example 2 below). + +To identify the location of a button on the device (e.g. top button of a two-button device), the seman­ +tic tags from the Common Position Namespace (section 9) SHALL be used where applicable. + +For devices where these are not applicable or not sufficient (e.g. a switch device with four buttons +in a row), the semantic tags from the Common Number Namespace (section 8) SHALL be used to +enumerate the position of the buttons on the device, in left to right, top to bottom order, starting +with Number.One for the first button. + +For devices to control a Closure, the semantic tags from the Common Closure Namespace (section 2) + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 63 +``` + +SHALL be used where applicable. + +Example 1: a device with two rocker switches (mounted side by side), which has two endpoints +(11,12) for the switch-related functionality + +- endpoint 11 has device type Generic Switch and contains + ◦ cluster Switch (feature flags: LS) exposing the state and events of the left button + ◦ cluster Descriptor with its TagList containing two tags: Position.Left and Number.One +- endpoint 12 has device type Generic Switch and contains + ◦ cluster Switch (feature flags: LS) exposing the state and events of the right button + ◦ cluster Descriptor with its TagList containing two tags: Position.Right and Number.Two + +If this device were to have labeling on the buttons like an "up" and "down" icon, the TagList would +have a third tag (from the Switches Namespace) with values Switches.Up and Switches.Down +respectively. + +Example 2: a device with four push buttons (mounted in a square), each labeled with an icon for a +certain scene setting, which has four endpoints (21,22,23,24) for the switch-related functionality + +- endpoint 21 has device type Generic Switch and contains + ◦ cluster Switch (feature flags: MS) exposing the events of the top-left button + ◦ cluster Descriptor with its TagList containing four tags: Position.Top, Position.Left, Num­ + ber.One and (Tag=Switches.Custom, Label="watch tv") + ▪ This last tag is a Switches.Custom tag accompanied with a label (the other three tags do + not need a Label field). +- endpoint 22 has device type Generic Switch and contains + ◦ cluster Switch (feature flags: MS) exposing the events of the top-right button + ◦ cluster Descriptor with its TagList containing four tags: Position.Top, Position.Right, Num­ + ber.Two and (Tag=Switches.Custom, Label="dinner") +- endpoint 23 has device type Generic Switch and contains + ◦ cluster Switch (feature flags: MS) exposing the events of the bottom-left button + ◦ cluster Descriptor with its TagList containing four tags: Position.Bottom, Position.Left, Num­ + ber.Three and (Tag=Switches.Custom, Label="reading") +- endpoint 24 has device type Generic Switch and contains + ◦ cluster Switch (feature flags: MS) exposing the events of the bottom-right button + ◦ cluster Descriptor with its TagList containing four tags: Position.Bottom, Position.Right, + Number.Four and (Tag=Switches.Custom, Label="nightlight") + +**6.6.5. Relation with other Switch device types (informative)** + +The Generic Switch device type and the On/Off Light Switch device type both convey information +about interactions with a switch to another device. + +``` +Page 64 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +- The On/Off Light Switch will send On/Off/Toggle commands from its On/Off (client) cluster to a + device implementing the On/Off (server) cluster to control the on/off functionality of that + device. An On/Off Light Switch device can also implement Groups and Scenes Management clus­ + ters and thus send group and scene commands. Basically, it is targeted at directly sending con­ + trol commands to other devices. The binding table is used to tell the device where to send the + commands. +- The Generic Switch device type will send updates of attributes (for Latching Switch only) and + events to subscribed parties which implement the Switch client cluster, as indications of inter­ + action with the switch - leaving the interpretation (e.g. which device should be actuated because + of the interaction) to the subscribed party. So it can be compared to a sensor-type device. + This allows a more comprehensive controller to combine the information from the switch with + other inputs or information sources (e.g. time of day, user presence) to determine which control + commands (e.g. on/off, scene recall, attribute change) are sent to other devices in the network. + +A device manufacturer MAY implement both device types on the same switch device, to allow it to +be used for both types of control, as in this example for a rocker switch which implements: + +- endpoint 31 with device type On/Off Light Switch which contains + ◦ (client) cluster On/Off exposing the On/Off/Toggle commands +- endpoint 32 with device type Generic Switch which contains + ◦ (server) cluster Switch (feature flags: LS) exposing the state and events of the switch + +When this device is used in a particular setup, binding tables and subscriptions can be used to +determine how it is used: + +- used as an On/Off Light Switch (no subscriptions to endpoint 32) +- used as a Generic Switch (no bindings on endpoint 31) +- used as both at the same time. In this case, an interaction with the switch would result in an + On/Off/Toggle command being sent to devices listed in the binding table of endpoint 31, as well + as attribute update and events being sent towards devices having a subscription with endpoint + 32. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 65 +``` + +Page 66 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 7. Sensor Device Types** + +**7.1. Contact Sensor Device Type** + +This defines conformance to the Contact Sensor device type. + +**7.1.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Add Boolean State Configuration as optional +cluster +``` +**7.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0015 Contact Sensor Simple Endpoint +``` +**7.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +0x0045 Boolean State Server M +0x0080 Boolean State Con­ +figuration +``` +``` +Server O +``` +**7.1.4.1. Identify Cluster** + +This is used to identify the endpoint. + +**7.1.4.2. Boolean State Cluster** + +This is used to indicate the state of the sensor/detector. + +The state of the Boolean State cluster SHALL reflect the sensor detection using this scheme: + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 67 +``` + +``` +Value State +True Closed or contact +False Open or no contact +``` +**7.1.4.3. Boolean State Configuration Cluster** + +This is used to configure the sensor/detector and is for this device type linked to the configuration +of the Boolean State cluster. + +**7.2. Light Sensor** + +A Light Sensor device is a measurement and sensing device that is capable of measuring and +reporting the intensity of light (illuminance) to which the sensor is being subjected. + +**7.2.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Restricting Groups client to Zigbee. +``` +**7.2.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0106 Light Sensor Simple Endpoint +``` +**7.2.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.2.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 17. Light Sensor Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Client [Zigbee] +0x0400 Illuminance Mea­ +surement +``` +``` +Server M +``` +``` +Page 68 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.3. Occupancy Sensor Device Type** + +An Occupancy Sensor is a measurement and sensing device that is capable of measuring and +reporting the occupancy state in a designated area. + +**7.3.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Restricting Groups client to Zigbee +4 Add Boolean State Configuration as optional +cluster +``` +**7.3.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0107 Occupancy Sensor Simple Endpoint +``` +**7.3.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.3.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +0x0080 Boolean State Con­ +figuration +``` +``` +Server O +``` +``` +0x0406 Occupancy Sens­ +ing +``` +``` +Server M +``` +**7.3.4.1. Identify Cluster** + +This is used to identify the endpoint. + +**7.3.4.2. Boolean State Configuration Cluster** + +This is used to configure the sensor/detector (e.g. sensitivity) and is for this device type linked to the +configuration of the Occupancy Sensing cluster on the same endpoint. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 69 +``` + +**7.3.4.3. Occupancy Sensing Cluster** + +This is used to indicate occupancy as well as the type of occupancy sensor used for detection and +configuring the delays related to the occupied and unoccupied transitions. + +**7.3.5. Multi-modality sensors** + +The Occupancy Sensing cluster defines multiple modalities that can be employed to sense occu­ +pancy. A device implementing multiple such modalities (exposed in the feature flags) can be imple­ +mented in two ways: + +- A single endpoint with an Occupancy Sensing cluster which has two or more of these feature + bits set to 1. + ◦ This requires reporting the combination the sensing results as a single bit in the Occupancy + attribute (and the OccupancyChanged event, when supported), with a single set of timing + parameters applied. + ◦ Sensitivity setting (via a Boolean State Configuration cluster on the same endpoint) applies + to all the sensing modalities together via a manufacturer-specific mapping. +- Multiple endpoints each hosting an Occupancy Sensing cluster (each with one feature bit set): + ◦ The sensing result of each modality is reported separately in the Occupancy attribute (and + the OccupancyChanged event, when supported) of each endpoint, governed by the set of + timing parameters provided in the cluster on that endpoint. + ▪ This implies some of these attributes can have a different values than their counterparts + on other endpoints and that a client MAY have to combine these values if it wants to + derive a single value. + ◦ Each modality can be provided with an independent sensitivity setting via a Boolean State + Configuration cluster located on one or more of the endpoints. + +**7.4. Temperature Sensor** + +A Temperature Sensor device reports measurements of temperature. + +**7.4.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +``` +**7.4.2. Classification** + +``` +Page 70 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Device Name Superset Class Scope +0x0302 Temperature Sen­ +sor +``` +``` +Simple Endpoint +``` +**7.4.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.4.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0402 Temperature Mea­ +surement +``` +``` +Server M +``` +``` +0x0003 Identify Server M +0x0004 Groups Client [Zigbee] +``` +**7.5. Pressure Sensor** + +A Pressure Sensor device measures and reports the pressure of a fluid. + +**7.5.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +``` +**7.5.2. Classification** + +``` +ID Device name Superset Class Scope +0x0305 Pressure Sensor Simple Endpoint +``` +**7.5.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.5.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 18. Pressure Sensor Cluster Requirements_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 71 +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0403 Pressure Measure­ +ment +``` +``` +Server M +``` +``` +0x0003 Identify Server M +0x0004 Groups Client [Zigbee] +``` +**7.6. Flow Sensor** + +A Flow Sensor device measures and reports the flow rate of a fluid. + +**7.6.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +``` +**7.6.2. Classification** + +``` +ID Device name Superset Class Scope +0x0306 Flow Sensor Simple Endpoint +``` +**7.6.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.6.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 19. Flow Sensor Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0404 Flow Measure­ +ment +``` +``` +Server M +``` +``` +0x0003 Identify Server M +0x0004 Groups Client [Zigbee] +``` +**7.7. Humidity Sensor** + +A humidity sensor (in most cases a Relative humidity sensor) reports humidity measurements. + +``` +Page 72 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.7.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +``` +**7.7.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0307 Humidity Sensor Simple Endpoint +``` +**7.7.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.7.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0405 Relative Humidity +Measurement +``` +``` +Server M +``` +``` +0x0004 Groups Client [Zigbee] +``` +**7.8. On/Off Sensor** + +An On/Off Sensor is a measurement and sensing device that, when bound to a lighting device such +as a Dimmable Light, is capable of being used to switch the device on or off. + +**7.8.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 73 +``` + +**7.8.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0850 On/Off Sensor Simple Endpoint +``` +**7.8.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.8.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +_Table 20. On/Off Sensor Cluster Requirements_ + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0003 Identify Client M +0x0004 Groups Client O +0x0062 Scenes Manage­ +ment +``` +``` +Client P, O +``` +``` +0x0006 On/Off Client M +0x0008 Level Control Client O +0x0300 Color Control Client O +``` +**7.9. Smoke CO Alarm** + +A Smoke CO Alarm device is capable of sensing smoke, carbon monoxide or both. It is capable of +issuing a visual and audible alert to indicate elevated concentration of smoke or carbon monoxide. + +Smoke CO Alarms are capable of monitoring themselves and issuing visual and audible alerts for +hardware faults, critical low battery conditions, and end of service. Optionally, some of the audible +alerts can be temporarily silenced. Smoke CO Alarms are capable of performing a self-test which +performs a diagnostic of the primary sensor and issuing a cycle of the audible and visual life safety +alarm indications. + +Some smoke alarms MAY be capable of adjusting sensitivity. Smoke CO Alarm MAY have the ability +to detect and report humidity levels, temperature levels, and contamination levels. + +**7.9.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Page 74 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Revision Description +1 Initial revision +``` +**7.9.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0076 Smoke CO Alarm Simple Endpoint +``` +**7.9.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.9.4. Device Type Requirements** + +A Smoke CO Alarm device type SHALL support an instance of a Power Source device type on some +endpoint. Please see the Power Source cluster for more information. + +``` +ID Name Constraint Conformance +0x0011 Power Source min 1 M +``` +**7.9.5. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server O +0x005C Smoke CO Alarm Server M +0x0405 Relative Humidity +Measurement +``` +``` +Server O +``` +``` +0x0402 Temperature Mea­ +surement +``` +``` +Server O +``` +``` +0x040C Carbon Monoxide +Concentration +Measurement +``` +``` +Server O +``` +**7.10. Air Quality Sensor** + +This defines conformance for the Air Quality Sensor device type. + +An air quality sensor is a device designed to monitor and measure various parameters related to +the quality of ambient air in indoor or outdoor environments. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 75 +``` + +**7.10.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**7.10.2. Classification** + +``` +ID Device Name Superset Class Scope +0x002C Air Quality Sensor Simple Endpoint +``` +**7.10.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.10.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x005B Air Quality Server M +0x0402 Temperature Mea­ +surement +``` +``` +Server O +``` +``` +0x0405 Relative Humidity +Measurement +``` +``` +Server O +``` +``` +0x040C Carbon Monoxide +Concentration +Measurement +``` +``` +Server O +``` +``` +0x040D Carbon Dioxide +Concentration +Measurement +``` +``` +Server O +``` +``` +0x0413 Nitrogen Dioxide +Concentration +Measurement +``` +``` +Server O +``` +``` +0x0415 Ozone Concentra­ +tion Measurement +``` +``` +Server O +``` +``` +0x042B Formaldehyde +Concentration +Measurement +``` +``` +Server O +``` +``` +Page 76 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x042C PM1 Concentra­ +tion Measurement +``` +``` +Server O +``` +``` +0x042A PM2.5 Concentra­ +tion Measurement +``` +``` +Server O +``` +``` +0x042D PM10 Concentra­ +tion Measurement +``` +``` +Server O +``` +``` +0x042F Radon Concentra­ +tion Measurement +``` +``` +Server O +``` +``` +0x042E Total Volatile +Organic Com­ +pounds Concentra­ +tion Measurement +``` +``` +Server O +``` +**7.11. Water Freeze Detector Device Type** + +This defines conformance to the Water Freeze Detector device type. + +**7.11.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**7.11.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0041 Water Freeze +Detector +``` +``` +Simple Endpoint +``` +**7.11.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.11.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 77 +``` + +``` +ID Name Client/Server Quality Conformance +0x0045 Boolean State Server M +0x0080 Boolean State Con­ +figuration +``` +``` +Server O +``` +**7.11.4.1. Identify Cluster** + +This is used to identify the endpoint. + +**7.11.4.2. Boolean State Cluster** + +This is used to indicate the state of the sensor/detector. + +The state of the Boolean State cluster SHALL reflect the sensor detection using this scheme of: + +``` +Value State +True Water could potentially freeze in the current +ambient conditions +False Water is very unlikely to freeze in the current +ambient conditions +``` +Due to the difficulty in quantifying the risk of freezing based on the dependency on external factors +such as temperature, humidity, pressure, etc, the actual triggering of a detector of this type depends +on the physical construction and characteristics of the device and is therefore considered manufac­ +turer specific. + +**7.11.4.3. Boolean State Configuration Cluster** + +This is used to configure the sensor/detector and is for this device type linked to the configuration +of the Boolean State cluster. + +**7.11.5. Element Requirements** + +The following table lists qualities and conformance that override the cluster specification require­ +ments. A blank table cell means there is no change to that item and the value from the cluster speci­ +fication applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0045 Boolean +State +``` +``` +Event StateChange M +``` +**7.12. Water Leak Detector Device Type** + +This defines conformance to the Water Leak Detector device type. + +``` +Page 78 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.12.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**7.12.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0043 Water Leak Detec­ +tor +``` +``` +Simple Endpoint +``` +**7.12.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.12.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +0x0045 Boolean State Server M +0x0080 Boolean State Con­ +figuration +``` +``` +Server O +``` +**7.12.4.1. Identify Cluster** + +This is used to identify the endpoint. + +**7.12.4.2. Boolean State Cluster** + +This is used to indicate the state of the sensor/detector. + +The state of the Boolean State cluster SHALL reflect the sensor detection using this scheme of: + +``` +Value State +True Water leak detected +False No water leak detected +``` +**7.12.4.3. Boolean State Configuration Cluster** + +This is used to configure the sensor/detector and is for this device type linked to the configuration + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 79 +``` + +of the Boolean State cluster. + +**7.12.5. Element Requirements** + +The following table lists qualities and conformance that override the cluster specification require­ +ments. A blank table cell means there is no change to that item and the value from the cluster speci­ +fication applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0045 Boolean +State +``` +``` +Event StateChange M +``` +**7.13. Rain Sensor Device Type** + +This defines conformance to the Rain Sensor device type. + +**7.13.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**7.13.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0044 Rain Sensor Simple Endpoint +``` +**7.13.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**7.13.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +0x0045 Boolean State Server M +0x0080 Boolean State Con­ +figuration +``` +``` +Server O +``` +``` +Page 80 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**7.13.4.1. Identify Cluster** + +This is used to identify the endpoint. + +**7.13.4.2. Boolean State Cluster** + +This is used to indicate the state of the sensor/detector. + +The state of the Boolean State cluster SHALL reflect the sensor detection using this scheme of: + +``` +Value State +True Rain detected +False No rain detected +``` +**7.13.4.3. Boolean State Configuration Cluster** + +This is used to configure the sensor/detector and is for this device type linked to the configuration +of the Boolean State cluster. + +**7.13.5. Element Requirements** + +The following table lists qualities and conformance that override the cluster specification require­ +ments. A blank table cell means there is no change to that item and the value from the cluster speci­ +fication applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0045 Boolean +State +``` +``` +Event StateChange M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 81 +``` + +Page 82 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 8. Closure Device Types** + +**8.1. Door Lock Device Type** + +A Door Lock is a device used to secure a door. It is possible to actuate a door lock either by means of +a manual or a remote method. + +**8.1.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 Initial Matter revision +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**8.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x000A Door Lock Simple Endpoint +``` +**8.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**8.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server X +0x0062 Scenes Manage­ +ment +``` +``` +Server X +``` +``` +0x0101 Door Lock Server M +``` +Nodes supporting this device type MAY implement Matter Time Synchronization by including the +Time Synchronization Cluster (0x0038) server on the Root Node Endpoint and MAY also implement +a Time Synchronization Cluster client for querying time from other nodes. Nodes supporting this +device type that implement a Time Synchronization Cluster client SHALL include the Time Synchro­ +nization Cluster server on the Root Node Endpoint and SHALL include the Time Synchronization +Client Feature. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 83 +``` + +**8.1.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0001 AccessCon­ +trol +``` +``` +Attribute Extension Matter +``` +``` +0x0101 Door Lock Feature User Matter & +(PIN | RID | +FPG | FACE | +ALIRO ) +0x0101 Door Lock Feature RFIDCreden­ +tial +``` +### P, O + +``` +0x0101 Door Lock Attribute AlarmMask [Alarms] +``` +**8.2. Door Lock Controller Device Type** + +A Door Lock Controller is a device capable of controlling a door lock. + +**8.2.1. Revision History** + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 Initial Matter revision +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**8.2.2. Classification** + +``` +ID Device Name Superset Class Scope +0x000B Door Lock Con­ +troller +``` +``` +Simple Endpoint +``` +**8.2.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**8.2.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +Page 84 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Client/Server Quality Conformance +0x0004 Groups Client O +0x0062 Scenes Manage­ +ment +``` +``` +Client P, O +``` +``` +0x0038 Time Synchroniza­ +tion +``` +``` +Server O +``` +``` +0x0101 Door Lock Client M +``` +**8.3. Window Covering** + +This defines conformance to the Window Covering device type. + +**8.3.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**8.3.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0202 Window Covering Simple Endpoint +``` +**8.3.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**8.3.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server Active, O +0x0102 Window Covering Server M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 85 +``` + +**8.3.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0102 Window +Covering +``` +``` +Feature AbsolutePo­ +sition +``` +``` +Zigbee +``` +**8.4. Window Covering Controller** + +A Window Covering Controller is a device that controls an automatic window covering. + +**8.4.1. Revision History** + +``` +Rev Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation +3 Updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +``` +**8.4.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0203 Window Covering +Controller +``` +``` +Simple Endpoint +``` +**8.4.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**8.4.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server O +0x0003 Identify Client O +0x0004 Groups Client Active, O +0x0102 Window Covering Client M +``` +``` +Page 86 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**8.4.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0102 Window +Covering +``` +``` +Feature AbsolutePo­ +sition +``` +``` +Zigbee +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 87 +``` + +Page 88 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 9. HVAC Device Types** + +**9.1. Thermostat** + +A Thermostat device is capable of having either built-in or separate sensors for temperature, +humidity or occupancy. It allows the desired temperature to be set either remotely or locally. The +thermostat is capable of sending heating and/or cooling requirement notifications to a heating/cool­ +ing unit (for example, an indoor air handler) or is capable of including a mechanism to control a +heating or cooling unit directly. + +**9.1.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial Zigbee 3.0 revision +2 New data model format and notation, added +Clusters required for Matter support, restricted +legacy elements to Zigbee only +3 Addition of Energy Preference cluster and +updated the Scenes cluster to Scenes Manage­ +ment with Cluster ID: 0x0062 +4 Remove Time Synchronization cluster and Zig­ +bee only clusters, remove provisional marking +from Energy Preference cluster +``` +**9.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0301 Thermostat Simple Endpoint +``` +**9.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**9.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server Active +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 89 +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0201 Thermostat Server M +0x0204 Thermostat User +Interface Configu­ +ration +``` +``` +Server O +``` +``` +0x009B Energy Preference Server O +0x0202 Fan Control Client O +0x0402 Temperature Mea­ +surement +``` +``` +Client O +``` +``` +0x0405 Relative Humidity +Measurement +``` +``` +Client O +``` +``` +0x0406 Occupancy Sens­ +ing +``` +``` +Client O +``` +**9.1.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0201 Thermostat Feature Schedule­ +Configura­ +tion +``` +### X + +``` +0x0201 Thermostat Attribute AlarmMask X +0x0201 Thermostat Command GetRelaySta­ +tusLog +``` +### X + +``` +0x0201 Thermostat Command GetRelaySta­ +tusLogRe­ +sponse +``` +### X + +**9.2. Fan** + +A Fan device is typically standalone or mounted on a ceiling or wall and is used to circulate air in a +room. + +**9.2.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Page 90 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Revision Description +1 Initial revision +2 Added ability to be composed with a Thermostat +for fan heaters +3 Added On/Off cluster +``` +**9.2.2. Classification** + +``` +ID Device Name Superset Class Scope +0x002B Fan Simple Endpoint +``` +**9.2.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**9.2.4. Device Type Requirements** + +A fan MAY expose elements of its functionality through one or more additional device types on dif­ +ferent endpoints. All devices used in compositions SHALL adhere to the disambiguation require­ +ments of the System Model. Other device types, not explicitly listed in the table, MAY also be +included in device compositions but are not considered part of the core functionality of the device. + +``` +ID Name Constraint Conformance +0x0301 Thermostat O +``` +**9.2.5. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify server M +0x0004 Groups server M +0x0006 On/Off server O +0x0202 Fan Control server M +``` +**9.2.6. Cluster Restrictions** + +**9.2.6.1. On/Off Cluster (Server) Clarifications** + +The On/Off cluster is independent from the Fan Control Cluster’s FanMode attribute, which also +includes an Off setting. + +If the FanMode attribute of the Fan Control cluster is set to a value other than Off when the OnOff + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 91 +``` + +attribute of the On/Off cluster transitions from TRUE to FALSE, it may be desirable to restore the +FanMode, SpeedSetting and PercentSetting attribute values of the Fan Control cluster when the OnOff +attribute of the On/Off cluster later transitions from FALSE to TRUE. If the FanMode is set to Off when +the device is turned off, this information is lost, as the SpeedSetting and PercentSetting will be set to +zero. Using the On/Off cluster alongside the Fan Control cluster allows the FanMode, SpeedSetting and +PercentSetting to remain unchanged when the device is turned off. In this case, the On/Off cluster +would be set to Off, and the SpeedCurrent and PercentCurrent set to zero, without changing FanMode, +SpeedSetting and PercentSetting. + +**9.2.7. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +entry means no change. + +``` +ID Cluster Element Name Quality Constraint Access Confor­ +mance +0x0202 Fan Con­ +trol +``` +``` +Attribute FanMode­ +Sequence +``` +``` +F R V Matter +``` +**9.3. Air Purifier** + +An Air Purifier is a standalone device that is designed to clean the air in a room. + +It is a device that has a fan to control the air speed while it is operating. Optionally, it can report on +the condition of its filters. + +**9.3.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Added On/Off cluster +``` +**9.3.2. Classification** + +``` +ID Device Name Superset Class Scope +0x002D Air Purifier Simple Endpoint +``` +**9.3.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +``` +Page 92 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**9.3.4. Device Type Requirements** + +An Air Purifier MAY expose elements of its functionality through one or more additional device +types on different endpoints. All devices used in compositions SHALL adhere to the disambiguation +requirements of the System Model. Other device types, not explicitly listed in the table, MAY also be +included in device compositions but are not considered part of the core functionality of the device. + +``` +ID Name Constraint Conformance +0x0301 Thermostat O +0x0302 Temperature Sensor O +0x0307 Humidity Sensor O +0x002C Air Quality Sensor O +``` +**9.3.5. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0004 Groups Server O +0x0006 On/Off Server O +0x0202 Fan Control Server M +0x0071 HEPA Filter Moni­ +toring +``` +``` +Server O +``` +``` +0x0072 Activated Carbon +Filter Monitoring +``` +``` +Server O +``` +**9.3.6. Cluster Restrictions** + +**9.3.6.1. On/Off Cluster (Server) Clarifications** + +The On/Off cluster is independent from the Fan Control Cluster’s FanMode attribute, which also +includes an Off setting. + +If the FanMode attribute of the Fan Control cluster is set to a value other than Off when the OnOff +attribute of the On/Off cluster transitions from TRUE to FALSE, it may be desirable to restore the +FanMode, SpeedSetting and PercentSetting attribute values of the Fan Control cluster when the OnOff +attribute of the On/Off cluster later transitions from FALSE to TRUE. If the FanMode is set to Off when +the device is turned off, this information is lost, as the SpeedSetting and PercentSetting will be set to +zero. Using the On/Off cluster alongside the Fan Control cluster allows the FanMode, SpeedSetting and +PercentSetting to remain unchanged when the device is turned off. In this case, the On/Off cluster +would be set to Off, and the SpeedCurrent and PercentCurrent set to zero, without changing FanMode, +SpeedSetting and PercentSetting. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 93 +``` + +**9.3.7. Element Requirements** + +There are no cluster element overrides. + +``` +Page 94 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 10. Media Device Types** + +**10.1. Video Player Architecture** + +**10.1.1. Introduction** + +A Video Player endpoint (either Casting Video Player or Basic Video Player) represents a device that +is able to play media to a physical output or to a display screen which is part of the device. For +example, a Video Player can be a traditional TV device, a physical media playback device such as a +DVD Player, a TV Set Top Box, or a content streaming device that provides input to another device +like a TV or computer monitor. + +Video Player features can be categorized into **basic** and **content launching**. + +The **basic** features include (conceptually): On/Off, Volume Control, Playback Control, Channel +Change, Input Control, Output Control, Sleep/Wake, Target Navigation and Keypad Navigation. + +The **content launching** features include: discovery and launch of Content Apps, search and launch +of content by content name and by URL. + +A Basic Video Player is a **commissionable node** and supports these basic features which include, at +a minimum, media playback controls (Media Playback cluster server) and remote controls (Keypad +Input cluster server). + +A Casting Video Player is a **commissioner** and supports both the Basic Video Player features and +content launching features which include, at a minimum, the ability to launch content (Content +Launcher cluster server). + +A Content App is usually an application built by a Content Provider and exists as a separate end­ +point on a Casting Video Player with a Content App Platform. + +When a Casting Video Player includes a Content App Platform, it can launch Content Apps (Applica­ +tion Launcher cluster server) and represent these apps as separate endpoints on the Node. + +A Video Remote Control is a **commissionable node** used to control basic features including, at a +minimum, the ability to initiate keypad navigation (Keypad Input cluster client) and media play­ +back (Media Playback cluster client). + +A Casting Video Client is a **commissionable node** which extends the Video Remote Control features +with the ability to initiate content launching (Content Launcher cluster client). A Casting Video +Client is often associated with a Content App built by a specific Content Provider - for example, the +Vendor Id of the Content App’s Application Basic cluster will match the Vendor Id of the Casting +Video Client. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 95 +``` + +_Figure 1. Video Player Device Types_ + +**10.1.2. Clients of a Casting Video Player** + +The clients for a Video Player device can be categorized into 2 high-level groups. + +1. Clients controlling the Video Player endpoint such as a remote control (eg : Video Remote device + type) +2. Clients controlling specific Content App(s) such as a Phone App casting to a corresponding Con­ + tent App (eg : Casting Video Client device type) + +**10.1.3. Endpoint Composition for Content Apps of a Casting Video Player** + +A Casting Video Player with a Content App Platform SHALL represent each Content App as its own +dedicated endpoint where each is identified using the Device ID 0x0024 for "Content App". + +The requirements for allocating and deallocating an endpoint address for a Content App SHALL be +as described in the System Model specification (see "Dynamic Endpoint allocation"). + +The following diagram shows a Video Player device containing 3 separate Content Apps: + +``` +Page 96 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 2. Endpoint Composition for Video Player Device_ + +**10.1.4. Commissioning** + +A Basic Video Player SHALL be commissioned like any commissionable node. + +A Casting Video Player SHALL be a Commissioner. The primary reason for this requirement is to +enable the Casting Video Player to verify, using device attestation, the vendor of a Client for the pur­ +pose of controlling content on the Casting Video Player, and to ensure that only clients authorized +by a Content App can control it. In this way, a Commissionee associated with a Content App on the +Casting Video Player can be commissioned by the Casting Video Player and granted access to the +endpoint associated with that Content App. + +When a Casting Video Player commissions a Client, such as a Video Remote Control or a Casting +Video Client, the Casting Video Player SHALL determine the Content App access for the given Client +following the rules defined in this section. Since the Client is being commissioned by the Casting +Video Player, the Client, which may be a phone app, SHALL include attestation credentials which +are used by the Casting Video Player to determine its Vendor ID. + +1. A Casting Video Player SHOULD allow each Content App to specify which clusters it implements, + and reflect these clusters in the corresponding endpoint for the given Content App. The method + for conveying this information between the Content App and the Casting Video Player is specific + to the vendor of the Casting Video Player. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 97 +``` + +2. A Casting Video Player SHALL allow each Content App to specify values for fields in the Applica­ + tion Basic cluster, such as Vendor ID and Application Name. A Casting Video Player SHALL also + use this information to determine access control for Clients commissioned by the Casting Video + Player. The method for conveying this information between the Content App and the Casting + Video Player is specific to the vendor of the Casting Video Player. +3. A Casting Video Player device SHALL allow each Content App to provide an Allowed Controller + Vendor ID list. The Allowed Controller Vendor ID list specifies a list of Vendor IDs for Clients that + SHALL be granted access to the endpoint for the given Content App. The Casting Video Player + device SHALL use the Allowed Controller Vendor ID list to determine access control for Clients + commissioned by the Casting Video Player. Only Clients with a Vendor ID in the Allowed Con­ + troller Vendor ID list SHALL be granted access to the given Content App endpoint. The method + for conveying this information between the Content App and the Casting Video Player is specific + to the vendor of the Casting Video Player. When a Client is commissioned, its attested Vendor ID + is used to determine access to Content App endpoints. The Allowed Controller Vendor ID list is + contained in the AllowedVendorList attribute of the Application Basic cluster. + +A Casting Video Player MAY enable a commissioning flow, which avoids Setup PIN entry by the +user, when the following conditions are met: + +1. The Client’s Vendor ID and a Rotating ID (used as a TempAccountIdentifier) are present in its + commissionable node advertisement, or present in a User Directed Commissioning message + sent by the Client to initiate commissioning with the Casting Video Player. +2. The Casting Video Player is able to determine an endpoint corresponding to the given Vendor ID + which contains the Account Login cluster (for example, a Content App endpoint). +3. The Account Login cluster’s GetSetupPIN command returns a SetupPIN which is then used suc­ + cessfully to commission the Client. + +A Casting Video Player MAY enable a Content App account login flow, which avoids login name and +password entry by the user, when the following conditions are met: + +1. The Client’s Vendor ID and a Rotating ID (used as a TempAccountIdentifier) are present in its + commissionable node advertisement, or present in a User Directed Commissioning message + sent by the Client to initiate commissioning with the Casting Video Player. +2. The Casting Video Player is able to determine an endpoint corresponding to the given Vendor ID + which contains the Account Login cluster (for example, a Content App endpoint). +3. The Account Login cluster’s Login command returns successfully. + +In these flows, when the Account Login cluster is located on a Content App endpoint, the Account +Login cluster will often be implemented by a different vendor from the Casting Video Player itself. +See AccountLoginCluster for further details on the use of these commands. + +Since a Client commissioned by the Casting Video Player will only have access to one or more Con­ +tent App endpoints and the Speaker endpoint (when present), it will not have the ability to access +the Application Launcher cluster on the Casting Video Player endpoint. If they do not already exist, +the Casting Video Player device SHALL create endpoints for each Content App to which the Client +has access and notify the Client of such access by adding an entry for each Content App to the Bind­ +ing cluster of the Client. The Casting Video Player device SHALL automatically launch the Content + +``` +Page 98 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +App upon commands targeted to a Content App endpoint. + +The following steps are performed by a Casting Video Player when granting and removing Client +access to Content App endpoints: + +1. Upon commissioning a Client and granting it access to a Content App endpoint, the Casting + Video Player SHALL invoke the Login command of the AccountLogin cluster on the Content App + endpoint (when implemented by the Content App) in order to notify the Content App endpoint + of the Client. + a. If the Client is a Casting Video Client and it implements the Content App Observer server + cluster, and if the Content App endpoint implements both the Binding server cluster and the + Content App Observer client cluster, then the Casting Video Player SHALL create a binding + on the Content App endpoint which specifies the Node and Endpoint of the Casting Video + Client’s Content App Observer server cluster. The Casting Video Player SHALL provide a way + for the Content App to send a Content App Observer cluster ContentAppMessage command + to the Casting Video Client and to receive a ContentAppMessageResponse in return. +2. Upon removing access to a Content App endpoint for a Client, the Casting Video Player SHALL + invoke the Logout command of the AccountLogin cluster on the Content App endpoint (when + implemented by the Content App) in order to notify the Content App endpoint that Client access + has been removed. + a. If the Casting Video Player created a binding on the Content App endpoint corresponding to + the Casting Video Client’s Content App Observer server cluster, then the Casting Video Player + SHALL remove this binding. + +When the Content App endpoint generates a LoggedOut event, the Casting Video Player SHALL +remove access to the Node specified to the given Content App endpoint. + +### NOTE + +``` +A Client commissioned by the Casting Video Player is able to determine if the corre­ +sponding Content App is visible to the user using the Status attribute on the Appli­ +cation Basic cluster for the Content App endpoint. This ensures that the Client can­ +not access foreground Content App information about any other Content App to +which it does not have access. It also ensures that such a client will only need access +to specific Content App endpoints and the Speaker endpoint (when present). +``` +**10.1.5. Determining Context** + +A client that controls multiple aspects of the Video Player functionality (like a voice assistant) may +have access to multiple endpoints on the Video Player. To determine the current context on the +Video Player when the user interacts with the client (for example, when the user interacts with the +device using voice), the client can look at the state in the various clusters on the Casting Video +Player. + +Specifically: + +1. Media Input cluster (when CurrentInput does NOT have type INTERNAL, then Video Player is + displaying content from a physical input) +2. Application Launcher cluster (CurrentApp indicates the current application endpoint - which + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 99 +``` + +``` +may be the Video Player endpoint when no Content App is in the foreground). +``` +3. Target Navigator cluster on current application endpoint (indicates which navigation target the + user is in) + +The Video Player SHOULD provide a way for the user to view the list of clients with access to con­ +trol the screen and SHOULD provide a way for the user to revoke this access. + +**10.1.6. Basic Video Player Features** + +**10.1.6.1. On/Off/Toggle** + +This feature turns on/off the user-visible power state of the device, corresponding to the on/off/tog­ +gle button usually found on a remote or button on the device. + +An On/Off cluster on the Video Player endpoint SHALL be used for this feature. + +**10.1.6.2. Volume Control** + +This feature controls the speaker volume of the device. + +A Speaker endpoint SHALL be used for this feature when the device controls a speaker. + +**10.1.6.3. Media Playback Control** + +This feature controls media playback on the device which includes functionality such as Play, +Pause, Stop, Rewind, and Fast Forward. + +The Media Playback cluster SHALL be used for this functionality. + +**10.1.6.4. Channel Change** + +This feature controls channel control functionality on the device which includes functionality such +as lineup discovery, change and skip channels. + +The Channel cluster SHALL be used for this functionality. + +**10.1.6.5. Media Input Control** + +This feature controls the input selection on the device which includes functionality such as input +discovery, selection and naming. + +The Media Input cluster SHALL be used for this functionality. + +**10.1.6.6. Audio Output Control** + +This feature controls audio output selection on the device which includes functionality such as out­ +put discovery, selection and naming. + +The Audio Output cluster SHALL be used for this functionality. + +Note that when the current output is set to an output of type HDMI, adjustments to volume via a + +``` +Page 100 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +Speaker endpoint on the same node MAY cause HDMI volume up/down commands to be sent to the +given HDMI output. + +**10.1.6.7. Sleep/Wake** + +This feature controls low power mode on the device which includes functionality such as sleep, and +declaration of protocols supported for Wakeup. + +The Low Power cluster SHALL be used for putting a device into low power (sleep) mode. + +The WakeOnLAN cluster SHALL be used for declaring that a device supports the WakeOnLAN pro­ +tocol. + +**10.1.6.8. Target Navigation** + +This feature controls on-screen navigation to custom-named targets, for example, "Settings", "On +Demand" and "Search". A list of named targets can be provided for the Video Player endpoint itself, +as well as for Content App represented as endpoints. + +The Target Navigator cluster SHALL be used for listing navigation targets, invoking navigation to a +target, and tracking the current target. + +**10.1.6.9. Keypad Navigation** + +This feature controls on-screen navigation, commonly referred to as D-Pad navigation, and includes +navigation commands such as UP, DOWN, LEFT, RIGHT, SELECT, BACK, EXIT, MENU. + +The Keypad Input cluster SHALL be used for this functionality. + +**10.1.6.10. Account Login** + +This cluster provides commands that facilitate user account login on an application or a node. + +The Account Login cluster SHALL be used for this functionality. + +**10.1.7. Content Launching Features** + +Many Video Player devices (traditional TVs, Set Top Boxes, Content Streamers) have advanced fea­ +tures that MAY include any of the following: + +- the ability to search for and playback content such as movies and TV shows +- a platform for Content Apps that can themselves be launched, and instructed to search and + playback content such as movies and TV shows +- the ability to download and playback basic content referenced by URL + +**10.1.7.1. Discover and Launch Content App from another Device** + +This feature allows a client to discover the Content App identification catalogs supported by a Video +Player device, and launch an Application based upon a Content App identifier within a given cata­ +log. An example Content App identification catalog is the DIAL registry (http://www.dial-multi­ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 101 +``` + +screen.org/). + +The Application Launcher cluster SHALL be used for this functionality. + +**10.1.7.2. Launch Content from another Device** + +Content search and launch is defined by the Content Launcher cluster which includes feature flags +for Content Search and URL Playback which are used to indicate which of these features is sup­ +ported. + +The Content Launcher cluster SHALL be used for this functionality. + +**10.2. Basic Video Player** + +This defines conformance to the Basic Video Player device type. + +A Video Player (either Basic or Casting) represents a device that is able to play media to a physical +output or to a display screen which is part of the device. + +A Basic Video Player has playback controls (play, pause, etc.) and keypad remote controls (up, +down, number input), but is not able to launch content and is not a content app platform (the Cast­ +ing Video Player device type is used for these functions). + +For example, a Basic Video Player can be a traditional TV device a physical media playback device +such as a DVD Player, or a device that provides input to another device like a TV or computer moni­ +tor. + +Please see Video Player Architecture for additional Basic Video Player requirements relating to +Video Player device endpoint composition, commissioning, feature representation in clusters, and +UI context. + +**10.2.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Added Messages and Content Control clusters +``` +**10.2.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0028 Basic Video Player Simple Endpoint +``` +**10.2.3. Conditions** + +This device type SHALL support the following conformance conditions as defined below. + +``` +Page 102 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Feature Description +PhysicalInputs The device has physical inputs for media. +``` +Please see the Base Device Type definition for additional conformance tags. + +**10.2.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0006 OnOff Server M +0x0503 WakeOnLAN Server O +0x0504 Channel Server O +0x0505 Target Navigator Server O +0x0506 Media Playback Server M +0x0507 Media Input Server PhysicalInputs +0x0508 Low Power Server O +0x0509 Keypad Input Server M +0x050B Audio Output Server O +0x050F Content Control Server P, O +0x0097 Messages Server O +``` +**10.3. Casting Video Player** + +This defines conformance to the Casting Video Player device type. + +A Video Player (either Basic or Casting) represents a device that is able to play media to a physical +output or to a display screen which is part of the device. + +A Casting Video Player has basic controls for playback (play, pause, etc.) and keypad input (up, +down, number input), and is able to launch content. + +For example, a Casting Video Player can be a smart TV device, a TV Set Top Box, or a content +streaming device that provides input to another device like a TV or computer monitor. + +Please see Video Player Architecture for additional Casting Video Player requirements relating to +Video Player device endpoint composition, commissioning, feature representation in clusters, and +UI context. + +**10.3.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 103 +``` + +``` +Revision Description +1 Initial revision +2 Added Messages and Content Control clusters +``` +**10.3.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0023 Casting Video +Player +``` +``` +Simple Endpoint +``` +**10.3.3. Conditions** + +This device type SHALL support the following conformance conditions as defined below. + +``` +Feature Description +ContentAppPlatform The device includes a Content App Platform. A +Content App is usually an application built by a +Content Provider. A Casting Video Player with a +Content App Platform is able to launch Content +Apps and represent these apps as separate end­ +points. +PhysicalInputs The device has physical inputs for media. +``` +Please see the Base Device Type definition for additional conformance tags. + +**10.3.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0006 OnOff Server M +0x0503 WakeOnLAN Server O +0x0504 Channel Server O +0x0505 Target Navigator Server O +0x0506 Media Playback Server M +0x0507 Media Input Server PhysicalInputs +0x0508 Low Power Server O +0x0509 Keypad Input Server M +0x050A Content Launcher Server M +0x050B Audio Output Server O +``` +``` +Page 104 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x050C Application +Launcher +``` +``` +Server ContentAppPlat­ +form +0x050E Account Login Server O +0x050F Content Control Server P, O +0x0097 Messages Server O +``` +**10.3.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +entry means no change. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x050C Application +Launcher +``` +``` +Feature Application­ +Platform +``` +### M + +**10.4. Speaker** + +This defines conformance to the Speaker device type. + +This feature controls the speaker volume of the device. + +To control unmute/mute, the On/Off cluster SHALL be used. A value of TRUE for the OnOff attribute +SHALL represent the volume on (not muted) state, while a value of FALSE SHALL represent the vol­ +ume off (muted) state. For volume level control, the Level cluster SHALL be used. + +A dedicated endpoint is needed because the On/Off cluster can also be used for other purposes, +such as for power control. + +The decision to use Level and On/Off clusters for volume (rather than defining a new audio control +cluster) was made in order to treat volume in a fashion consistent with lighting which also uses +these clusters and has matching functional requirements. + +**10.4.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**10.4.2. Classification** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 105 +``` + +``` +ID Device Name Superset Class Scope +0x0022 Speaker Simple Endpoint +``` +**10.4.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**10.4.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0006 OnOff Server M +0x0008 Level Control Server M +``` +**10.5. Content App** + +This defines conformance to the Content App device type. + +A Content App is usually an application built by a Content Provider. A Casting Video Player with a +Content App Platform is able to launch Content Apps and represent these apps as separate end­ +points. + +**10.5.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Added Content App Observer cluster +``` +**10.5.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0024 Content App Simple Endpoint +``` +**10.5.3. Conditions** + +``` +Condition Description +ObserverClient The node is a client for ContentAppObservers. +``` +Please see the Base Device Type definition for additional conformance tags. + +``` +Page 106 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**10.5.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x001E Binding Server ObserverClient +0x0504 Channel Server O +0x0505 Target Navigator Server O +0x0506 Media Playback Server O +0x0509 Keypad Input Server M +0x050A Content Launcher Server O +0x050C Application +Launcher +``` +``` +Server M +``` +``` +0x050D Application Basic Server M +0x050E Account Login Server O +0x0510 Content App +Observer +``` +``` +Client ObserverClient +``` +**10.5.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +entry means no change. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x050C Application +Launcher +``` +``` +Feature Application­ +Platform +``` +### X + +**10.5.6. Endpoint Composition** + +Endpoints with this device type SHALL support Dynamic Endpoint Allocation as specified in the +System Model specification. + +**10.5.7. Disambiguation** + +When there is more than one sibling endpoint with this device type in a PartsList, disambiguation +information SHALL be provided by having a unique value in the ApplicationName attribute of the +Application Basic cluster on each of these endpoints. + +**10.6. Casting Video Client** + +This defines conformance to the Casting Video Client device type. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 107 +``` + +A Casting Video Client is a client that can launch content on a Casting Video Player, for example, a +Smart Speaker or a Content Provider phone app. + +**10.6.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Added Content App Observer, Messages and +Content Control Clusters +``` +**10.6.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0029 Casting Video +Client +``` +``` +Simple Endpoint +``` +**10.6.3. Conditions** + +Please see the Base Device Type definition for additional conformance tags. + +**10.6.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +See Base Device Type Cluster Requirements for additional clusters including the Binding cluster. + +``` +ID Cluster Client/Server Quality Conformance +0x0006 OnOff Client M +0x0008 Level Control Client O +0x0503 WakeOnLAN Client O +0x0504 Channel Client O +0x0505 Target Navigator Client O +0x0506 Media Playback Client O +0x0507 Media Input Client O +0x0508 Low Power Client O +0x0509 Keypad Input Client M +0x050A Content Launcher Client M +0x050B Audio Output Client O +``` +``` +Page 108 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x050C Application +Launcher +``` +``` +Client O +``` +``` +0x050D Application Basic Client M +0x050E Account Login Client O +0x050F Content Control Client P, O +0x0510 Content App +Observer +``` +``` +Server O +``` +``` +0x0097 Messages Client O +``` +**10.7. Video Remote Control** + +This defines conformance to the Video Remote Control device type. + +A Video Remote Control is a client that can control a Video Player, for example, a traditional univer­ +sal remote control. + +**10.7.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Added Content Control cluster +``` +**10.7.2. Classification** + +``` +ID Device Name Superset Class Scope +0x002A Video Remote Con­ +trol +``` +``` +Simple Endpoint +``` +**10.7.3. Conditions** + +Please see the Base Device Type definition for additional conformance tags. + +**10.7.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0006 OnOff Client M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 109 +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0008 Level Control Client O +0x0503 WakeOnLAN Client O +0x0504 Channel Client O +0x0505 Target Navigator Client O +0x0506 Media Playback Client M +0x0507 Media Input Client O +0x0508 Low Power Client O +0x0509 Keypad Input Client M +0x050A Content Launcher Client O +0x050B Audio Output Client O +0x050C Application +Launcher +``` +``` +Client O +``` +``` +0x050E Account Login Client O +0x050F Content Control Client P, O +``` +Page 110 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 11. Generic Device Types** + +**11.1. Mode Select** + +This defines conformance to the Mode Select device type. + +**11.1.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +``` +**11.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0027 Mode Select Simple Endpoint +``` +**11.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**11.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0050 Mode Select Server M +``` +**11.2. Aggregator** + +This device type aggregates endpoints as a collection. Clusters on the endpoint indicating this +device type provide functionality for the collection of descendant endpoints present in the PartsList +of the endpoint’s descriptor, for example the Actions cluster. + +The purpose of this device type is to aggregate functionality for a collection of endpoints. The defin­ +ition of the collection or functionality is not defined here. + +When using this device type as a collection of bridged nodes, please see the "Bridge" section in the +System Model specification. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 111 +``` + +**11.2.1. Revision History** + +This is the revision history for this device type. The highest revision number in the table below is +the revision for this device type. + +``` +Revision Description +1 Initial revision +2 Added Commissioner Control Cluster and Fabric­ +Synchronization Condition. +``` +**11.2.2. Classification** + +``` +ID Device Name Superset Class Scope +0x000E Aggregator Simple Endpoint +``` +**11.2.3. Conditions** + +This device type MAY support the following conformance conditions as defined below. + +``` +Condition Description +FabricSynchronization See description below. +``` +Please see the Base Device Type definition for additional conformance tags. + +**11.2.3.1. FabricSynchronization Condition** + +The FabricSynchronization condition applies when there is a Commissioner Control Cluster on this +endpoint with a SupportedDeviceCategories attribute with the FabricSynchronization bit set. + +**11.2.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0025 Actions Server O +0x0003 Identify Server O +0x0751 Commissioner +Control +``` +``` +Server FabricSynchro­ +nization +``` +The Identify cluster SHOULD be used in case this device type is used to represent a Bridge which +has a mechanism to identify itself to the user (e.g. blinking LED on the bridge itself ). + +For the Identify-functionality of the individual bridged devices, see the Identify cluster on the end­ +point for a bridged device. + +``` +Page 112 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**11.2.5. Endpoint Composition** + +An Aggregator endpoint’s Descriptor cluster PartsList attribute SHALL list the collection of all end­ +points aggregated by the Aggregator device type, i.e. the full-family pattern defined in the System +Model specification. + +**11.2.6. Disambiguation** + +If the Duplicate condition applies to child endpoints of an Aggregator endpoint that represent mul­ +tiple independent bridged devices, the endpoints SHOULD make available metadata to allow a +client to disambiguate distinct bridged devices with an overlap in application device types. + +Typically this is done using the NodeLabel attribute of the Bridged Device Basic Information cluster + +- thus reusing the naming information which the bridge already has to allow disambiguation to the +user when using a direct user interface to the bridge. + +``` +Example: the Aggregator in this figure (copied from the "Bridge for non-Matter devices" sec­ +tion in the Core Specification) exposes several Color Temperature Lights (endpoints 13 and +22) which are disambiguated with their NodeLabel. Note that the composed device at end­ +points 24, 25 and 26 also uses a TagList (for information rather than disambiguation) since, +for this case, the bridge knows the lighting direction of both elements of the composed device. +``` +``` +Descriptor cluster:DeviceTypeList: Extended Color Light +TagList:Direction.Downward +``` +``` +Descriptor cluster:DeviceTypeList: Extended Color Light,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "dining table" +``` +``` +Descriptor cluster:DeviceTypeList: Color Temperature Light,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "ceiling light" +``` +``` +Descriptor cluster:DeviceTypeList: Color Temperature Light,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "kitchen light" +``` +``` +Descriptor cluster:DeviceTypeList: Temperature Sensor,Bridged Node, +Bridge Device Basic Information cluster:Power Source +Power Source cluster: (features=BAT,REPLC)NodeLabel: "bedroom temperature" +BatChargeLevel: WarningBatReplacementDescription: "AAA batteries" +BatQuantity: 2EndpointList: 23 +Descriptor cluster:DeviceTypeList: Generic Switch,Bridged Node +Bridge Device Basic Information cluster:NodeLabel: "living room entrance" +``` +``` +In this example, the Actions cluster is used to indicate +grouping,i.e.which devices are in which room. The bedroom +has 3 bridged devices, and one of them (endpoint 24,25,26) +is a composed device - it uses theTagListin the Descriptor +cluster to expose information on the user-relevant +components of the composed device (endpoint 25,26). +``` +``` +living room bedroom +``` +``` +Descriptor cluster:DeviceTypeList: Extended Color Light +TagList:Direction.Upward +``` +``` +composed device +Descriptor cluster:DeviceTypeList:Bridged Node +Bridge Device Basic Information cluster:PartsList: 25,26 +NodeLabel: "bedroom light" +``` +``` +EP 12 +``` +``` +EP 13 +``` +``` +EP 14 +``` +``` +EP 24 +``` +``` +EP 25 +``` +``` +EP 26 +``` +``` +EP 22 +``` +``` +EP 23 +``` +``` +Descriptor cluster:DeviceTypeList: Root Node +Basic Information cluster:PartsList: EP 1, 12,13,14,22,23,24,25,26 +.. +``` +``` +EP 0 +Descriptor cluster:DeviceTypeList: Aggregator +Actions cluster:PartsList: EP 12,13,14,22,23,24,25,26 +ActionListEndpointLists: [ ]: [ +[0xE001, "living room", room, [12,13,14] ],[0xE002, "bedroom", room, [22,23,24,25,26] ] +] +``` +``` +EP 1 +``` +``` +Figure 3. use of NodeLabel and TagList for disambiguation +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 113 +``` + +Page 114 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 12. Robotic Device Types** + +**12.1. Robotic Vacuum Cleaner Device Type** + +This defines conformance for the Robotic Vacuum Cleaner device type. + +**12.1.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +2 Add cluster usage constraints and informative +data. Remove the element requirements section, +after moving all constraints to the respective +cluster specifications. +3 Add support for the Service Area cluster +``` +**12.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0074 Robotic Vacuum +Cleaner +``` +``` +Simple Endpoint +``` +**12.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**12.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server M +0x0054 RVC Run Mode Server M +0x0055 RVC Clean Mode Server O +0x0061 RVC Operational +State +``` +``` +Server M +``` +``` +0x0150 Service Area Server O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 115 +``` + +**12.1.5. Cluster Usage** + +This section describes how to control and monitor the operation of a Robotic Vacuum Cleaner +device. This information is meant to clarify how the data dependencies within the device type’s +cluster composition are to be used. + +Note that the device operations may also be the result of, or affected by, out-of-band actions such as +robot physical button presses, internally scheduled events, vendor application requests, commands +sent from other fabrics, internal device timeouts, etc. For example, a user may pause the robot dur­ +ing cleaning by using a Matter client and then resume cleaning by using a physical button of the +device, or a robot may stop cleaning after an internal timeout occurs, and so forth. + +The RVC Operational State cluster’s OperationalState attribute SHALL be updated according to the +state of the device, and therefore it SHOULD be used for monitoring purposes. Note that while the +robot is in a cleaning cycle it may automatically seek the charger, recharge, and then resume clean­ +ing. + +The sections below describe various operational flows with preconditions and actions. The behav­ +ior in case the preconditions are not met is described in the corresponding cluster descriptions. + +**12.1.5.1. Starting Cleaning** + +**12.1.5.1.1. Preconditions** + +Cleaning can only be started when the RVC Run Mode cluster’s CurrentMode attribute is set to a +mode that has the Idle mode tag associated with it, and the RVC Operational State cluster’s Opera­ +tionalState attribute is set to the Stopped, Paused, Docked or Charging state. + +Note that if the RVC Clean Mode cluster is implemented, it determines the type of cleaning. + +**12.1.5.1.2. Actions** + +To attempt starting a cleaning operation, the RVC Run Mode cluster can be sent a ChangeToMode +command with the NewMode field set to a mode that has the Cleaning mode tag associated with it. + +**12.1.5.2. Pausing Cleaning** + +**12.1.5.2.1. Preconditions** + +Cleaning can only be paused when the RVC Operational State cluster’s OperationalState attribute is +set to a Pause-compatible state. See the Pause Compatibility table and the RVC Pause Compatibility +Table. + +Note that even if the Pause command is not implemented, the RVC Operational State cluster’s Oper­ +ationalState attribute MAY report that the device is in the Paused state due to an out-of-band action, +such as the user pressing a physical button on the device. + +**12.1.5.2.2. Actions** + +To attempt pausing a cleaning operation, the RVC Operational State cluster can be sent a Pause com­ +mand. + +``` +Page 116 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**12.1.5.3. Resuming Cleaning** + +**12.1.5.3.1. Preconditions** + +Cleaning can only be resumed if the RVC Operational State cluster’s OperationalState attribute is set +to a Resume-compatible state (see Resume Compatibility table and the RVC Resume Compatibility +table), and the RVC Run Mode cluster’s CurrentMode is set to a mode with the Cleaning mode tag. + +Note that even if the Resume command is not implemented, the RVC Operational State cluster’s +OperationalState attribute MAY indicate that the device transitioned from the Paused state to the +Running state due to an out-of-band action, such as the user pressing a physical button on the +device. + +**12.1.5.3.2. Actions** + +To attempt resuming a cleaning operation, the RVC Operational State cluster can be sent a Resume +command. + +**12.1.5.4. Stopping Cleaning** + +**12.1.5.4.1. Preconditions** + +Stopping cleaning can only happen if the RVC Run Mode cluster’s CurrentMode attribute is set to a +mode that has the Cleaning mode tag associated with it. + +**12.1.5.4.2. Actions** + +To attempt stopping a cleaning operation, the RVC Run Mode cluster can be sent a ChangeToMode +command with the NewMode field set to a mode that has the Idle mode tag associated with it. + +**12.1.5.4.3. Side Effects** + +Note that the device MAY seek the charger after successfully switching the RVC Run Mode cluster to +an Idle mode. The OperationalState attribute indicates whether the device is seeking the charger, +stopped, charging, docked etc. + +**12.1.5.5. Other Device Operations** + +The RVC Run Mode cluster’s SupportedModes attribute list MAY include modes that have neither +the Idle nor the Cleaning mode tags, for example the Mapping mode tag. + +Starting, pausing, resuming and stopping these other operations have similar preconditions, actions +and side effects as those described above for the cleaning operations. + +**12.1.5.6. Device Error Handling** + +When in an error condition, as indicated by the RVC Operational State cluster’s OperationalState +attribute, out-of-band action will be required to clear that condition. + +If an error occurs while the device operates, such as while cleaning or while mapping, the device +MAY pause and set the RVC Operational State cluster’s OperationalState attribute to Error. If the +operation can be resumed after the error is cleared, the device SHALL set the RVC Operational State + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 117 +``` + +cluster’s OperationalState attribute to Paused and MAY be resumed either via a Resume command, +if implemented, or by out-of-band actions, such as by pressing the robot’s physical buttons. + +Note that certain errors may not pause or disable the device. For example, a dual-function device, +that can both vacuum and mop, may report a WaterTankEmpty error but may still be able to be +used if it has a vacuum only cleaning mode. Certain modes of the RVC Run Mode and the RVC Clean­ +ing Mode clusters MAY become unavailable and the ChangeToModeResponse commands' Status­ +Code SHALL be set to InvalidInMode, when attempting to switch to those modes. + +``` +Page 118 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 13. Appliances Device Types** + +**13.1. Laundry Washer** + +A Laundry Washer represents a device that is capable of laundering consumer items. Any laundry +washer product may utilize this device type. + +A Laundry Washer SHALL be composed of at least one endpoint with the Laundry Washer device +type. + +**13.1.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**13.1.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0073 Laundry Washer Simple Endpoint +``` +**13.1.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**13.1.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server O +0x0051 Laundry Washer +Mode +``` +``` +Server O +``` +``` +0x0006 On/Off Server O +0x0053 Laundry Washer +Controls +``` +``` +Server O +``` +``` +0x0056 Temperature Con­ +trol +``` +``` +Server O +``` +``` +0x0060 Operational State Server M +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 119 +``` + +**13.1.5. Cluster Restrictions** + +**13.1.5.1. On/Off Cluster (Server) Clarifications** + +As indicated in the Element Requirements section below, the DF (Dead Front) feature is required for +the On/Off cluster in this device type. See the "DeadFrontBehavior feature" section in the On/Off +cluster description for detailed requirements. The "dead front" state is linked to the OnOff attribute +in the On/Off cluster having the value False. Thus, the Off command of the On/Off cluster SHALL +move the device into the "dead front" state, the On command of the On/Off cluster SHALL bring the +device out of the "dead front" state, and the device SHALL adhere with the associated requirements +on subscription handling and event reporting. + +**13.1.5.2. Best Effort Attribute Values in "Dead Front" State** + +When in "dead front", should the operational values of the cluster attributes not be available or +accessible, the following are the RECOMMENDED best effort values for per cluster attributes when +responding to a new subscription request or a read request. Attributes not listed have no change in +their defined or expected values. + +``` +Cluster Name Attribute Default +Laundry Washer Mode CurrentMode MS +Laundry Washer Controls SpinSpeedCurrent null +NumberOfRinses null +SpinSpeeds null +MaxRinses null +Temperature Control All attributes MS +Identify All attributes MS +Operational State PhaseList null +CurrentPhase null +CountdownTime null +OperationalState Stopped +OperationalError No Error +``` +**13.1.6. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0006 On/Off Feature DeadFront­ +Behavior +``` +### M + +``` +Page 120 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0051 Laundry +Washer +Mode +``` +``` +Attribute StartUpMode X +``` +``` +0x0051 Laundry +Washer +Mode +``` +``` +Feature OnOff X +``` +**13.2. Refrigerator** + +A refrigerator represents a device that contains one or more cabinets that are capable of chilling or +freezing food. Examples of consumer products that MAY make use of this device type include refrig­ +erators, freezers, and wine coolers. + +**13.2.1. Refrigerator Architecture** + +A Refrigerator is always defined via endpoint composition. See the Section 13.2.5, “Device Type +Requirements” section for more details. + +A Refrigerator MAY include a semantic tag in the TagList attribute of the Descriptor cluster to +describe the primary function of the device, e.g., "Refrigerator" or "Freezer". + +An example of a Refrigerator with multiple cabinets is illustrated below. + +_Figure 4. Example of a Refrigerator_ + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 121 +``` + +**13.2.2. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +2 Added Cooler requirement +``` +**13.2.3. Classification** + +``` +ID Device Name Superset Class Scope +0x0070 Refrigerator Simple Endpoint +``` +**13.2.4. Conditions** + +A Refrigerator SHALL have the Cooler condition applied to at least one endpoint containing the +Temperature Control Cluster. + +Please see the Base Device Type definition for conformance tags. + +**13.2.5. Device Type Requirements** + +A Refrigerator SHALL be composed of at least one endpoint with the Temperature Controlled Cabi­ +net device type as defined by the conformance below. There MAY be more endpoints with other +device types existing in the Refrigerator. + +If the Refrigerator contains more than one instance of a Temperature Controlled Cabinet, those +instances SHALL include a semantic tag in the TagList attribute of the Descriptor cluster to disam­ +biguate the cabinet, e.g., "freezer" or "refrigerator". Such a semantic tag SHALL be from either the +defined Common or Refrigerator namespaces. + +``` +ID Name Constraint Conformance +0x0071 Temperature Con­ +trolled Cabinet +``` +``` +min 1 M +``` +**13.2.6. Cluster Requirements** + +Each endpoint supporting the refrigerator device type MAY include these clusters based on the con­ +formance defined below. + +``` +ID Cluster Client/Server Quality Conformance +0x0003 Identify Server O +0x0052 Refrigerator And +Temperature Con­ +trolled Cabinet +Mode +``` +``` +Server O +``` +``` +Page 122 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Cluster Client/Server Quality Conformance +0x0057 Refrigerator +Alarm +``` +``` +Server O +``` +**13.2.7. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0052 Refrigerator +And Temper­ +ature Con­ +trolled Cabi­ +net Mode +``` +``` +Attribute StartUpMode X +``` +``` +0x0052 Refrigerator +And Temper­ +ature Con­ +trolled Cabi­ +net Mode +``` +``` +Feature OnOff X +``` +**13.3. Room Air Conditioner** + +This defines conformance to the Room Air Conditioner device type. + +A Room Air Conditioner is a device with the primary function of controlling the air temperature in +a single room. + +**13.3.1. Room Air Conditioner Architecture** + +A Room Air Conditioner is a device which at a minimum is capable of being turned on and off and +of controlling the temperature in the living space. + +A Room Air Conditioner MAY also support additional capabilities via endpoint composition. See the +Section 13.3.5, “Device Type Requirements” section for typical device types. + +The following diagram shows an example Room Air Conditioner consisting of a parent endpoint +that is the Room Air Conditioner device type and several child endpoints providing additional capa­ +bilities. Note that two of the child endpoints are of the same device type, Temperature Sensor, +which are being disambiguated via the requirements of endpoint composition defined in the sys­ +tem model. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 123 +``` + +_Figure 5. Example of a Room Air Conditioner_ + +**13.3.2. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +2 Thermostat User Interface Configuration cluster +added; Updated the Scenes cluster to Scenes +Management with Cluster ID: 0x0062 +``` +**13.3.3. Classification** + +``` +ID Device Name Superset Class Scope +0x0072 Room Air Condi­ +tioner +``` +``` +Simple Endpoint +``` +**13.3.4. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**13.3.5. Device Type Requirements** + +A Room Air Conditioner MAY have zero or more of each device type listed in this table subject to +the conformance column of the table. All devices used in compositions SHALL adhere to the disam­ +biguation requirements of the System Model. Additional device types not listed in this table MAY +also be included in device compositions. + +``` +Page 124 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Constraint Conformance +0x0302 Temperature Sensor O +0x0307 Humidity Sensor O +``` +**13.3.6. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Conformance +0x0003 Identify Server M +0x0004 Groups Server O +0x0062 Scenes Management Server P, O +0x0006 On/Off Server M +0x0201 Thermostat Server M +0x0202 Fan Control Server O +0x0204 Thermostat User Inter­ +face Configuration +``` +``` +Server O +``` +``` +0x0402 Temperature Measure­ +ment +``` +``` +Server O +``` +``` +0x0405 Relative Humidity Mea­ +surement +``` +``` +Server O +``` +**13.3.7. Cluster Restrictions** + +**13.3.7.1. On/Off Cluster (Server) Clarifications** + +As indicated in the Element Requirements section below, the DF (Dead Front) feature is required for +the On/Off cluster in this device type. See the "DeadFrontBehavior feature" section in the On/Off +cluster description for detailed requirements. The "dead front" state is linked to the OnOff attribute +in the On/Off cluster having the value False. Thus, the Off command of the On/Off cluster SHALL +move the device into the "dead front" state, the On command of the On/Off cluster SHALL bring the +device out of the "dead front" state, and the device SHALL adhere with the associated requirements +on subscription handling and event reporting. + +**13.3.7.2. Best Effort Attribute Values in "Dead Front" State** + +When in "dead front", should the operational values of the cluster attributes not be available or +accessible, the following are the RECOMMENDED best effort values for per cluster attributes when +responding to a new subscription request or a read request. Attributes not listed have no change in +their defined or expected values. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 125 +``` + +``` +Cluster Name Attribute Default +Thermostat LocalTemperature null +Temperature Measurement MeasuredValue null +Relative Humidity Measure­ +ment +``` +``` +MeasuredValue null +``` +``` +Fan Control SpeedSetting null +PercentSetting null +``` +**13.3.8. Element Requirements** + +This lists qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0006 On/Off Feature DeadFront­ +Behavior +``` +### M + +``` +0x0204 Thermostat +User Inter­ +face Configu­ +ration +``` +``` +Attribute KeypadLock­ +out +``` +### O + +**13.4. Temperature Controlled Cabinet** + +A Temperature Controlled Cabinet only exists composed as part of another device type. It repre­ +sents a single cabinet that is capable of having its temperature controlled. Such a cabinet may be +chilling or freezing food, for example as part of a refrigerator, freezer, wine chiller, or other similar +device. Equally, such a cabinet may be warming or heating food, for example as part of an oven, +range, or similar device. + +**13.4.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +2 Extension to heating cabinets +3 Added exclusivity for conditions +``` +**13.4.2. Classification** + +``` +Page 126 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Device Name Superset Class Scope +0x0071 Temperature Con­ +trolled Cabinet +``` +``` +Simple Endpoint +``` +**13.4.3. Conditions** + +This device type SHALL support the following conformance conditions as defined below. + +``` +Condition Description +Cooler The device has cooling functionality. +Heater The device has heating functionality. +``` +Endpoints SHALL support at most one condition. + +Please see the Base Device Type definition for conformance tags. + +**13.4.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0056 Temperature Con­ +trol +``` +``` +Server M +``` +``` +0x0402 Temperature Mea­ +surement +``` +``` +Server O +``` +``` +0x0052 Refrigerator and +Temperature Con­ +trolled Cabinet +Mode +``` +``` +Server [Cooler] +``` +``` +0x0049 Oven Mode Server [Heater] +0x0048 Oven Cavity Oper­ +ational State +``` +``` +Server [Heater] +``` +**13.4.5. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 127 +``` + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0052 Refrigerator +and Temper­ +ature Con­ +trolled Cabi­ +net Mode +``` +``` +Attribute StartUpMode X +``` +``` +0x0052 Refrigerator +and Temper­ +ature Con­ +trolled Cabi­ +net Mode +``` +``` +Feature OnOff X +``` +``` +0x0049 Oven Mode Attribute StartUpMode X +0x0049 Oven Mode Feature OnOff X +0x0048 Oven Cavity +Operational +State +``` +``` +Command Pause X +``` +``` +0x0048 Oven Cavity +Operational +State +``` +``` +Command Resume X +``` +**13.5. Dishwasher** + +A dishwasher is a device that is generally installed in residential homes and is capable of washing +dishes, cutlery, and other items associate with food preparation and consumption. The device can +be permanently installed or portable and can have variety of filling and draining methods. + +**13.5.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**13.5.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0075 Dishwasher Simple Endpoint +``` +**13.5.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +``` +Page 128 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**13.5.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Cluster Client/Server Conformance +0x0003 Identify Server O +0x0006 On/Off Server O +0x0056 Temperature Control Server O +0x0059 Dishwasher Mode Server O +0x005D Dishwasher Alarm Server O +0x0060 Operational State Server M +``` +Notes + +- A dishwasher cycle is a combination of a mode (if supported) and a temperature (if supported). + The operational state cluster is then used to start the cycle once these selections have been + made via the client. + +**13.5.5. Cluster Restrictions** + +**13.5.5.1. On/Off Cluster (Server) Clarifications** + +As indicated in the Element Requirements section below, the DF (Dead Front) feature is required for +the On/Off cluster in this device type. See the "DeadFrontBehavior feature" section in the On/Off +cluster description for detailed requirements. The "dead front" state is linked to the OnOff attribute +in the On/Off cluster having the value False. Thus, the Off command of the On/Off cluster SHALL +move the device into the "dead front" state, the On command of the On/Off cluster SHALL bring the +device out of the "dead front" state, and the device SHALL adhere with the associated requirements +on subscription handling and event reporting. + +**13.5.5.2. Best Effort Attribute Values in "Dead Front" State** + +When in "dead front", should the operational values of the cluster attributes not be available or +accessible, the following are the RECOMMENDED best effort values for per cluster attributes when +responding to a new subscription request or a read request. Attributes not listed have no change in +their defined or expected values. + +``` +Cluster Name Attribute Default +Dishwasher Mode CurrentMode MS +Temperature Control All attributes MS +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 129 +``` + +``` +Cluster Name Attribute Default +Dishwasher Operational State PhaseList null +CurrentPhase null +CountdownTime null +OperationalState Stopped +OperationalError No Error +``` +**13.5.6. Element Requirements** + +This lists qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0006 On/Off Feature DeadFront­ +Behavior +``` +### M + +``` +0x0059 Dishwasher +Mode +``` +``` +Attribute StartUpMode X +``` +``` +0x0059 Dishwasher +Mode +``` +``` +Feature OnOff X +``` +**13.6. Laundry Dryer** + +A Laundry Dryer represents a device that is capable of drying laundry items. + +**13.6.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**13.6.2. Classification** + +``` +ID Device Name Superset Class Scope +0x007C Laundry Dryer Simple Endpoint +``` +**13.6.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +``` +Page 130 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**13.6.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server O +0x0051 Laundry Washer +Mode +``` +``` +Server O +``` +``` +0x0006 On/Off Server O +0x004A Laundry Dryer +Controls +``` +``` +Server O +``` +``` +0x0056 Temperature Con­ +trol +``` +``` +Server O +``` +``` +0x0060 Operational State Server M +``` +**13.6.5. Cluster Restrictions** + +**13.6.5.1. On/Off Cluster (Server) Clarifications** + +The actions carried out by a Laundry Dryer device on receipt of specific commands are shown +below. As indicated in the Element Requirements section below, the DF (Dead Front) feature is +required for the On/Off cluster in this device type. See the "DeadFrontBehavior feature" section in +the On/Off cluster description for detailed requirements. The "dead front" state is linked to the +OnOff attribute in the On/Off cluster having the value False. Thus, the Off command of the On/Off +cluster SHALL move the device into the "dead front" state, the On command of the On/Off cluster +SHALL bring the device out of the "dead front" state, and the device SHALL adhere with the associ­ +ated requirements on subscription handling and event reporting. + +**13.6.5.2. Best Effort Attribute Values in "Dead Front" State** + +When in "dead front", should the operational values of the cluster attributes not be available or +accessible, the following are the RECOMMENDED best effort values for per cluster attributes when +responding to a new subscription request or a read request. Note that some of these attributes may +be missing for the clusters not implemented on the endpoint due to optionality. + +``` +Cluster Name Attribute Value +Laundry Dryer Mode CurrentMode Manufacturer Specific +Laundry Dryer Controls TemperatureLevel Null +DrynessLevel Null +Temperature Control All attributes Manufacturer Specific +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 131 +``` + +``` +Cluster Name Attribute Value +Operational State PhaseList Null +CurrentPhase Null +CountdownTime Null +OperationalStateList Fully populated +OperationalState Stopped +OperationalError No Error +``` +**13.6.6. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0006 On/Off Feature DeadFront­ +Behavior +``` +### M + +``` +0x0051 Laundry +Washer +Mode +``` +``` +Attribute StartUpMode X +``` +``` +0x0051 Laundry +Washer +Mode +``` +``` +Feature OnOff X +``` +**13.7. Cook Surface** + +A Cook Surface device type represents a heating object on a cooktop or other similar device. It +SHALL only be used when composed as part of another device type. + +**13.7.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**13.7.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0077 Cook Surface Simple Endpoint +``` +``` +Page 132 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**13.7.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**13.7.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0056 Temperature Con­ +trol +``` +``` +Server O.a+ +``` +``` +0x0402 Temperature Mea­ +surement +``` +``` +Server O.a+ +``` +``` +0x0006 On/Off Server O +``` +**13.7.5. Cluster Restrictions** + +**13.7.5.1. On/Off Cluster (Server) Clarifications** + +The OffOnly feature is required for the On/Off cluster in this device type due to safety require­ +ments. + +**13.7.6. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0006 On/Off Feature OffOnly M +``` +**13.8. Cooktop** + +A cooktop is a cooking surface that heats food either by transferring currents from an electromag­ +netic field located below the glass surface directly to the magnetic induction cookware placed +above or through traditional gas or electric burners. + +**13.8.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 133 +``` + +**13.8.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0078 Cooktop Simple Endpoint +``` +**13.8.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**13.8.4. Device Type Requirements** + +A Cooktop SHALL be composed of zero or more endpoints with the Cook Surface device type as +defined by the conformance below. + +A cooktop falls under strict regulatory control in some regions. One of these restrictions for non- +induction cooktops is that the only remote commands available are to turn off the entire device or +read out the temperature setting. This one scenario for allowed remote operation is specifically to +address the use case of a device that is left on after a user leaves the home. The individual cooking +surfaces cannot be shut off. This leads to a model of a cooktop that has 0 controllable cooking sur­ +faces. For example, the requirements that exist for a gas cooktop would result in zero Cook Surface +instances being exposed. + +If the Cooktop contains more than one instance of a Cook Surface, those instances SHALL include a +semantic tag in the TagList attribute of the Descriptor cluster to disambiguate the cook surface, e.g., +"front", "left", or "back". Such a semantic tag SHALL be from the Common namespaces. + +``` +ID Name Constraint Conformance +0x0077 Cook Surface min 1 O +``` +**13.8.5. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server O +0x0006 On/Off Server M +``` +**13.8.6. Cluster Restrictions** + +**13.8.6.1. On/Off Cluster (Server) Clarifications** + +The OffOnly feature is required for the On/Off cluster in this device type due to safety require­ +ments. + +``` +Page 134 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**13.8.7. Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0006 On/Off Feature OffOnly M +``` +**13.9. Oven** + +An oven represents a device that contains one or more cabinets, and optionally a single cooktop, +that are all capable of heating food. Examples of consumer products implementing this device type +include ovens, wall ovens, convection ovens, etc. + +**13.9.1. Oven Architecture** + +An oven is always defined via endpoint composition. See Section 13.9.5, “Device Type Require­ +ments” for more details. + +An example of an oven with two cabinets (one above the other) and a cooktop (with two cook sur­ +faces) is illustrated below. + +``` +EP 0 - Root Node +``` +DPearvtiscLeisTyt:p [e 1 L,i 2 st,: 3 [,R 4 o,o 5 t (^) ,N 6 o]de] +EP 1 – Oven +DPearvtiscLeiTsyt:p [e 2 L,i 3 st,: 4 []Oven] +EDPe (^2) v (^) i-ceCTaybpineeLtist: +[PTaermtspLeisrta: t[u]reControlledCabinet] Descriptor^ Cluster Temperature^ Control +Semantic Tag: [Position.Top] +EDPe (^3) v (^) i-ceCTaybpineeLtist: +[PTaermtspLeisrta: t[u]reControlledCabinet] Descriptor^ CluSsetmerantic Tag: Temperature^ Control +[Position.Bottom] +EDPe (^4) v (^) i-cCeToyopketoLipst: [Cooktop] +PartsList: [ 5 , 6 ] +Descriptor Cluster On/Off +Oven Mode +Oven Mode +EDPe (^5) v (^) i–ceCToyopke (^) LSiusrtf: a[cCeookSurface] +PartsList: [] +EDPe (^6) v (^) i–ceCToyopke (^) LSiusrtf: a[cCeookSurface] +PartsList: [] +Descriptor Cluster +Semantic Tag: [Position.Left] +Descriptor Cluster +Semantic Tag: [Position.Right] +Temperature Measurement +Temperature Measurement +_Figure 6. Example of an Oven_ +**13.9.2. Revision History** +This is the revision history for this document. +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 135 + + +``` +Revision Description +1 Initial revision +2 Added Heater requirement +``` +**13.9.3. Classification** + +``` +ID Device Name Superset Class Scope +0x007B Oven Simple Endpoint +``` +**13.9.4. Conditions** + +An Oven SHALL have the Heater condition applied to at least one endpoint containing the Tempera­ +ture Control Cluster. + +Please see the Base Device Type definition for conformance tags. + +**13.9.5. Device Type Requirements** + +An Oven SHALL be composed of at least one endpoint with Temperature Controlled Cabinet device +type. There MAY be more endpoints with other device types existing in the Oven. Note that any +instance of the TemperatureControl cluster on an endpoint is scoped to the device type on that end­ +point, and not the whole node. + +If the Oven contains more than one instance of a Temperature Controlled Cabinet, those instances +SHALL include a semantic tag in the TagList attribute of the Descriptor cluster to disambiguate the +cabinet, e.g., "Top" or "Bottom". Such a semantic tag SHALL be from the defined Common Position +namespaces. + +Regional restrictions and safety regulations may dictate which aspects of a Temperature Controlled +Cabinet may be remotely accessible. In such cases, clusters exposed by an instance of a Tempera­ +ture Controlled Cabinet MAY have limitations on what commands are supported or what attributes +are mutable. + +``` +ID Name Constraint Conformance +0x0071 Temperature Con­ +trolled Cabinet +``` +``` +min 1 M +``` +``` +0x0078 Cooktop max 1 O +``` +**13.9.6. Cluster Requirements** + +Each endpoint supporting this device type MAY include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0003 Identify Server O +``` +``` +Page 136 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**13.10. Extractor Hood** + +An Extractor Hood is a device that is generally installed above a cooking surface in residential +kitchens. An Extractor Hood’s primary purpose is to reduce odors that arise during the cooking +process by either extracting the air above the cooking surface or by recirculating and filtering it. It +may also contain a light for illuminating the cooking surface. + +Extractor Hoods may also be known by the following names: + +- Hoods +- Extractor Fans +- Extractors +- Range Hoods +- Telescoping Hoods +- Telescoping Extractors + +**13.10.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**13.10.2. Classification** + +``` +ID Device Name Superset Class Scope +0x007A Extractor Hood Simple Endpoint +``` +**13.10.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**13.10.4. Device Type Requirements** + +An Extractor Hood is composed of other device types listed in this table subject to the conformance +column of the table. All devices used in compositions SHALL adhere to the disambiguation and +superset requirements of the System Model. Specifically, please note that the On/Off Light as listed +is a Superset Device Type as defined by the System Model (see _Superset Device Types_ in [Matter­ +Core]), and so the rules defined in that section apply to the use of On/Off Light as a superset when +composed in this device type. Additional device types not listed in this table MAY also be included +in device compositions. + +``` +ID Name Constraint Conformance +0x0100+ On/Off Light+ O +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 137 +``` + +**13.10.5. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Conformance +0x0003 Identify Server O +0x0071 HEPA Filter Monitoring Server O +0x0072 Activated Carbon Filter +Monitoring +``` +``` +Server O +``` +``` +0x0202 Fan Control Server M +``` +**13.10.6. Element Requirements** + +This lists qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0202 Fan Control Feature Rocking X +0x0202 Fan Control Feature Wind X +0x0202 Fan Control Feature AirflowDi­ +rection +``` +### X + +**13.11. Microwave Oven** + +This defines conformance to the Microwave Oven device type. + +A Microwave Oven is a device with the primary function of heating foods and beverages using a +magnetron. + +**13.11.1. Microwave Oven Architecture** + +A Microwave Oven is a device which at a minimum is capable of being started and stopped and of +setting a power level. + +A Microwave Oven MAY also support additional capabilities via endpoint composition. See the +Device Type Requirements section for typical device types. + +The following diagram shows an example Microwave Oven consisting of a parent endpoint that is +the Microwave Oven device type and a child endpoint providing additional capabilities. + +A microwave oven placed above a thermal oven or cooktop/hob may also include a light for illumi­ +nating the cooking surface of the thermal oven or cooktop/hob and an exhaust fan for removing +cooking odors. + +``` +Page 138 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 7. Example of a Microwave Oven_ + +**13.11.2. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**13.11.3. Classification** + +``` +ID Device Name Superset Class Scope +0x0079 Microwave Oven Simple Endpoint +``` +**13.11.4. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**13.11.5. Device Type Requirements** + +Each endpoint supporting this device type SHALL include endpoints with these device types based +on the conformance defined below. + +``` +ID Name Constraint Conformance +0x0100+ On/Off Light+ O +``` +When a light is included as part of a composed device, it is intended to be used as surface light +when the microwave oven is installed above a range in an "over the range" configuration rather +than the internal light of the microwave oven cavity. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 139 +``` + +**13.11.6. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Conformance +0x0003 Identify Server O +0x0060 Operational State Server M +0x0202 Fan Control Server O +0x005E Microwave Oven Mode Server M +0x005F Microwave Oven Con­ +trol +``` +``` +Server M +``` +When the Fan Control cluster is supported on an endpoint of this device type, it is intended to be +used as a ventilation fan when the microwave oven is installed above a range in an "over the +range" configuration rather than the internal fan of the microwave oven cavity. + +**13.11.7. Element Requirements** + +This lists qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0060 Operational +State +``` +``` +Attribute Countdown­ +Time +``` +### M + +``` +0x0202 Fan Control Feature Wind X +0x0202 Fan Control Feature AirflowDi­ +rection +``` +### X + +**13.11.8. Cluster Usage** + +This section describes how to control and monitor the operation of a Microwave Oven device. This +information is meant to clarify how the data dependencies within the device type’s cluster composi­ +tion are to be used. + +Note that the device operations may also be the result of, or affected by, out-of-band actions such as +physical button presses on the device, internally scheduled events, vendor application requests, +commands invoked via other fabrics, internal device timeouts, etc. For example, a user may pause +the oven during operation by opening the door to check on the food. + +**13.11.8.1. Starting the Oven** + +The oven operational attributes are set by sending the SetCookingParameters command of the +Microwave Oven Control cluster with the values as intended by the user via a client. Oven opera­ +tion can be started by sending the Start command via the Operational State cluster or one of its + +``` +Page 140 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +derivatives, if supported, or within the SetCookingParameters command via the StartAfterSetting +attribute, if supported. + +Upon setting the CookTime attribute via the SetCookingParameters command, the CountdownTime +attribute of the Operational State cluster or one of its derivatives , if supported, is set to the same +value as the CookTime attribute. + +Once oven operation is started, the values previously sent by the SetCookingParameters command +are used to control the oven operation and the CountdownTime attribute of the Operational State +cluster or one of its derivatives begins counting down. + +**13.11.8.2. During Operation** + +While the oven is in the Running state, the CountdownTime attribute of the Operational State clus­ +ter or one of its derivatives counts down and the CookTime attribute of the Microwave Oven Con­ +trol cluster remains fixed. + +**13.11.8.3. Stopping the Oven** + +Oven operation will end when either the Stop command of the Operational State cluster or one of +its derivatives, if supported, is sent, the CountdownTime value reaches zero, or the oven is stopped +via an out-of-band method. + +It is recommended that when the oven enters the Stopped state of the Operational State cluster or +one of its derived clusters, the attribute values of the Microwave Oven Control cluster be set to their +default values by the server. + +**13.11.8.4. Adding More Time** + +When time is added to the CookTime attribute using the AddMoreTime command of the Microwave +Oven Control cluster, the same amount of time is also added to the CountdownTime attribute of the +Operational State cluster or one of its derivatives. See the CookTime attribute constraints and +AddMoreTime command for more details. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 141 +``` + +Page 142 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 14. Energy Device Types** + +**14.1. EVSE Device Type** + +An EVSE (Electric Vehicle Supply Equipment) is a device that allows an EV (Electric Vehicle) to be +connected to the mains electricity supply to allow it to be charged (or discharged in case of Vehicle +to Grid / Vehicle to Home applications). + +**14.1.1. EVSE Architecture** + +An EVSE is always defined via endpoint composition. See the Section 14.1.5, “Device Type Require­ +ments” section for more details. + +An example of an EVSE with single phase AC supply is illustrated below. + +_Figure 8. Example of a single phase EVSE_ + +The EVSE may also indicate its internal temperature using the temperature measurement cluster +(not shown). + +An example of an EVSE with a 3 phase AC supply is illustrated below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 143 +``` + +_Figure 9. Example of a 3 phase EVSE_ + +**14.1.2. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +2 Addition of associated Device Energy Manage­ +ment device +``` +**14.1.3. Classification** + +``` +ID Device Name Superset Class Scope +0x050C Energy EVSE Simple Endpoint +``` +**14.1.4. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**14.1.5. Device Type Requirements** + +An EVSE SHALL be composed of at least one endpoint with device types as defined by the confor­ +mance below. There MAY be more endpoints with other device types existing in the EVSE. + +``` +ID Name Constraint Conformance +0x0011 Power Source min 1 M +0x0510 Electrical Sensor min 1 M +``` +``` +Page 144 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Constraint Conformance +0x050D Device Energy Manage­ +ment +``` +``` +min 1 M +``` +**14.1.5.1. Cluster Requirements on Composing Device Types** + +The Electrical Sensor device SHALL include both the Electrical Energy Measurement and Electrical +Power Measurement clusters, measuring the total energy and power of the EVSE. + +If an EVSE supports three phase power then it SHALL include three additional endpoints including +an Electrical Sensor Device Type as child elements. For each child endpoint it SHALL include a +semantic tag from the Electrical Measurement Namespace in the TagList attribute of the Descriptor +cluster to describe the endpoint for the relevant Electrical Power Measurement and Electrical +Energy Measurement clusters indicating the relevant AC phase that is being measured. + +The Device Energy Management cluster included in the Device Energy Management device SHALL +support the Power Forecast Reporting (PFR) feature. If the EVSE supports the V2X feature then the +Device Energy Management cluster included in the Device Energy Management device SHALL sup­ +port the Power Adjustment (PA) feature. + +**14.1.6. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Conformance +0x0003 Identify Server O +0x0099 Energy EVSE Server M +0x009D Energy EVSE Mode Server M +0x0402 Temperature Measure­ +ment +``` +``` +Server O +``` +**14.2. Water Heater Device Type** + +A water heater is a device that is generally installed in properties to heat water for showers, baths +etc. + +**14.2.1. Water Heater Architecture** + +A Water Heater is always defined via endpoint composition. + +If a Water Heater supports multiple temperature measurement sensors as child elements, it SHALL +include a separate endpoint for each sensor. Each endpoint SHALL include a semantic tag in the +TagList attribute of the Descriptor cluster to describe the relevant position of the sensor. Such a +semantic tag SHALL be from the defined Common Position namespace (i.e. Top, Middle, Bottom +etc). + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 145 +``` + +For basic control features the Water Heater re-uses the Thermostat cluster with the **HEAT** and **SCH** +features. This allows it to have daily schedules set as to when the hot water heating is enabled, as +well as setting the desired setpoint of the hot water. + +Additional features of the Water Heater (such as reporting estimated hot water content, and smart +reheating functions) are provided by the Water Heater application cluster. + +In order to add energy management capability, the Device Energy Management cluster may be +optionally supported, and if so, the Electrical Power Measurement and Electrical Energy Measure­ +ment clusters are supported via the Electrical Sensor device type. + +An example of a Water Heater device is illustrated below. + +_Figure 10. Example of a Water Heater_ + +**14.2.2. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**14.2.3. Classification** + +``` +ID Device Name Superset Class Scope +0x050F Water Heater Simple Endpoint +``` +**14.2.4. Conditions** + +Please see the Base Device Type definition for conformance tags. + +``` +Page 146 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**14.2.5. Device Type Requirements** + +A Water Heater SHALL be composed of at least one endpoint with device types as defined by the +conformance below. There MAY be more endpoints with other device types existing in the Water +Heater. + +``` +ID Name Constraint Conformance +0x0011 Power Source O +0x0302 Temperature Sensor O +0x0510 Electrical Sensor desc +0x050D Device Energy Manage­ +ment +``` +### O + +**14.2.5.1. Electrical Sensor Device Type** + +If a Device Energy Management device type is included as part of a composition, the Electrical Sen­ +sor device type SHALL also be included. + +**14.2.5.2. Cluster Requirements on Composing Device Types** + +If an Electrical Sensor device is included as part of a composition, it SHALL include both the Electri­ +cal Energy Measurement and Electrical Power Measurement clusters, measuring the total energy +and power of the Water Heater. + +If a Device Energy Management device type is included on a separate endpoint as part of a compo­ +sition and the Device Energy Management cluster is supported on the same endpoint, the Power +Forecast Reporting feature of the Device Energy Management cluster SHALL also be supported. + +**14.2.6. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Conformance +0x0003 Identify Server O +0x0201 Thermostat Server M +0x0094 Water Heater Manage­ +ment +``` +``` +Server M +``` +``` +0x009E Water Heater Mode Server M +``` +**14.2.7. Element Requirements** + +This lists qualities and conformance that override the cluster specification requirements. A blank +table cell means there is no change to that item and the value from the cluster specification applies. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 147 +``` + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x0201 Thermostat Feature Heating M +``` +The Energy Management feature of the Water Heater cluster SHALL be supported if the Device +Energy Management device type is included. + +If Off is a supported SystemMode in the Thermostat cluster, setting the SystemMode of the Thermo­ +stat cluster to Off SHALL set the CurrentMode attribute of the Water Heater Mode cluster to a mode +having the Off mode tag value and vice versa. + +At least one entry in the SupportedModes attribute of the Water Heater Mode cluster SHALL +include the Timed mode tag in the ModeTags field list. + +**14.3. Solar Power Device Type** + +A Solar Power device is a device that allows a solar panel array, which can optionally be comprised +of a set parallel strings of solar panels, and its associated controller and, if appropriate, inverter, to +be monitored and controlled by an Energy Management System. + +**14.3.1. Solar Power Architecture** + +A Solar Power device is always defined via endpoint composition. See the Section 14.3.5, “Device +Type Requirements” section for more details. + +An example of a Solar Power device with single phase AC output is illustrated below. + +_Figure 11. Example of a Solar Power device with single phase AC output_ + +An example of a Solar Power device with single phase AC output, but with the ability to measure +the output from 4 sets of solar panels supplying the overall device is illustrated below. + +``` +Page 148 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 12. Example of a Solar Power device with solar panel measurements_ + +An example of a Solar Power device with single phase AC output, but with the ability to measure +the output from 4 individual solar panels, arranged as 2 strings or 2 panels each is illustrated +below. + +_Figure 13. Example of a Solar Power device with solar panel measurements_ + +**14.3.2. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 149 +``` + +**14.3.3. Classification** + +``` +ID Device Name Superset Class Scope +0x0017 Solar Power Simple Endpoint +``` +**14.3.4. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**14.3.5. Device Type Requirements** + +A Solar Power device SHALL be composed of at least one endpoint with device types as defined by +the conformance below. There MAY be more endpoints with additional instances of these device +types or additional device types existing in the Solar Power device. + +``` +ID Name Constraint Conformance +0x0011 Power Source min 1 M +0x0510 Electrical Sensor min 1 M +0x050D Device Energy Manage­ +ment +``` +### O + +``` +0x0302 Temperature Sensor O +``` +**14.3.5.1. Cluster Requirements on Composing Device Types** + +Below list qualities and conformance that override the cluster specification requirements for the +composing device types. A blank table cell means there is no change to that item and the value from +the cluster specification applies. + +``` +Device +ID +``` +``` +Device Cluster +ID +``` +``` +Cluster Element Name Con­ +straint +``` +``` +Access Confor­ +mance +0x0011 Power +Source +``` +``` +0x002F Power +Source +``` +``` +Feature Wired M +``` +``` +0x0011 Power +Source +``` +``` +0x001D Descrip­ +tor +``` +``` +Feature TagList M +``` +``` +0x0510 Electrical +Sensor +``` +``` +0x0090 Electrical +Power +Measure­ +ment +``` +### M + +``` +0x0510 Electrical +Sensor +``` +``` +0x0090 Electrical +Power +Measure­ +ment +``` +``` +Attribute Voltage M +``` +``` +Page 150 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +Device +ID +``` +``` +Device Cluster +ID +``` +``` +Cluster Element Name Con­ +straint +``` +``` +Access Confor­ +mance +0x0510 Electrical +Sensor +``` +``` +0x0090 Electrical +Power +Measure­ +ment +``` +``` +Attribute Active­ +Current +``` +### M + +``` +0x0510 Electrical +Sensor +``` +``` +0x0091 Electrical +Energy +Measure­ +ment +``` +### M + +``` +0x0510 Electrical +Sensor +``` +``` +0x0091 Electrical +Energy +Measure­ +ment +``` +``` +Feature Exporte­ +dEnergy +``` +### M + +``` +0x050D Device +Energy +Manage­ +ment +``` +``` +0x0098 Device +Energy +Manage­ +ment +``` +``` +Feature PowerAd­ +justment +``` +### M + +``` +0x0302 Tempera­ +ture Sen­ +sor +``` +``` +0x001D Descrip­ +tor +``` +``` +Feature TagList M +``` +The Descriptor cluster for the endpoint including the Power Source device SHALL include the Grid +tag if it is connected to the premises wiring. + +The Electrical Sensor device SHALL also conform to the following: + +- An Electrical Sensor device SHALL measure the energy and power flows of the Solar Power + device at the AC grid or DC connection point. +- If the Solar Power device is connected to AC wiring, this Electrical Power Measurement cluster + SHALL support the AlternatingCurrent feature, and SHALL support the PolyPhasePower feature + if the Solar Power device is connected via polyphase wiring. +- If the Solar Power device is connected to DC wiring, this Electrical Power Measurement cluster + SHALL support the DirectCurrent feature. +- This Electrical Power Measurement cluster SHOULD support the ReactivePower attribute if con­ + nected to AC wiring. +- This Electrical Energy Measurement cluster SHOULD support the CumulativeEnergy feature. + +If a Solar Power device supports two or three phase power output then it MAY include two or three +additional endpoints, each including an Electrical Sensor Device Type as child elements. For each +such child endpoint it SHALL include a semantic tag from the Electrical Measurement Namespace +in the TagList attribute of the Descriptor cluster to describe the endpoint for the relevant Electrical +Power Measurement and Electrical Energy Measurement clusters indicating the relevant AC phase +that is being measured. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 151 +``` + +If a Solar Power device supports measurement of the output of individual solar panels or strings of +solar panels then it MAY include additional endpoints for each such measurement, including an +Electrical Sensor Device Type as child elements. For each such child endpoint: + +- It SHALL include a semantic tag from a Common Namespace, or a Manufacturer defined Tag + and Label, in the TagList attribute of the Descriptor cluster to describe the endpoint for the rele­ + vant Electrical Power Measurement and Electrical Energy Measurement clusters, indicating the + relevant device port, panel, or string of panels that is being measured. +- It SHALL also include a User Label cluster to allow an installer to add identifying information + for the panel or string of panels. + +If the Solar Power device output power can be controlled, then the Device Energy Management +device SHALL be included. + +Any Temperature Sensors included SHALL include Tag(s), and for non-standard Namespaces, +Label(s) in the Descriptor clusters of their endpoints to identify the temperature being measured. + +**14.3.6. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Conformance +0x0003 Identify Server O +``` +**14.4. Battery Storage Device Type** + +A Battery Storage device is a device that allows a DC battery, which can optionally be comprised of +a set parallel strings of battery packs and associated controller, and an AC inverter, to be monitored +and controlled by an Energy Management System in order to manage the peaks and troughs of sup­ +ply and demand, and/or to optimize cost of the energy consumed in premises. It is not intended to +be used for a UPS directly supplying a set of appliances, nor for portable battery storage devices. + +**14.4.1. Battery Storage Architecture** + +A Battery Storage device is always defined via endpoint composition. See the Section 14.4.5, “Device +Type Requirements” section for more details. + +An example of a Battery Storage device with single phase AC output is illustrated below. + +``` +Page 152 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +_Figure 14. Example of a Battery Storage device with single phase AC output_ + +An example of a Battery Storage device which also includes a directly connected Solar Power device +supplying DC power to the battery and using a single common inverter to the single phase AC input +and output is illustrated below. + +_Figure 15. Example of a Battery Storage device with DC-connected Solar Power device_ + +**14.4.2. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**14.4.3. Classification** + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 153 +``` + +``` +ID Device Name Superset Class Scope +0x0018 Battery Storage Simple Endpoint +``` +**14.4.4. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**14.4.5. Device Type Requirements** + +A Battery Storage device SHALL be composed of at least one endpoint with device types as defined +by the conformance below. There MAY be more endpoints with additional instances of these device +types or additional device types existing in the Battery Storage device. + +``` +ID Name Constraint Conformance +0x0011 Power Source min 1 M +0x0510 Electrical Sensor min 1 M +0x050D Device Energy Manage­ +ment +``` +### M + +``` +0x0302 Temperature Sensor O +0x0017 Solar Power O +``` +The Solar Power devices, if included, SHALL have separate endpoints, and include their own Power +Source, Electrical Sensor, and Device Energy Management devices, as defined by the Solar Power +Device device. + +**14.4.5.1. Cluster Requirements on Composing Device Types** + +Below list qualities and conformance that override the cluster specification requirements for the +composing device types. A blank table cell means there is no change to that item and the value from +the cluster specification applies. + +``` +Device +ID +``` +``` +Device Cluster +ID +``` +``` +Cluster Element Name Con­ +straint +``` +``` +Access Confor­ +mance +0x0011 Power +Source +``` +``` +0x002F Power +Source +``` +``` +Feature Wired M +``` +``` +0x0011 Power +Source +``` +``` +0x002F Power +Source +``` +``` +Feature Battery M +``` +``` +0x0011 Power +Source +``` +``` +0x002F Power +Source +``` +``` +Attribute BatVolt­ +age +``` +### M + +``` +0x0011 Power +Source +``` +``` +0x002F Power +Source +``` +``` +Attribute BatPer­ +centRema +ining +``` +### M + +``` +Page 154 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Device +ID** + +``` +Device Cluster +ID +``` +``` +Cluster Element Name Con­ +straint +``` +``` +Access Confor­ +mance +``` +0x0011 Power +Source + +``` +0x002F Power +Source +``` +``` +Attribute Bat­ +TimeRe­ +maining +``` +### M + +0x0011 Power +Source + +``` +0x002F Power +Source +``` +``` +Attribute Active­ +BatFaults +``` +### M + +0x0011 Power +Source + +``` +0x002F Power +Source +``` +``` +Attribute BatCapac­ +ity +``` +### M + +0x0011 Power +Source + +``` +0x002F Power +Source +``` +``` +Attribute Bat­ +TimeTo­ +FullCharg +e +``` +### M + +0x0011 Power +Source + +``` +0x002F Power +Source +``` +``` +Attribute BatCharg­ +ingCur­ +rent +``` +### M + +0x0011 Power +Source + +``` +0x002F Power +Source +``` +``` +Attribute Active­ +BatCharg +eFaults +``` +### M + +0x0011 Power +Source + +``` +0x001D Descrip­ +tor +``` +``` +Feature TagList M +``` +0x0011 Power +Source + +``` +0x001D Descrip­ +tor +``` +``` +Attribute TagList Includes +Grid and +Battery +``` +### M + +0x0510 Electrical +Sensor + +``` +0x0090 Electrical +Power +Measure­ +ment +``` +### M + +0x0510 Electrical +Sensor + +``` +0x0090 Electrical +Power +Measure­ +ment +``` +``` +Feature Alternat­ +ingCur­ +rent +``` +### M + +0x0510 Electrical +Sensor + +``` +0x0090 Electrical +Power +Measure­ +ment +``` +``` +Attribute Voltage M +``` +0x0510 Electrical +Sensor + +``` +0x0090 Electrical +Power +Measure­ +ment +``` +``` +Attribute Active­ +Current +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 155 +``` + +``` +Device +ID +``` +``` +Device Cluster +ID +``` +``` +Cluster Element Name Con­ +straint +``` +``` +Access Confor­ +mance +0x0510 Electrical +Sensor +``` +``` +0x0091 Electrical +Energy +Measure­ +ment +``` +### M + +``` +0x0510 Electrical +Sensor +``` +``` +0x0091 Electrical +Energy +Measure­ +ment +``` +``` +Feature Exporte­ +dEnergy +``` +### M + +``` +0x050D Device +Energy +Manage­ +ment +``` +``` +0x0098 Device +Energy +Manage­ +ment +``` +``` +Feature PowerAd­ +justment +``` +### M + +``` +0x0302 Tempera­ +ture Sen­ +sor +``` +``` +0x001D Descrip­ +tor +``` +``` +Feature TagList M +``` +The Power Source cluster in the Power Source device SHALL support the RECHG feature if it can be +charged as well as discharged through the connection to the premises wiring. + +The Electrical Sensor device SHALL also conform to the following: + +- An Electrical Sensor device SHALL measure the energy and power flows of the Battery Storage + device at the AC grid connection point. +- The Electrical Power Measurement cluster of this Electrical Sensor device SHALL support the + PolyphasePower feature if the Battery Storage device is connected via polyphase wiring, and + SHOULD support the ReactivePower attribute. +- The Electrical Energy Measurement cluster of this Electrical Sensor device SHALL support the + ImportedEnergy feature if it can be charged as well as discharged through the connection to the + premises wiring, and SHOULD support the CumulativeEnergy feature. + +If a Battery Storage device supports two or three phase power output then it MAY include two or +three additional endpoints, each including an Electrical Sensor Device Type as child elements. For +each such child endpoint it SHALL include a semantic tag from the Electrical Measurement Name­ +space in the TagList attribute of the Descriptor cluster to describe the endpoint for the relevant +Electrical Power Measurement and Electrical Energy Measurement clusters indicating the relevant +AC phase that is being measured. + +If a Battery Storage device supports measurement of the input and output of individual batteries or +sets of batteries then it MAY include additional endpoints for each such measurement, including an +Electrical Sensor Device Type as child elements. For each such child endpoint: * it SHALL include a +semantic tag from the Common Number Namespace, or a Manufacturer defined Tag and Label, in +the TagList attribute of the Descriptor cluster to describe the endpoint for the relevant Electrical +Power Measurement and Electrical Energy Measurement clusters indicating the relevant device +port, battery, or set of batteries that is being measured. * it SHOULD also include a User Label clus­ + +``` +Page 156 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +ter to allow an installer to add identifying information if the device permits flexible connection of +the actual batteries at installation time. + +Any Temperature Sensors included SHALL include Tag(s), and for non-standard Namespaces, +Label(s) in the Descriptor clusters of their endpoints to identify the temperature being measured. + +**14.4.6. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Conformance +0x0003 Identify Server O +``` +**14.5. Heat Pump Device Type** + +A Heat Pump device is a device that uses electrical energy to heat either spaces or water tanks using +ground, water or air as the heat source. These typically can heat the air or can pump water via cen­ +tral heating radiators or underfloor heating systems. It is typical to also heat hot water and store +the heat in a hot water tank. + +Note that the Water Heater device type can also be heated by a heat pump and has similar require­ +ments, but that cannot be used for space heating. + +**14.5.1. Heat Pump Architecture** + +A Heat Pump device is always defined via endpoint composition. See the Section 14.5.5, “Device +Type Requirements” section for more details. + +The Heat Pump device may contain Temperature Sensors for example to measure the flow and +return temperatures of the water it is providing to the premises heating system. + +The Heat Pump device may also include Thermostats located in the rooms that are being heated by +it, which in turn may also include Temperature Sensor clusters which can report the temperatures +in those rooms. These Thermostats may be included as servers within Thermostat devices within +the Heat Pump device itself, or may be separate third-party Thermostat devices for which the Heat +Pump has a client to use them. + +An example of a Heat Pump device is illustrated below. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 157 +``` + +_Figure 16. Example of a Heat Pump device_ + +**14.5.2. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**14.5.3. Classification** + +``` +ID Device Name Superset Class Scope +0x0309 Heat Pump Simple Endpoint +``` +**14.5.4. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**14.5.5. Device Type Requirements** + +A Heat Pump device SHALL be composed of at least one endpoint with device types as defined by +the conformance below. There MAY be more endpoints with additional instances of these device +types or additional device types existing in the Heat Pump device. + +``` +ID Name Constraint Conformance +0x0011 Power Source M +0x0510 Electrical Sensor min 1 M +0x050D Device Energy Manage­ +ment +``` +### M + +``` +0x0301 Thermostat O +``` +``` +Page 158 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +ID Name Constraint Conformance +0x050F Water Heater O +0x0302 Temperature Sensor O +``` +The Heat Pump device SHALL include either one or more Thermostat devices, or include a Thermo­ +stat client. + +**14.5.5.1. Cluster Requirements on Composing Device Types** + +Below list qualities and conformance that override the cluster specification requirements for the +composing device types. A blank table cell means there is no change to that item and the value from +the cluster specification applies. + +``` +Device +ID +``` +``` +Device Cluster +ID +``` +``` +Cluster Element Name Con­ +straint +``` +``` +Access Confor­ +mance +0x0011 Power +Source +``` +``` +0x002F Power +Source +``` +``` +Feature Wired M +``` +``` +0x0011 Power +Source +``` +``` +0x001D Descrip­ +tor +``` +``` +Feature TagList M +``` +``` +0x0011 Power +Source +``` +``` +0x001D Descrip­ +tor +``` +``` +Attribute TagList Includes +Grid +``` +``` +0x0510 Electrical +Sensor +``` +``` +0x0090 Electrical +Power +Measure­ +ment +``` +### M + +``` +0x0510 Electrical +Sensor +``` +``` +0x0090 Electrical +Power +Measure­ +ment +``` +``` +Feature Alternat­ +ingCur­ +rent +``` +### M + +``` +0x0510 Electrical +Sensor +``` +``` +0x0090 Electrical +Power +Measure­ +ment +``` +``` +Attribute Voltage M +``` +``` +0x0510 Electrical +Sensor +``` +``` +0x0090 Electrical +Power +Measure­ +ment +``` +``` +Attribute Active­ +Current +``` +### M + +``` +0x0510 Electrical +Sensor +``` +``` +0x0091 Electrical +Energy +Measure­ +ment +``` +### M + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 159 +``` + +``` +Device +ID +``` +``` +Device Cluster +ID +``` +``` +Cluster Element Name Con­ +straint +``` +``` +Access Confor­ +mance +0x050D Device +Energy +Manage­ +ment +``` +``` +0x0098 Device +Energy +Manage­ +ment +``` +``` +Feature PowerAd­ +justment +``` +### M + +``` +0x0301 Thermo­ +stat +``` +``` +0x001D Descrip­ +tor +``` +``` +Feature TagList M +``` +``` +0x0301 Thermo­ +stat +``` +``` +0x0041 User +Label +``` +### M + +``` +0x0302 Tempera­ +ture Sen­ +sor +``` +``` +0x001D Descrip­ +tor +``` +``` +Feature TagList M +``` +If a Heat Pump device supports two or three phase power input then it MAY include two or three +additional endpoints, each including an Electrical Sensor Device Type as child elements. For each +such child endpoint it SHALL include a semantic tag from the Electrical Measurement Namespace +in the TagList attribute of the Descriptor cluster to describe the endpoint for the relevant Electrical +Power Measurement and Electrical Energy Measurement clusters indicating the relevant AC phase +that is being measured. + +The Electrical Energy Measurement and Electrical Power Measurement clusters of the mandatory +Electrical Sensor device SHALL measure the energy and power of the Heat Pump device at the AC +grid connection point. + +The Electrical Power Measurement clusters of the mandatory Electrical Sensor device SHALL sup­ +port the PolyPhasePower feature if the Heat Pump device is connected via polyphase wiring. + +The Electrical Energy Measurement cluster of the mandatory Electrical Sensor device SHOULD sup­ +port the ImportedEnergy and CumulativeEnergy features. + +Any Temperature Sensors using non-standard Namespaces for their Tags SHALL include Label(s) in +the Descriptor clusters of their endpoints to identify the temperature being measured. + +Any Thermostat SHALL include a semantic tag from a Common Namespace, or a Manufacturer +defined Tag and Label, in the TagList attribute of the Descriptor cluster to describe the endpoint for +the relevant Thermostat clusters, indicating the relevant device (or its connected port) that is being +measured. It SHALL also include a User Label cluster to allow an installer to add identifying infor­ +mation for the rooms or spaces where the Thermostat measurement point is located. + +**14.5.6. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Conformance +0x0003 Identify Server O +``` +``` +Page 160 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**ID Name Client/Server Conformance** + +0x0201 Thermostat Client O + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 161 +``` + +Page 162 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 15. Network Infrastructure Device** + +**Types** + +**15.1. Introduction** + +Matter aims to build a universal IPv6-based communication protocol for smart home devices, and +in principle almost any IPv6-bearing Wi-Fi, Thread, or Ethernet network is suitable for Matter +deployment (see _Network Topology_ in [MatterCore]). + +The Network Infrastructure device types defined in this chapter are designed to provide a reliable, +secure, and performant connectivity experience for Matter devices and their users. To achieve this, +these device types expose Matter application clusters for the purposes of network management, +diagnostics, and configuration. They also include requirements on lower layers (including the net­ +work and physical layers) that contribute to the desired connectivity experience. + +Note that Matter devices and applications cannot rely on the presence of Matter-certified Network +Infrastructure Devices, or the presence of network features mandated by these device types, for +their correct operation. + +**15.2. Network Infrastructure Manager Device Type** + +A Network Infrastructure Manager provides interfaces that allow for the management of the Wi-Fi, +Thread, and Ethernet networks underlying a Matter deployment, realizing the _Star Network Topol­ +ogy_ described in [MatterCore]. + +Examples of physical devices that implement the Matter Network Infrastructure Manager device +type include Wi-Fi gateway routers. + +Relevant hardware and software requirements for Network Infrastructure Manager devices are +defined in Section 15.2.6, “Other Requirements” and within the clusters mandated by this device +type. + +A Network Infrastructure Manager device MAY be managed by a service associated with the device +vendor, for example, an Internet Service Provider. Sometimes this managing service will have poli­ +cies that require the use of the Managed Device feature of the Access Control Cluster (see Section +15.2.5.1, “Access Control MNGD Conformance”). Consequently, Commissioners of this device type +should be aware of this feature and its use. + +**15.2.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial release +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 163 +``` + +**15.2.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0090 Network Infra­ +structure Manager +``` +``` +Simple Endpoint +``` +**15.2.3. Conditions** + +Please see the Base Device Type definition for conformance tags. + +**15.2.4. Cluster Requirements** + +Each endpoint supporting this device type SHALL include these clusters based on the conformance +defined below. + +``` +ID Name Client/Server Quality Conformance +0x0451 Wi-Fi Network +Management +``` +``` +Server M +``` +``` +0x0452 Thread Border +Router Manage­ +ment +``` +``` +Server M +``` +``` +0x0453 Thread Network +Directory +``` +``` +Server M +``` +**15.2.5. Root Node Element Requirements** + +Below list qualities and conformance that override the cluster specification requirements for the +Section 2.1, “Root Node”. A blank table cell means there is no change to that item and the value +from the cluster specification applies. + +``` +ID Cluster Element Name Constraint Access Confor­ +mance +0x001F Access Con­ +trol +``` +``` +Feature MNGD desc +``` +**15.2.5.1. Access Control MNGD Conformance** + +A Network Infrastructure Manager device MAY utilize the Managed Device (MNGD) feature flag of +the Access Control Cluster on the device’s Root Node endpoint (i.e. Endpoint 0). + +Please refer to the "Managed Device Feature Usage Restrictions" section in the Access Control Clus­ +ter chapter of the Matter Core Specification for the complete set of limitations on use of this feature +on endpoints with the Network Infrastructure Manager device type. + +### NOTE + +``` +The conformance of this element crosses endpoints. It is expressed against the Root +Node endpoint and there SHALL NOT be a separate AccessControl cluster on the +``` +``` +Page 164 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +``` +endpoint having the Network Infrastructure Manager device type. +``` +**15.2.6. Other Requirements** + +The device SHALL implement a bridged Wi-Fi / Ethernet hub network, enabling IPv6 connectivity +between Matter Nodes across transports. + +**15.2.6.1. Ethernet Requirements** + +The device SHALL provide an Ethernet LAN interface that is part of the bridged hub network. + +The Root Node endpoint of the device MAY include a Network Commissioning cluster associated +with this Ethernet interface. + +**15.2.6.2. Wi-Fi Requirements** + +The device SHALL support the operation of an IEEE 802.11 Wi-Fi network (ESS) and provide access +to the SSID and credentials of this network via the Wi-Fi Network Management cluster. The mecha­ +nisms by which this network is configured are outside the scope of this specification. The device +SHALL support concurrently operating BSSs for this ESS in the 2.4 GHz and 5 GHz frequency bands; +it MAY support operating additional BSSs for this ESS in other frequency bands such as 6 GHz or +sub-1 GHz. All BSSs in this ESS SHALL be part of the bridged hub network, i.e. bridged to each other +and to the Ethernet interface. + +The device MAY support operating additional Wi-Fi networks (e.g. a "guest network"); the require­ +ments above do not apply to any such additional networks. + +The device SHOULD NOT include any Network Commissioning cluster instances associated with the +Wi-Fi Access Point interface. + +The device SHALL be certified by the Wi-Fi Alliance in the Access Point role for Wi-Fi 6 or above. It +SHALL additionally be certified in the Access Point role for Wi-Fi 6E if it supports operating in the 6 +GHz band, and for Wi-Fi HaLow if it supports operating in the sub-1 GHz band. + +**15.2.6.3. Thread Requirements** + +The Network Infrastructure Manager device SHALL be certified by the Thread Group as _Built on +Thread: Border Router_ based on Thread 1.3.0 or above. It SHOULD be certified based on Thread +1.4.0 or above. + +``` +NOTE Certification based on Thread 1.4.0 or above will become mandatory in Matter 1.5. +``` +The device SHALL implement a Thread Border Router as described by the Thread specification, and +provide connectivity between the Thread network and the Wi-Fi / Ethernet hub network. The +Thread Interface associated with the Border Router SHALL be exposed via the Thread Border +Router Management cluster. + +The device SHOULD NOT include any Network Commissioning cluster instances associated with the +Thread Border Router. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 165 +``` + +**15.2.6.4. Discovery and Commissioning** + +A Network Infrastructure Manager device SHOULD implement Extended Discovery in order to be +discoverable by entities on the local IP network, even when not in Commissioning Mode, and +SHOULD populate the optional _device type_ subtype (e.g., _T144) to allow for filtering of discovery +results to find only Nodes that match the Network Infrastructure Manager device type (see Commis­ +sioning Subtypes). + +A Network Infrastructure Manager SHOULD populate the following DNS-SD TXT record key/value +pairs in the Commissionable Node Discovery response: Commissioning Pairing Hint, and Commission­ +ing Pairing Instruction so that the Commissioner can guide the user through the steps needed to +put the Commissionee into Commissioning Mode. If the Network Infrastructure Manager provides +its own app or website which includes a UX for putting the device into Commissioning Mode, then +the device SHOULD populate the Commissioning VID/PID key/value pair and SHOULD set bit 1 of the +Pairing Hint (Device Manufacturer URL), so that the Commissioner can utilize the URL specified in +the CommissioningCustomFlowUrl of the DeviceModel schema entry indexed by the Vendor ID and Prod­ +uct ID in the Distributed Compliance Ledger and utilize flows described in Custom Commissioning +Flow to redirect the user to a custom app or website specified by the device vendor, and receive the +user back following the callback flow which contains the onboarding payload. This flow is +described in detail in the Initiating Commissioning section of the Matter Core specification, under +the User Journey titled User-Initiated Beacon Detection, Already Commissioned Device. + +**15.3. Thread Border Router Device Type** + +A Thread Border Router device type provides interfaces for querying and configuring the associ­ +ated Thread network. + +Instances of physical devices categorized as Thread Border Routers encompass standalone Thread +Border Routers, conventional application devices like smart speakers, media streamers, and light­ +ing fixtures equipped with a Thread Border Router, as well as Wi-Fi Routers incorporating Thread +Border Router functionality. + +The necessary hardware and software prerequisites are detailed within the clusters that are man­ +dated by this device type. + +**15.3.1. Revision History** + +This is the revision history for this document. + +``` +Revision Description +1 Initial revision +``` +**15.3.2. Classification** + +``` +ID Device Name Superset Class Scope +0x0091 Thread Border +Router +``` +``` +Simple Endpoint +``` +``` +Page 166 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**15.3.3. Conditions** + +Please see the Base Device Type definition for additional conformance tags. + +**15.3.4. Device Type Requirements** + +The following table lists other device types to be implemented along with this device type based on +conformance. + +``` +ID Name Constraint Conformance +0x0019 Secondary Network +Interface +``` +### O + +If a Thread Border Router endpoint supports the Secondary Network Interface device type, then + +- The Thread Border Router Management cluster and the Network Commissioning Cluster SHALL + reflect the same underlying network configuration, i.e. changes made via either cluster SHALL + also be reflected in the other. +- The MaxNetworks attribute in the Network Commissioning Cluster SHALL have a value of 1. + +**15.3.5. Cluster Requirements** + +Each endpoint supporting the Thread Border Router device type SHALL include these clusters +based on the conformance defined below. + +``` +ID Name Client/Server Quality Conformance +0x0035 Thread Network +Diagnostics +``` +``` +Server M +``` +``` +0x0452 Thread Border +Router Manage­ +ment +``` +``` +Server M +``` +``` +0x0453 Thread Network +Directory +``` +``` +Server O +``` +**15.3.6. Other Requirements** + +The device SHALL implement a Thread Border Router as described by the Thread specification, and +provide connectivity between the Thread network and a hub network when connected via a func­ +tioning adjacent infrastructure link. + +The Thread Interface associated with the Border Router SHALL be exposed via the Thread Border +Router Management cluster. + +The device MAY include a Network Commissioning cluster instance associated with the Wi-Fi or +Ethernet adjacent infrastructure link interface on its Root Node. It SHOULD NOT include a Network +Commissioning cluster instance associated with the Thread interface of the Border Router on its +Root Node. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 167 +``` + +**15.3.6.1. Thread Requirements** + +A device exposing the Thread Border Router device type SHALL be certified by the Thread Group as +_Built on Thread: Border Router_ based on Thread 1.3.0 or above. It SHOULD be certified based on +Thread 1.4.0 or above. + +``` +NOTE Certification based on Thread 1.4.0 or above will become mandatory in Matter 1.5. +``` +**15.3.7. Usage** + +The Thread Border Router Device Type provides the Thread Border Router Management Cluster +with the goal of ensuring a seamless user experience when adding a new Border Router to form a +new Thread network or join an existing one. This section presents informative configuration +sequences that a Fabric Admin can set up to improve coverage and Internet access redundancy for +Thread networks using the Thread Border Router device type. Four use cases are covered: + +- Initial configuration of a Thread Border Router when no PAN exists +- Joining an existing PAN +- Sharing an existing PAN +- Moving to a new PAN + +**15.3.7.1. Initial configuration of Thread Border Router** + +In this use case, there is initially no PAN at the user’s home. The user installs a Matter certified +Thread Border Router to use Thread connectivity for their Matter devices. + +After installation, the PAN configured by Admin A on the Thread Border Router is used to install the +Thread Matter device on Fabric A. + +``` +Page 168 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**15.3.7.2. Joining an existing PAN** + +In this use case, there is already a PAN in the user’s home that is managed by a Fabric A with TBR1 +(e.g. as a result of the above sequence diagram applied previously between Admin 1 and TBR1). The +user installs a Matter-certified Thread Border Router (TBR2) to extend the Thread coverage and +Internet access redundancy of Thread networks for their Matter devices. + +After installation, a single Thread PAN is shared by all Border Routers. + +**15.3.7.3. Share an existing PAN** + +In this use case, there is already a PAN in the user’s home that is managed by Fabric A with TBR1 +(e.g. as a result of the above sequence diagram applied previously between Admin 1 and TBR1). The +user wants to use the Thread connectivity provided by the Matter-certified Thread Border Router +managed by Fabric A with Fabric B to share its connectivity. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 169 +``` + +After the installation, the Thread PAN is shared by Fabric A and B. + +Note: The user must use the Multiple Fabrics feature process between Fabrics A and B to onboard +the Thread Border Router from Fabric A to Fabric B. + +**15.3.7.4. Merging to a new PAN** + +This use case is a specific configuration where the user already has 2 PANs. One is managed by a +Fabric A through a Matter Thread Border Router (TBR1) and the other is managed by a Fabric B +through another Matter Thread Border Router (TBR2). + +The user wishes to merge the existing Thread connectivity provided by the two Matter certified +Thread Border Routers to share their connectivity to extend the Thread coverage and Internet +access redundancy of the Thread networks for their Matter devices. + +``` +Page 170 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +After installation, the Thread PAN is shared between Fabrics A and B. + +Note 1 : Activation of the pending dataset is Thread stack dependent and propagation of the new +dataset to all Matter devices may fail, for example if devices are disconnected during the process. + +Note 2 : This configuration should remain very rare if the previous installations followed the previ­ +ous use cases. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 171 +``` + diff --git a/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_NAMESPACE_SPEC.md b/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_NAMESPACE_SPEC.md new file mode 100644 index 000000000..bb50f0c76 --- /dev/null +++ b/lib/libesp32/berry_matter/specs_for_ai/MATTER_1.4.1_NAMESPACE_SPEC.md @@ -0,0 +1,1113 @@ +# Matter Standard Namespaces + +# Version 1.4. + +``` +Document: 23-31936-004_Matter-1.4.1-Standard-Namespaces.pdf +March 17, 2025 +Sponsored by: Connectivity Standards Alliance +Accepted by: This document has been accepted for release by the Connectivity +Standards Alliance Board of Directors on March 17, 2025 +Abstract: The Matter specification defines fundamental requirements to +enable an interoperable application layer solution for smart home +devices over the Internet Protocol. +Keywords: Referenced in Chapter 1. +``` +Copyright © 2022-2025 Connectivity Standards Alliance, Inc. +508 Second Street, Suite 109B Davis, CA 95616 - USA +[http://www.csa-iot.org](http://www.csa-iot.org) +All rights reserved. + +Permission is granted to members of the Connectivity Standards Alliance to reproduce this +document for their own use or the use of other Connectivity Standards Alliance members only, +provided this notice is included. All other rights reserved. Duplication for sale, or for commercial or +for-profit use is strictly prohibited without the prior written consent of the Connectivity Standards +Alliance. + + + +# Matter Semantic Tag Namespaces + +``` +Version 1.4.1, 2025-03-12 06:42:16 -0700: Approved +``` + + +## Table of Contents + +## Revision History.   + +- Notice of Use and Disclosure.   +- Revision History.   +- 1. Introduction.   + - 1.1. CSA Reference Documents.   +- 2. Common Closure Semantic Tag Namespace.   +- 3. Common Compass Direction Semantic Tag Namespace.   +- 4. Common Compass Location Semantic Tag Namespace.   +- 5. Common Direction Semantic Tag Namespace.   +- 6. Common Level Semantic Tag Namespace.   +- 7. Common Location Semantic Tag Namespace.   +- 8. Common Number Semantic Tag Namespace.   +- 9. Common Position Semantic Tag Namespace.   + - 9.1. Examples.   +- 10. Common Landmark Semantic Tag Namespace.   +- 11. Common Relative Position Semantic Tag Namespace.   +- 12. Electrical Measurement Semantic Tag Namespace.   +- 13. Common Area Semantic Tag Namespace.   +- 14. Laundry Semantic Tag Namespace.   +- 15. Power Source Semantic Tag Namespace.   + - 15.1. Grid Tag.   + - 15.2. Solar Tag.   + - 15.3. Battery Tag.   + - 15.4. EV Tag.   +- 16. Refrigerator Semantic Tag Namespace.   +- 17. Room Air Conditioner Semantic Tag Namespace.   +- 18. Switches Semantic Tag Namespace.   + - 18.1. Custom Tag.   + + + +**Notice of Use and Disclosure** + +Copyright © Connectivity Standards Alliance (2023). All rights reserved. The information within this +document is the property of the Connectivity Standards Alliance and its use and disclosure are +restricted, except as expressly set forth herein. + +Connectivity Standards Alliance hereby grants you a fully-paid, non-exclusive, nontransferable, +worldwide, limited and revocable license (without the right to sublicense), under Connectivity Stan­ +dards Alliance’s applicable copyright rights, to view, download, save, reproduce and use the docu­ +ment solely for your own internal purposes and in accordance with the terms of the license set +forth herein. This license does not authorize you to, and you expressly warrant that you shall not: +(a) permit others (outside your organization) to use this document; (b) post or publish this docu­ +ment; (c) modify, adapt, translate, or otherwise change this document in any manner or create any +derivative work based on this document; (d) remove or modify any notice or label on this docu­ +ment, including this Copyright Notice, License and Disclaimer. The Connectivity Standards Alliance +does not grant you any license hereunder other than as expressly stated herein. + +Elements of this document may be subject to third party intellectual property rights, including +without limitation, patent, copyright or trademark rights, and any such third party may or may not +be a member of the Connectivity Standards Alliance. Connectivity Standards Alliance members +grant other Connectivity Standards Alliance members certain intellectual property rights as set +forth in the Connectivity Standards Alliance IPR Policy. Connectivity Standards Alliance members +do not grant you any rights under this license. The Connectivity Standards Alliance is not responsi­ +ble for, and shall not be held responsible in any manner for, identifying or failing to identify any or +all such third party intellectual property rights. Please visit [http://www.csa-iot.org](http://www.csa-iot.org) for more information +on how to become a member of the Connectivity Standards Alliance. + +This document and the information contained herein are provided on an “AS IS” basis and the Con­ +nectivity Standards Alliance DISCLAIMS 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 INTELLEC­ +TUAL PROPERTY RIGHTS INCLUDING PATENT, COPYRIGHT OR TRADEMARK RIGHTS); OR (B) ANY +IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR +NONINFRINGEMENT. IN NO EVENT WILL THE CONNECTIVITY STANDARDS ALLIANCE BE LIABLE +FOR ANY LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF BUSI­ +NESS, OR FOR ANY OTHER DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTAL, 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 in this document may be trademarks that are the sole prop­ +erty of their respective owners. + +This notice and disclaimer must be included on all copies of this document. + +Connectivity Standards Alliance +508 Second Street, Suite 206 +Davis, CA 95616, USA + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 1 +``` + +Page 2 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Revision History** + +``` +Revision Date Details Editor +1 October 18, 2023 Version 1.2 Robert Szewczyk +2 April 17, 2024 Version 1.3 Robert Szewczyk +3 November 4, 2024 Version 1.4 Robert Szewczyk +4 March 17, 2024 Version 1.4.1 Robert Szewczyk +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 3 +``` + +Page 4 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 1. Introduction** + +This document contains namespaces as part of the semantic tag feature. + +The standard namespaces are defined in this appendix. They consist of the common namespaces +and device-specific namespaces. + +The Common namespaces start with Namespace ID 0x01 and contains semantic tags that can apply +to any domain. Examples include direction words like 'left', 'right', 'up' and 'down' or location words +like 'inside' and 'outside'. + +Device-specific namespaces begin with Namespace ID 0x41. The semantic tags defined in the +device-specific namespaces SHALL be restricted for use within each device type or set of device +types. + +### NOTE + +``` +Some namespaces specific to certain group of device types (related to Energy and +Laundry) have been assigned an ID from the common range, even though they are +only applicable to a certain set of device types only. +``` +A TagList MAY combine several of these tags, as appropriate for the device, provided that for any +given device type the tags come from the namespace for that device type as well as any of the com­ +mon namespaces, and/or from a manufacturer-specific namespace. Example: An outdoor luminaire +with two light units, one shining upwards and one shining downwards. One light unit would be +represented by an endpoint with a TagList which has TagStructs with Tags "Location.Outdoor" and +"Position.Top" and "Direction.Upward", while the other light unit would be represented by an end­ +point with a TagList which has TagStructs with Tags "Location.Outdoor" and "Position.Bottom" and +"Direction.Downward". + +``` +ID Namespace Summary +Common namespaces +0x01 Common Closure Namespace Tags which are useful in +describing things related to +closing and opening +0x02 Common Compass Direction +Namespace +``` +``` +Tags which are useful in +describing things related to +compass direction +0x03 Common Compass Location +Namespace +``` +``` +Tags which are useful in +describing things related to +compass location +0x04 Common Direction Namespace Tags which are useful in +describing things related to +direction +0x05 Common Level Namespace Tags which are useful in +describing things related to +level +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 5 +``` + +``` +ID Namespace Summary +0x06 Common Location Namespace Tags which are useful in +describing things related to +location +0x07 Common Number Namespace Tags which are useful in +describing things related to +numbering +0x08 Common Position Namespace Tags which are useful in +describing things related to +position +0x0A Electrical Measurement Name­ +space +``` +``` +Tags which are useful in +describing electrical loads +0x0E Laundry Namespace Tags which are useful with +laundry device types +0x0F Power Source Namespace Tags which are useful with +power source device types +0x10 Common Area Namespace Tags which are useful in +describing things related to +home areas +0x11 Common Landmark Namespace Tags which are useful in +describing things related to +home landmarks +0x12 Common Relative Position +Namespace +``` +``` +Tags which are useful in +describing things related to +position relative to a reference +external to the device +Device-specific namespaces +0x41 Refrigerator Namespace Tags which are useful with +refrigeration device types +0x42 Room Air Conditioner Name­ +space +``` +``` +Tags which are useful with +Room Air Conditioner device +types +0x43 Switches Namespace Tags which are useful with +switch device types +``` +**1.1. CSA Reference Documents** + +``` +Reference Reference Location/URL Description +[CoreSpec] https://groups.csa-iot.org/wg/ +members-all/document/ +``` +``` +Core Matter Specification +``` +``` +Page 6 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Reference Reference Location/URL Description** +[DeviceLibrary] https://groups.csa-iot.org/wg/ +members-all/document/ + +``` +Device Library +``` +[AppClusters] https://groups.csa-iot.org/wg/ +members-all/document/ + +``` +Application Clusters +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 7 +``` + +Page 8 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 2. Common Closure Semantic Tag** + +**Namespace** + +This section contains the Common Closure semantic tag namespace as part of the semantic tag fea­ +ture. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a feature of a Closure, e.g. the button to activate opening a garage door. + +``` +ID Namespace +0x01 Common Closure +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Opening Move toward open position +0x01 Closing Move toward closed position +0x02 Stop Stop any movement +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 9 +``` + +Page 10 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 3. Common Compass Direction** + +**Semantic Tag Namespace** + +This section contains the Common Compass Direction semantic tag namespace as part of the +semantic tag feature. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a movement into a certain compass direction. Note the difference with Chapter 4, _Com­_ + +## 4. Common Compass Location Semantic Tag Namespace.   + +``` +ID Namespace +0x02 Common Compass Direction +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Northward +0x01 North-Eastward +0x02 Eastward +0x03 South-Eastward +0x04 Southward +0x05 South-Westward +0x06 Westward +0x07 North-Westward +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 11 +``` + +Page 12 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 4. Common Compass Location** + +**Semantic Tag Namespace** + +This section contains the Common Compass Location semantic tag namespace as part of the seman­ +tic tag feature. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a position in a certain compass direction (e.g. an outdoor sensor in the North garden). +Note the difference with Chapter 3, _Common Compass Direction Semantic Tag Namespace_. + +``` +ID Namespace +0x03 Common Compass Location +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 North +0x01 North-East +0x02 East +0x03 South-East +0x04 South +0x05 South-West +0x06 West +0x07 North-West +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 13 +``` + +Page 14 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 5. Common Direction Semantic Tag** + +**Namespace** + +This section contains the Common Direction semantic tag namespace as part of the semantic tag +feature. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a movement in a certain direction relative to the device. Note the difference with Chapter + +## 9. Common Position Semantic Tag Namespace.   + +``` +ID Namespace +0x04 Common Direction +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Upward +0x01 Downward +0x02 Leftward +0x03 Rightward +0x04 Forward +0x05 Backward +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 15 +``` + +Page 16 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 6. Common Level Semantic Tag** + +**Namespace** + +This section contains the Common Level semantic tag namespace as part of the semantic tag fea­ +ture. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a certain level for a feature of a device (e.g. a button to set the speed of a fan). + +``` +ID Namespace +0x05 Common Level +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Low +0x01 Medium +0x02 High +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 17 +``` + +Page 18 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 7. Common Location Semantic Tag** + +**Namespace** + +This section contains the Common Location semantic tag namespace as part of the semantic tag fea­ +ture. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a location of a device (e.g. an outdoor temperature sensor). + +``` +ID Namespace +0x06 Common Location +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Indoor Element is indoors or related to +indoor equipment/conditions +(e.g. the "indoor" temperature). +0x01 Outdoor Element is outdoors or related +to outdoor equipment/condi­ +tions (e.g. the "outdoor" temper­ +ature). +0x02 Inside Element is located inside the +equipment (e.g. a sensor +"inside" a cabinet). +0x03 Outside Element is located outside the +equipment (e.g. a sensor "out­ +side" a cabinet) +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 19 +``` + +Page 20 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 8. Common Number Semantic Tag** + +**Namespace** + +This section contains the Common Number semantic tag namespace as part of the semantic tag fea­ +ture. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a certain numeric feature of a device (e.g. a numeric input button). + +``` +ID Namespace +0x07 Common Number +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Zero +0x01 One +0x02 Two +0x03 Three +0x04 Four +0x05 Five +0x06 Six +0x07 Seven +0x08 Eight +0x09 Nine +0x0A Ten +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 21 +``` + +Page 22 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 9. Common Position Semantic Tag** + +**Namespace** + +This section contains the Common Position semantic tag namespace as part of the semantic tag fea­ +ture. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a position relative to the device (e.g. the temperature sensor in the top drawer of a refrig­ +erator, or location of the buttons on a multi-button switch device). Note the difference with Chapter + +## 3. Common Compass Direction Semantic Tag Namespace.   + +``` +ID Namespace +0x08 Common Position +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Left +0x01 Right +0x02 Top +0x03 Bottom +0x04 Middle +0x05 Row Numeric value provided in +Label field +0x06 Column Numeric value provided in +Label field +``` +When multiple endpoints are used for device types, and the associated consumer-facing locations +of those endpoints are organized in a straight line, grid or matrix, these endpoints SHOULD be allo­ +cated in top-to-bottom, left-to-right order. + +For grids or arrays larger than 3 elements in any direction, the Row and Column tags SHOULD be +used. + +If the Row or Column tags are used, the Label field in the same Semantic Tag structure SHALL be +filled with a number comprised of Arabic numerals encoded as a string to indicate the row/column +of the item. Number words (e.g. "one", "two", etc.) SHALL NOT be used to describe the position of +the item. The first row/column SHALL use Label "1". + +**9.1. Examples** + +``` +The following example illustrates a composed device comprised of 9 endpoints arranged in a +3x3 grid. This example uses position tags to indicate position. +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 23 +``` + +``` +Composed device arranged in a 3x3 grid +Top Left Top Middle Top Right +Middle Left Middle Middle Right +Bottom Left Bottom Middle Bottom Right +``` +``` +The endpoints would be populated in this order (showing the TagList in their Descriptor clus­ +ter): +``` +- EP 21: Top Left +- EP 22: Top Middle +- EP 23: Top Right +- EP 24: Middle Left +- EP 25: Middle +- EP 26: Middle Right +- EP 27: Bottom Left +- EP 28: Bottom Middle +- EP 29: Bottom Right + +``` +The following example illustrates a composed device comprised of 8 endpoints arranged in a +2x4 grid. This example uses the Row and Column tags along with Arabic numeral Labels to +indicate position. +Row "1" Column "1" Row "1" Column "2" Row "1" Column "3" Row "1" Column "4" +Row "2" Column "1" Row "2" Column "2" Row "2" Column "3" Row "2" Column "4" +The endpoints would be populated in this order (showing the TagList in their Descriptor clus­ +ter): +``` +- EP 31: {Row, "1"}, {Column, "1"} +- EP 32: {Row, "1"}, {Column, "2"} +- EP 33: {Row, "1"}, {Column, "3"} +- EP 34: {Row, "1"}, {Column, "4"} +- EP 35: {Row, "2"}, {Column, "1"} +- EP 36: {Row, "2"}, {Column, "2"} +- EP 37: {Row, "2"}, {Column, "3"} +- EP 38: {Row, "2"}, {Column, "4"} + +Page 24 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 10. Common Landmark Semantic** + +**Tag Namespace** + +This section contains the Common Landmark semantic tag namespace as part of the semantic tag +feature. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a home landmark. + +``` +ID Namespace +0x11 Common Landmark Namespace +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Air Conditioner +0x01 Air Purifier +0x02 Back Door +0x03 Bar Stool +0x04 Bath Mat +0x05 Bathtub +0x06 Bed +0x07 Bookshelf +0x08 Chair +0x09 Christmas Tree +0x0A Coat Rack +0x0B Coffee Table +0x0C Cooking Range +0x0D Couch +0x0E Countertop +0x0F Cradle +0x10 Crib +0x11 Desk +0x12 Dining Table +0x13 Dishwasher +0x14 Door +0x15 Dresser +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 25 +``` + +``` +ID Name Summary +0x16 Laundry Dryer +0x17 Fan +0x18 Fireplace +0x19 Freezer +0x1A Front Door +0x1B High Chair +0x1C Kitchen Island +0x1D Lamp +0x1E Litter Box +0x1F Mirror +0x20 Nightstand +0x21 Oven +0x22 Pet Bed +0x23 Pet Bowl +0x24 Pet Crate +0x25 Refrigerator +0x26 Scratching Post +0x27 Shoe Rack +0x28 Shower +0x29 Side Door +0x2A Sink +0x2B Sofa +0x2C Stove +0x2D Table +0x2E Toilet +0x2F Trash Can +0x30 Laundry Washer +0x31 Window +0x32 Wine Cooler +``` +Page 26 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 11. Common Relative Position** + +**Semantic Tag Namespace** + +This section contains the Common Relative Position semantic tag namespace as part of the semantic +tag feature. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with a position relative to some reference, which must be specified by the user of these tags. +For example, the position may be relative to a household item, such as a dining table, and the user +of these tags must indicate that. Note the difference with Chapter 9, _Common Position Semantic Tag +Namespace_ , which contains tags indicating the position relative to the device. + +``` +ID Namespace +0x12 Common Relative Position +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Under +0x01 Next To Area in proximity to the point +of reference +0x02 Around The area surrounding the point +the reference +0x03 On +0x04 Above +0x05 Front Of +0x06 Behind +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 27 +``` + +Page 28 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 12. Electrical Measurement** + +**Semantic Tag Namespace** + +This section contains the standard semantic tag namespace for electrical measurement as part of +the semantic tag feature. + +The tags contained in this namespace are restricted for use in the electrical measurement domain +and SHALL NOT be used in any other domain or context. + +``` +ID Namespace +0x0A Electrical Measurement +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 DC Indicates values measured for a +DC load +0x01 AC Indicates values measured for a +single-phase AC load, or values +measured for the collective load +on a polyphase AC power sup­ +ply +0x02 ACPhase1 Indicates values measured for +an AC load on phase 1 of a +polyphase power supply +0x03 ACPhase2 Indicates values measured for +an AC load on phase 2 of a +polyphase power supply +0x04 ACPhase3 Indicates values measured for +an AC load on phase 3 of a +polyphase power supply +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 29 +``` + +Page 30 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 13. Common Area Semantic Tag** + +**Namespace** + +This section contains the Common Area semantic tag namespace as part of the semantic tag feature. + +The tags contained in this namespace MAY be used in any domain or context, to indicate an associa­ +tion with an indoor or outdoor area of a home. + +``` +ID Namespace +0x10 Common Area Namespace +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Aisle +0x01 Attic +0x02 Back Door +0x03 Back Yard +0x04 Balcony +0x05 Ballroom +0x06 Bathroom Also known as Restroom +0x07 Bedroom +0x08 Border +0x09 Boxroom A small room typically used for +storage +0x0A Breakfast Room +0x0B Carport +0x0C Cellar +0x0D Cloakroom +0x0E Closet +0x0F Conservatory +0x10 Corridor +0x11 Craft Room +0x12 Cupboard +0x13 Deck +0x14 Den A small, comfortable room for +individual activities such as +work or hobbies +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 31 +``` + +``` +ID Name Summary +0x15 Dining +0x16 Drawing Room +0x17 Dressing Room +0x18 Driveway +0x19 Elevator +0x1A Ensuite A bathroom directly accessible +from a bedroom +0x1B Entrance +0x1C Entryway +0x1D Family Room +0x1E Foyer +0x1F Front Door +0x20 Front Yard +0x21 Game Room +0x22 Garage +0x23 Garage Door +0x24 Garden +0x25 Garden Door +0x26 Guest Bathroom Also known as Guest Restroom +0x27 Guest Bedroom +0x28 Guest Room +0x29 Gym +0x2A Hallway +0x2B Hearth Room A cozy room containing a fire­ +place or other point heat source +0x2C Kids Room +0x2D Kids Bedroom +0x2E Kitchen +0x2F Laundry Room +0x30 Lawn +0x31 Library +0x32 Living Room +0x33 Lounge +0x34 Media/TV Room +``` +Page 32 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**ID Name Summary** +0x35 Mud Room A space used to remove soiled +garments prior to entering the +domicile proper +0x36 Music Room +0x37 Nursery +0x38 Office +0x39 Outdoor Kitchen +0x3A Outside +0x3B Pantry AKA a larder, a place where +food is stored +0x3C Parking Lot +0x3D Parlor +0x3E Patio +0x3F Play Room +0x40 Pool Room +0x41 Porch +0x42 Primary Bathroom +0x43 Primary Bedroom +0x44 Ramp +0x45 Reception Room +0x46 Recreation Room +0x47 Roof +0x48 Sauna +0x49 Scullery A utility space for cleaning +dishes and laundry +0x4A Sewing Room +0x4B Shed +0x4C Side Door +0x4D Side Yard +0x4E Sitting Room +0x4F Snug An informal space meant to be +'cozy', 'snug', relaxed, meant to +share with family or friends +0x50 Spa +0x51 Staircase + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 33 +``` + +``` +ID Name Summary +0x52 Steam Room +0x53 Storage Room +0x54 Studio +0x55 Study +0x56 Sun Room +0x57 Swimming Pool +0x58 Terrace +0x59 Toilet A room dedicated to a toilet; a +water closet / WC +0x5A Utility Room +0x5B Ward +0x5C Workshop +``` +Page 34 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 14. Laundry Semantic Tag** + +**Namespace** + +This section contains the standard semantic tag namespace for laundry as part of the semantic tag +feature. + +The tags contained in this namespace are restricted for use in the laundry domain and SHALL NOT +be used in any other domain or context. + +``` +ID Namespace +0x0E Laundry +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Normal +0x01 Light Dry +0x02 Extra Dry +0x03 No Dry +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 35 +``` + +Page 36 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 15. Power Source Semantic Tag** + +**Namespace** + +This section contains the standard semantic tag namespace for power sources as part of the seman­ +tic tag feature. + +The tags contained in this namespace are restricted for use in the power source domain and SHALL +NOT be used in any other domain or context. + +``` +ID Namespace +0x0F Power Source +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Unknown The Power Source cluster is +related to power provided from +an unknown source +0x01 Grid The Power Source cluster is +related to power provided from +the electrical grid +0x02 Solar The Power Source cluster is +related to power provided from +a solar panel array +0x03 Battery The Power Source cluster is +related to power provided from +a battery +0x04 EV The Power Source cluster is +related to power provided from +an electric vehicle +``` +**15.1. Grid Tag** + +Power Source clusters with this tag SHALL implement the WIRED feature. + +**15.2. Solar Tag** + +Power Source clusters with this tag SHALL implement the WIRED feature. + +**15.3. Battery Tag** + +Power Source clusters with this tag SHALL implement the BAT feature. + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 37 +``` + +**15.4. EV Tag** + +Power Source clusters with this tag SHALL implement the BAT feature. + +``` +Page 38 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. +``` + +**Chapter 16. Refrigerator Semantic Tag** + +**Namespace** + +This section contains the standard semantic tag namespace for refrigerators as part of the semantic +tag feature. + +The tags contained in this namespace are restricted for use in the refrigerator domain and SHALL +NOT be used in any other domain or context. + +``` +ID Namespace +0x41 Refrigerator +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Refrigerator +0x01 Freezer +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 39 +``` + +Page 40 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 17. Room Air Conditioner Semantic** + +**Tag Namespace** + +This section contains the standard semantic tag namespace for room air conditioners as part of the +semantic tag feature. + +The tags contained in this namespace are restricted for use in the room air conditioner domain and +SHALL NOT be used in any other domain or context. + +``` +ID Namespace +0x42 Room Air Conditioner +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +0x00 Evaporator +0x01 Condenser +``` +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 41 +``` + +Page 42 Copyright © Connectivity Standards Alliance, Inc. All rights reserved. + + +**Chapter 18. Switches Semantic Tag** + +**Namespace** + +This section contains the standard semantic tag namespace for switches as part of the semantic tag +feature. + +The tags contained in this namespace are restricted for use in the switches domain and SHALL NOT +be used in any other domain or context. They are intended to indicate the function of a button on a +switch device to allow a client to make an optimized user interface which matches the actual device +without requiring a-priori knowledge of the layout of each specific switch device. + +Please see the rules for applying these and other tags for switch devices, e.g. from the Common +Position Namespace and the Common Number Namespace in the Generic Switch device type sec­ +tion in the Device Library. + +``` +ID Namespace +0x43 Switches +``` +The following tags are defined in this namespace. + +``` +ID Name Summary +tags to identify intended function of a button +0x00 On +0x01 Off +0x02 Toggle +0x03 Up e.g. dim up (light) +0x04 Down e.g. dim down (light) +0x05 Next e.g. select next scene +0x06 Previous e.g. select previous scene +0x07 Enter/OK/Select +0x08 Custom Textual description provided in +Label field +``` +**18.1. Custom Tag** + +When this value is used, the Label field in the same Semantic Tag structure SHALL be filled with a +textual description of the function indicated on the button, such as a label or icon printed on the +button, e.g. "dining". + +``` +Copyright © Connectivity Standards Alliance, Inc. All rights reserved. Page 43 +``` +