Chapter 11. Service and Device Management

    1. Basic Information Cluster

      1. Scope & Purpose

        This cluster provides attributes and events for determining basic information about Nodes, which supports both Commissioning and operational determination of Node characteristics, such as Vendor ID, Product ID and serial number, which apply to the whole Node.


      2. Revision History

        • The global ClusterRevision attribute value SHALL be the highest revision number in the table below.


          Rev isio n

          Description

          1

          Initial Release


      3. Classification


        Hierarchy

        Role

        Context

        PICS Code

        Base

        Utility

        Node

        BINFO


      4. Cluster Identifiers


        Ident ifier

        Name

        0x002

        8

        Basic Information


      5. Features

        This cluster has no Features.


      6. Server


              1. Data Types


              2. CapabilityMinimaStruct


                This structure provides constant values related to overall global capabilities of this Matter Node, that are not cluster-specific.

                ID

                Name

                Type

                Constraint

                Quality

                Default

                Conformanc e

                0

                CaseSession sPerFabric

                uint16

                min 3


                3

                M

                1

                Subscriptio nsPerFabric

                uint16

                min 3


                3

                M


                CaseSessionsPerFabric field


                This field SHALL indicate the actual minimum number of concurrent CASE sessions that are supported per fabric.

                This value SHALL NOT be smaller than the required minimum indicated in Section 4.13.2.8, “Minimal 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”.


              3. Attributes


                ID

                Name

                Type

                Constraint

                Quality

                Default

                Access

                Conforma nce

                0x0000

                DataMode lRevision

                uint16

                all

                F

                MS

                R V

                M

                0x0001

                VendorNa me

                string

                max 32

                F

                MS

                R V

                M

                0x0002

                VendorID

                vendor-id

                all

                F

                MS

                R V

                M

                0x0003

                ProductN ame

                string

                max 32

                F

                MS

                R V

                M

                0x0004

                ProductID

                uint16

                all

                F

                MS

                R V

                M

                0x0005

                NodeLabe l

                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 VersionSt ring

                string

                1 to 64

                F

                MS

                R V

                M

                ID

                Name

                Type

                Constraint

                Quality

                Default

                Access

                Conforma nce

                0x0009

                SoftwareV ersion

                uint32

                desc

                F

                0

                R V

                M

                0x000a

                SoftwareV ersionStri ng

                string

                1 to 64

                F

                MS

                R V

                M

                0x000b

                Manufact uringDate

                string

                8 to 16

                F

                MS

                R V

                O

                0x000c

                PartNumb er

                string

                max 32

                F

                MS

                R V

                O

                0x000d

                ProductU RL

                string

                max 256

                F

                MS

                R V

                O

                0x000e

                ProductLa bel

                string

                max 64

                F

                MS

                R V

                O

                0x000f

                SerialNu mber

                string

                max 32

                F

                MS

                R V

                O

                0x0010

                LocalConf igDisabled

                bool

                all

                N

                False

                RW VM

                O

                0x0011

                Reachable

                bool

                all


                True

                R V

                O

                0x0012

                UniqueID

                string

                max 32

                F

                MS

                R V

                O

                0x0013

                Capability Minima

                Capability MinimaStr uct

                all

                F

                MS

                R V

                M


                DataModelRevision Attribute


                The DataModelRevision attribute SHALL be set to the revision number of the Data Model against which the Node is certified.


                VendorName Attribute


                The VendorName attribute SHALL specify a human readable (displayable) name of the vendor for the Node.


                VendorID Attribute


                The VendorID attribute SHALL specify the Vendor ID.


                ProductName Attribute


                The ProductName 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.

                ProductID Attribute


                The ProductID attribute SHALL specify the Product ID assigned by the vendor that is unique to the specific product of the Node.


                NodeLabel Attribute


                The NodeLabel 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.


                Location Attribute


                The Location 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 configured, 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.


                HardwareVersion Attribute


                The HardwareVersion attribute SHALL specify the version number of the hardware of the Node. The meaning of its value, and the versioning scheme, are vendor defined.


                HardwareVersionString Attribute


                The HardwareVersionString 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.


                SoftwareVersion Attribute


                This field SHALL contain the current version number for the software running on this Node. 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.


                SoftwareVersionString Attribute


                This field 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 SoftwareVersionString 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".


                ManufacturingDate Attribute


                The ManufacturingDate 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.


                PartNumber Attribute


                The PartNumber 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 different packaging (with different PartNumbers) for different regions; also different colors of a product might share the ProductID but may have a different PartNumber.


                ProductURL Attribute


                The ProductURL attribute SHALL specify a link to a product specific web page. The syntax of the ProductURL attribute SHALL follow the syntax as specified in RFC 3986. The specified URL SHOULD resolve to a maintained web page available for the lifetime of the product. The maximum length of the ProductUrl attribute is 256 ASCII characters.


                ProductLabel Attribute


                The ProductLabel 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 vendor as defined within the VendorName attribute.


                SerialNumber Attribute


                The SerialNumber attributes SHALL specify a human readable (displayable) serial number.


                LocalConfigDisabled Attribute


                The LocalConfigDisabled 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.


                Reachable Attribute


                The Reachable attribute (when used) SHALL indicate whether the Node can be reached. For a native Matter 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 indicate whether the bridged device is reachable by the bridge over the non-Matter network.

                UniqueID Attribute


                This attribute (when used) SHALL indicate a unique identifier for the device, which is constructed in a manufacturer 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 SHOULD 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.

                  CapabilityMinima Attribute


                  This attribute SHALL provide the minimum guaranteed value for some system-wide resource capabilities 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 forever unchanging values and SHOULD NOT cache this value permanently at Commissioning time.


              4. Commands


                This cluster has no commands.


              5. Events


        Id

        Name

        Priority

        Access

        Conformance

        0x00

        StartUp

        CRITICAL

        V

        M

        0x01

        ShutDown

        CRITICAL

        V

        O

        0x02

        Leave

        INFO

        V

        O

        0x03

        ReachableChange d

        INFO

        V

        desc


        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

        Conformanc e

        0

        SoftwareVe rsion

        uint32




        M


        The SoftwareVersion field SHALL be set to the same value as the one available in the Software Version attribute of the Basic Information Cluster.


        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 completion of a future boot or reboot process.


        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 leaving Node.

        The data of this event SHALL contain the following information:


        Id

        Field

        Type

        Constraint

        Quality

        Default

        Conformanc e

        0

        FabricIndex

        fabric-idx

        1 to 254



        M


        The FabricIndex field SHALL contain the local Fabric Index of the fabric which the node is about to leave.


        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:

        Table 86. ReachableChangedEvent Struct

        Id

        Name

        Type

        Quality

        Constraint

        Conformance

        0

        ReachableNe wValue

        bool



        M


        The ReachableNewValue field SHALL indicate the value of the Reachable attribute after it was changed.


    2. Group Key Management Cluster

      1. Scope & Purpose

        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 modifications 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 scoped to an endpoint. Please see the System Model specification for more information on groups.


      2. Revision History

        • The global ClusterRevision attribute value SHALL be the highest revision number in the table below.


          Revision

          Description

          1

          Initial Release


      3. Classification


        Hierarchy

        Role

        Context

        PICS Code

        Base

        Utility

        Node

        GRPKEY


      4. Cluster Identifiers


        Identifier

        Name

        0x003F

        GroupKeyManagement


      5. Features

        This cluster SHALL support the FeatureMap global attribute:

        Bit

        Code

        Name

        Def

        Description

        0

        CS

        CacheAnd Sync

        0

        The ability to support CacheAndSync security policy and MCSP.


        The following sections describe each feature in some detail. Further details are found within the specification.


      6. Data Types


              1. GroupKeyMapStruct


                Access Quality: Fabric Scoped

                ID

                Name

                Type

                Constraint

                Quality

                Access

                Default

                Conforman ce

                1

                GroupId

                group-id

                all




                M

                2

                GroupKeyS etID

                uint16

                1 to 65535




                M


                GroupId


                This field uniquely identifies the group within the scope of the given Fabric.


                GroupKeySetID


                This field references the set of group keys that generate operational group keys for use with this group, as specified in Section 4.15.3.5.1, “Group Key Set ID”.

                A GroupKeyMapStruct SHALL NOT accept GroupKeySetID of 0, which is reserved for the IPK.


              2. GroupKeySetStruct


                ID

                Name

                Type

                Constraint

                Quality

                Access

                Default

                Conforma nce

                0

                GroupKeyS etID

                uint16

                all




                M

                1

                GroupKeyS ecurityPoli cy

                enum8

                all


                S


                M

                2

                EpochKey0

                octstr

                16

                X

                S


                M

                3

                EpochStart Time0

                epoch-us

                all

                X

                S


                M

                4

                EpochKey1

                octstr

                16

                X

                S


                M

                5

                EpochStart Time1

                epoch-us

                all

                X

                S


                M

                ID

                Name

                Type

                Constraint

                Quality

                Access

                Default

                Conforma nce

                6

                EpochKey2

                octstr

                16

                X

                S


                M

                7

                EpochStart Time2

                epoch-us

                all

                X

                S


                M

                8

                GroupKey MulticastP olicy

                enum8

                all


                S


                M


                GroupKeySetID


                This field SHALL provide the fabric-unique index for the associated group key set, as specified in Section 4.15.3.5.1, “Group Key Set ID”.


                GroupKeySecurityPolicy


                This field SHALL provide the security policy for an operational group key set.


                Table 87. Values of the GroupKeySecurityPolicy Attribute


                Value

                Name

                Conformance

                Description

                0

                TrustFirst

                M

                Message counter synchronization using trust-first

                1

                CacheAndSync

                CS

                Message counter synchronization using cache-and-sync


                When CacheAndSync is not supported in the FeatureMap of this cluster, any action attempting to write CacheAndSync to GroupKeySecurityPolicy SHALL fail with an INVALID_COMMAND error.


                EpochKey0


                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.


                EpochStartTime0


                This field, if not null, SHALL define when EpochKey0 becomes valid as specified by Section 4.15.3, “Epoch Keys”. Units are absolute UTC time in microseconds encoded using the epoch-us representation.


                EpochKey1


                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


                This field, if not null, SHALL define when EpochKey1 becomes valid as specified by Section 4.15.3, “Epoch Keys”. Units are absolute UTC time in microseconds encoded using the epoch-us representation.


                EpochKey2


                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


                This field, if not null, SHALL define when EpochKey2 becomes valid as specified by Section 4.15.3, “Epoch Keys”. Units are absolute UTC time in microseconds encoded using the epoch-us representation.


                GroupKeyMulticastPolicy


                This field specifies how the IPv6 Multicast Address SHALL be formed for groups using this operational 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.

                Table 88. Values of the GroupKeyMulticastPolicy Attribute


                Value

                Name

                Conformance

                Description

                0

                PerGroupID

                M

                The 16-bit Group Identifier of the Multicast Address SHALL be the Group ID of the group.

                1

                AllNodes

                M

                The 16-bit Group Identifier of the Multicast Address SHALL be 0xFFFF.


              3. GroupInfoMapStruct


        Access Quality: Fabric Scoped

        ID

        Name

        Type

        Constraint

        Quality

        Access

        Default

        Conforman ce

        1

        GroupId

        group-id

        all


        R


        M

        2

        Endpoints

        list[endpoi nt-no]

        min 1


        R


        M

        Access Quality: Fabric Scoped

        3

        GroupNam e

        string

        max 16


        R


        O


        GroupId


        This field uniquely identifies the group within the scope of the given Fabric.


        Endpoints


        This field provides the list of Endpoint IDs on the Node to which messages to this group SHALL be forwarded.


        GroupName


        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.


      7. Server


              1. Attributes


                ID

                Name

                Type

                Constraint

                Quality

                Access

                Default

                Conforma nce

                0x0000

                GroupKey Map

                list[Group KeyMapStr uct]

                desc

                N

                RW F VM

                empty

                M

                0x0001

                GroupTabl e

                list[GroupI nfoMapStr uct]

                desc


                R F

                empty

                M

                0x0002

                MaxGroup sPerFabric

                uint16

                all

                F

                R

                0

                M

                0x0003

                MaxGroup KeysPerFa bric

                uint16

                1 to 65535

                F

                R

                1

                M


              2. GroupKeyMap Attribute


                This attribute is a list of GroupKeyMapStruct entries. Each entry associates a logical Group Id with a particular group key set.


              3. 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. 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.


        MaxGroupsPerFabric


        This attribute SHALL indicate the maximum number of groups that this node supports per fabric. 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.


        MaxGroupKeysPerFabric


        This attribute SHALL indicate the maximum number of group key sets this node supports per fabric. This attribute SHALL be greater than 0 to reserve a slot for the IPK.


      8. Client

        The client cluster has no dependencies nor cluster specific attributes.


      9. Commands

        All commands in this cluster SHALL be scoped to the accessing fabric.


        Id

        Name

        Direction

        Response

        Access

        Conformance

        0x00

        KeySetWrite

        Client ⇒ Server

        Y

        F A

        M

        0x01

        KeySetRead

        Client ⇒ Server

        KeySetReadRe sponse

        F A

        M

        0x02

        KeySetReadResponse

        Server ⇒ Client

        N


        M

        0x03

        KeySetRemove

        Client ⇒ Server

        Y

        F A

        M

        0x04

        KeySetReadAllIndices

        Client ⇒ Server

        KeySetReadAll IndicesRespon se

        F A

        M

        0x05

        KeySetReadAllIndicesRespo nse

        Server ⇒ Client

        N


        M


              1. KeySetWrite Command


                This command is used by Administrators to set the state of a given Group Key Set, including atomically updating the state of all epoch keys.


                Id

                Field

                Type

                Constraint

                Conformance

                0

                GroupKeySet

                GroupKeySetStruc t


                M

                Effect on Receipt


                If the EpochKey0 field is null or its associated EpochStartTime0 field is null, then this command SHALL fail with an INVALID_COMMAND status code sent back to the initiator.

                If the EpochKey1 field is not null, its associated EpochStartTime1 field 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 sent back to the initiator.

                If the EpochKey2 field is not null, then the EpochKey1 field SHALL NOT be null. Otherwise this command SHALL fail with an INVALID_COMMAND status code sent back to the initiator.

                If the EpochKey2 field is not null, its associated EpochStartTime2 field 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 sent back to the initiator.


                If there exists a Group Key Set associated with the accessing fabric which has the same GroupKeySetID as that provided in the GroupKeySet field, then the contents of that group key set SHALL be replaced. A replacement SHALL be done by executing the equivalent of entirely removing the previous 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 status code SHALL be set to RESOURCE_EXHAUSTED (see group key limits);

                • Otherwise, this status code SHALL be set to FAILURE.


              2. KeySetRead Command


                This command is used by Administrators to read the state of a given Group Key Set.


                Id

                Field

                Type

                Constraint

                Conformance

                0

                GroupKeySetID

                uint16

                all

                M


                Effect on Receipt


                If there exists a Group Key Set associated with the accessing fabric which has the same GroupKeySetID 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.

              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

                Field

                Type

                Constraint

                Conformance

                0

                GroupKeySet

                GroupKeySetStruc t


                M


              4. KeySetRemove Command


                This command is used by Administrators to remove all state of a given Group Key Set.


                Id

                Field

                Type

                Constraint

                Conformance

                0

                GroupKeySetID

                uint16

                all

                M


                Effect on Receipt


                If there exists a Group Key Set associated with the accessing fabric which has the same GroupKeySetID 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.


              5. KeySetReadAllIndices Command


                This command is used by Administrators to query a list of all Group Key Sets associated with the accessing fabric.

                This command has no payload.


                Effect on Receipt


                Upon receipt, this command SHALL iterate all stored GroupKeySetStruct associated with the accessing fabric and generate a KeySetReadAllIndicesResponse command containing the list of GroupKeySetID values from those structs.


              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

        Field

        Type

        Constraint

        Conformance

        0

        GroupKeySetIDs

        list[uint16]


        M


        GroupKeySetIDs


        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.


    3. Localization Configuration Cluster

      1. Scope & Purpose

        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 standards. 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.


              1. Revision History


                The global ClusterRevision attribute value SHALL be the highest revision number in the table below.


                Revision

                Description

                1

                Initial Release


              2. Classification


                Hierarchy

                Role

                Scope

                PICS Code

                Base

                Utility

                Node

                LCFG


              3. Cluster Identifiers


                Identifier

                Name

                0x002B

                LocalizationConfiguration


                Attributes

                Id

                Name

                Type

                Constraint

                Quality

                Default

                Access

                Conforma nce

                0x0000

                ActiveLoca le

                string

                max 35

                N

                MS

                RW VM

                M

                0x0001

                Supported Locales

                list[string]

                max 32[max 35]

                F

                MS

                R V

                M


              4. 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 list.

        An attempt to write a value to ActiveLocale that is not present in SupportedLocales SHALL result in a CONSTRAINT_ERROR error.


        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.


    4. Time Format Localization Cluster

      1. Scope & Purpose

        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.


              1. Revision History


                The global ClusterRevision attribute value SHALL be the highest revision number in the table below.


                Revision

                Description

                1

                Initial Release


              2. Classification


                Hierarchy

                Role

                Scope

                PICS Code

                Base

                Utility

                Node

                LTIME

              3. Cluster Identifiers


        Identifier

        Name

        0x002c

        TimeFormatLocalization


      2. Features


        Bit

        Code

        Feature

        Description

        0

        CALFMT

        CalendarFormat

        The Node can be configured to use different calendar formats when conveying values to a user.


      3. Data Types


              1. HourFormat


                HourFormat Data Type is derived from enum8


                Value

                Name

                Description

                Conformance

                0

                12hr

                Time SHALL be conveyed with a 12- hour clock

                M

                1

                24hr

                Time SHALL be conveyed with a 24- hour clock

                M


              2. CalendarType


        CalendarType Data Type is derived from enum8


        Value

        Name

        Description

        Conformance

        0

        Buddhist

        Dates SHALL be conveyed using the Buddhist calendar

        M

        1

        Chinese

        Dates SHALL be conveyed using the Chinese calendar

        M

        2

        Coptic

        Dates SHALL be conveyed using the Coptic calendar

        M

        Value

        Name

        Description

        Conformance

        3

        Ethiopian

        Dates SHALL be conveyed using the Ethiopian calendar

        M

        4

        Gregorian

        Dates SHALL be conveyed using the Gregorian calendar

        M

        5

        Hebrew

        Dates SHALL be conveyed using the Hebrew calendar

        M

        6

        Indian

        Dates SHALL be conveyed using the Indian calendar

        M

        7

        Islamic

        Dates SHALL be conveyed using the Islamic calendar

        M

        8

        Japanese

        Dates SHALL be conveyed using the Japanese calendar

        M

        9

        Korean

        Dates SHALL be conveyed using the Korean calendar

        M

        10

        Persian

        Dates SHALL be conveyed using the Persian calendar

        M

        11

        Taiwanese

        Dates SHALL be conveyed using the Taiwanese calendar

        M


      4. Attributes


        ID

        Name

        Type

        Constraint

        Quality

        Default

        Access

        Conforma nce

        0x0000

        HourForm at

        HourForm at

        all

        XN

        null

        RW VM

        M

        0x0001

        ActiveCale ndarType

        CalendarT ype

        all

        XN

        null

        RW VM

        CALFMT

        0x0002

        Supported CalendarT ypes

        list[Calend arType]

        desc

        F

        N/A

        R V

        CALFMT

              1. HourFormat Attribute


                The HourFormat attribute SHALL represent the format that the Node is currently configured to use when conveying the hour unit of time. If provided, this value SHALL take priority over any unit implied through the ActiveLocale Attribute.


              2. ActiveCalendarType Attribute


                The ActiveCalendarType attribute SHALL represent the calendar format that the Node is currently configured to use when conveying dates. If provided, this value SHALL take priority over any unit implied through the ActiveLocale Attribute.


              3. SupportedCalendarTypes Attribute


        The SupportedCalendarTypes attribute SHALL represent a list of CalendarType 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 the CalendarType enum.


    5. Unit Localization Cluster

      1. Scope & Purpose

        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 mechanism 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.


              1. Revision History


                The global ClusterRevision attribute value SHALL be the highest revision number in the table below.


                Revision

                Description

                1

                Initial Release


              2. Classification


                Hierarchy

                Role

                Scope

                PICS Code

                Base

                Utility

                Node

                LUNIT


              3. Cluster Identifiers

        Identifier

        Name

        0x002D

        UnitLocalization


      2. Features


        Bit

        Code

        Feature

        Description

        0

        TEMP

        TemperatureUnit

        The Node can be configured to use different units of temperature when conveying values to a user.


      3. Data Types


        11.5.3.1. TempUnit


        TempUnit Data Type is derived from enum8


        Value

        Name

        Description

        Conformance

        0

        Fahrenheit

        Temperature conveyed in Fahrenheit

        M

        1

        Celsius

        Temperature conveyed in Celsius

        M

        2

        Kelvin

        Temperature conveyed in Kelvin

        M


      4. Attributes


        Id

        Name

        Type

        Constraint

        Quality

        Default

        Access

        Conforma nce

        0x0000

        Temperat ureUnit

        TempUnit

        all

        XN

        null

        RW VM

        TEMP


        11.5.4.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.


    6. Power Source Configuration Cluster

      This cluster is used to describe the configuration and capabilities of a Device’s power system. It provides an ordering overview as well as linking to the one or more endpoints each supporting a Power Source cluster.

      1. Revision History

        The global ClusterRevision attribute value SHALL be the highest revision number in the table below.


        Rev isio n

        Description

        1

        Initial Release


      2. Classification


        Hierarchy

        Role

        Context

        PICS Code

        Base

        Utility

        Endpoint

        PSCFG


      3. Cluster Identifiers


        Ident ifier

        Name

        0x002 E

        Power Source Configuration


      4. Features

        The Power Source Configuration Cluster has no features.


      5. Server


              1. Attributes


                Id

                Name

                Type

                Constrai nt

                Quality

                Default

                Access

                Conform ance

                Volatility

                0x0000

                Sources

                list[endp oint-no]

                max 6

                R

                N/A

                V

                M

                N


                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.

              2. Events

        The Power Source Configuration Cluster has no Server specific events.


      6. Client


              1. Attributes


                The 'Power Source Configuration' cluster has no Client specific attributes.


              2. Events

        The Power Source Configuration Cluster has no Client specific events.


      7. Commands

        The Power Source Configuration Cluster has no commands.


    7. Power Source Cluster

      This cluster is used to describe the configuration and capabilities of a physical power source that provides power to the Node. In case the Node has multiple power sources, each is described by its own Power Source cluster. The Power Source Configuration cluster referenced by the Root Node device type for the Node provides the overview of the power source(s) of the Node.


      1. Revision History

        The global ClusterRevision attribute value SHALL be the highest revision number in the table below.


        Rev isio n

        Description

        1

        Initial Release


      2. Classification


        Hierarchy

        Role

        Context

        PICS Code

        Base

        Utility

        Node

        PS


      3. Cluster Identifiers


        Ident ifier

        Name

        0x002 F

        Power Source

      4. Features


        Bit

        Code

        Feature

        Description

        0

        WIRED

        Wired

        A wired power source

        1

        BAT

        Battery

        A battery power source

        2

        RECHG

        Rechargeable

        A rechargeable battery power source (requires Battery feature)

        3

        REPLC

        Replaceable

        A replaceable battery power source (requires Battery feature)


      5. Data Types


              1. WiredFault


                WiredFault Data Type is derived from enum8


                Table 89. WiredFault ENUM


                Value

                Name

                Conformance

                Description

                0

                Unspecified

                M

                The Node detects an unspecified fault on this wired power source.

                1

                OverVoltage

                M

                The Node detects the supplied voltage is above maximum supported value for this wired power source.

                2

                UnderVoltage

                M

                The Node detects the supplied voltage is below maximum supported value for this wired power source.


              2. BatFault


                BatFault Data Type is derived from enum8


                Table 90. BatFault ENUM

                Value

                Name

                Conformance

                Description

                0

                Unspecified

                M

                The Node detects an unspecified fault on this battery power source.

                1

                OverTemp

                M

                The Node detects the temperature of this battery power source is above ideal operating conditions.

                2

                UnderTemp

                M

                The Node detects the temperature of this battery power source is below ideal operating conditions.


              3. BatChargeFault


        BatChargeFault Data Type is derived from enum8


        Table 91. BatChargeFault ENUM


        Value

        Name

        Conformance

        Description

        0

        Unspecified

        M

        The Node detects an unspecified fault on this battery source.

        1

        AmbientTooHot

        M

        The Node detects the ambient temperature is above the nominal range for this battery source.

        2

        AmbientTooCold

        M

        The Node detects the ambient temperature is below the nominal range for this battery source.

        3

        BatteryTooHot

        M

        The Node detects the temperature of this battery source is above the nominal range.

        4

        BatteryTooCold

        M

        The Node detects the temperature of this battery source is below the nominal range.

        Value

        Name

        Conformance

        Description

        5

        BatteryAbsent

        M

        The Node detects this battery source is not present.

        6

        BatteryOverVoltage

        M

        The Node detects this battery source is over voltage.

        7

        BatteryUnderVoltage

        M

        The Node detects this battery source is under voltage.

        8

        ChargerOverVoltage

        M

        The Node detects the charger for this battery source is over voltage.

        9

        ChargerUnderVoltage

        M

        The Node detects the charger for this battery source is under voltage.

        10

        SafetyTimeout

        M

        The Node detects a charging safety timeout for this battery source.


      6. Server


              1. Attributes


                Id

                Name

                Type

                Constrai nt

                Quality

                Default

                Access

                Conform ance

                Volatility

                0x0000

                Status

                PowerSo urceStatu s

                desc

                R

                N/A

                V

                M

                V

                0x0001

                Order

                uint8

                all

                R

                N/A

                V

                M

                N

                0x0002

                Descripti on

                string

                max 60

                R

                N/A

                V

                M

                N

                0x0003

                WiredAs sessedIn putVolta ge

                uint32

                all

                RX

                N/A

                V

                [WIRED]

                V

                0x0004

                WiredAs sessedIn putFrequ ency

                uint16

                all

                RX

                N/A

                V

                [WIRED]

                V

                Id

                Name

                Type

                Constrai nt

                Quality

                Default

                Access

                Conform ance

                Volatility

                0x0005

                WiredCu rrentTyp e

                WiredCur rentType

                desc

                R

                N/A

                V

                WIRED

                N

                0x0006

                WiredAs sessedCu rrent

                uint32

                all

                RX

                N/A

                V

                [WIRED]

                V

                0x0007

                WiredNo minalVol tage

                uint32

                all

                R

                N/A

                V

                [WIRED]

                N

                0x0008

                WiredMa ximumC urrent

                uint32

                all

                R

                N/A

                V

                [WIRED]

                N

                0x0009

                WiredPr esent

                bool

                all

                R

                N/A

                V

                [WIRED]

                V

                0x000a

                ActiveWi redFault s

                list[Wire dFault]

                8 entries

                R

                N/A

                V

                [WIRED]

                V

                0x000b

                BatVolta ge

                uint32

                all

                RX

                N/A

                V

                [BAT]

                V

                0x000c

                BatPerce ntRemai ning

                uint8

                0 to 200

                RX

                N/A

                V

                [BAT]

                V

                0x000d

                BatTime Remaini ng

                uint32

                all

                RX

                N/A

                V

                [BAT]

                V

                0x000e

                BatCharg eLevel

                BatCharg eLevel

                desc

                R

                N/A

                V

                BAT

                V

                0x000f

                BatRepla cementN eeded

                bool

                all

                R

                N/A

                V

                BAT

                V

                0x0010

                BatRepla ceability

                BatReplac eability

                all

                R

                N/A

                V

                BAT

                N

                0x0011

                BatPrese nt

                bool

                all

                R

                N/A

                V

                [BAT]

                V

                0x0012

                ActiveBa tFaults

                list[BatFa ult]

                8 entries

                R

                N/A

                V

                [BAT]

                V

                Id

                Name

                Type

                Constrai nt

                Quality

                Default

                Access

                Conform ance

                Volatility

                0x0013

                BatRepla cementD escriptio n

                string

                max 60

                R

                N/A

                V

                REPLC

                N

                0x0014

                BatCom monDesi gnation

                uint32

                desc

                R

                N/A

                V

                [REPLC]

                N

                0x0015

                BatANSI

                Designat ion

                string

                max 20

                R

                N/A

                V

                [REPLC]

                N

                0x0016

                BatIECDe signation

                string

                max 20

                R

                N/A

                V

                [REPLC]

                N

                0x0017

                BatAppr ovedChe mistry

                uint32

                desc

                R

                N/A

                V

                [REPLC]

                N

                0x0018

                BatCapac ity

                uint32

                all

                R

                N/A

                V

                [REPLC]

                N

                0x0019

                BatQuan tity

                uint8

                all

                R

                N/A

                V

                REPLC

                N

                0x001a

                BatCharg eState

                BatCharg eState

                desc

                R

                N/A

                V

                RECHG

                V

                0x001b

                BatTime ToFullCh arge

                uint32

                all

                RX

                N/A

                V

                [RECHG]

                V

                0x001c

                BatFunct ionalWhi leChargi ng

                bool

                all

                R

                N/A

                V

                RECHG

                V

                0x001d

                BatCharg ingCurre nt

                uint32

                all

                RX

                N/A

                V

                [RECHG]

                V

                0x001e

                ActiveBa tChargeF aults

                list[BatCh argeFault

                ]

                16 entries

                R

                N/A

                V

                [RECHG]

                V


                Status


                This field SHALL indicate the participation of this power source in providing power to the Node.


                Table 92. PowerSourceStatus ENUM

                Value

                Name

                Conformance

                Description

                0

                Unspecified

                M

                SHALL indicate the source status is not specified

                1

                Active

                M

                SHALL indicate the source is available and currently supplying power

                2

                Standby

                M

                SHALL indicate the source is available, but is not currently supplying power

                3

                Unavailable

                M

                SHALL indicate the source is not currently available to supply power


                Order


                This field 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 Section 11.7.6.1.1, “Status”).

                Note, Order is read-only and therefore NOT intended to allow clients control over power source selection.


                Description


                This field 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.


                WiredAssessedInputVoltage


                This field 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. A Node interested in the value of the WiredAssessedInputVoltage attribute SHOULD NOT subscribe to value changes but SHOULD perform a single read of the value.


                WiredAssessedInputFrequency


                This field 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. A Node interested in the value of the WiredAssessedInputFrequency attribute SHOULD NOT subscribe to value changes but SHOULD

                perform a single read of the value.


                WiredCurrentType


                This field SHALL indicate the type of current the Node expects to be provided by the hard-wired source.

                Table 93. WiredCurrentType ENUM


                Value

                Name

                Conformance

                Description

                0

                AC

                M

                SHALL indicate AC current

                1

                DC

                M

                SHALL indicate DC current


                WiredAssessedCurrent


                This field 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. A Node interested in the value of the WiredAssessedCurrent attribute SHOULD NOT subscribe to value changes but SHOULD perform a single read of the value.


                WiredNominalVoltage


                This field SHALL indicate the nominal voltage, printed as part of the Node’s regulatory compliance label in mV (millivolts), expected to be provided by the hard-wired source.


                WiredMaximumCurrent


                This field SHALL indicate the maximum current, printed as part of the Node’s regulatory compliance label in mA (milliamps), expected to be provided by the hard-wired source.


                WiredPresent


                This field SHALL indicate if the Node detects that the hard-wired power source is properly connected.


                ActiveWiredFaults


                This field SHALL indicate the set of wired faults currently detected by the Node on this power source. This set is represented as a list of WiredFault. When the Node detects a fault has been raised, the appropriate WiredFault 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 WiredFault value. When the Node detects all conditions contributing to a fault have been cleared, the corresponding WiredFault 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 WiredFaultChange.

                BatVoltage


                This field SHALL indicate the currently measured output voltage of the battery in mV (millivolts). A value of NULL SHALL indicate the Node is currently unable to assess the value. A Node interested in the value of the BatVoltage attribute SHOULD NOT subscribe to value changes but SHOULD perform a single read of the value.


                BatPercentRemaining


                This field SHALL indicate the estimated percentage of battery charge remaining until the battery 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. A Node interested in the value of the BatPercentRemaining attribute SHOULD NOT subscribe to value changes but SHOULD perform a single read of the value.


                BatTimeRemaining


                This field 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. A Node interested in the value of the BatTimeRemaining attribute SHOULD NOT subscribe to value changes but SHOULD perform a single read of the value.


                BatChargeLevel


                This field SHALL indicate a coarse ranking of the charge level of the battery, used to indicate when intervention is required.

                Table 94. BatChargeLevel ENUM


                Value

                Name

                Conformance

                Description

                0

                OK

                M

                Charge level is nominal

                1

                Warning

                M

                Charge level is low, intervention may soon be required.

                2

                Critical

                M

                Charge level is critical, immediate intervention is required


                BatReplacementNeeded


                This field SHALL indicate if the battery needs to be replaced. Replacement MAY be simple routine 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.


                BatReplaceability


                This field SHALL indicate the replaceability of the battery.

                Table 95. BatReplaceability ENUM


                Value

                Name

                Conformance

                Description

                0

                Unspecified

                M

                The replaceability is unspecified or unknown.

                1

                NotReplaceable

                M

                The battery is not replaceable.

                2

                UserReplaceable

                M

                The battery is replaceable by the user or customer.

                3

                FactoryReplaceable

                M

                The battery is replaceable by an authorized factory technician.


                BatPresent


                This field SHALL indicate whether the Node detects that the batteries are properly installed.


                ActiveBatFaults


                This field SHALL indicate the set of battery faults currently detected by the Node on this power source. This set is represented as a list of BatFault. When the Node detects a fault has been raised, the appropriate BatFault 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 BatFault value. When the Node detects all conditions contributing to a fault have been cleared, the corresponding BatFault 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 Section 11.7.6.2.2, “BatFaultChange Event”.


                BatReplacementDescription


                This field 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 manufacturer.


                BatCommonDesignation


                This field SHALL indicate the ID of the common or colloquial designation of the battery, as specified in https://github.com/CHIP-Specifications/connectedhomeip-spec-external/blob/master/src/csa/ CommonBatteryDesignation.


                image

                WARNING TODO: Note, this reference is still in development. Once finalized it will be replaced with a reference to the published document.

                BatANSIDesignation


                This field SHALL indicate the string representing the ANSI designation for the battery as specified in ANSI C18.


                BatIECType


                This field SHALL indicate the string representing the IEC designation for the battery as specified in IEC 60086.


                BatApprovedChemistry


                This field SHALL indicate the ID of the preferred chemistry of the battery source as specified in https://github.com/CHIP-Specifications/connectedhomeip-spec-external/blob/master/src/csa/ ApprovedBatteryChemistry.


                image

                WARNING TODO: Note, this reference is still in development. Once finalized it will be replaced with a reference to the published document.


                BatCapacity


                This field SHALL indicate the preferred minimum charge capacity rating in mAh of individual, user- or factory-serviceable battery cells or packs in the battery source.


                BatQuantity


                This field SHALL indicate the quantity of individual, user- or factory-serviceable battery cells or packs in the battery source.


                BatChargeState


                This field SHALL indicate the current state of the battery source with respect to charging.


                Table 96. BatChargeState ENUM


                Value

                Name

                Conformance

                Description

                0

                Unknown

                M

                Unable to determine the charging state

                1

                IsCharging

                M

                The battery is charging

                2

                IsAtFullCharge

                M

                The battery is at full charge

                3

                IsNotCharging

                M

                The battery is not charging


                BatTimeToFullCharge


                This field 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. A Node interested in the value of the BatTimeToFullCharge attribute SHOULD NOT subscribe to value changes but SHOULD perform a single read of the value.

                BatFunctionalWhileCharging


                This field SHALL indicate whether the Node can remain operational while the battery source is charging.


                BatChargingCurrent


                This field 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. A Node interested in the value of the BatChargingCurrent attribute SHOULD NOT subscribe to value changes but SHOULD perform a single read of the value.


                ActiveBatChargeFaults


                This field SHALL indicate the set of charge faults currently detected by the Node on this power source. This set is represented as a list of BatChargeFault. When the Node detects a fault has been raised, the appropriate BatChargeFault 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 BatChargeFault value. When the Node detects all conditions contributing to a fault have been cleared, the corresponding BatChargeFault 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 Section 11.7.6.2.3, “BatChargeFaultChange Event”.


              2. Events


        Id

        Name

        Type

        Constraint

        Access

        Conformance

        0

        WiredFaultCh ange

        WiredFaultCha ngeType

        all

        V

        [WIRED]

        1

        BatFaultChan ge

        BatFaultChang eType

        all

        V

        [BAT]

        2

        BatChargeFau ltChange

        BatChargeFaul tChangeType

        all

        V

        [RECHG]


        WiredFaultChange Event


        The WiredFaultChange Event SHALL indicate a change in the set of wired faults currently detected by the Node on this wired power source. This event SHALL correspond to a change in value of Section 11.7.6.1.11, “ActiveWiredFaults”. The change is represented as follows.

        Table 97. WiredFaultChangeType Struct


        Id

        Name

        Type

        Constraint

        Conformance

        0

        Current

        list[WiredFault]

        8 entries

        M

        1

        Previous

        list[WiredFault]

        8 entries

        M


        The Current field SHALL represent the set of faults currently detected, as per Section 11.7.6.1.11, “ActiveWiredFaults”.

        The Previous field SHALL represent the set of faults detected prior to this change event, as per Section 11.7.6.1.11, “ActiveWiredFaults”.


        BatFaultChange Event


        The BatFaultChange Event SHALL indicate a change in the set of battery faults currently detected by the Node on this battery power source. This event SHALL correspond to a change in value of Section 11.7.6.1.19, “ActiveBatFaults”. The change is represented as follows.

        Table 98. BatFaultChangeType Struct


        Id

        Name

        Type

        Constraint

        Conformance

        0

        Current

        list[BatFault]

        8 entries

        M

        1

        Previous

        list[BatFault]

        8 entries

        M


        The Current field SHALL represent the set of faults currently detected, as per Section 11.7.6.1.19, “ActiveBatFaults”.

        The Previous field SHALL represent the set of faults detected prior to this change event, as per Section 11.7.6.1.19, “ActiveBatFaults”.


        BatChargeFaultChange Event


        The BatChargeFaultChange Event SHALL indicate a change in the set of charge faults currently detected by the Node on this battery power source. This event SHALL correspond to a change in value of Section 11.7.6.1.31, “ActiveBatChargeFaults”. The change is represented as follows.

        Table 99. BatChargeFaultChangeType Struct


        Id

        Name

        Type

        Constraint

        Conformance

        0

        Current

        list[BatChargeFaul t]

        16 entries

        M

        1

        Previous

        list[BatChargeFaul t]

        16 entries

        M


        The Current field SHALL represent the set of faults currently detected, as per Section 11.7.6.1.31, “ActiveBatChargeFaults”.

        The Previous field SHALL represent the set of faults detected prior to this change event, as per Section 11.7.6.1.31, “ActiveBatChargeFaults”.


      7. Client


              1. Attributes

                The Power Source Cluster has no Client specific attributes.


              2. Events

        The Power Source Cluster has no Client specific events.

      8. Commands

        The Power Source Cluster has no commands.


      9. Configuration Examples

        The following examples illustrate use of the Order attribute in the Power Source Cluster and its correspondence to the Sources list attribute of the Power Source Configuration Cluster, which together describe the relationship between sources in a Node’s power system.


              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. Both must be on a non-zero endpoint. The system indicates no preference for either source, so the sources have the same Order.

                image

                Description: "Mains A" Order: 0

                Power Source (on Endpoint 2)


                image

                Description: "Mains B" Order: 0

                Power Source (on Endpoint 5)


                Both of these sources must be listed in the Power Source Configuration Cluster, with the sources listed in any order.

                image

                Sources: [5,2]

                Power Source Configuration (on Endpoint 0)


              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.

                image

                Description: "Primary Battery" Order: 0

                Power Source (on Endpoint 2)

                image

                Description: "Mains" Order: 1

                Power Source (on Endpoint 5)


                Both of these sources must be listed in the Power Source Configuration Cluster, with the source on Endpoint 2 listed first since it has the lowest Order.

                image

                Sources: [2,5]

                Power Source Configuration (on Endpoint 0)


              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 powers the system. The Node must define two Power Source Clusters, one for the mains and another for the battery. Since the mains source is primary, it must have a lower Order than the battery source.

                image

                Description: "Mains" Order: 0

                Power Source (on Endpoint 2)


                image

                Description: "Battery Back-up" Order: 1

                Power Source (on Endpoint 5)


                Both of these sources must be listed in the Power Source Configuration Cluster, with the source on Endpoint 2 listed first since it has the lowest Order.

                image

                Sources: [2,5]

                Power Source Configuration (on Endpoint 0)


              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.

                image

                Description: "Primary Battery" Order: 0

                Power Source (on Endpoint 2)


                image

                Description: "DC Adapter" Order: 1

                Power Source (on Endpoint 5)


                image

                Description: "USB Power" Order: 1

                Power Source (on Endpoint 7)


                Each of these sources must be listed in the Power Source Configuration Cluster, with the source on Endpoint 2 listed first since it has the lowest Order.

                image

                Sources: [2,7,5]

                Power Source Configuration (on Endpoint 0)


              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.

        image

        Description: "Mains Power" Order: 0

        Power Source (on Endpoint 2)


        image

        Description: "Peripheral Battery" Order: 0

        Power Source (on Endpoint 7)


        Each of these sources must be listed in the Power Source Configuration Cluster.


        image

        Sources: [7,2]

        Power Source Configuration (on Endpoint 0)

    8. Network Commissioning Cluster

      1. Scope & Purpose

        Network commissioning is part of the overall Node commissioning. The main goal of Network Commissioning 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.


      2. Revision History

        • The global ClusterRevision attribute value SHALL be the highest revision number in the table below.


          Rev isio n

          Description

          1

          Initial Release


      3. Classification


        Hierarchy

        Role

        Context

        PICS Code

        Base

        Utility

        Node

        CNET


      4. Cluster Identifiers


        Ident ifier

        Name

        0x003

        1

        Network Commissioning


      5. Features


        Bit

        Code

        Feature

        Description

        0

        WI

        Wi-Fi network interface

        Wi-Fi related features

        Bit

        Code

        Feature

        Description

        1

        TH

        Thread network interface

        Thread related features

        2

        ET

        Ethernet network interface

        Ethernet related features


        There SHALL be exactly one of the features bits in the set (WI, TH, ET) present in the FeatureMap attribute, to describe the type of network technology supported by a given instance of this cluster.


      6. Data Types


              1. WiFiSecurity Bitmap

                The WiFiSecurity type is derived from the map8 data type.


                The WiFiSecurity bitmap encodes the supported Wi-Fi security types present in the Security field of the WiFiInterfaceScanResult.


                Bit

                Description

                0

                Unencrypted

                1

                WEP

                2

                WPA-PERSONAL

                3

                WPA2-PERSONAL

                4

                WPA3-PERSONAL


              2. WiFiBand Enum

                The WiFiBand type is derived from the enum8 data type.


                The WiFiBand enum encodes a supported Wi-Fi frequency band present in the WiFiBand field of the

                WiFiInterfaceScanResult.


                Value

                Description

                0

                2.4GHz - 2.401GHz to 2.495GHz (802.11b/g/n/ax)

                1

                3.65GHz - 3.655GHz to 3.695GHz (802.11y)

                2

                5GHz - 5.150GHz to 5.895GHz (802.11a/n/ac/ax)

                3

                6GHz - 5.925GHz to 7.125GHz (802.11ax / WiFi

                6E)

                4

                60GHz - 57.24GHz to 70.20GHz (802.11ad/ay)


              3. NetworkInfo structure

                The NetworkInfo struct describes an existing network configuration, as provided in the Networks

                attribute.

                ID

                Name

                Type

                Constraint

                Quality

                Access

                Conformanc e

                0

                NetworkID

                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 contains SSID for Wi-Fi networks, Extended PAN ID (XPAN ID) for Thread networks and netif name for Ethernet networks.



                  image

                  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 requiring a particular encoding for transfer. Only the commissioner should try to potentially 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 commissioner MAY decode using UTF-8, replacing encoding errors with "?" at the application 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).


              4. Scan result structures


                These are the structures returned by Section 11.8.8.2, “ScanNetworks Command” for the network interface types allowing scanning of available infrastructure (e.g. Wi-Fi and Thread). Interface types where scanning does not apply (e.g. Ethernet) do not have a corresponding scan results structure.


                WiFiInterfaceScanResult structure


                The WiFiInterfaceScanResult struct represents a single Wi-Fi network scan result.

                ID

                Name

                Type

                Constraint

                Quality

                Access

                Conformanc e

                0

                Security

                WiFiSecurity

                all



                WI

                1

                SSID

                octstr

                max 32



                WI

                2

                BSSID

                octstr

                6



                WI

                3

                Channel

                uint16

                all



                WI

                4

                WiFiBand

                WiFiBand

                all



                [WI]

                5

                RSSI

                int8

                all



                [WI]


                The WiFiBand field, if present, MAY be used to differentiate overlapping channel number values across different Wi-Fi frequency bands.


                RSSI, if present, SHALL denote the signal strength in dBm of the associated scan result.


                ThreadInterfaceScanResult structure


                This ThreadInterfaceScanResult struct represents a single Thread network scan result.


                ID

                Name

                Type

                Constraint

                Quality

                Access

                Conformanc e

                0

                PanId

                uint16

                0 to 65534



                TH

                1

                ExtendedPan Id

                uint64

                all



                TH

                2

                NetworkNa me

                string

                1 to 16



                TH

                3

                Channel

                uint16

                all



                TH

                4

                Version

                uint8

                all



                TH

                5

                ExtendedAd dress

                hwadr

                all



                TH

                6

                RSSI

                int8

                all



                TH

                7

                LQI

                uint8

                all



                TH


                ExtendedAddress stands for an IEEE 802.15.4 Extended Address.


              5. Specific status codes


        NetworkCommissioningStatus Enum


        The NetworkCommissioningStatus enumeration is used within many responses.


        Value

        Name

        Description

        0

        Success

        OK, no error

        1

        OutOfRange

        Value Outside Range

        Value

        Name

        Description

        2

        BoundsExceeded

        A collection would exceed its size limit

        3

        NetworkIDNotFound

        The NetworkID is not among the collection of added networks

        4

        DuplicateNetworkID

        The NetworkID is already among the collection of added networks

        5

        NetworkNotFound

        Cannot find AP: SSID Not found

        6

        RegulatoryError

        Cannot find AP: Mismatch on band/channels/regulatory domain / 2.4GHz vs 5GHz

        7

        AuthFailure

        Cannot associate due to authentication failure

        8

        UnsupportedSecurity

        Cannot associate due to unsupported security mode

        9

        OtherConnectionFailure

        Other association failure

        10

        IPV6Failed

        Failure to generate an IPv6 address

        11

        IPBindFailed

        Failure to bind Wi-Fi <-> IP interfaces

        12

        UnknownError

        Unknown error


      7. Attributes


        ID

        Name

        Type

        Constraint

        Quality

        Default

        Access

        Conforma nce

        0x0000

        MaxNetwo rks

        uint8

        min 1

        F


        R A

        M

        0x0001

        Networks

        list[Networ kInfo]

        max MaxNetwo rks


        empty

        R A

        M

        0x0002

        ScanMaxTi meSeconds

        uint8

        desc

        F


        R V

        WI | TH

        0x0003

        ConnectMa xTimeSeco nds

        uint8

        desc

        F


        R V

        WI | TH

        0x0004

        InterfaceE nabled

        bool


        N

        true

        RW VA

        M

        ID

        Name

        Type

        Constraint

        Quality

        Default

        Access

        Conforma nce

        0x0005

        LastNetwo rkingStatus

        NetworkCo mmissioni ngStatus


        X

        null

        R A

        M

        0x0006

        LastNetwo rkID

        octstr

        1 to 32

        X

        null

        R A

        M

        0x0007

        LastConne ctErrorVal ue

        int32


        X

        null

        R A

        M


              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 list SHALL be less than or equal to this value.


              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, AddOrUpdateWiFiNetwork and ReorderNetwork commands. In other words, the list SHALL be stable over time, unless mutated externally.