CH11-Service and Device Management-2

Matter

Matter Core Specification

Chapter 11. Service and Device Management

11.1. Basic Information Cluster

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

11.1.1. Revision History

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

Revision	Description
1	Initial Release

11.1.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	BINFO

Cluster ID

ID	Name
0x0028	Basic Information

Data Types

11.1.4.1. CapabilityMinimaStruct

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

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	CaseSes sionsPer Fabric	uint16	min 3		3		M
1	Subscrip tionsPer Fabric	uint16	min 3		3		M

CaseSessionsPerFabric Field

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

This value SHALL NOT be smaller than the required minimum indicated in Section 4.13.2.8, “Mini mal Number of CASE Sessions”.

SubscriptionsPerFabric Field

This field SHALL indicate the actual minimum number of concurrent subscriptions supported per fabric.

This value SHALL NOT be smaller than the required minimum indicated in Section 8.5.1, “Subscribe Transaction”.

11.1.5. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	DataMod elRevision	uint16	all	F	MS	R V	M
0x0001	Vendor Name	string	max 32	F	MS	R V	M
0x0002	VendorID	vendor-id	all	F	MS	R V	M
0x0003	Product Name	string	max 32	F	MS	R V	M
0x0004	ProductID	uint16	all	F	MS	R V	M
0x0005	NodeLabel	string	max 32	N	“”	RW VM	M
0x0006	Location	string	2	N	“XX”	RW VA	M
0x0007	Hardware Version	uint16	all	F	0	R V	M
0x0008	Hardware Version String	string	1 to 64	F	MS	R V	M
0x0009	Software Version	uint32	desc	F	0	R V	M
0x000a	Software Version String	string	1 to 64	F	MS	R V	M
0x000b	Manufac turing Date	string	8 to 16	F	MS	R V	O

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x000c	PartNum ber	string	max 32	F	MS	R V	O
0x000d	Produc tURL	string	max 256	F	MS	R V	O
0x000e	Product Label	string	max 64	F	MS	R V	O
0x000f	Serial Number	string	max 32	F	MS	R V	O
0x0010	LocalCon figDis abled	bool	all	N	False	RW VM	O
0x0011	Reachable	bool	all		True	R V	O
0x0012	UniqueID	string	max 32	F	MS	R V	O
0x0013	Capabili tyMinima	Capabili tyMini maStruct	all	F	MS	R V	M

11.1.5.1. DataModelRevision Attribute

This attribute SHALL be set to the revision number of the Data Model against which the Node is cer tified.

11.1.5.2. VendorName Attribute

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

11.1.5.3. VendorID Attribute

This attribute SHALL specify the Vendor ID.

11.1.5.4. ProductName Attribute

This attribute SHALL specify a human readable (displayable) name of the model for the Node such as the model number (or other identifier) assigned by the vendor.

11.1.5.5. ProductID Attribute

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

11.1.5.6. NodeLabel Attribute

This attribute SHALL represent a user defined name for the Node. This attribute SHOULD be set during initial commissioning and MAY be updated by further reconfigurations.

11.1.5.7. Location Attribute

This attribute SHALL be an ISO 3166-1 alpha-2 code to represent the country, dependent territory, or special area of geographic interest in which the Node is located at the time of the attribute being set. This attribute SHALL be set during initial commissioning (unless already set) and MAY be updated by further reconfigurations. This attribute MAY affect some regulatory aspects of the Node’s operation, such as radio transmission power levels in given spectrum allocation bands if technologies where this is applicable are used. The Location’s region code SHALL be interpreted in a case-insensitive manner. If the Node cannot understand the location code with which it was con figured, or the location code has not yet been configured, it SHALL configure itself in a region- agnostic manner as determined by the vendor, avoiding region-specific assumptions as much as is practical. The special value XX SHALL indicate that region-agnostic mode is used.

11.1.5.8. HardwareVersion Attribute

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

11.1.5.9. HardwareVersionString Attribute

This attribute SHALL specify the version number of the hardware of the Node. The meaning of its value, and the versioning scheme, are vendor defined. The HardwareVersionString attribute SHALL be used to provide a more user-friendly value than that represented by the HardwareVersion attribute.

11.1.5.10. SoftwareVersion Attribute

This attribute SHALL contain the current version number for the software running on this Node. 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.19.3.3, “Availability of Software Images”). Nodes MAY query this field to determine the currently running version of software on another given Node.

11.1.5.11. SoftwareVersionString Attribute

This attribute SHALL contain a current human-readable representation for the software running on the Node. This version information MAY be conveyed to users. The maximum length of the Soft wareVersionString attribute is 64 bytes of UTF-8 characters. The contents SHOULD only use simple 7-bit ASCII alphanumeric and punctuation characters, so as to simplify the conveyance of the value to a variety of cultures.

Examples of version strings include “1.0”, “1.2.3456”, “1.2-2”, “1.0b123”, “1.2_3”.

11.1.5.12. ManufacturingDate Attribute

This attribute SHALL specify the date that the Node was manufactured. The first 8 characters SHALL specify the date of manufacture of the Node in international date notation according to ISO 8601, i.e., YYYYMMDD, e.g., 20060814. The final 8 characters MAY include country, factory, line, shift or other related information at the option of the vendor. The format of this information is vendor

defined.

11.1.5.13. PartNumber Attribute

This attribute SHALL specify a human-readable (displayable) vendor assigned part number for the Node whose meaning and numbering scheme is vendor defined.

Multiple products (and hence PartNumbers) can share a ProductID. For instance, there may be dif ferent packaging (with different PartNumbers) for different regions; also different colors of a prod uct might share the ProductID but may have a different PartNumber.

11.1.5.14. ProductURL Attribute

This attribute SHALL specify a link to a product specific web page. The syntax of the ProductURL attribute SHALL follow the syntax as specified in RFC 3986 [https://tools.ietf.org/html/rfc3986]. The speci fied 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.

11.1.5.15. ProductLabel Attribute

This attribute SHALL specify a vendor specific human readable (displayable) product label. The ProductLabel attribute MAY be used to provide a more user-friendly value than that represented by the ProductName attribute. The ProductLabel attribute SHOULD NOT include the name of the ven dor as defined within the VendorName attribute.

11.1.5.16. SerialNumber Attribute

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

11.1.5.17. LocalConfigDisabled Attribute

This attribute SHALL allow a local Node configuration to be disabled. When this attribute is set to True the Node SHALL disable the ability to configure the Node through an on-Node user interface. The value of the LocalConfigDisabled attribute SHALL NOT in any way modify, disable, or otherwise affect the user’s ability to trigger a factory reset on the Node.

11.1.5.18. Reachable Attribute

This attribute (when used) SHALL indicate whether the Node can be reached. For a native Node this is implicitly True (and its use is optional).

Its main use case is in the derived Bridged Device Basic Information cluster where it is used to indi cate whether the bridged device is reachable by the bridge over the non-native network.

11.1.5.19. UniqueID Attribute

This attribute (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

11.1.5.20. CapabilityMinima Attribute

This attribute SHALL provide the minimum guaranteed value for some system-wide resource capa bilities that are not otherwise cluster-specific and do not appear elsewhere. This attribute MAY be used by clients to optimize communication with Nodes by allowing them to use more than the strict minimum values required by this specification, wherever available.

The values supported by the server in reality MAY be larger than the values provided in this attribute, such as if a server is not resource-constrained at all. However, clients SHOULD only rely on the amounts provided in this attribute.

Note that since the fixed values within this attribute MAY change over time, both increasing and decreasing, as software versions change for a given Node, clients SHOULD take care not to assume forever unchanging values and SHOULD NOT cache this value permanently at Commissioning time.

11.1.6. Events

ID	Name	Priority	Access	Conformance
0x00	StartUp	CRITICAL	V	M
0x01	ShutDown	CRITICAL	V	O
0x02	Leave	INFO	V	O
0x03	Reach ableChanged	INFO	V	desc

11.1.6.1. StartUp Event

The StartUp event SHALL be generated by a Node as soon as reasonable after completing a boot or reboot process. The StartUp event SHOULD be the first Data Model event recorded by the Node after it completes a boot or reboot process.

The data of this event SHALL contain the following information:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Software Version	uint32				M

SoftwareVersion Field

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

11.1.6.2. ShutDown Event

The ShutDown event SHOULD be generated by a Node prior to any orderly shutdown sequence on a best-effort basis. When a ShutDown event is generated, it SHOULD be the last Data Model event recorded by the Node. This event SHOULD be delivered urgently to current subscribers on a best- effort basis. Any subsequent incoming interactions to the Node MAY be dropped until the comple tion of a future boot or reboot process.

11.1.6.3. Leave Event

The Leave event SHOULD be generated by a Node prior to permanently leaving a given Fabric, such as when the RemoveFabric command is invoked for a given fabric, or triggered by factory reset or some other manufacturer specific action to disable or reset the operational data in the Node. When a Leave event is generated, it SHOULD be assumed that the fabric recorded in the event is no longer usable, and subsequent interactions targeting that fabric will most likely fail.

Upon receipt of Leave Event on a subscription, the receiving Node MAY update other nodes in the fabric by removing related bindings, access control list entries and other data referencing the leav ing Node.

The data of this event SHALL contain the following information:

ID	Field	Type	Constraint	Quality	Default	Confor mance
0	FabricIndex	fabric-idx	1 to 254			M

FabricIndex Field

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

11.1.6.4. ReachableChanged Event

This event SHALL be supported if and only if the Reachable attribute is supported.

This event (when supported) SHALL be generated when there is a change in the Reachable attribute.

Its main use case is in the derived Bridged Device Basic Information cluster. The data of this event SHALL contain the following information:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Reachable NewValue	bool				M

ReachableNewValue Field

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

11.2. Group Key Management Cluster

11.2.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 modifi cations of the list. Such modifications require Administer privilege.

Each group entry includes a membership list of zero of more endpoints that are members of the group on the node. Modification of this membership list is done via the Groups cluster, which is scoped to an endpoint. Please see the System Model specification for more information on groups.

11.2.2. Revision History

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

Revision	Description
1	Initial Release

11.2.3. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	GRPKEY

Cluster ID

ID	Name
0x003F	GroupKeyManagement

Features

This cluster SHALL support the FeatureMap global attribute:

Bit	Code	Feature	Summary
0	CS	CacheAndSync	The ability to support CacheAndSync security policy and MCSP.

11.2.6. Data Types

11.2.6.1. GroupKeySecurityPolicyEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	TrustFirst	Message counter syn chronization using trust-first	M
1	CacheAndSync	Message counter syn chronization using cache-and-sync	CS

11.2.6.2. GroupKeyMulticastPolicyEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	PerGroupID	Indicates filtering of multicast messages for a specific Group ID	M
1	AllNodes	Indicates not filtering of multicast messages	M

PerGroupID Value

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

AllNodes Value

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

11.2.6.3. GroupKeyMapStruct

Access Quality: Fabric Scoped
ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
1	GroupId	group-id	all				M
2	GroupKey SetID	uint16	1 to 65535				M

GroupId Field

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

GroupKeySetID Field

This field references the set of group keys that generate operational group keys for use with this

group, as specified in Section 4.15.3.5.1, “Group Key Set ID”.

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

11.2.6.4. GroupKeySetStruct

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	GroupKey SetID	uint16	all				M
1	GroupKey Security Policy	GroupKey Security Poli cyEnum	all			S	M
2	EpochKey 0	octstr	16	X		S	M
3	EpochStar tTime0	epoch-us	all	X		S	M
4	EpochKey 1	octstr	16	X		S	M
5	EpochStar tTime1	epoch-us	all	X		S	M
6	EpochKey 2	octstr	16	X		S	M
7	EpochStar tTime2	epoch-us	all	X		S	M
8	GroupKey Multicast Policy	GroupKey Multicast Poli cyEnum	all			S	P, M

GroupKeySetID Field

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

GroupKeySecurityPolicy Field

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

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

EpochKey0 Field

This field, if not null, SHALL be the root credential used in the derivation of an operational group key for epoch slot 0 of the given group key set. If EpochKey0 is not null, EpochStartTime0 SHALL NOT be null.

EpochStartTime0 Field

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 representa tion.

EpochKey1 Field

This field, if not null, SHALL be the root credential used in the derivation of an operational group key for epoch slot 1 of the given group key set. If EpochKey1 is not null, EpochStartTime1 SHALL NOT be null.

EpochStartTime1 Field

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

EpochKey2 Field

This field, if not null, SHALL be the root credential used in the derivation of an operational group key for epoch slot 2 of the given group key set. If EpochKey2 is not null, EpochStartTime2 SHALL NOT be null.

EpochStartTime2 Field

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

GroupKeyMulticastPolicy Field

This field specifies how the IPv6 Multicast Address SHALL be formed for groups using this opera tional group key set.

The PerGroupID method maximizes filtering of multicast messages, so that receiving nodes receive only multicast messages for groups to which they are subscribed.

The AllNodes method minimizes the number of multicast addresses to which a receiver node needs to subscribe.

NOTE Support for GroupKeyMulticastPolicy is provisional. Correct default behavior is that implied by value PerGroupID.

11.2.6.5. GroupInfoMapStruct

Access Quality: Fabric Scoped
ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
1	GroupId	group-id	all			R	M
2	Endpoints	list[end point-no]	min 1			R	M
3	Group Name	string	max 16			R	O

GroupId Field

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

Endpoints Field

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

GroupName Field

This field provides a name for the group. This field SHALL contain the last GroupName written for a given GroupId on any Endpoint via the Groups cluster.

11.2.7. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	Group KeyMap	list[Group KeyMap Struct]	desc	N	empty	RW F VM	M
0x0001	GroupT able	list[GroupI nfoMap Struct]	desc		empty	R F	M
0x0002	Max GroupsPer Fabric	uint16	all	F	0	R	M
0x0003	MaxGroup KeysPer Fabric	uint16	1 to 65535	F	1	R	M

11.2.7.1. GroupKeyMap Attribute

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

11.2.7.2. GroupTable Attribute

This attribute is a list of GroupInfoMapStruct entries. Each entry provides read-only information about how a given logical Group ID maps to a particular set of endpoints, and a name for the group. The content of this attribute reflects data managed via the Groups cluster (see AppClusters), and is in general terms referred to as the ‘node-wide Group Table’.

The GroupTable SHALL NOT contain any entry whose GroupInfoMapStruct has an empty Endpoints list. If a RemoveGroup or RemoveAllGroups command causes the removal of a group mapping from its last mapped endpoint, the entire GroupTable entry for that given GroupId SHALL be removed.

11.2.7.3. MaxGroupsPerFabric Attribute

This attribute SHALL indicate the maximum number of groups that this node supports per fabric. The value of this attribute SHALL be set to be no less than the required minimum supported groups as specified in Group Limits. The length of the GroupKeyMap and GroupTable list attributes SHALL NOT exceed the value of the MaxGroupsPerFabric attribute multiplied by the number of supported fabrics.

11.2.7.4. MaxGroupKeysPerFabric Attribute

This attribute SHALL indicate the maximum number of group key sets this node supports per fab ric. The value of this attribute SHALL be set according to the minimum number of group key sets to support as specified in Group Limits.

11.2.8. 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	KeySetRead Response	F A	M
0x02	KeySetRead Response	Server ⇒ Client	N		M
0x03	KeySe tRemove	Client ⇒ Server	Y	F A	M
0x04	KeySe tReadAllIndic es	Client ⇒ Server	KeySe tReadAllIndice sResponse	F A	M
0x05	KeySe tReadAllIndic esResponse	Server ⇒ Client	N		M

11.2.8.1. KeySetWrite Command

This command is used by Administrators to set the state of a given Group Key Set, including atomi

cally updating the state of all epoch keys.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	GroupKey Set	GroupKey SetStruct				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 com mand 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 GroupKey SetID 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 pre vious Group Key Set with the given GroupKeySetID, followed by an addition of a Group Key Set with the provided configuration. Otherwise, if the GroupKeySetID did not match an existing entry, a new Group Key Set associated with the accessing fabric SHALL be created with the provided data. The Group Key Set SHALL be written to non-volatile storage.

Upon completion, this command SHALL send a status code back to the initiator:

If the Group Key Set was properly installed or updated on the Node, the status code SHALL be set to
If there are insufficient resources on the receiver to store an additional Group Key Set, the sta tus code SHALL be set to RESOURCE_EXHAUSTED (see group key limits);
Otherwise, this status code SHALL be set to

11.2.8.2. KeySetRead Command

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

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	GroupKey SetID	uint16	all			M

Effect on Receipt

If there exists a Group Key Set associated with the accessing fabric which has the same GroupKey SetID as that provided in the GroupKeySetID field, then the contents of that Group Key Set SHALL be sent in a KeySetReadResponse command, but with the EpochKey0, EpochKey1 and EpochKey2 fields replaced by null.

Otherwise, if the GroupKeySetID does not refer to a Group Key Set associated with the accessing fabric, then this command SHALL fail with a NOT_FOUND status code.

11.2.8.3. KeySetReadResponse Command

This command SHALL be generated in response to the KeySetRead command, if a valid Group Key Set was found. It SHALL contain the configuration of the requested Group Key Set, with the EpochKey0, EpochKey1 and EpochKey2 key contents replaced by null.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	GroupKeySet	GroupKey SetStruct				M

11.2.8.4. KeySetRemove Command

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

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	GroupKey SetID	uint16	all			M

Effect on Receipt

If there exist any entries for the accessing fabric within the GroupKeyMap attribute that refer to the GroupKeySetID just removed, then these entries SHALL be removed from that list.

This command SHALL fail with an INVALID_COMMAND status code back to the initiator if the GroupKeySetID being removed is 0, which is the Key Set associated with the Identity Protection Key (IPK). The only method to remove the IPK is usage of the RemoveFabric command or any operation which causes the equivalent of a RemoveFabric to occur by side-effect.

This command SHALL send a SUCCESS status code back to the initiator on success, or NOT_FOUND if the GroupKeySetID requested did not exist.

11.2.8.5. KeySetReadAllIndices Command

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

Effect on Receipt

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

11.2.8.6. KeySetReadAllIndicesResponse Command

This command SHALL be generated in response to KeySetReadAllIndices and it SHALL contain the list of GroupKeySetID for all Group Key Sets associated with the scoped Fabric.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	GroupKey SetIDs	list[uint16]				M

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.

11.3. Localization Configuration Cluster

Nodes should be expected to be deployed to any and all regions of the world. These global regions may have differing common languages, units of measurements, and numerical formatting stan dards. As such, Nodes that visually or audibly convey information need a mechanism by which they can be configured to use a user’s preferred language, units, etc.

This cluster supports an interface to a Node. It provides attributes for determining and configuring localization information that a Node SHALL utilize when conveying values to a user.

11.3.1. Revision History

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

Revision	Description
1	Initial Release

11.3.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	LCFG

Cluster ID

ID	Name
0x002B	Localization Configuration

Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	ActiveLo cale	string	max 35	N	MS	RW VM	M
0x0001	Support edLocales	list[string]	max 32[max 35]	F	MS	R V	M

11.3.4.1. ActiveLocale Attribute

The ActiveLocale attribute SHALL represent the locale that the Node is currently configured to use when conveying information. The ActiveLocale attribute SHALL be a Language Tag as defined by BCP47 [https://tools.ietf.org/rfc/bcp/bcp47.txt]. 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.

11.3.4.2. SupportedLocales Attribute

The SupportedLocales attribute SHALL represent a list of locale strings that are valid values for the ActiveLocale attribute. The list SHALL NOT contain any duplicate entries. The ordering of items within the list SHOULD NOT express any meaning.

11.4. Time Format Localization Cluster

Nodes should be expected to be deployed to any and all regions of the world. These global regions may have differing preferences for how dates and times are conveyed. As such, Nodes that visually or audibly convey time information need a mechanism by which they can be configured to use a user’s preferred format.

This cluster supports an interface to a Node. It provides attributes for determining and configuring time and date formatting information that a Node SHALL utilize when conveying values to a user.

11.4.1. Revision History

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

Revision	Description
1	Initial Release

11.4.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	LTIME

Cluster ID

ID	Name
0x002c	Time Format Localization

Features

Bit	Code	Feature	Summary
0	CALFMT	CalendarFormat	The Node can be con figured to use different calendar formats when conveying values to a user.

Data Types

11.4.5.1. HourFormatEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	12hr	Time conveyed with a 12-hour clock	M
1	24hr	Time conveyed with a 24-hour clock	M

11.4.5.2. CalendarTypeEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Buddhist	Dates conveyed using the Buddhist calendar	M
1	Chinese	Dates conveyed using the Chinese calendar	M
2	Coptic	Dates conveyed using the Coptic calendar	M
3	Ethiopian	Dates conveyed using the Ethiopian calendar	M
4	Gregorian	Dates conveyed using the Gregorian calendar	M
5	Hebrew	Dates conveyed using the Hebrew calendar	M
6	Indian	Dates conveyed using the Indian calendar	M
7	Islamic	Dates conveyed using the Islamic calendar	M
8	Japanese	Dates conveyed using the Japanese calendar	M
9	Korean	Dates conveyed using the Korean calendar	M
10	Persian	Dates conveyed using the Persian calendar	M
11	Taiwanese	Dates conveyed using the Taiwanese calendar	M

11.4.6. Attributes

ID	Name	Type	Constraint	Quality	Access	Default	Confor mance
0x0000	HourFor mat	HourFor matEnum	all	X N	RW VM	null	M
0x0001	ActiveCal endarType	Calendar TypeEnum	all	X N	RW VM	null	CALFMT
0x0002	Support edCalen darTypes	list[Calen darType Enum]	desc	F	R V	N/A	CALFMT

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

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

11.4.6.3. SupportedCalendarTypes Attribute

The SupportedCalendarTypes attribute SHALL represent a list of CalendarTypeEnum values that are supported by the Node. The list SHALL NOT contain any duplicate entries. The ordering of items within the list SHOULD NOT express any meaning. The maximum length of the SupportedCalendar Types list SHALL be equivalent to the number of enumerations within CalendarTypeEnum.

11.5. Unit Localization Cluster

Nodes should be expected to be deployed to any and all regions of the world. These global regions may have differing preferences for the units in which values are conveyed in communication to a user. As such, Nodes that visually or audibly convey measurable values to the user need a mecha nism by which they can be configured to use a user’s preferred unit.

This cluster supports an interface to a Node. It provides attributes for determining and configuring the units that a Node SHALL utilize when conveying values in communication to a user.

11.5.1. Revision History

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

Revision	Description
1	Initial Release

11.5.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	LUNIT

Cluster ID

ID	Name
0x002D	Unit Localization

Features

Bit	Code	Feature	Summary
0	TEMP	TemperatureUnit	The Node can be con figured to use different units of temperature when conveying values to a user.

Data Types

11.5.5.1. TempUnitEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Fahrenheit	Temperature conveyed in Fahrenheit	M
1	Celsius	Temperature conveyed in Celsius	M
2	Kelvin	Temperature conveyed in Kelvin	M

11.5.6. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	Tempera tureUnit	Tem pUnitEnu m	all	X N	null	RW VM	TEMP

11.5.6.1. TemperatureUnit Attribute

The TemperatureUnit attribute SHALL indicate the unit for the Node to use only when conveying temperature in communication to the user. If provided, this value SHALL take priority over any unit implied through the ActiveLocale Attribute.

11.6. Power Source Configuration Cluster

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

11.6.1. Revision History

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

Revision	Description
1	Initial Release

11.6.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Endpoint	PSCFG

Cluster ID

ID	Name
0x002E	Power Source Configuration

Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	Sources	list[end point-no]	max 6	N		R V	M

11.6.4.1. Sources Attribute

This list SHALL contain the set of all power sources capable of participating in the power system of this Node. Each entry in the list SHALL be the endpoint number of an endpoint having a Power Source cluster, which corresponds to a physical power source. The endpoint number SHALL be unique within the list.

The order of power sources on a Node is defined by the Order attribute of its associated Power Source cluster provided on the endpoint. List entries SHALL be sorted in increasing order, that is, an entry with a lower order SHALL have a lower index than any entry with a higher order. Multiple entries MAY have the same order, there are no restrictions on their relative sorting.

11.7. Power Source Cluster

This cluster is used to describe the configuration and capabilities of a physical power source that provides power to 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.

11.7.1. Revision History

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

Revision	Description
1	Initial Release

11.7.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	PS

11.7.3. Cluster ID

ID	Name
0x002F	Power Source

11.7.4. Features

Bit	Code	Feature	Summary
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)

11.7.5. Data Types

11.7.5.1. WiredFaultEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	The Node detects an unspecified fault on this wired power source.	M
1	OverVoltage	The Node detects the supplied voltage is above maximum sup ported value for this wired power source.	M

Value	Name	Summary	Conformance
2	UnderVoltage	The Node detects the supplied voltage is below maximum sup ported value for this wired power source.	M

11.7.5.2. BatFaultEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	The Node detects an unspecified fault on this battery power source.	M
1	OverTemp	The Node detects the temperature of this bat tery power source is above ideal operating conditions.	M
2	UnderTemp	The Node detects the temperature of this bat tery power source is below ideal operating conditions.	M

11.7.5.3. BatChargeFaultEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	The Node detects an unspecified fault on this battery source.	M
1	AmbientTooHot	The Node detects the ambient temperature is above the nominal range for this battery source.	M
2	AmbientTooCold	The Node detects the ambient temperature is below the nominal range for this battery source.	M

Value	Name	Summary	Conformance
3	BatteryTooHot	The Node detects the temperature of this bat tery source is above the nominal range.	M
4	BatteryTooCold	The Node detects the temperature of this bat tery source is below the nominal range.	M
5	BatteryAbsent	The Node detects this battery source is not present.	M
6	BatteryOverVoltage	The Node detects this battery source is over voltage.	M
7	BatteryUnderVoltage	The Node detects this battery source is under voltage.	M
8	ChargerOverVoltage	The Node detects the charger for this battery source is over voltage.	M
9	ChargerUnderVoltage	The Node detects the charger for this battery source is under voltage.	M
10	SafetyTimeout	The Node detects a charging safety timeout for this battery source.	M

11.7.5.4. PowerSourceStatusEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	Indicate the source sta tus is not specified	M
1	Active	Indicate the source is available and currently supplying power	M
2	Standby	Indicate the source is available, but is not currently supplying power	M

Value	Name	Summary	Conformance
3	Unavailable	Indicate the source is not currently available to supply power	M

11.7.5.5. WiredCurrentTypeEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	AC	Indicates AC current	M
1	DC	Indicates DC current	M

11.7.5.6. BatChargeLevelEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	OK	Charge level is nominal	M
1	Warning	Charge level is low, intervention may soon be required.	M
2	Critical	Charge level is critical, immediate intervention is required	M

11.7.5.7. BatReplaceabilityEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	The replaceability is unspecified or unknown.	M
1	NotReplaceable	The battery is not replaceable.	M
2	UserReplaceable	The battery is replace able by the user or cus tomer.	M
3	FactoryReplaceable	The battery is replace able by an authorized factory technician.	M

11.7.5.8. BatCommonDesignationEnum

This data type is derived from enum16.

Value	Name	Summary	Conformance
0	Unspecified	Common type is unknown or unspeci fied	M
1	AAA	Common type is as specified	M
2	AA	Common type is as specified	M
3	C	Common type is as specified	M
4	D	Common type is as specified	M
5	4v5	Common type is as specified	M
6	6v0	Common type is as specified	M
7	9v0	Common type is as specified	M
8	1_2AA	Common type is as specified	M
9	AAAA	Common type is as specified	M
10	A	Common type is as specified	M
11	B	Common type is as specified	M
12	F	Common type is as specified	M
13	N	Common type is as specified	M
14	No6	Common type is as specified	M
15	SubC	Common type is as specified	M
16	A23	Common type is as specified	M

Value	Name	Summary	Conformance
17	A27	Common type is as specified	M
18	BA5800	Common type is as specified	M
19	Duplex	Common type is as specified	M
20	4SR44	Common type is as specified	M
21	523	Common type is as specified	M
22	531	Common type is as specified	M
23	15v0	Common type is as specified	M
24	22v5	Common type is as specified	M
25	30v0	Common type is as specified	M
26	45v0	Common type is as specified	M
27	67v5	Common type is as specified	M
28	J	Common type is as specified	M
29	CR123A	Common type is as specified	M
30	CR2	Common type is as specified	M
31	2CR5	Common type is as specified	M
32	CR_P2	Common type is as specified	M
33	CR_V3	Common type is as specified	M
34	SR41	Common type is as specified	M
35	SR43	Common type is as specified	M

Value	Name	Summary	Conformance
36	SR44	Common type is as specified	M
37	SR45	Common type is as specified	M
38	SR48	Common type is as specified	M
39	SR54	Common type is as specified	M
40	SR55	Common type is as specified	M
41	SR57	Common type is as specified	M
42	SR58	Common type is as specified	M
43	SR59	Common type is as specified	M
44	SR60	Common type is as specified	M
45	SR63	Common type is as specified	M
46	SR64	Common type is as specified	M
47	SR65	Common type is as specified	M
48	SR66	Common type is as specified	M
49	SR67	Common type is as specified	M
50	SR68	Common type is as specified	M
51	SR69	Common type is as specified	M
52	SR516	Common type is as specified	M
53	SR731	Common type is as specified	M
54	SR712	Common type is as specified	M

Value	Name	Summary	Conformance
55	LR932	Common type is as specified	M
56	A5	Common type is as specified	M
57	A10	Common type is as specified	M
58	A13	Common type is as specified	M
59	A312	Common type is as specified	M
60	A675	Common type is as specified	M
61	AC41E	Common type is as specified	M
62	10180	Common type is as specified	M
63	10280	Common type is as specified	M
64	10440	Common type is as specified	M
65	14250	Common type is as specified	M
66	14430	Common type is as specified	M
67	14500	Common type is as specified	M
68	14650	Common type is as specified	M
69	15270	Common type is as specified	M
70	16340	Common type is as specified	M
71	RCR123A	Common type is as specified	M
72	17500	Common type is as specified	M
73	17670	Common type is as specified	M

Value	Name	Summary	Conformance
74	18350	Common type is as specified	M
75	18500	Common type is as specified	M
76	18650	Common type is as specified	M
77	19670	Common type is as specified	M
78	25500	Common type is as specified	M
79	26650	Common type is as specified	M
80	32600	Common type is as specified	M

11.7.5.9. BatApprovedChemistryEnum

This data type is derived from enum16.

Value	Name	Summary	Conformance
0	Unspecified	Cell chemistry is unspecified or unknown	M
1	Alkaline	Cell chemistry is alka line	M
2	LithiumCarbonFluo ride	Cell chemistry is lithium carbon fluoride	M
3	LithiumChromiumOx ide	Cell chemistry is lithium chromium oxide	M
4	LithiumCopperOxide	Cell chemistry is lithium copper oxide	M
5	LithiumIronDisulfide	Cell chemistry is lithium iron disulfide	M
6	LithiumManganese Dioxide	Cell chemistry is lithium manganese dioxide	M
7	LithiumThionylChlo ride	Cell chemistry is lithium thionyl chloride	M

Value	Name	Summary	Conformance
8	Magnesium	Cell chemistry is mag nesium	M
9	MercuryOxide	Cell chemistry is mer cury oxide	M
10	NickelOxyhydride	Cell chemistry is nickel oxyhydride	M
11	SilverOxide	Cell chemistry is silver oxide	M
12	ZincAir	Cell chemistry is zinc air	M
13	ZincCarbon	Cell chemistry is zinc carbon	M
14	ZincChloride	Cell chemistry is zinc chloride	M
15	ZincManganeseDiox ide	Cell chemistry is zinc manganese dioxide	M
16	LeadAcid	Cell chemistry is lead acid	M
17	LithiumCobaltOxide	Cell chemistry is lithium cobalt oxide	M
18	LithiumIon	Cell chemistry is lithium ion	M
19	LithiumIonPolymer	Cell chemistry is lithium ion polymer	M
20	LithiumIronPhos phate	Cell chemistry is lithium iron phosphate	M
21	LithiumSulfur	Cell chemistry is lithium sulfur	M
22	LithiumTitanate	Cell chemistry is lithium titanate	M
23	NickelCadmium	Cell chemistry is nickel cadmium	M
24	NickelHydrogen	Cell chemistry is nickel hydrogen	M
25	NickelIron	Cell chemistry is nickel iron	M
26	NickelMetalHydride	Cell chemistry is nickel metal hydride	M

Value	Name	Summary	Conformance
27	NickelZinc	Cell chemistry is nickel zinc	M
28	SilverZinc	Cell chemistry is silver zinc	M
29	SodiumIon	Cell chemistry is sodium ion	M
30	SodiumSulfur	Cell chemistry is sodium sulfur	M
31	ZincBromide	Cell chemistry is zinc bromide	M
32	ZincCerium	Cell chemistry is zinc cerium	M

11.7.5.10. BatChargeStateEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unknown	Unable to determine the charging state	M
1	IsCharging	The battery is charging	M
2	IsAtFullCharge	The battery is at full charge	M
3	IsNotCharging	The battery is not charging	M

11.7.6. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	Status	Power SourceSta tusEnum	desc			R V	M
0x0001	Order	uint8	all	N		R V	M
0x0002	Descrip tion	string	max 60	F		R V	M
0x0003	WiredAsse ssedInput Voltage	uint32	all	X C		R V	[WIRED]

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0004	WiredAsse ssedInput Frequency	uint16	all	X C		R V	[WIRED]
0x0005	WiredCur rentType	WiredCur rentType Enum	desc	F		R V	WIRED
0x0006	WiredAsse ssedCur rent	uint32	all	X C		R V	[WIRED]
0x0007	Wired Nominal Voltage	uint32	all	F		R V	[WIRED]
0x0008	Wired Maxi mumCur rent	uint32	all	F		R V	[WIRED]
0x0009	WiredPre sent	bool	all			R V	[WIRED]
0x000a	ActiveWir edFaults	list[Wired Fault Enum]	8 entries			R V	[WIRED]
0x000b	BatVoltage	uint32	all	X C		R V	[BAT]
0x000c	BatPer centRemai ning	uint8	0 to 200	X C		R V	[BAT]
0x000d	Bat TimeRe maining	uint32	all	X C		R V	[BAT]
0x000e	BatCharge Level	BatCharge LevelEnum	desc			R V	BAT
0x000f	BatRe place ment Needed	bool	all			R V	BAT
0x0010	BatRe placeabil ity	BatRe placeabili tyEnum	all	F		R V	BAT
0x0011	BatPre sent	bool	all			R V	[BAT]

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0012	ActiveBat Faults	list[Bat Fault Enum]	8 entries			R V	[BAT]
0x0013	BatRe place mentDe scription	string	max 60	F		R V	REPLC
0x0014	BatCom monDesig nation	BatCom monDesig natio nEnum	desc	F		R V	[REPLC]
0x0015	BatANSID esignation	string	max 20	F		R V	[REPLC]
0x0016	BatIECDes ignation	string	max 20	F		R V	[REPLC]
0x0017	BatAp proved Chemistry	BatAp proved Chem istryEnum	desc	F		R V	[REPLC]
0x0018	BatCapac ity	uint32	all	F		R V	[REPLC]
0x0019	BatQuan tity	uint8	all	F		R V	REPLC
0x001a	BatCharge State	BatCharge StateEnum	desc			R V	RECHG
0x001b	Bat TimeTo FullCharg e	uint32	all	X C		R V	[RECHG]
0x001c	BatFunc tional WhileChar ging	bool	all			R V	RECHG
0x001d	BatCharg ingCur rent	uint32	all	X C		R V	[RECHG]
0x001e	Active BatCharge Faults	list[BatCha rgeFault Enum]	16 entries			R V	[RECHG]

11.7.6.1. Status Attribute

This attribute SHALL indicate the participation of this power source in providing power to the Node as specified in PowerSourceStatusEnum.

11.7.6.2. Order Attribute

This attribute SHALL indicate the relative preference with which the Node will select this source to provide power. A source with a lower order SHALL be selected by the Node to provide power before any other source with a higher order, if the lower order source is available (see Status).

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

11.7.6.3. Description Attribute

This attribute SHALL provide a user-facing description of this source, used to distinguish it from other power sources, e.g. “DC Power”, “Primary Battery” or “Battery back-up”. This attribute SHALL NOT be used to convey information such as battery form factor, or chemistry.

11.7.6.4. WiredAssessedInputVoltage Attribute

This attribute SHALL indicate the assessed RMS or DC voltage currently provided by the hard-wired source, in mV (millivolts). A value of NULL SHALL indicate the Node is currently unable to assess the value. If the wired source is not connected, but the Node is still able to assess a value, then the assessed value MAY be reported.

11.7.6.5. WiredAssessedInputFrequency Attribute

This attribute SHALL indicate the assessed frequency of the voltage, currently provided by the hard-wired source, in Hz. A value of NULL SHALL indicate the Node is currently unable to assess the value. If the wired source is not connected, but the Node is still able to assess a value, then the assessed value MAY be reported.

11.7.6.6. WiredCurrentType Attribute

This attribute SHALL indicate the type of current the Node expects to be provided by the hard- wired source as specified in WiredCurrentTypeEnum.

11.7.6.7. WiredAssessedCurrent Attribute

This attribute SHALL indicate the assessed instantaneous current draw of the Node on the hard- wired source, in mA (milliamps). A value of NULL SHALL indicate the Node is currently unable to assess the value. If the wired source is not connected, but the Node is still able to assess a value, then the assessed value MAY be reported.

11.7.6.8. WiredNominalVoltage Attribute

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

11.7.6.9. WiredMaximumCurrent Attribute

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

11.7.6.10. WiredPresent Attribute

This attribute SHALL indicate if the Node detects that the hard-wired power source is properly con nected.

11.7.6.11. ActiveWiredFaults Attribute

This attribute SHALL indicate the set of wired faults currently detected by the Node on this power source. This set is represented as a list of WiredFaultEnum. When the Node detects a fault has been raised, the appropriate WiredFaultEnum value SHALL be added to this list, provided it is not already present. This list SHALL NOT contain more than one instance of a specific WiredFaultEnum value. When the Node detects all conditions contributing to a fault have been cleared, the corre sponding WiredFaultEnum value SHALL be removed from this list. An empty list SHALL indicate there are currently no active faults. The order of this list SHOULD have no significance. Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or they MAY sub scribe to WiredFaultChange.

11.7.6.12. BatVoltage Attribute

This attribute SHALL indicate the currently measured output voltage of the battery in mV (milli volts). A value of NULL SHALL indicate the Node is currently unable to assess the value.

11.7.6.13. BatPercentRemaining Attribute

This attribute SHALL indicate the estimated percentage of battery charge remaining until the bat tery will no longer be able to provide power to the Node. Values are expressed in half percent units, ranging from 0 to 200. E.g. a value of 48 is equivalent to 24%. A value of NULL SHALL indicate the Node is currently unable to assess the value.

11.7.6.14. BatTimeRemaining Attribute

This attribute SHALL indicate the estimated time in seconds before the battery will no longer be able to provide power to the Node. A value of NULL SHALL indicate the Node is currently unable to assess the value.

11.7.6.15. BatChargeLevel Attribute

This attribute SHALL indicate a coarse ranking of the charge level of the battery, used to indicate when intervention is required as specified in BatChargeLevelEnum.

11.7.6.16. BatReplacementNeeded Attribute

This attribute SHALL indicate if the battery needs to be replaced. Replacement MAY be simple rou tine maintenance, such as with a single use, non-rechargeable cell. Replacement, however, MAY also indicate end of life, or serious fault with a rechargeable or even non-replaceable cell.

11.7.6.17. BatReplaceability Attribute

This attribute SHALL indicate the replaceability of the battery as specified in BatReplaceabili tyEnum.

11.7.6.18. BatPresent Attribute

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

11.7.6.19. ActiveBatFaults Attribute

This attribute SHALL indicate the set of battery faults currently detected by the Node on this power source. This set is represented as a list of BatFaultEnum. When the Node detects a fault has been raised, the appropriate BatFaultEnum value SHALL be added to this list, provided it is not already present. This list SHALL NOT contain more than one instance of a specific BatFaultEnum value. When the Node detects all conditions contributing to a fault have been cleared, the corresponding BatFaultEnum value SHALL be removed from this list. An empty list SHALL indicate there are cur rently no active faults. The order of this list SHOULD have no significance. Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or they MAY subscribe to Sec tion 11.7.7.2, “BatFaultChange Event”.

11.7.6.20. BatReplacementDescription Attribute

This attribute SHALL provide a user-facing description of this battery, which SHOULD contain information required to identify a replacement, such as form factor, chemistry or preferred manu facturer.

11.7.6.21. BatCommonDesignation Attribute

This attribute SHALL indicate the ID of the common or colloquial designation of the battery, as specified in BatCommonDesignationEnum.

11.7.6.22. BatANSIDesignation Attribute

This attribute SHALL indicate the string representing the ANSI designation for the battery as speci fied in ANSI C18.

11.7.6.23. BatIECDesignation Attribute

This attribute SHALL indicate the string representing the IEC designation for the battery as speci fied in IEC 60086.

11.7.6.24. BatApprovedChemistry Attribute

This attribute SHALL indicate the ID of the preferred chemistry of the battery source as specified in BatApprovedChemistryEnum.

11.7.6.25. BatCapacity Attribute

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

11.7.6.26. BatQuantity Attribute

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

11.7.6.27. BatChargeState Attribute

This attribute SHALL indicate the current state of the battery source with respect to charging as specified in BatChargeStateEnum.

11.7.6.28. BatTimeToFullCharge Attribute

This attribute SHALL indicate the estimated time in seconds before the battery source will be at full charge. A value of NULL SHALL indicate the Node is currently unable to assess the value.

11.7.6.29. BatFunctionalWhileCharging Attribute

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

11.7.6.30. BatChargingCurrent Attribute

This attribute SHALL indicate assessed current in mA (milliamps) presently supplied to charge the battery source. A value of NULL SHALL indicate the Node is currently unable to assess the value.

11.7.6.31. ActiveBatChargeFaults Attribute

This attribute SHALL indicate the set of charge faults currently detected by the Node on this power source. This set is represented as a list of BatChargeFaultEnum. When the Node detects a fault has been raised, the appropriate BatChargeFaultEnum value SHALL be added to this list, provided it is not already present. This list SHALL NOT contain more than one instance of a specific BatCharge FaultEnum value. When the Node detects all conditions contributing to a fault have been cleared, the corresponding BatChargeFaultEnum value SHALL be removed from this list. An empty list SHALL indicate there are currently no active faults. The order of this list SHOULD have no signifi cance. Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or they MAY subscribe to the BatFaultChange event.

11.7.7. Events

ID	Name	Priority	Access	Conformance
0	WiredFault Change	INFO	V	[WIRED]
1	BatFaultChange	INFO	V	[BAT]
2	BatChargeFault Change	INFO	V	[RECHG]

11.7.7.1. WiredFaultChange Event

The WiredFaultChange Event SHALL be generated when the set of wired faults currently detected by the Node on this wired power source changes. This event SHALL correspond to a change in value of ActiveWiredFaults.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Current	list[Wired FaultEnum]	max 8		empty	M
1	Previous	list[Wired FaultEnum]	max 8		empty	M

Current Field

This field SHALL represent the set of faults currently detected, as per Section 11.7.6.11, “ActiveWiredFaults Attribute”.

Previous Field

This field SHALL represent the set of faults detected prior to this change event, as per Section 11.7.6.11, “ActiveWiredFaults Attribute”.

11.7.7.2. BatFaultChange Event

The BatFaultChange Event SHALL be generated when the set of battery faults currently detected by the Node on this battery power source changes. This event SHALL correspond to a change in value of ActiveBatFaults.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Current	list[BatFault Enum]	max 8		empty	M
1	Previous	list[BatFault Enum]	max 8		empty	M

Current Field

This field SHALL represent the set of faults currently detected, as per Section 11.7.6.19, “ActiveBat Faults Attribute”.

Previous Field

This field SHALL represent the set of faults detected prior to this change event, as per Section 11.7.6.19, “ActiveBatFaults Attribute”.

11.7.7.3. BatChargeFaultChange Event

The BatChargeFaultChange Event SHALL be generated when the set of charge faults currently

detected by the Node on this battery power source changes. This event SHALL correspond to a change in value of ActiveBatChargeFaults.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Current	list[BatCharg eFaultEnum]	max 16		empty	M
1	Previous	list[BatCharg eFaultEnum]	max 16		empty	M

Current Field

This field SHALL represent the set of faults currently detected, as per Section 11.7.6.31, “Active BatChargeFaults Attribute”.

Previous Field

This field SHALL represent the set of faults detected prior to this change event, as per Section 11.7.6.31, “ActiveBatChargeFaults Attribute”.

11.7.8. Configuration Examples

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

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

Power Source (on Endpoint 2)

Description: “Mains A” Order: 0

Power Source (on Endpoint 5)

Description: “Mains B” Order: 0

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

Power Source Configuration (on Endpoint 0)

Sources: [5,2]

11.7.8.2. Example: Battery with Mains Power Back-up

This example describes a design with a built-in battery as the primary source, where the mains power serves to keep the battery charged and act as back-up if the battery fails. The Node must define two Power Source Clusters, one for the battery and another for the mains. Since the battery is primary, it must have a lower Order than the mains source.

Power Source (on Endpoint 2)

Description: “Primary Battery” Order: 0

Power Source (on Endpoint 5)

Description: “Mains” Order: 1

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.

Power Source Configuration (on Endpoint 0)

Sources: [2,5]

11.7.8.3. Example: Mains Power with Battery Back-up

This example describes a design where the system always runs from the a mains power source and the back-up battery is out-of-circuit until mains power fails at which point the back-up battery pow ers the system. The Node must define two Power Source Clusters, one for the mains and another for the battery. Since the mains source is primary, it must have a lower Order than the battery source.

Power Source (on Endpoint 2)

Description: “Mains” Order: 0

Power Source (on Endpoint 5)

Description: “Battery Back-up” Order: 1

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.

Power Source Configuration (on Endpoint 0)

Sources: [2,5]

11.7.8.4. Example: Battery with Dual Back-up

This example describes a design with a built-in battery as the primary source, and where two wired sources, USB and a DC adapter, redundantly serve to keep the battery charged and act as back-up if the battery fails. The Node must define three Power Source Clusters, one for each of the battery, the USB source, and the DC adapter. Since the battery is primary, the battery source must have a lower Order than the other sources. This system has no preference between the DC Adapter and USB sources, so these sources will have the same Order.

Power Source (on Endpoint 2)

Description: “Primary Battery” Order: 0

Power Source (on Endpoint 5)

Description: “DC Adapter” Order: 1

Power Source (on Endpoint 7)

Description: “USB Power” Order: 1

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.

Power Source Configuration (on Endpoint 0)

Sources: [2,7,5]

11.7.8.5. Example: Mains Power with Battery Powered Peripheral

This example describes a design with a mains powered core and battery powered peripheral. In this example both power sources are required for proper operation. The Node must define two Power Source Clusters, one for the wired source and one for the battery. Since both sources are required, both sources will have the same Order. We will use Endpoint 2 for the mains power and Endpoint 7 for the battery.

Power Source (on Endpoint 2)

Description: “Mains Power” Order: 0

Power Source (on Endpoint 7)

Description: “Peripheral Battery” Order: 0

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

Power Source Configuration (on Endpoint 0)

Sources: [7,2]

11.8. Network Commissioning Cluster

Network commissioning is part of the overall Node commissioning. The main goal of Network Com missioning Cluster is to associate a Node with or manage a Node’s one or more network interfaces. These network interfaces can include the following types.

Wi-Fi (IEEE 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.

11.8.1. Revision History

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

Revision	Description
1	Initial Release

11.8.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	CNET

11.8.3. Cluster ID

ID	Name
0x0031	Network Commissioning

11.8.4. Features

Bit	Code	Feature	Conformance	Summary
0	WI	WiFiNetworkIn terface	O.a	Wi-Fi related fea tures
1	TH	ThreadNetworkIn terface	O.a	Thread related features
2	ET	EthernetNetwork Interface	O.a	Ethernet related features

11.8.5. Data Types

11.8.5.1. WiFiSecurityBitmap

This data type is derived from map8.

WiFiSecurityBitmap encodes the supported Wi-Fi security types present in the Security field of the WiFiInterfaceScanResultStruct.

Bit	Name	Summary
0	Unencrypted	Supports unencrypted Wi-Fi
1	WEP	Supports Wi-Fi using WEP secu rity
2	WPA-PERSONAL	Supports Wi-Fi using WPA-Per sonal security
3	WPA2-PERSONAL	Supports Wi-Fi using WPA2-Per sonal security
4	WPA3-PERSONAL	Supports Wi-Fi using WPA3-Per sonal security

11.8.5.2. WiFiBandEnum

This data type is derived from enum8.

WiFiBandEnum encodes a supported Wi-Fi frequency band present in the WiFiBand field of the WiFiInterfaceScanResultStruct.

Value

Name

Summary

Conformance

2G4

2.4GHz – 2.401GHz to

2.495GHz

(802.11b/g/n/ax)

O.a+

3G65

3.65GHz – 3.655GHz to

3.695GHz (802.11y)

O.a+

Value	Name	Summary	Conformance
2	5G	5GHz – 5.150GHz to 5.895GHz (802.11a/n/ac/ax)	O.a+
3	6G	6GHz – 5.925GHz to 7.125GHz (802.11ax / WiFi 6E)	O.a+
4	60G	60GHz – 57.24GHz to 70.20GHz (802.11ad/ay)	O.a+

11.8.5.3. NetworkCommissioningStatusEnum

This data type is derived from enum8.

Value	Name	Summary
0	Success	OK, no error
1	OutOfRange	Value Outside Range
2	BoundsExceeded	A collection would exceed its size limit
3	NetworkIDNotFound	The NetworkID is not among the collection of added net works
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 authen tication failure
8	UnsupportedSecurity	Cannot associate due to unsup ported 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

11.8.5.4. NetworkInfoStruct

NetworkInfoStruct struct describes an existing network configuration, as provided in the Networks attribute.

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	Net workID	octstr	1 to 32				M
1	Connected	bool					M

NetworkID Field

Every network is uniquely identified (for purposes of commissioning) by a NetworkID mapping to the following technology-specific properties:

SSID for Wi-Fi
Extended PAN ID for Thread
Network interface instance name at operating system (or equivalent unique name) for

The semantics of the NetworkID field therefore varies between network types accordingly. It con tains SSID for Wi-Fi networks, Extended PAN ID (XPAN ID) for Thread networks and netif name for Ethernet networks.

NOTE

SSID in Wi-Fi is a collection of 1-32 bytes, the text encoding of which is not specified. Implementations must be careful to support reporting byte strings without requir ing a particular encoding for transfer. Only the commissioner should try to poten tially decode the bytes. The most common encoding is UTF-8, however this is just a convention. Some configurations may use Latin-1 or other character sets. A commis sioner MAY decode using UTF-8, replacing encoding errors with “?” at the applica tion level while retaining the underlying representation.

XPAN ID is a big-endian 64-bit unsigned number, represented on the first 8 octets of the octet string.

Connected Field

This field SHALL indicate the connected status of the associated network, where “connected” means currently linked to the network technology (e.g. Associated for a Wi-Fi network, media connected for an Ethernet network).

11.8.5.5. WiFiInterfaceScanResultStruct

WiFiInterfaceScanResultStruct represents a single Wi-Fi network scan result.

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	Security	WiFiSecu rityBitmap	all				WI
1	SSID	octstr	max 32				WI
2	BSSID	octstr	6				WI
3	Channel	uint16	all				WI
4	WiFiBand	WiFiBan dEnum	all				[WI]
5	RSSI	int8	all				[WI]

WiFiBand Field

This field, if present, MAY be used to differentiate overlapping channel number values across dif ferent Wi-Fi frequency bands.

RSSI Field

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

11.8.5.6. ThreadInterfaceScanResultStruct

ThreadInterfaceScanResultStruct represents a single Thread network scan result.

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	PanId	uint16	0 to 65534				TH
1	Extended PanId	uint64	all				TH
2	Network Name	string	1 to 16				TH
3	Channel	uint16	all				TH
4	Version	uint8	all				TH
5	Extended Address	hwadr	all				TH
6	RSSI	int8	all				TH
7	LQI	uint8	all				TH

ExtendedAddress Field

ExtendedAddress stands for an IEEE 802.15.4 Extended Address.

11.8.6. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	MaxNet works	uint8	min 1	F		R A	M
0x0001	Networks	list[Net workInfoS truct]	max MaxNet works		empty	R A	M
0x0002	ScanMax TimeSec onds	uint8	desc	F		R V	WI \| TH
0x0003	Connect Max TimeSec onds	uint8	desc	F		R V	WI \| TH
0x0004	Inter faceEn abled	bool		N	true	RW VA	M
0x0005	LastNet work ingStatus	Network Commis sioningSta tusEnum		X	null	R A	M
0x0006	LastNet workID	octstr	1 to 32	X	null	R A	M
0x0007	LastCon nectError Value	int32		X	null	R A	M

11.8.6.1. MaxNetworks Attribute

This SHALL indicate the maximum number of network configuration entries that can be added, based on available device resources. The length of the Networks attribute list SHALL be less than or equal to this value.

11.8.6.2. Networks Attribute

This attribute SHALL indicate the network configurations that are usable on the network interface represented by this cluster server instance.

The order of configurations in the list reflects precedence. That is, any time the Node attempts to connect to the network it SHALL attempt to do so using the configurations in Networks Attribute in the order as they appear in the list.

The order of list items SHALL only be modified by the AddOrUpdateThreadNetwork, AddOrUp dateWiFiNetwork and ReorderNetwork commands. In other words, the list SHALL be stable over

time, unless mutated externally.

Ethernet networks SHALL be automatically populated by the cluster server. Ethernet Network Com missioning Cluster instances SHALL always have exactly one Section 11.8.5.4, “NetworkInfoStruct” instance in their Networks attribute. There SHALL be no way to add, update or remove Ethernet network configurations to those Cluster instances.

11.8.6.3. ScanMaxTimeSeconds Attribute

This attribute SHALL indicate the maximum duration taken, in seconds, by the network interface on this cluster server instance to provide scan results.

See Section 11.8.7.1, “ScanNetworks Command” for usage.

11.8.6.4. ConnectMaxTimeSeconds Attribute

This attribute SHALL indicate the maximum duration taken, in seconds, by the network interface on this cluster server instance to report a successful or failed network connection indication. This maximum time SHALL account for all operations needed until a successful network connection is deemed to have occurred, including, for example, obtaining IP addresses, or the execution of neces sary internal retries.

11.8.6.5. InterfaceEnabled Attribute

This attribute SHALL indicate whether the associated network interface is enabled or not. By default all network interfaces SHOULD be enabled during initial commissioning (InterfaceEnabled set to true).

It is undefined what happens if InterfaceEnabled is written to false on the same interface as that which is used to write the value. In that case, it is possible that the Administrator would have to await expiry of the fail-safe, and associated recovery of network configuration to prior safe values, before being able to communicate with the node again (see Section 11.9.6.2, “ArmFailSafe Com mand”).

It MAY be possible to disable Ethernet interfaces but it is implementation-defined. If not supported, a write to this attribute with a value of false SHALL fail with a status of INVALID_ACTION. When disabled, an Ethernet interface would longer employ media detection. That is, a simple unplug and replug of the cable SHALL NOT re-enable the interface.

On Ethernet-only Nodes, there SHALL always be at least one of the Network Commissioning server cluster instances with InterfaceEnabled set to true.

11.8.6.6. LastNetworkingStatus Attribute

This attribute SHALL indicate the status of the last attempt either scan or connect to an operational network, using this interface, whether by invocation of the ConnectNetwork command or by autonomous connection after loss of connectivity or during initial establishment. If no such attempt was made, or no network configurations exist in the Networks attribute, then this attribute SHALL be set to null.

This attribute is present to assist with error recovery during Network commissioning and to assist in non-concurrent networking commissioning flows.

11.8.6.7. LastNetworkID Attribute

This attribute SHALL indicate the NetworkID used in the last attempt to connect to an operational network, using this interface, whether by invocation of the ConnectNetwork command or by autonomous connection after loss of connectivity or during initial establishment. If no such attempt was made, or no network configurations exist in the Networks attribute, then this attribute SHALL be set to null.

If a network configuration is removed from the Networks attribute using the RemoveNetwork com mand after a connection attempt, this field MAY indicate a NetworkID that is no longer configured on the Node.

This attribute is present to assist with error recovery during Network commissioning and to assist in non-concurrent networking commissioning flows.

11.8.6.8. LastConnectErrorValue Attribute

This attribute SHALL indicate the ErrorValue used in the last failed attempt to connect to an opera tional network, using this interface, whether by invocation of the ConnectNetwork command or by autonomous connection after loss of connectivity or during initial establishment. If no such attempt was made, or no network configurations exist in the Networks attribute, then this attribute SHALL be set to null.

If the last connection succeeded, as indicated by a value of Success in the LastNetworkingStatus attribute, then this field SHALL be set to null.

This attribute is present to assist with error recovery during Network commissioning and to assist in non-concurrent networking commissioning flows.

11.8.7. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	ScanNetworks	Client ⇒ Server	ScanNetwork sResponse	A	WI \| TH
0x01	ScanNetwork sResponse	Server ⇒ Client	N		WI \| TH
0x02	AddOrUp dateWiFiNet work	Client ⇒ Server	NetworkConfi gResponse	A	WI
0x03	AddOrUp dateThread Network	Client ⇒ Server	NetworkConfi gResponse	A	TH
0x04	RemoveNet work	Client ⇒ Server	NetworkConfi gResponse	A	WI \| TH

ID	Name	Direction	Response	Access	Conformance
0x05	NetworkConfi gResponse	Server ⇒ Client	N		WI \| TH
0x06	ConnectNet work	Client ⇒ Server	ConnectNet workResponse	A	WI \| TH
0x07	ConnectNet workResponse	Server ⇒ Client	N		WI \| TH
0x08	ReorderNet work	Client ⇒ Server	NetworkConfi gResponse	A	WI \| TH

11.8.7.1. ScanNetworks Command

This command SHALL scan on the Cluster instance’s associated network interface for either of:

All available networks (non-directed scanning)
Specific networks (directed scanning)

Scanning for available networks detects all networks of the type corresponding to the cluster server instance’s associated network interface that are possible to join, such as all visible Wi-Fi access points for Wi-Fi cluster server instances, all Thread PANs for Thread cluster server instances, within bounds of the maximum response size.

Scanning for a specific network (i.e. directed scanning) takes place if a network identifier (e.g. Wi-Fi SSID) is provided in the command arguments. Directed scanning SHALL restrict the result set to the specified network only.

The client SHALL NOT expect the server to be done scanning and have responded with ScanNet worksResponse before ScanMaxTimeSeconds seconds have elapsed. Enough transport time affor dances for retries SHOULD be expected before a client determines the operation to have timed-out.

This command SHALL fail with a status code of BUSY if the server determines that it will fail to reli ably send a response due to changes of networking interface configuration at runtime for the inter face over which the command was invoked, or if it is currently unable to proceed with such an operation.

Clients SHALL be resilient to a server that either does not support or cannot proceed with the Scan Networks command.

The arguments for this command are as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	SSID	octstr	1 to 32	X	null	[WI]
1	Bread crumb	uint64	all			O

SSID Field

This field, if present, SHALL contain the SSID for a directed scan of that particular Wi-Fi SSID. Oth erwise, if the field is absent, or it is null, this SHALL indicate scanning of all BSSID in range. This field SHALL be ignored for ScanNetworks invocations on non-Wi-Fi server instances.

Breadcrumb Field

The Breadcrumb field, if present, SHALL be used to atomically set the Breadcrumb attribute in the General Commissioning cluster on success of the associated command. If the command fails, the Breadcrumb attribute in the General Commissioning cluster SHALL be left unchanged.

11.8.7.2. ScanNetworksResponse Command

This command SHALL contain the status of the last ScanNetworks command, and the associated scan results if the operation was successful.

ID	Name	Type	Constraint	Default	Conformance
0	Network ingStatus	NetworkCom missioningSta tusEnum	desc		M
1	DebugText	string	max 512		O
2	WiFiScanRe sults	list[WiFiInter faceScanRe sultStruct]	desc		WI
3	ThreadScan Results	list[ThreadIn terfaceScanRe sultStruct]	desc		TH

Results are valid only if NetworkingStatus is Success.

Before generating a ScanNetworksResponse, the server SHALL set the LastNetworkingStatus attribute value to the NetworkingStatus matching the response.

NetworkingStatus Field

The NetworkingStatus field SHALL indicate the status of the last scan operation, taking one of these values:

Success: Scanning
NetworkNotFound: No instance of an explicitly-provided network identifier was found during the scan. This error cannot occur if no network identifier was provided, such as when scanning for all available
OutOfRange: Network identifier was invalid (e.g. empty, too long, etc).
RegulatoryError: Could not scan on any bands due to lack of regulatory
UnknownError: An internal error occurred during

DebugText Field

This field, if present and non-empty, MAY contain error information which MAY be communicated to the user in case the NetworkingStatus was not Success. Its purpose is to help developers in trou bleshooting errors and MAY go into logs or crash reports.

WiFiScanResults Field

If NetworkingStatus was Success, this field SHALL contain the Wi-Fi network scan results. The list MAY be empty if none were found in range on the bands supported by the interface, or if directed scanning had been used and the desired SSID was not found in range.

The maximum number of results present in the result list supported MAY depend on memory and MAY contain a subset of possibilities, to avoid memory exhaustion on the cluster server and avoid crossing the maximum command response size supported (see Section 4.4.4, “Message Size Require ments”).

The order in which results are reported is implementation-specific. Results SHOULD be reported in decreasing RSSI order, even if RSSI is not reported in the response, to maximize the likelihood that most likely to be reachable elements are included within the size limits of the response.

ThreadScanResults Field

If NetworkingStatus was Success, this field SHALL contain the Thread network scan results. The list MAY be empty if none were found in range on the bands supported by the interface.

The order in which results are reported is implementation-specific. Results SHOULD be reported in decreasing LQI order, to maximize the likelihood that most likely to be reachable elements are included within the size limits of the response.

11.8.7.3. AddOrUpdateWiFiNetwork Command

This command SHALL be used to add or modify Wi-Fi network configurations.

If this command is received without an armed fail-safe context (see Section 11.9.6.2, “ArmFailSafe Command”), then this command SHALL fail with a FAILSAFE_REQUIRED status code sent back to the initiator.

The Credentials associated with the network are not readable after execution of this command, as they do not appear in the Networks attribute list, for security reasons.

See Section 11.8.7.5, “Common processing of AddOrUpdateWiFiNetwork and AddOrUpdateThread Network” for behavior of addition/update.

The data for this command is as follows:

ID	Name	Type	Constraint	Default	Conformance
0	SSID	octstr	max 32		M
1	Credentials	octstr	max 64		M
2	Breadcrumb	uint64	all		O

SSID Field

This field SHALL contain the SSID to which to attempt connection. Specific BSSID selection is not supported by this cluster.

Credentials Field

Credentials is the passphrase or PSK for the network (if any is needed).

Security type, cipher and credential format (passphrase or PSK) SHALL be contextually auto- selected during execution of the ConnectNetwork Command and during subsequent operational state network connections, based on the most secure Wi-Fi security type available within beacons and probe responses for the set of all discovered BSSIDs for the configured SSID. The type of PSK or passphrase used SHALL be inferred based on the length and contents of the Credentials field pro vided, matching the security type chosen.

Valid Credentials length are:

0 bytes: Unsecured (open) connection
5 bytes: WEP-64 passphrase
10 hexadecimal ASCII characters: WEP-64 40-bit hex raw PSK
13 bytes: WEP-128 passphrase
26 hexadecimal ASCII characters: WEP-128 104-bit hex raw PSK
.63 bytes: WPA/WPA2/WPA3 passphrase
64 bytes: WPA/WPA2/WPA3 raw hex PSK

These lengths SHALL be contextually interpreted based on the security type of the BSSID where connection will occur.

When the length of Credentials and available set of BSSID admits more than one option, such as the presence of both WPA2 and WPA security type within the result set, WPA2 SHALL be considered more secure.

Note that it MAY occur that a station cannot connect to a particular access point with higher secu rity and selects a lower security connectivity type if the link quality is deemed to be too low to achieve successful operation, or if all retry attempts fail.

Breadcrumb Field

See Section 11.8.7.1.2, “Breadcrumb Field” for usage.

11.8.7.4. AddOrUpdateThreadNetwork Command

This command SHALL be used to add or modify Thread network configurations.

See Section 11.8.7.5, “Common processing of AddOrUpdateWiFiNetwork and AddOrUpdateThread Network” for behavior of addition/update.

The data for this command is as follows:

ID	Name	Type	Constraint	Conformance
0	Operational Dataset	octstr	max 254	M
1	Breadcrumb	uint64	all	O

The XPAN ID in the OperationalDataset serves as the NetworkID for the network configuration to be added or updated.

If the Networks attribute list does not contain an entry with the same NetworkID as the one pro vided in the OperationalDataset, the operation SHALL be considered an addition, otherwise, it shall be considered an update.

OperationalDataset Field

The OperationalDataset field SHALL contain the Thread Network Parameters, including channel, PAN ID, and Extended PAN ID.

The encoding for the OperationalDataset field is defined in the Thread specification. The client SHALL pass the OperationalDataset as an opaque octet string.

Breadcrumb Field

See Section 11.8.7.1.2, “Breadcrumb Field” for usage.

11.8.7.5. Common processing of AddOrUpdateWiFiNetwork and AddOrUpdateThreadNetwork

Both AddOrUpdateWiFiNetwork and AddOrUpdateThreadNetwork operate similarly, against differ ent underlying technologies. The processing of these commands in the addition and update case is covered by the following subsections.

Processing an addition

If the Networks attribute list is already full, the command SHALL immediately respond with Net workConfigResponse having NetworkingStatus status field set to BoundsExceeded.

If any of the parameters in the OperationalDataset are invalid, the command SHALL immediately respond with NetworkConfigResponse having NetworkingStatus status field set to a value different

than Success and consistent with the error.

If validation of all parameters has succeeded, this command SHALL append the configuration at the end of the existing list in the Networks attribute, making this new network the one with least prior ity.

On success, the NetworkConfigResponse command SHALL have its NetworkIndex field set to the 0- based index of the entry in the Networks attribute that was just added.

11.8.7.6. Processing an update

If any of the parameters in the OperationalDataset are invalid, the command SHALL immediately respond with NetworkConfigResponse having NetworkingStatus status field set to a value different than Success and consistent with the error.

If validation of all parameters has succeeded, this command SHALL update the existing entry indexed by NetworkId in the Networks attribute list, keeping existing position within the list.

On success, the NetworkConfigResponse command SHALL have its NetworkIndex field set to the 0- based index of the entry in the Networks attribute that was just updated, and a NetworkingStatus status field set to Success.

11.8.7.7. RemoveNetwork Command

This command SHALL remove the network configuration from the Cluster if there was already a network configuration with the same NetworkID. The relative order of the entries in the Networks attribute list SHALL remain unchanged, except for the removal of the requested network configura tion.

The data for this command is as follows:

ID	Name	Type	Constraint	Conformance
0	NetworkID	octstr	1 to 32	M
1	Breadcrumb	uint64	all	O

If the Networks attribute does not contain a matching entry, the command SHALL immediately respond with NetworkConfigResponse having NetworkingStatus status field set to NetworkIdNot Found.

On success, the NetworkConfigResponse command SHALL have its NetworkIndex field set to the 0- based index of the entry in the Networks attribute that was just removed, and a NetworkingStatus status field set to Success.

NetworkID Field

This field SHALL contain the NetworkID for the entry to remove: the SSID for Wi-Fi and XPAN ID

for Thread.

Breadcrumb Field

See Section 11.8.7.1.2, “Breadcrumb Field” for usage.

11.8.7.8. NetworkConfigResponse Command

This response command relates status information for some commands which require it as their response command. See each individual cluster server command for the situations that may cause a NetworkingStatus different than Success.

The data for this command is as follows:

ID	Name	Type	Constraint	Default	Conformance
0	Network ingStatus	NetworkCom missioningSta tusEnum	desc		M
1	DebugText	string	max 512		O
2	NetworkIndex	uint8	0 to (MaxNet works – 1)		O

Before generating a NetworkConfigResponse, the server SHALL set the LastNetworkingStatus attribute value to the NetworkingStatus matching the response.

Before generating a NetworkConfigResponse, the server SHALL set the LastNetworkID attribute value to the NetworkID that was used in the command for which an invocation caused the response to be generated.

NetworkingStatus Field

The NetworkingStatus field SHALL indicate the status of the last operation attempting to modify the Networks attribute configuration, taking one of these values:

Success: Operation
OutOfRange: Network identifier was invalid (e.g. empty, too long, etc).
BoundsExceeded: Adding this network configuration would exceed the limit defined by Section 11.8.6.1, “MaxNetworks Attribute”.
NetworkIdNotFound: The network identifier was expected to be found, but was not found among the added network configurations in Networks
UnknownError: An internal error occurred during the

DebugText Field

See Section 11.8.7.2.2, “DebugText Field” for usage.

NetworkIndex Field

When the NetworkingStatus is Success, this field SHALL be present. It SHALL contain the 0-based index of the entry in the Networks attribute that was last added, updated or removed successfully by the associated request command.

11.8.7.9. ConnectNetwork Command

This command SHALL attempt to connect to a network whose configuration was previously added by either the AddOrUpdateWiFiNetwork or AddOrUpdateThreadNetwork commands. Network is identified by its NetworkID.

The data for this command is as follows:

ID	Name	Type	Constraint	Conformance
0	NetworkID	octstr	1 to 32	M
1	Breadcrumb	uint64	all	O

This command SHALL fail with a BUSY status code returned to the initiator if the server is currently unable to proceed with such an operation, such as if it is currently attempting to connect in the background, or is already proceeding with a prior ConnectNetwork.

Success or failure of this command SHALL be communicated by the ConnectNetworkResponse com mand, unless some data model validations caused a FAILURE status to be sent prior to finishing execution of the command. The ConnectNetworkResponse SHALL indicate the value Success in the NetworkingStatus field on successful connection. On failure to connect, the ConnectNetworkRe sponse SHALL contain an appropriate NetworkingStatus, DebugText and ErrorValue indicating the reason for failure.

The amount of time needed to determine successful or failing connectivity on the cluster server’s associated interface is provided by the ConnectMaxTimeSeconds attribute. Clients SHALL NOT con sider the connection to have timed-out until at least that duration has taken place. For non-concur rent commissioning situations, the client SHOULD allow additional margin of time to account for its delay in executing operational discovery of the Node once it is connected to the new network.

On successful connection, the entry associated with the given Network configuration in the Net works attribute SHALL indicate its Connected field set to true, and all other entries, if any exist, SHALL indicate their Connected field set to false.

On failure to connect, the entry associated with the given Network configuration in the Networks attribute SHALL indicate its Connected field set to false.

The precedence order of any entry subject to ConnectNetwork SHALL NOT change within the Net works attribute.

Even after successfully connecting to a network, the configuration SHALL revert to the prior state

of configuration if the CommissioningComplete command (see Section 11.9.6.6, “Commissioning Complete Command”) is not successfully invoked before expiry of the Fail-Safe timer.

When non-concurrent commissioning is being used by a Commissioner or Administrator, it is possi ble that the only method to determine success of the operation is operational discovery of the Node on the new operational network. Therefore, before invoking the ConnectNetwork command, the client SHOULD re-invoke the Arm Fail-Safe command with a duration that meets the following:

Sufficient time to meet the minimum required time (see Section 11.8.6.4, “ConnectMaxTimeSec onds Attribute”) that may be taken by the server to connect to the desired
Sufficient time to account for possible message-layer retries when a response is
Sufficient time to allow operational discovery on the new network by a Commissioner or Administrator.
Sufficient time to establish a CASE session after operational discovery
Not so long that, in error situations, the delay to reverting back to being discoverable for com missioning with a previous configuration would cause significant user-perceived

Note as well that the CommissioningTimeout duration provided in a prior OpenCommissioningWin dow or OpenBasicCommissioningWindow command may impact the total time available to proceed with error recovery after a connection failure.

The LastNetworkingStatus, LastNetworkID and LastConnectErrorValue attributes MAY assist the client in determining the reason for a failure after reconnecting over a Commissioning channel, especially in non-concurrent commissioning situations.

NetworkID Field

This field SHALL contain the NetworkID for the entry used to configure the connection: the SSID for Wi-Fi and XPAN ID for Thread.

Breadcrumb Field

See Section 11.8.7.1.2, “Breadcrumb Field” for usage.

11.8.7.10. ConnectNetworkResponse Command

The data for this command is as follows:

ID	Name	Type	Constraint	Quality	Conformance
0	Network ingStatus	NetworkCom missioningSta tusEnum	all		M
1	DebugText	string			O
2	ErrorValue	int32	all	X	M

Before generating a ConnectNetworkResponse, the server SHALL:

Set the LastNetworkingStatus attribute value to the NetworkingStatus matching the
Set the LastNetworkID attribute value to the NetworkID that was used in the ConnectNetwork command which caused the response to be
Set the LastConnectErrorValue attribute value to the ErrorValue matching the response, includ ing setting it to null if the ErrorValue is not

NetworkingStatus Field

The NetworkingStatus field SHALL indicate the status of the last connection attempt, taking one of these values:

Success: Connection
NetworkNotFound: No instance of an explicitly-provided network identifier was found during the attempt to join the
OutOfRange: Network identifier was invalid (e.g. empty, too long, etc).
NetworkIdNotFound: The network identifier was not found among the added network configu rations in Networks
RegulatoryError: Could not connect to a network due to lack of regulatory
UnknownError: An internal error occurred during the
Association errors (see also description of errors in Section 11.8.5.3, “NetworkCommission ingStatusEnum”): AuthFailure, UnsupportedSecurity, OtherConnectionFailure, IPV6Failed, IPBindFailed

DebugText Field

See Section 11.8.7.2.2, “DebugText Field” for usage.

ErrorValue Field

ErrorValue interpretation for Wi-Fi association errors:
- On any association failure during enabling of a network, the ErrorValue field SHALL be set to the Status Code value that was present in the last frame related to association where Sta tus Code was not equal to zero and which caused the failure of a final retry attempt, if this final failure was due to one of the following Management frames:
  - Association Response (Type 0, Subtype 1)
  - Reassociation Response (Type 0, Subtype 3)
  - Authentication (Type 0, Subtype 11)
- Table 9-50 “Status Codes” in IEEE 802.11-2020 contains a description of all values possible, which can unambiguously be used to determine the cause, such as an invalid security type, unsupported rate,
Otherwise, the ErrorValue field SHALL contain an implementation-dependent value which MAY be used by a reader of the structure to record, report or diagnose the

11.8.7.11. ReorderNetwork Command

This command SHALL set the specific order of the network configuration selected by its NetworkID in the Networks attribute list to match the position given by NetworkIndex.

The data for this command is as follows:

ID	Name	Type	Constraint	Conformance
0	NetworkID	octstr	1 to 32	M
1	NetworkIndex	uint8	desc	M
2	Breadcrumb	uint64	all	O

NetworkID Field

This field SHALL contain the NetworkID for the entry to reorder: the SSID for Wi-Fi and XPAN ID for Thread.

NetworkIndex Field

This field SHALL contain the 0-based index of the new desired position of the entry in the Networks attribute.

Breadcrumb Field

See Section 11.8.7.1.2, “Breadcrumb Field” for usage.

Effect when received

If the Networks attribute does not contain a matching entry, the command SHALL immediately respond with NetworkConfigResponse having NetworkingStatus status field set to NetworkIdNot Found.

If the NetworkIndex field has a value larger or equal to the current number of entries in the Net works attribute, the command SHALL immediately respond with NetworkConfigResponse having NetworkingStatus status field set to OutOfRange.

On success, the NetworkConfigResponse command SHALL have its NetworkIndex field set to the 0- based index of the entry in the Networks attribute that was just updated, matching the incoming NetworkIndex, and a NetworkingStatus status field set to Success.

The entry selected SHALL be inserted at the new position in the list. All other entries, if any exist, SHALL be moved to allow the insertion, in a way that they all retain their existing relative order between each other, with the exception of the newly re-ordered entry.

Re-ordering to the same NetworkIndex as the current location SHALL be considered as a success and yield no visible changes of the Networks attribute.

Examples of re-ordering

To better illustrate the re-ordering operation, consider this initial state, exemplary of a Wi-Fi

device:

Index in list	NetworkID field	Connected field
0	FancyCat	false
1	BlueDolphin	true
2	Home-Guest	false
3	WillowTree	false

On receiving ReorderNetwork with:

NetworkId = Home-Guest
NetworkIndex = 0

The outcome, after applying to the initial state would be:

Index in list	NetworkID field	Connected field
0	Home-Guest	false
1	FancyCat	false
2	BlueDolphin	true
3	WillowTree	false

In the above outcome, FancyCat and BlueDolphin moved “down” and Home-Guest became the high est priority network in the list.

On receiving ReorderNetwork with:

NetworkId = FancyCat
NetworkIndex = 3

The outcome, after applying to the initial state would be:

Index in list	NetworkID field	Connected field
0	BlueDolphin	true
1	Home-Guest	false
2	WillowTree	false
3	FancyCat	false

In the above outcome, BlueDolphin, Home-Guest and WillowTree moved “up” and FancyCat became the lowest priority network in the list.

11.8.8. Usage of networking configurations

This section describes how to ensure deterministic and well-behaved network connectivity, both when concurrent and non-concurrent commissioning flows (see Section 5.5, “Commissioning

Flows”) are used.

Operational Networking configuration is managed by the set of Network Commissioning cluster server instances distributed on a Node’s Endpoints.

Since Matter employs IPv6 communication and DNS-SD for operational Discovery, there is a funda mental aspect of multi-homing present, where a Node with multiple concurrently operated net work interfaces device may be reachable using a variety of addresses on different network tech nologies. Care SHOULD be taken by Administrators and Commissioners to avoid making strong assumptions about single address reachability. Administrators and Commissioners SHOULD be pre pared to attempt reachability tests against specific network technologies if the final desired state of networking requires a specific reachable path.

The primary network interface of a Node SHOULD be the one present on the root node endpoint (see Section 9.2, “Endpoint Composition”). This interface SHOULD be the one most likely to yield an operational reachable state if appropriately configured. Secondary network interfaces SHOULD be additional technologies that MAY increase reachability or support a stub router feature.

A Node MAY be configured in such a way that there are no Network Commissioning cluster server instances present, in which case the remainder of this section SHALL NOT apply.

11.8.8.1. Order of connectivity during connection establishment

When at least one Network Commissioning cluster server instance (hereafter, “Network Commis sioning cluster” for short), the following behavior SHOULD take place for each interface associated with a Network Commissioning cluster, in increasing order of associated endpoint number:

If the Network Commissioning cluster’s InterfaceEnabled attribute is set to false, skip the processing the interface
Set all configurations of the Networks attribute entry’s Connected field to false
Iterate through all configurations in the Networks attribute
1. If there was a “last known good” network configuration, that is, the one which was both last successfully connected during prior boot and over which at least one secure channel exchange message was received, it MAY be used as the first attempt. Otherwise, iterate through all configurations in the precedence order of the list, starting at index
Attempt to connect to the technology, using the current iteration’s network configuration
On success, set the Connected state of the list entry to true, and stop attempting further connec tion. Otherwise, on failure, move to the next

11.8.8.2. Connectivity management during commissioning or administration

When a network interface is configured during commissioning or reconfigured during ongoing administration, behavior is different than for the startup case described previously, since there is are tentative attempts being made to make a Node reachable on an operational network.

Network configuration can be seen as:

A list of existing configurations, reflected by the Networks attribute.

The list SHALL be managed by the AddOrUpdateWiFiNetwork, AddOrUpdateThreadNet work, RemoveNetwork and ReorderNetwork
The list SHALL be tentative until committed by successful invocation of the Commissioning Complete command, or reverted to prior configuration by the expiry of the Fail-Safe timer (see Section 11.9.6.2, “ArmFailSafe Command”).

A current candidate configuration, the subject of the most recent ConnectNetwork
- There SHALL NOT be new connections to any network during the Fail-Safe timer period unless attempted by invocation of the ConnectNetwork

Failures of connection during the Fail-Safe timer window SHALL cause the Node to follow the steps in Section 5.5.1, “Commissioning Flows Error Handling” after recording the cause of the failure in the LastNetworkingStatus, LastNetworkID and LastConnectErrorValue attributes.

After Commissioning or reconfiguration ends successfully, because of successful invocation of the CommissioningComplete command, the cluster server SHOULD NOT attempt to change connected network until connectivity failure or restart occurs, but rather it SHALL commit the tentative con figuration to persistent storage so that it is usable the next time connectivity establishment is needed.

After Commissioning or reconfiguration ends in failure due to expiry of the Fail-Safe timer, the Node SHALL revert to the network configuration present prior to the Fail-Safe timer being armed.

Because it is possible that multiple network configurations being present could successfully result in an established operational network connection, but only some of these configurations actually have the desired reachability by Administrators on certain fabrics, the following precautions SHOULD be taken to avoid a situation where a Node forever dwells on a network with successful connectivity, but no reachable peers:

Commissioners and Administrators MAY notify users if multiple independent configurations exist that could cause an alternate configuration to make the device unreachable for reconfigu ration by Nodes on the current client’s fabric in the
Commissioners and Administrators SHOULD avoid configuring Nodes in ways where it may be ambiguous to end-users which final network configuration will take
Cluster servers on devices with no user interface to express current network configuration to an end-user SHOULD be configured to only support a single entry in the Networks attribute.
Upon discovering that a user is desiring to configure a Network in a way that would change the set of configured networks, and there are multiple fabrics configured in the Fabrics attribute of the Node Operational Credentials cluster, the client SHOULD notify the user that some other Administrators on other fabrics MAY fail to reach the Node and report connectivity

11.9. General Commissioning Cluster

This cluster is used to manage basic commissioning lifecycle.

This cluster also represents responsibilities related to commissioning that don’t well fit other com missioning clusters, like Section 11.8, “Network Commissioning Cluster”. It also hosts functionalities

those other clusters may depend on.

11.9.1. Revision History

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

Revision	Description
1	Initial Release

11.9.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	CGEN

11.9.3. Cluster ID

ID	Name
0x0030	General Commissioning

11.9.4. Data Types

11.9.4.1. CommissioningErrorEnum

This data type is derived from enum8.

This enumeration is used by several response commands in this cluster to indicate particular errors.

Value	Name	Summary	Conformance
0	OK	No error	M
1	ValueOutsideRange	Attempting to set regu latory configuration to a region or indoor/out door mode for which the server does not have proper configura tion.	M
2	InvalidAuthentication	Executed Commission ingComplete outside CASE session.	M
3	NoFailSafe	Executed Commission ingComplete when there was no active Fail-Safe context.	M

Value	Name	Summary	Conformance
4	BusyWithOtherAdmin	Attempting to arm fail- safe or execute Com missioningComplete from a fabric different than the one associated with the current fail- safe context.	M

11.9.4.2. RegulatoryLocationTypeEnum

This data type is derived from enum8.

This enumeration is used by the RegulatoryConfig and LocationCapability attributes to indicate pos sible radio usage.

Value	Name	Summary	Conformance
0	Indoor	Indoor only	M
1	Outdoor	Outdoor only	M
2	IndoorOutdoor	Indoor/Outdoor	M

11.9.4.3. BasicCommissioningInfo

This structure provides some constant values that MAY be of use to all commissioners.

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	FailSafe Ex piryLengt hSeconds	uint16	all				M
1	MaxCu mulative Fail safeSec onds	uint16	desc				M

FailSafeExpiryLengthSeconds Field

This field SHALL contain a conservative initial duration (in seconds) to set in the FailSafe for the commissioning flow to complete successfully. This may vary depending on the speed or sleepiness of the Commissionee. This value, if used in the ArmFailSafe command’s ExpiryLengthSeconds field SHOULD allow a Commissioner to proceed with a nominal commissioning without having to-rearm the fail-safe, with some margin.

MaxCumulativeFailsafeSeconds Field

This field SHALL contain a conservative value in seconds denoting the maximum total duration for which a fail safe timer can be re-armed. See Section 11.9.6.2.1, “Fail Safe Context”.

The value of this field SHALL be greater than or equal to the FailSafeExpiryLengthSeconds. Absent additional guidelines, it is RECOMMENDED that the value of this field be aligned with Section 5.4.2.3, “Announcement Duration” and default to 900 seconds.

11.9.5. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x00	Bread crumb	uint64	all		0	RW VA	M
0x01	BasicCom mis sioning Info	BasicCom mis sioningInfo	desc	F		R V	M
0x02	Regulato ryConfig	Regulato ryLoca tionType Enum	all		Location Capability	R V	M
0x03	Location Capability	Regulato ryLoca tionType Enum	all	F	IndoorOut door	R V	M
0x04	Support sConcur rentCon nection	bool	all	F	true	R V	M

11.9.5.1. Breadcrumb Attribute

This attribute allows for the storage of a client-provided small payload which Administrators and Commissioners MAY write and then subsequently read, to keep track of their own progress. This MAY be used by the Commissioner to avoid repeating already-executed actions upon re-establishing a commissioning link after an error.

On start/restart of the server, such as when a device is power-cycled, this attribute SHALL be reset to zero.

Some commands related to commissioning also have a side-effect of updating or resetting this attribute and this is specified in their respective functional descriptions.

The format of the value within this attribute is unspecified and its value is not otherwise used by the functioning of any cluster, other than being set as a side-effect of commands where this behav

ior is described.

11.9.5.2. BasicCommissioningInfo Attribute

This attribute SHALL describe critical parameters needed at the beginning of commissioning flow. See BasicCommissioningInfo for more information.

11.9.5.3. RegulatoryConfig Attribute

This attribute SHALL indicate the regulatory configuration for the product.

Note that the country code is part of Basic Information Cluster and therefore NOT listed on the Reg ulatoryConfig attribute.

11.9.5.4. LocationCapability Attribute

LocationCapability is statically set by the manufacturer and indicates if this Node needs to be told an exact RegulatoryLocation. For example a Node which is “Indoor Only” would not be certified for outdoor use at all, and thus there is no need for a commissioner to set or ask the user about whether the device will be used inside or outside. However a device which states its capability is “Indoor/Outdoor” means it would like clarification if possible.

For Nodes without radio network interfaces (e.g. Ethernet-only devices), the value IndoorOutdoor SHALL always be used.

The default value of the RegulatoryConfig attribute is the value of LocationCapability attribute. This means devices always have a safe default value, and Commissioners which choose to implement smarter handling can.

11.9.5.5. SupportsConcurrentConnection Attribute

This attribute SHALL indicate whether this device supports “concurrent connection flow” commis sioning mode (see Section 5.5, “Commissioning Flows”). If false, the device only supports “non-con current connection flow” mode.

11.9.6. Commands

For all client-to-server commands in this cluster, if the client deems that it has timed-out in receiv ing the corresponding response command to any request, the corresponding step in the commis sioning flow SHALL be considered to have failed, with the error handled as described in Section 5.5.1, “Commissioning Flows Error Handling”.

11.9.6.1. Common fields in General Commissioning cluster responses

Some response commands have a DebugText argument which SHOULD NOT be presented directly in user interfaces. Its purpose is to help developers in troubleshooting errors. The value MAY go into logs or crash reports.

ID	Name	Direction	Response	Access	Conformance
0x00	ArmFailSafe	Client ⇒ Server	ArmFailSafeRe sponse	A	M
0x01	ArmFailSafeR esponse	Server ⇒ Client	N		M
0x02	SetRegulato ryConfig	Client ⇒ Server	SetRegulato ryConfigRe sponse	A	M
0x03	SetRegulato ryConfigRe sponse	Server ⇒ Client	N		M
0x04	Commission ingComplete	Client ⇒ Server	Commission ingCom pleteResponse	F A	M
0x05	Commission ingCom pleteResponse	Server ⇒ Client	N		M

11.9.6.2. ArmFailSafe Command

The arguments for this command are as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	ExpiryLengt hSeconds	uint16			900	M
1	Bread crumb	uint64				M

Success or failure of this command SHALL be communicated by the ArmFailSafeResponse com mand, unless some data model validations caused a failure status code to be issued during the processing of the command.

If the fail-safe timer is not currently armed, the commissioning window is open, and the command was received over a CASE session, the command SHALL leave the current fail-safe state unchanged and immediately respond with an ArmFailSafeResponse containing an ErrorCode value of Busy WithOtherAdmin. This is done to allow commissioners, which use PASE connections, the opportu nity to use the failsafe during the relatively short commissioning window.

Otherwise, the command SHALL arm or re-arm the “fail-safe timer” with an expiry time set for a duration of ExpiryLengthSeconds, or disarm it, depending on the situation:

If ExpiryLengthSeconds is 0 and the fail-safe timer was already armed and the accessing fabric matches the Fabric currently associated with the fail-safe context, then the fail-safe timer SHALL be immediately expired (see further below for side-effects of expiration).

If ExpiryLengthSeconds is 0 and the fail-safe timer was not armed, then this command invoca tion SHALL lead to a success response with no side-effects against the fail-safe
If ExpiryLengthSeconds is non-zero and the fail-safe timer was not currently armed, then the fail-safe timer SHALL be armed for that
If ExpiryLengthSeconds is non-zero and the fail-safe timer was currently armed, and the access ing Fabric matches the fail-safe context’s associated Fabric, then the fail-safe timer SHALL be re- armed to expire in
Otherwise, the command SHALL leave the current fail-safe state unchanged and immediately respond with ArmFailSafeResponse containing an ErrorCode value of BusyWithOtherAdmin, indicating a likely conflict between

The value of the Breadcrumb field SHALL be written to the Breadcrumb Attribute on successful execution of the command.

If the receiver restarts unexpectedly (e.g., power interruption, software crash, or other reset) the receiver SHALL behave as if the fail-safe timer expired and perform the sequence of clean-up steps listed below.

On successful execution of the command, the ErrorCode field of the ArmFailSafeResponse SHALL be set to OK.

Fail Safe Context

When first arming the fail-safe timer, a ‘Fail Safe Context’ SHALL be created on the receiver, to track the following state information while the fail-safe is armed:

The fail-safe timer
The state of all Network Commissioning Networks attribute configurations, to allow recovery of connectivity after Fail-Safe
Whether an AddNOC command or UpdateNOC command has taken
A Fabric Index for the fabric-scoping of the context, starting at the accessing fabric index for the ArmFailSafe command, and updated with the Fabric Index associated with an AddNOC com mand or an UpdateNOC command being invoked successfully during the ongoing Fail-Safe timer
The operational credentials associated with any Fabric whose configuration is affected by the UpdateNOC
Optionally: the previous state of non-fabric-scoped data that is mutated during the fail-safe period.

Note the following to assist in understanding the above state-keeping, which summarizes other nor mative requirements in the respective sections:

The AddNOC command can only be invoked once per contiguous non-expiring fail-safe timer period, and only if no UpdateNOC command was previously processed within the same fail-safe timer
The UpdateNOC command can only be invoked once per contiguous non-expiring fail-safe timer

period, can only be invoked over a CASE session, and only if no AddNOC command was previ ously processed in the same fail-safe timer period.

On creation of the Fail Safe Context a second timer SHALL be created to expire at MaxCumulative FailsafeSeconds as specified in BasicCommissioningInfo. This Cumulative Fail Safe Context timer (CFSC timer) serves to limit the lifetime of any particular Fail Safe Context; it SHALL NOT be extended or modified on subsequent invocations of ArmFailSafe associated with this Fail Safe Con text. Upon expiry of the CFSC timer, the receiver SHALL execute cleanup behavior equivalent to that of fail-safe timer expiration as detailed in Section 11.9.6.2.2, “Behavior on expiry of Fail-Safe timer”. Termination of the session prior to the expiration of that timer for any reason (including a successful end of commissioning or an expiry of a fail-safe timer) SHALL also delete the CFSC timer.

Behavior on expiry of Fail-Safe timer

If the fail-safe timer expires before the CommissioningComplete command is successfully invoked, the following sequence of clean-up steps SHALL be executed, in order, by the receiver:

Terminate any open PASE secure session by clearing any associated Secure Session Context at the
Revoke the temporary administrative privileges granted to any open PASE session (see Section 6.6.2.8, “Bootstrapping of the Access Control Cluster”) at the
If an AddNOC or UpdateNOC command has been successfully invoked, terminate all CASE ses sions associated with the Fabric whose Fabric Index is recorded in the Fail-Safe context (see Sec tion 11.9.6.2, “ArmFailSafe Command”) by clearing any associated Secure Session Context at the Server.
Reset the configuration of all Network Commissioning Networks attribute to their state prior to the Fail-Safe being
If an UpdateNOC command had been successfully invoked, revert the state of operational key pair, NOC and ICAC for that Fabric to the state prior to the Fail-Safe timer being armed, for the Fabric Index that was the subject of the UpdateNOC
If an AddNOC command had been successfully invoked, achieve the equivalent effect of invok ing the RemoveFabric command against the Fabric Index stored in the Fail-Safe Context for the Fabric Index that was the subject of the AddNOC command. This SHALL remove all associations to that Fabric including all fabric-scoped data, and MAY possibly factory-reset the device depending on current device state. This SHALL only apply to Fabrics added during the fail-safe period as the result of the AddNOC command.
Remove any RCACs added by the AddTrustedRootCertificate command that are not currently referenced by any entry in the Fabrics attribute.
Reset the Breadcrumb attribute to
Optionally: if no factory-reset resulted from the previous steps, it is RECOMMENDED that the Node rollback the state of all non fabric-scoped data present in the Fail-Safe

11.9.6.3. ArmFailSafeResponse Command

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	ErrorCode	Commis sioningEr rorEnum			OK	M
1	DebugText	String	max 128		“”	M

ErrorCode Field

This field SHALL contain the result of the operation, based on the behavior specified in the func tional description of the ArmFailSafe command.

DebugText Field

See Section 11.9.6.1, “Common fields in General Commissioning cluster responses”.

11.9.6.4. SetRegulatoryConfig Command

This SHALL add or update the regulatory configuration in the RegulatoryConfig Attribute to the value provided in the NewRegulatoryConfig field.

The data for this command is as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	NewRegula toryConfig	Regulatory Location TypeEnum				M
1	Coun tryCode	string	2			M
2	Bread crumb	uint64				M

Success or failure of this command SHALL be communicated by the SetRegulatoryConfigResponse command, unless some data model validations caused a failure status code to be issued during the processing of the command.

The CountryCode field SHALL conforms to ISO 3166-1 alpha-2 and SHALL be used to set the Loca tion attribute reflected by the Basic Information Cluster.

If the server limits some of the values (e.g. locked to a particular country, with no regulatory data for others), then setting regulatory information outside a valid country or location SHALL still set the Location attribute reflected by the Basic Information Cluster configuration, but the SetRegulato ryConfigResponse replied SHALL have the ErrorCode field set to ValueOutsideRange error.

If the LocationCapability attribute is not Indoor/Outdoor and the NewRegulatoryConfig value received does not match either the Indoor or Outdoor fixed value in LocationCapability, then the SetRegulatoryConfigResponse replied SHALL have the ErrorCode field set to ValueOutsideRange

error and the RegulatoryConfig attribute and associated internal radio configuration SHALL remain unchanged.

If the LocationCapability attribute is set to Indoor/Outdoor, then the RegulatoryConfig attribute SHALL be set to match the NewRegulatoryConfig field.

On successful execution of the command, the ErrorCode field of the SetRegulatoryConfigResponse SHALL be set to OK.

The Breadcrumb field SHALL be used to atomically set the Breadcrumb attribute on success of this command, when SetRegulatoryConfigResponse has the ErrorCode field set to OK. If the command fails, the Breadcrumb attribute SHALL be left unchanged.

11.9.6.5. SetRegulatoryConfigResponse Command

The data for this command is as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	ErrorCode	Commis sioningEr rorEnum			OK	M
1	DebugText	String			“”	M

ErrorCode Field

This field SHALL contain the result of the operation, based on the behavior specified in the func tional description of the SetRegulatoryConfig command.

DebugText Field

See Section 11.9.6.1, “Common fields in General Commissioning cluster responses”.

11.9.6.6. CommissioningComplete Command

This command has no data.

Success or failure of this command SHALL be communicated by the CommissioningCompleteRe sponse command, unless some data model validations caused a failure status code to be issued dur ing the processing of the command.

This command signals the Server that the Commissioner or Administrator has successfully com pleted all steps needed during the Fail-Safe period, such as commissioning (see Section 5.5, “Com missioning Flows”) or other Administrator operations requiring usage of the Fail Safe timer. It ensures that the Server is configured in a state such that it still has all necessary elements to be fully operable within a Fabric, such as ACL entries (see Access Control Cluster) and operational cre dentials (see Section 6.4, “Node Operational Credentials Specification”), and that the Node is reach able using CASE (see Section 4.13.2, “Certificate Authenticated Session Establishment (CASE)”) over an operational network.

An ErrorCode of NoFailSafe SHALL be responded to the invoker if the CommissioningComplete command was received when no Fail-Safe context exists.

This command is fabric-scoped, so cannot be issued over a session that does not have an associated fabric, i.e. over PASE session prior to an AddNOC command. In addition, this command is only per mitted over CASE and must be issued by a node associated with the ongoing Fail-Safe context. An ErrorCode of InvalidAuthentication SHALL be responded to the invoker if the CommissioningCom plete command was received outside a CASE session (e.g., over Group messaging, or PASE session after AddNOC), or if the accessing fabric is not the one associated with the ongoing Fail-Safe con text.

This command SHALL only result in success with an ErrorCode value of OK in the Commissioning CompleteResponse if received over a CASE session and the accessing fabric index matches the Fab ric Index associated with the current Fail-Safe context. In other words:

If no AddNOC command had been successfully invoked, the CommissioningComplete command must originate from the Fabric that initiated the Fail-Safe
After an AddNOC command has been successfully invoked, the CommissioningComplete com mand must originate from the Fabric which was joined through the execution of that command, which updated the Fail-Safe context’s Fabric

On successful execution of the CommissioningComplete command, where the CommissioningCom pleteResponse has an ErrorCode of OK, the following actions SHALL be undertaken on the Server:

The Fail-Safe timer associated with the current Fail-Safe context SHALL be
The commissioning window at the Server SHALL be
Any temporary administrative privileges automatically granted to any open PASE session SHALL be revoked (see Section 6.6.2.8, “Bootstrapping of the Access Control Cluster”).
The Secure Session Context of any PASE session still established at the Server SHALL be
The Breadcrumb attribute SHALL be reset to

After receipt of a CommissioningCompleteResponse with an ErrorCode value of OK, a client cannot expect any previously established PASE session to still be usable, due to the server having cleared such sessions.

11.9.6.7. CommissioningCompleteResponse Command

The data for this command is as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	ErrorCode	Commis sioningEr rorEnum			OK	M
1	DebugText	String			“”	M

ErrorCode Field

This field SHALL contain the result of the operation, based on the behavior specified in the func tional description of the CommissioningComplete command.

DebugText Field

See Section 11.9.6.1, “Common fields in General Commissioning cluster responses”.

11.10. Diagnostic Logs Cluster

This Cluster supports an interface to a Node. It provides commands for retrieving unstructured diagnostic logs from a Node that may be used to aid in diagnostics. It will often be the case that unstructured diagnostic logs will be Node-wide and not specific to any subset of Endpoints. When present, this Cluster SHALL be implemented once for the Node. The Node SHOULD also implement the BDX Initiator and BDX Sender roles as defined in the BDX Protocol.

NOTE Support for Diagnostic Logs cluster is provisional.

11.10.1. Revision History

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

Revision	Description
1	Initial Release

11.10.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	DLOG

11.10.3. Cluster ID

ID	Name
0x0032	Diagnostic Logs

11.10.4. Data Types

11.10.4.1. IntentEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	EndUserSupport	Logs to be used for end- user support	M

Value	Name	Summary	Conformance
1	NetworkDiag	Logs to be used for net work diagnostics	M
2	CrashLogs	Obtain crash logs from the Node	M

EndUserSupport Value

SHALL indicate that the purpose of the log request is to retrieve logs for the intention of providing support to an end-user.

NetworkDiag Value

SHALL indicate that the purpose of the log request is to diagnose the network(s) for which the Node is currently commissioned (and/or connected) or has previously been commissioned (and/or con nected).

CrashLogs Value

SHALL indicate that the purpose of the log request is to retrieve any crash logs that may be present on a Node.

11.10.4.2. StatusEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Success	Successful transfer of logs	M
1	Exhausted	All logs has been trans ferred	M
2	NoLogs	No logs of the requested type avail able	M
3	Busy	Unable to handle request, retry later	M
4	Denied	The request is denied, no logs being trans ferred	M

Success Value

SHALL be used if diagnostic logs will be or are being transferred.

Exhausted Value

SHALL be used when a BDX session is requested, however, all available logs were provided in a

LogContent field.

NoLogs Value

SHALL be used if the Node does not currently have any diagnostic logs of the requested type (Intent) to transfer.

Busy Value

SHALL be used if the Node is unable to handle the request (e.g. in the process of another transfer) and the Client SHOULD re-attempt the request later.

Denied Value

SHALL be used if the Node is denying the current transfer of diagnostic logs for any reason.

11.10.4.3. TransferProtocolEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	ResponsePayload	Logs to be returned as a response	M
1	BDX	Logs to be returned using BDX	M

ResponsePayload Value

SHALL be used by a Client to request that logs are transferred using the LogContent attribute of the response

BDX Value

SHALL be used by a Client to request that logs are transferred using BDX as defined in BDX Protocol

11.10.5. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	RetrieveL ogsRequest	Client ⇒ Server	RetrieveL ogsResponse	O	M
0x01	RetrieveL ogsResponse	Server ⇒ Client	N		M

11.10.5.1. RetrieveLogsRequest Command

Reception of this command starts the process of retrieving diagnostic logs from a Node. The data for this command is as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Intent	IntentEnum	all			M
1	Requested Protocol	TransferPro tocolEnum	all			M
2	Transfer FileDesigna tor	string	max 32			O

Intent Field

This field SHALL indicate why the diagnostic logs are being retrieved from the Node. A Node MAY utilize this field to selectively determine the logs to transfer.

RequestedProtocol Field

This field SHALL be used to indicate how the log transfer is to be realized. If the field is set to BDX, then if the receiving Node supports BDX it SHALL attempt to use BDX to transfer any potential diag nostic logs; if the receiving Node does not support BDX then the Node SHALL follow the require ments defined for a TransferProtocolEnum of ResponsePayload. If this field is set to ResponsePay load the receiving Node SHALL only utilize the LogContent field of the RetreiveLogsResponse com mand to transfer diagnostic log information.

TransferFileDesignator Field

This field SHALL be present if the RequestedProtocol is BDX. The TransferFileDesignator SHALL be set as the File Designator of the BDX transfer if initiated.

Effect on Receipt

On receipt of this command, the Node SHALL respond with a RetrieveLogsResponse command.

If the RequestedProtocol is set to BDX the Node SHOULD immediately realize the RetrieveLogsRe sponse command by initiating a BDX Transfer, sending a BDX SendInit message with the File Desig nator field of the message set to the value of the TransferFileDesignator field of the RetrieveLogsRe quest. On reception of a BDX SendAccept message the Node SHALL send a RetrieveLogsResponse command with a Status field set to Success and proceed with the log transfer over BDX. If a failure StatusReport is received in response to the SendInit message, the Node SHALL send a RetrieveL ogsResponse command with a Status of Denied. In the case where the Node is able to fit the entirety of the requested logs within the LogContent field, the Status field of the RetrieveLogsResponse SHALL be set to Exhausted and a BDX session SHALL NOT be initiated.

If the RequestedProtocol is set to BDX and either the Node does not support BDX or it is not possible for the Node to establish a BDX session, then the Node SHALL utilize the LogContent field of the RetrieveLogsResponse command to transfer as much of the current logs as it can fit within the response, and the Status field of the RetrieveLogsResponse SHALL be set to Exhausted.

If the RequestedProtocol is set to ResponsePayload the Node SHALL utilize the LogContent field of the RetrieveLogsResponse command to transfer as much of the current logs as it can fit within the

response, and a BDX session SHALL NOT be initiated.

If the RequestedProtocol is set to BDX and there is no TransferFileDesignator the command SHALL fail with a Status Code of INVALID_COMMAND.

If the Intent and/or the RequestedProtocol arguments contain invalid (out of range) values the com mand SHALL fail with a Status Code of INVALID_COMMAND.

11.10.5.2. RetrieveLogsResponse Command

This SHALL be generated as a response to the RetrieveLogsRequest. The data for this command is shown in the following.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Status	StatusEnum	all			M
1	LogContent	octstr	1024 octets			M
2	UTC TimeStamp	epoch-us	all			O
3	TimeSince Boot	System Time Microsec onds	all			O

Status Field

This field SHALL indicate the result of an attempt to retrieve diagnostic logs.

LogContent Field

This field SHALL be included in the command if the Status field has a value of Success or Exhausted. A Node SHOULD utilize this field to transfer the newest diagnostic log entries. This field SHALL be empty if BDX is requested and the Status field has a value of Success.

UTCTimeStamp Field

This field SHOULD be included in the command if the Status field has a value of Success and the Node maintains a wall clock. When included, the UTCTimeStamp field SHALL contain the value of the oldest log entry in the diagnostic logs that are being transferred.

TimeSinceBoot Field

This field SHOULD be included in the command if the Status field has a value of Success. When included, the TimeSinceBoot field SHALL contain the time of the oldest log entry in the diagnostic logs that are being transferred represented by the number of microseconds since the last time the Node went through a reboot.

11.11. General Diagnostics Cluster

The General Diagnostics Cluster, along with other diagnostics clusters, provide a means to acquire standardized diagnostics metrics that MAY be used by a Node to assist a user or Administrator in diagnosing potential problems. The General Diagnostics Cluster attempts to centralize all metrics that are broadly relevant to the majority of Nodes.

11.11.1. Revision History

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

Revision	Description
1	Initial Release

11.11.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	DGGEN

11.11.3. Cluster ID

ID	Name
0x0033	General Diagnostics

11.11.4. Data Types

11.11.4.1. HardwareFaultEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	The Node has encoun tered an unspecified fault.	M
1	Radio	The Node has encoun tered a fault with at least one of its radios.	O
2	Sensor	The Node has encoun tered a fault with at least one of its sensors.	O

Value	Name	Summary	Conformance
3	ResettableOverTemp	The Node has encoun tered an over-tempera ture fault that is reset table.	O
4	NonReset tableOverTemp	The Node has encoun tered an over-tempera ture fault that is not resettable.	O
5	PowerSource	The Node has encoun tered a fault with at least one of its power sources.	O
6	VisualDisplayFault	The Node has encoun tered a fault with at least one of its visual displays.	O
7	AudioOutputFault	The Node has encoun tered a fault with at least one of its audio outputs.	O
8	UserInterfaceFault	The Node has encoun tered a fault with at least one of its user interfaces.	O
9	NonVolatileMemory Error	The Node has encoun tered a fault with its non-volatile memory.	O
10	TamperDetected	The Node has encoun tered disallowed physi cal tampering.	O

11.11.4.2. RadioFaultEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	The Node has encoun tered an unspecified radio fault.	M
1	WiFiFault	The Node has encoun tered a fault with its Wi-Fi radio.	O

Value	Name	Summary	Conformance
2	CellularFault	The Node has encoun tered a fault with its cellular radio.	O
3	ThreadFault	The Node has encoun tered a fault with its 802.15.4 radio.	O
4	NFCFault	The Node has encoun tered a fault with its NFC radio.	O
5	BLEFault	The Node has encoun tered a fault with its BLE radio.	O
6	EthernetFault	The Node has encoun tered a fault with its Ethernet controller.	O

11.11.4.3. NetworkFaultEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	The Node has encoun tered an unspecified fault.	M
1	HardwareFailure	The Node has encoun tered a network fault as a result of a hardware failure.	O
2	NetworkJammed	The Node has encoun tered a network fault as a result of a jammed network.	O
3	ConnectionFailed	The Node has encoun tered a network fault as a result of a failure to establish a connection.	O

11.11.4.4. InterfaceTypeEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	Indicates an interface of an unspecified type.	M
1	WiFi	Indicates a Wi-Fi inter face.	O
2	Ethernet	Indicates a Ethernet interface.	O
3	Cellular	Indicates a Cellular interface.	O
4	Thread	Indicates a Thread interface.	O

11.11.4.5. BootReasonEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	The Node is unable to identify the Power-On reason as one of the other provided enu meration values.	M
1	PowerOnReboot	The Node has booted as the result of physical interaction with the device resulting in a reboot.	M
2	BrownOutReset	The Node has rebooted as the result of a brown-out of the Node’s power supply.	M
3	SoftwareWatchdogRe set	The Node has rebooted as the result of a soft ware watchdog timer.	M
4	HardwareWatchdo gReset	The Node has rebooted as the result of a hard ware watchdog timer.	M
5	SoftwareUpdateCom pleted	The Node has rebooted as the result of a com pleted software update.	M
6	SoftwareReset	The Node has rebooted as the result of a soft ware initiated reboot.	M

11.11.4.6. NetworkInterface

This structure describes a network interface supported by the Node, as provided in the NetworkIn terfaces attribute.

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	Name	string	max 32			R V	M
1	IsOpera tional	bool				R V	M
2	Off Premis eServices Reach ableIPv4	bool		X	null	R V	M
3	Off Premis eServices Reach ableIPv6	bool		X	null	R V	M
4	Hard wareAd dress	Hardware Address				R V	M
5	IPv4Ad dresses	list[ipv4ad r]	max 4			R V	M
6	IPv6Ad dresses	list[ipv6ad r]	max 8			R V	M
7	Type	Interface TypeEnum				R V	M

Name Field

This field SHALL indicate a human-readable (displayable) name for the network interface, that is different from all other interfaces.

IsOperational Field

This field SHALL indicate if the Node is currently advertising itself operationally on this network interface and is capable of successfully receiving incoming traffic from other Nodes.

OffPremiseServicesReachableIPv4 Field

This field SHALL indicate whether the Node is currently able to reach off-premise services it uses by utilizing IPv4. The value SHALL be null if the Node does not use such services or does not know whether it can reach them.

OffPremiseServicesReachableIPv6 Field

This field SHALL indicate whether the Node is currently able to reach off-premise services it uses by utilizing IPv6. The value SHALL be null if the Node does not use such services or does not know whether it can reach them.

HardwareAddress Field

This field SHALL contain the current link-layer address for a 802.3 or IEEE 802.11-2020 network interface and contain the current extended MAC address for a 802.15.4 interface. The byte order of the octstr SHALL be in wire byte order. For addresses values less than 64 bits, the first two bytes SHALL be zero.

IPv4Addresses Field

This field SHALL provide a list of the IPv4 addresses that are currently assigned to the network interface.

IPv6Addresses Field

This field SHALL provide a list of the unicast IPv6 addresses that are currently assigned to the net work interface. This list SHALL include the Node’s link-local address and SHOULD include any assigned GUA and ULA addresses. This list SHALL NOT include any multicast group addresses to which the Node is subscribed.

Type Field

This field SHALL indicate the type of the interface using the InterfaceTypeEnum.

11.11.5. Status Codes

Status Code	Value	Summary
0x02	EnableKeyMismatch	Provided EnableKey does not match the previously config ured value.

11.11.6. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	Network Interfaces	list[Net workInter face]	max 8			R V	M
0x0001	Reboot Count	uint16		N		R V	M
0x0002	UpTime	uint64		C		R V	O

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0003	TotalOper ational Hours	uint32		N C		R V	O
0x0004	BootRea son	BootReaso nEnum				R V	O
0x0005	Active Hardware Faults	list[Hard wareFault Enum]	max 11			R V	O
0x0006	ActiveRa dioFaults	list[Radio Fault Enum]	max 7			R V	O
0x0007	ActiveNet work Faults	list[Net workFault Enum]	max 4			R V	O
0x0008	TestEvent Trig gersEn abled	bool	all			R V	M

11.11.6.1. NetworkInterfaces Attribute

The NetworkInterfaces attribute SHALL be a list of NetworkInterface structs. Each logical network interface on the Node SHALL be represented by a single entry within the NetworkInterfaces attribute.

11.11.6.2. RebootCount Attribute

The RebootCount attribute SHALL indicate a best-effort count of the number of times the Node has rebooted. The RebootCount attribute SHOULD be incremented each time the Node reboots. The RebootCount attribute SHALL NOT be incremented when a Node wakes from a low-power or sleep state. The RebootCount attribute SHALL only be reset to 0 upon a factory reset of the Node.

11.11.6.3. UpTime Attribute

The UpTime attribute SHALL indicate a best-effort assessment of the length of time, in seconds, since the Node’s last reboot. The UpTime attribute SHOULD be incremented to account for the peri ods of time that a Node is in a low-power or sleep state. The UpTime attribute SHALL only be reset upon a device reboot.

11.11.6.4. TotalOperationalHours Attribute

The TotalOperationalHours attribute SHALL indicate a best-effort attempt at tracking the length of time, in hours, that the Node has been operational. The TotalOperationalHours attribute SHOULD be incremented to account for the periods of time that a Node is in a low-power or sleep state. The

TotalOperationalHours attribute SHALL only be reset upon a factory reset of the Node.

11.11.6.5. BootReason Attribute

The BootReason attribute SHALL indicate the reason for the Node’s most recent boot.

11.11.6.6. ActiveHardwareFaults Attribute

The ActiveHardwareFaults attribute SHALL indicate the set of faults currently detected by the Node. When the Node detects a fault has been raised, the appropriate HardwareFaultEnum value SHALL be added to this list. This list SHALL NOT contain more than one instance of a specific Hard wareFaultEnum value. When the Node detects that all conditions contributing to a fault has been cleared, the corresponding HardwareFaultEnum value SHALL be removed from this list. An empty list SHALL indicate there are currently no active faults. The order of this list SHOULD have no sig nificance. Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or they MAY subscribe to HardwareFaultChange.

11.11.6.7. ActiveRadioFaults Attribute

The ActiveRadioFaults attribute SHALL indicate the set of faults currently detected by the Node. When the Node detects a fault has been raised, the appropriate RadioFaultEnum value SHALL be added to this list. This list SHALL NOT contain more than one instance of a specific RadioFaultEnum value. When the Node detects that all conditions contributing to a fault has been cleared, the corre sponding RadioFaultEnum value SHALL be removed from this list. An empty list SHALL indicate there are currently no active faults. The order of this list SHOULD have no significance. Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or they MAY sub scribe to RadioFaultChange.

11.11.6.8. ActiveNetworkFaults Attribute

The ActiveNetworkFaults attribute SHALL indicate the set of faults currently detected by the Node. When the Node detects a fault has been raised, the appropriate NetworkFaultEnum value SHALL be added to this list. This list SHALL NOT contain more than one instance of a specific NetworkFault Enum value. When the Node detects that all conditions contributing to a fault has been cleared, the corresponding NetworkFaultEnum value SHALL be removed from this list. An empty list SHALL indicate there are currently no active faults. The order of this list SHOULD have no significance. Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or they MAY subscribe to NetworkFaultChange.

11.11.6.9. TestEventTriggersEnabled Attribute

The TestEventTriggersEnabled attribute SHALL indicate whether the Node has any TestEventTrig ger configured. When this attribute is true, the Node has been configured with one or more test event triggers by virtue of the internally programmed EnableKey value (see Section 11.11.7.1, “TestEventTrigger Command”) being set to a non-zero value. This attribute can be used by Adminis trators to detect if a device was inadvertently commissioned with test event trigger mode enabled, and take appropriate action (e.g. warn the user and/or offer to remove all fabrics on the Node).

11.11.7. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	TestEventTrig ger	client ⇒ server	Y	M	M

11.11.7.1. TestEventTrigger Command

This command SHALL be supported to provide a means for certification tests to trigger some test- plan-specific events, necessary to assist in automation of device interactions for some certification test cases. This command SHALL NOT cause any changes to the state of the device that persist after the last fabric is removed.

The fields for the TestEventTrigger command are as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	EnableKey	octstr	16			M
1	EventTrig ger	uint64				M

EnableKey Field

The EnableKey is a 128 bit value provided by the client in this command, which needs to match a value chosen by the manufacturer and configured on the server using manufacturer-specific means, such as pre-provisioning. The value of all zeroes is reserved to indicate that no EnableKey is set. Therefore, if the EnableKey field is received with all zeroes, this command SHALL FAIL with a response status of CONSTRAINT_ERROR.

The EnableKey SHOULD be unique per exact set of devices going to a certification test.

Devices not targeted towards going to a certification test event SHALL NOT have a non-zero EnableKey value configured, so that only devices in test environments are responsive to this com mand.

In order to prevent unwittingly actuating a particular trigger, this command SHALL respond with the cluster-specific error status code EnableKeyMismatch if the EnableKey field does not match the a-priori value configured on the device.

EventTrigger Field

This field SHALL indicate the test or test mode which the client wants to trigger.

The expected side-effects of EventTrigger values are out of scope of this specification and will be described within appropriate certification test literature provided to manufacturers by the Connec tivity Standards Alliance, in conjunction with certification test cases documentation.

Values of EventTrigger in the range 0xFFFF_FFFF_0000_0000 through 0xFFFF_FFFF_FFFF_FFFF are reserved for testing use by manufacturers and will not appear in CSA certification test literature.

If the value of EventTrigger received is not supported by the receiving Node, this command SHALL fail with a status code of INVALID_COMMAND.

Otherwise, if the EnableKey value matches the configured internal value for a particular Node, and the EventTrigger value matches a supported test event trigger value, the command SHALL succeed and execute the expected trigger action.

If no specific test event triggers are required to be supported by certification test requirements for the features that a given product will be certified against, this command MAY always fail with the INVALID_COMMAND status, equivalent to the situation of receiving an unknown EventTrigger, for all possible EventTrigger values.

11.11.8. Events

ID	Name	Priority	Access	Conformance
0x00	HardwareFault Change	CRITICAL	V	O
0x01	RadioFault Change	CRITICAL	V	O
0x02	NetworkFault Change	CRITICAL	V	O
0x03	BootReason	CRITICAL	V	M

11.11.8.1. HardwareFaultChange Event

The HardwareFaultChange Event SHALL indicate a change in the set of hardware faults currently detected by the Node.

The data of this event SHALL contain the following information:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Current	list[Hard wareFault Enum]	max 11			M
1	Previous	list[Hard wareFault Enum]	max 11			M

Current Field

This field SHALL represent the set of faults currently detected, as per Section 11.11.4.1, “Hardware FaultEnum”.

Previous Field

This field SHALL represent the set of faults detected prior to this change event, as per Section

11.11.4.1, “HardwareFaultEnum”.

11.11.8.2. RadioFaultChange Event

The RadioFaultChange Event SHALL indicate a change in the set of radio faults currently detected by the Node.

The data of this event SHALL contain the following information:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Current	list[Radio FaultEnum]	max 7			M
1	Previous	list[Radio FaultEnum]	max 7			M

Current Field

This field SHALL represent the set of faults currently detected, as per Section 11.11.4.2, “RadioFault Enum”.

Previous Field

This field SHALL represent the set of faults detected prior to this change event, as per Section 11.11.4.2, “RadioFaultEnum”.

11.11.8.3. NetworkFaultChange Event

The NetworkFaultChange Event SHALL indicate a change in the set of network faults currently detected by the Node.

The data of this event SHALL contain the following information:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Current	list[Network FaultEnum]	max 4			M
1	Previous	list[Network FaultEnum]	max 4			M

Current Field

This field SHALL represent the set of faults currently detected, as per Section 11.11.4.3, “Network FaultEnum”.

Previous Field

This field SHALL represent the set of faults detected prior to this change event, as per Section 11.11.4.3, “NetworkFaultEnum”.

11.11.8.4. BootReason Event

The BootReason Event SHALL indicate the reason that caused the device to start-up. The data of this event SHALL contain the following information:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	BootReason	BootReaso nEnum				M

BootReason Field

This field SHALL contain the reason for this BootReason event.

11.12. Software Diagnostics Cluster

The Software Diagnostics Cluster provides a means to acquire standardized diagnostics metrics that MAY be used by a Node to assist a user or Administrator in diagnosing potential problems. The Soft ware Diagnostics Cluster attempts to centralize all metrics that are relevant to the software that may be running on a Node.

11.12.1. Revision History

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

Revision	Description
1	Initial Release

11.12.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	DGSW

11.12.3. Cluster ID

ID	Name
0x0034	Software Diagnostics

Features

Bit	Code	Feature	Summary
0	WTRMRK	Watermarks	Node makes available the metrics for high watermark related to memory consumption.

Data Types

11.12.5.1. ThreadMetricsStruct

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	ID	uint64	all				M
1	Name	string	max 8		empty		O
2	Stack FreeCur rent	uint32	all		MS		O
3	Stack FreeMini mum	uint32	all		MS		O
4	StackSize	uint32	all		MS		O

ID Field

The Id field SHALL be a server-assigned per-thread unique ID that is constant for the duration of the thread. Efforts SHOULD be made to avoid reusing ID values when possible.

Name Field

The Name field SHALL be set to a vendor defined name or prefix of the software thread that is sta tic for the duration of the thread.

StackFreeCurrent Field

The StackFreeCurrent field SHALL indicate the current amount of stack memory, in bytes, that are not being utilized on the respective thread.

StackFreeMinimum Field

The StackFreeMinimum field SHALL indicate the minimum amount of stack memory, in bytes, that has been available at any point between the current time and this attribute being reset or initial ized on the respective thread. This value SHALL only be reset upon a Node reboot or upon receiv ing of the ResetWatermarks command.

StackSize Field

The StackSize field SHALL indicate the amount of stack memory, in bytes, that has been allocated

for use by the respective thread.

11.12.6. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	Thread Metrics	list[Thread Metric sStruct]	max 64			R V	O
0x0001	Cur rentHeapF ree	uint64				R V	O
0x0002	Cur rentHea pUsed	uint64				R V	O
0x0003	Cur rentHeap HighWa termark	uint64				R V	WTRMRK

11.12.6.1. ThreadMetrics Attribute

The ThreadMetrics attribute SHALL be a list of ThreadMetricsStruct structs. Each active thread on the Node SHALL be represented by a single entry within the ThreadMetrics attribute.

11.12.6.2. CurrentHeapFree Attribute

The CurrentHeapFree attribute SHALL indicate the current amount of heap memory, in bytes, that are free for allocation. The effective amount MAY be smaller due to heap fragmentation or other reasons.

11.12.6.3. CurrentHeapUsed Attribute

The CurrentHeapUsed attribute SHALL indicate the current amount of heap memory, in bytes, that is being used.

11.12.6.4. CurrentHeapHighWatermark Attribute

The CurrentHeapHighWatermark attribute SHALL indicate the maximum amount of heap memory, in bytes, that has been used by the Node. This value SHALL only be reset upon a Node reboot or upon receiving of the ResetWatermarks command.

11.12.7. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	ResetWater marks	Client ⇒ Server	Y	M	WTRMRK

11.12.7.1. ResetWatermarks Command

Receipt of this command SHALL reset the following values which track high and lower watermarks:

The StackFreeMinimum field of the ThreadMetrics attribute
The CurrentHeapHighWatermark attribute This command has no

Effect on Receipt

On receipt of this command, the Node SHALL make the following modifications to attributes it sup ports:

If implemented, the server SHALL set the value of the CurrentHeapHighWatermark attribute to the value of the CurrentHeapUsed attribute.

If implemented, the server SHALL set the value of the StackFreeMinimum field for every thread to the value of the corresponding thread’s StackFreeCurrent field.

11.12.8. Events

ID	Name	Priority	Access	Conformance
0x00	SoftwareFault	INFO	V	O

11.12.8.1. SoftwareFault Event

The SoftwareFault Event SHALL be generated when a software fault takes place on the Node. The event’s data are as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	ID	uint64	all		0	M
1	Name	string	max 8		empty	O
2	Fault Recording	octstr	max 1024		empty	O

ID Field

The ID field SHALL be set to the ID of the software thread in which the last software fault occurred.

Name Field

The Name field SHALL be set to a manufacturer-specified name or prefix of the software thread in which the last software fault occurred.

FaultRecording Field

The FaultRecording field SHALL be a manufacturer-specified payload intended to convey informa tion to assist in further diagnosing or debugging a software fault. The FaultRecording field MAY be used to convey information such as, but not limited to, thread backtraces or register contents.

11.13. Thread Network Diagnostics Cluster

The Thread Network Diagnostics Cluster provides a means to acquire standardized diagnostics met rics that MAY be used by a Node to assist a user or Administrator in diagnosing potential problems. The Thread Network Diagnostics Cluster attempts to centralize all metrics that are relevant to a potential Thread radio running on a Node.

11.13.1. Revision History

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

Revision	Description
1	Initial Release

11.13.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	DGTHREAD

Cluster ID

ID	Name
0x0035	Thread Network Diagnostics

Features

Bit	Code	Feature	Summary
0	PKTCNT	PacketCounts	Server supports the counts for the number of received and trans mitted packets on the Thread interface.

Bit	Code	Feature	Summary
1	ERRCNT	ErrorCounts	Server supports the counts for the number of errors that have occurred during the reception and transmis sion of packets on the Thread interface.
2	MLECNT	MLECounts	Server supports the counts for various MLE layer happenings.
3	MACCNT	MACCounts	Server supports the counts for various MAC layer happenings.

Data Types

11.13.5.1. NetworkFaultEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	Indicates an unspeci fied fault.	M
1	LinkDown	Indicates the Thread link is down.	M
2	HardwareFailure	Indicates there has been Thread hardware failure.	M
3	NetworkJammed	Indicates the Thread network is jammed.	M

11.13.5.2. ConnectionStatusEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Connected	Node is connected	M
1	NotConnected	Node is not connected	M

11.13.5.3. RoutingRoleEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	Unspecified routing role.	M
1	Unassigned	The Node does not cur rently have a role as a result of the Thread interface not currently being configured or operational.	M
2	SleepyEndDevice	The Node acts as a Sleepy End Device with RX-off-when-idle sleepy radio behavior.	M
3	EndDevice	The Node acts as an End Device without RX- off-when-idle sleepy radio behavior.	M
4	REED	The Node acts as an Router Eligible End Device.	M
5	Router	The Node acts as a Router Device.	M
6	Leader	The Node acts as a Leader Device.	M

11.13.5.4. NeighborTableStruct

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	ExtAd dress	uint64	all				M
1	Age	uint32	all				M
2	Rloc16	uint16	all				M
3	Link Frame Counter	uint32	all				M
4	MleFrame Counter	uint32	all				M
5	LQI	uint8	0 to 255				M
6	Aver ageRssi	int8	-128 to 0	X	null		M

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
7	LastRssi	int8	-128 to 0	X	null		M
8	FrameEr rorRate	uint8	0 to 100		0		O
9	Mes sageError Rate	uint8	0 to 100		0		O
10	RxOn WhenIdle	bool	all				M
11	FullThrea dDevice	bool	all				M
12	FullNet workData	bool	all				M
13	IsChild	bool	all				M

ExtAddress Field

This field SHALL specify the IEEE 802.15.4 extended address for the neighboring Node.

Age Field

This field SHALL specify the duration of time, in seconds, since a frame has been received from the neighboring Node.

Rloc16 Field

This field SHALL specify the RLOC16 of the neighboring Node.

LinkFrameCounter Field

This field SHALL specify the number of link layer frames that have been received from the neigh boring node. This field SHALL be reset to 0 upon a reboot of the Node.

MleFrameCounter Field

This field SHALL specify the number of Mesh Link Establishment frames that have been received from the neighboring node. This field SHALL be reset to 0 upon a reboot of the Node.

LQI Field

This field SHALL specify the implementation specific mix of IEEE 802.15.4 PDU receive quality indi cators, scaled from 0 to 255.

AverageRssi Field

This field SHOULD specify the average RSSI across all received frames from the neighboring Node since the receiving Node’s last reboot. If there is no known received frames this field SHOULD have

the value of null. This field SHALL have the units of dBm, having the range -128 dBm to 0 dBm.

LastRssi Field

This field SHALL specify the RSSI of the most recently received frame from the neighboring Node. If there is no known last received frame the LastRssi field SHOULD have the value of null. This field SHALL have the units of dBm, having the range -128 dBm to 0 dBm.

FrameErrorRate Field

This field SHALL specify the percentage of received frames from the neighboring Node that have resulted in errors.

MessageErrorRate Field

This field SHALL specify the percentage of received messages from the neighboring Node that have resulted in errors.

RxOnWhenIdle Field

This field SHALL specify if the neighboring Node is capable of receiving frames while the Node is in an idle state.

FullThreadDevice Field

This field SHALL specify if the neighboring Node is a full Thread device.

FullNetworkData Field

This field SHALL specify if the neighboring Node requires the full Network Data. If set to False, the neighboring Node only requires the stable Network Data.

IsChild Field

This field SHALL specify if the neighboring Node is a direct child of the Node reporting the Neigh borTable attribute.

11.13.5.5. RouteTableStruct

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	ExtAd dress	uint64					M
1	Rloc16	uint16					M
2	RouterId	uint8					M
3	NextHop	uint8					M
4	PathCost	uint8					M
5	LQIIn	uint8					M

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
6	LQIOut	uint8					M
7	Age	uint8					M
8	Allocated	bool					M
9	LinkEstab lished	bool					M

ExtAddress Field

This field SHALL specify the IEEE 802.15.4 extended address for the Node for which this route table entry corresponds.

Rloc16 Field

This field SHALL specify the RLOC16 for the Node for which this route table entry corresponds.

RouterId Field

This field SHALL specify the Router ID for the Node for which this route table entry corresponds.

NextHop Field

This field SHALL specify the Router ID for the next hop in the route to the Node for which this route table entry corresponds.

PathCost Field

This Field SHALL specify the cost of the route to the Node for which this route table entry corre sponds.

LQIIn Field

This field SHALL specify the implementation specific mix of IEEE 802.15.4 PDU receive quality indi cators, scaled from 0 to 255, from the perspective of the Node reporting the neighbor table.

LQIOut Field

This field SHALL specify the implementation specific mix of IEEE 802.15.4 PDU receive quality indi cators, scaled from 0 to 255, from the perspective of the Node specified within the NextHop field.

Age Field

This field SHALL specify the duration of time, in seconds, since a frame has been received from the Node for which this route table entry corresponds.

Allocated Field

This field SHALL specify if the router ID as defined within the RouterId field has been allocated.

LinkEstablished Field

This field SHALL specify if a link has been established to the Node for which this route table entry corresponds.

11.13.5.6. SecurityPolicy

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	Rotation Time	uint16					M
1	Flags	uint16					M

RotationTime Field

This field SHALL specify the interval of time, in hours, that Thread security keys are rotated. This attribute SHALL be null when there is no dataset configured.

Flags Field

This field SHALL specify the flags as specified in Thread 1.3.0 section 8.10.1.15. This attribute SHALL be null when there is no dataset configured.

11.13.5.7. OperationalDatasetComponents

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0	Active Timestam pPresent	bool					M
1	Pending Timestam pPresent	bool					M
2	Mas terKeyPre sent	bool					M
3	Network NamePre sent	bool					M
4	Extended PanIdPre sent	bool					M
5	MeshLo calPrefix Present	bool					M

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
6	DelayPre sent	bool					M
7	PanIdPre sent	bool					M
8	ChannelP resent	bool					M
9	PskcPre sent	bool					M
10	Security PolicyPre sent	bool					M
11	Channel MaskPre sent	bool					M

ActiveTimestampPresent Field

This field SHALL be True if the Node has an active timestamp present, else False.

PendingTimestampPresent Field

This field SHALL be True if the Node has a pending timestamp is present, else False.

MasterKeyPresent Field

This field SHALL be True if the Node has the Thread master key, else False.

NetworkNamePresent Field

This field SHALL be True if the Node has the Thread network’s name, else False.

ExtendedPanIdPresent Field

This field SHALL be True if the Node has an extended Pan ID, else False.

MeshLocalPrefixPresent Field

This field SHALL be True if the Node has the mesh local prefix, else False.

DelayPresent Field

This field SHALL be True if the Node has the Thread network delay set, else False.

PanIdPresent Field

This field SHALL be True if the Node has a Pan ID, else False.

ChannelPresent Field

This field SHALL be True if the Node has configured an operational channel for the Thread net work, else False.

PskcPresent Field

This field SHALL be True if the Node has been configured with the Thread network Pskc, else False.

SecurityPolicyPresent Field

This field SHALL be True if the Node has been configured with the Thread network security poli cies, else False.

ChannelMaskPresent Field

This field SHALL be True if the Node has available a mask of available channels, else False.

11.13.6. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	Channel	uint16	all	X		R V	M
0x0001	Routing Role	Routin gRoleEnum	all	X		R V	M
0x0002	Network Name	String	max 16	X		R V	M
0x0003	PanId	uint16	all	X		R V	M
0x0004	Extended PanId	uint64	all	X		R V	M
0x0005	MeshLo calPrefix	ipv6pre	all	X		R V	M
0x0006	Overrun Count	uint64	all	C	0	R V	ERRCNT
0x0007	Neigh borTable	list[Neigh borTa bleStruct]	all		[]	R V	M
0x0008	RouteTabl e	list[RouteT ableStruct]	all		[]	R V	M
0x0009	Parti tionId	uint32	all	X		R V	M
0x000a	Weighting	uint8	all	X		R V	M
0x000b	DataVer sion	uint8	all	X		R V	M

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x000c	Stable DataVer sion	uint8	all	X		R V	M
0x000d	Leader RouterId	uint8	all	X		R V	M
0x000e	DetachedR oleCount	uint16	all	C	0	R V	[MLECNT]
0x000f	ChildRole Count	uint16	all	C	0	R V	[MLECNT]
0x0010	Router RoleCount	uint16	all	C	0	R V	[MLECNT]
0x0011	Leader RoleCount	uint16	all	C	0	R V	[MLECNT]
0x0012	AttachAt tempt Count	uint16	all	C	0	R V	[MLECNT]
0x0013	Partition IdChange Count	uint16	all	C	0	R V	[MLECNT]
0x0014	BetterPar titionAt tachAt tempt Count	uint16	all	C	0	R V	[MLECNT]
0x0015	Par entChange Count	uint16	all	C	0	R V	[MLECNT]
0x0016	TxTotal Count	uint32	all	C	0	R V	[MACCNT]
0x0017	TxUnicast Count	uint32	all	C	0	R V	[MACCNT]
0x0018	TxBroad castCount	uint32	all	C	0	R V	[MACCNT]
0x0019	TxAckRe quested Count	uint32	all	C	0	R V	[MACCNT]
0x001a	TxAcked Count	uint32	all	C	0	R V	[MACCNT]

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x001b	TxNoAck Request edCount	uint32	all	C	0	R V	[MACCNT]
0x001c	TxData Count	uint32	all	C	0	R V	[MACCNT]
0x001d	TxDat aPoll Count	uint32	all	C	0	R V	[MACCNT]
0x001e	TxBeacon Count	uint32	all	C	0	R V	[MACCNT]
0x001f	TxBeacon Request Count	uint32	all	C	0	R V	[MACCNT]
0x0020	TxOther Count	uint32	all	C	0	R V	[MACCNT]
0x0021	TxRetryCo unt	uint32	all	C	0	R V	[MACCNT]
0x0022	TxDirect MaxRetry Ex piryCount	uint32	all	C	0	R V	[MACCNT]
0x0023	TxIndi rect MaxRetry Ex piryCount	uint32	all	C	0	R V	[MACCNT]
0x0024	TxErrCca Count	uint32	all	C	0	R V	[MACCNT]
0x0025	TxErrAbo rtCount	uint32	all	C	0	R V	[MACCNT]
0x0026	TxEr rBusy Channel Count	uint32	all	C	0	R V	[MACCNT]
0x0027	RxTotal Count	uint32	all	C	0	R V	[MACCNT]
0x0028	RxUnicast Count	uint32	all	C	0	R V	[MACCNT]

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0029	RxBroad castCount	uint32	all	C	0	R V	[MACCNT]
0x002a	RxData Count	uint32	all	C	0	R V	[MACCNT]
0x002b	RxDat aPoll Count	uint32	all	C	0	R V	[MACCNT]
0x002c	RxBeacon Count	uint32	all	C	0	R V	[MACCNT]
0x002d	RxBeacon Request Count	uint32	all	C	0	R V	[MACCNT]
0x002e	RxOther Count	uint32	all	C	0	R V	[MACCNT]
0x002f	RxAd dressFil tered Count	uint32	all	C	0	R V	[MACCNT]
0x0030	RxDestAd drFil tered Count	uint32	all	C	0	R V	[MACCNT]
0x0031	RxDupli cated Count	uint32	all	C	0	R V	[MACCNT]
0x0032	RxEr rNoFrame Count	uint32	all	C	0	R V	[MACCNT]
0x0033	RxErrUnk nown Neighbor Count	uint32	all	C	0	R V	[MACCNT]
0x0034	RxErrIn valid ScrAddr Count	uint32	all	C	0	R V	[MACCNT]
0x0035	RxErrSec Count	uint32	all	C	0	R V	[MACCNT]
0x0036	RxErrFc sCount	uint32	all	C	0	R V	[MACCNT]

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0037	RxEr rOther Count	uint32	all	C	0	R V	[MACCNT]
0x0038	Active Timestam p	uint64	all	X	0	R V	O
0x0039	Pending Timestam p	uint64	all	X	0	R V	O
0x003a	Delay	uint32	all	X	0	R V	O
0x003b	Security Policy	Security Policy		X		R V	M
0x003c	Channel Page0 Mask	octstr	4	X		R V	M
0x003d	Opera tional Dataset Compo nents	Opera tional Dataset Compo nents		X		R V	M
0x003e	ActiveNet work Faults	list[Net workFault Enum]	max 4			R V	M

11.13.6.1. Channel Attribute

The Channel attribute SHALL indicate the 802.15.4 channel number configured on the Node’s Thread interface (that is, the Active Operational Dataset’s current Channel value). A value of null SHALL indicate that the Thread interface is not currently configured or operational.

11.13.6.2. RoutingRole Attribute

The RoutingRole attribute SHALL indicate the role that this Node has within the routing of mes sages through the Thread network, as defined by RoutingRoleEnum. The potential roles are defined in the following table. A value of null SHALL indicate that the Thread interface is not currently con figured or operational.

11.13.6.3. NetworkName Attribute

The NetworkName attribute SHALL indicate a human-readable (displayable) name for the Thread network that the Node has been configured to join to. A value of null SHALL indicate that the Thread interface is not currently configured or operational.

11.13.6.4. PanId Attribute

The PanId attribute SHALL indicate the 16-bit identifier of the Node on the Thread network. A value of null SHALL indicate that the Thread interface is not currently configured or operational.

11.13.6.5. ExtendedPanId Attribute

The ExtendedPanId attribute SHALL indicate the unique 64-bit identifier of the Node on the Thread network. A value of null SHALL indicate that the Thread interface is not currently configured or operational.

11.13.6.6. MeshLocalPrefix Attribute

The MeshLocalPrefix attribute SHALL indicate the mesh-local IPv6 prefix for the Thread network that the Node has been configured to join to. A value of null SHALL indicate that the Thread inter face is not currently configured or operational.

11.13.6.7. OverrunCount Attribute

The OverrunCount attribute SHALL indicate the number of packets dropped either at ingress or egress, due to lack of buffer memory to retain all packets on the ethernet network interface. The OverrunCount attribute SHALL be reset to 0 upon a reboot of the Node.

11.13.6.8. NeighborTable Attribute

The NeighborTable attribute SHALL indicate the current list of Nodes that comprise the neighbor table on the Node.

11.13.6.9. RouteTable Attribute

The RouteTable attribute SHALL indicate the current list of router capable Nodes for which routes have been established.

11.13.6.10. PartitionId Attribute

The PartitionId attribute SHALL indicate the Thread Leader Partition Id for the Thread network to which the Node is joined. This attribute SHALL be null if not attached to a Thread network.

11.13.6.11. Weighting Attribute

The Weighting attribute SHALL indicate the Thread Leader Weight used when operating in the Leader role. This attribute SHALL be null if not attached to a Thread network.

11.13.6.12. DataVersion Attribute

The DataVersion attribute SHALL indicate the full Network Data Version the Node currently uses. This attribute SHALL be null if not attached to a Thread network.

11.13.6.13. StableDataVersion Attribute

The StableDataVersion attribute SHALL indicate the Network Data Version for the stable subset of

data the Node currently uses. This attribute SHALL be null if not attached to a Thread network.

11.13.6.14. LeaderRouterId Attribute

The LeaderRouterId attribute SHALL indicate the 8-bit LeaderRouterId the Node shall attempt to utilize upon becoming a router or leader on the Thread network. This attribute SHALL be null if not attached to a Thread network.

11.13.6.15. DetachedRoleCount Attribute

The DetachedRoleCount attribute SHALL indicate the number of times the Node entered the OT_DE VICE_ROLE_DETACHED role as specified within the Thread specification. This value SHALL only be reset upon a Node reboot.

11.13.6.16. ChildRoleCount Attribute

The ChildRoleCount attribute SHALL indicate the number of times the Node entered the OT_DE VICE_ROLE_CHILD role as specified within the Thread specification. This value SHALL only be reset upon a Node reboot.

11.13.6.17. RouterRoleCount Attribute

The RouterRoleCount attribute SHALL indicate the number of times the Node entered the OT_DE VICE_ROLE_ROUTER role as specified within the Thread specification. This value SHALL only be reset upon a Node reboot.

11.13.6.18. LeaderRoleCount Attribute

The LeaderRoleCount attribute SHALL indicate the number of times the Node entered the OT_DE VICE_ROLE_LEADER role as specified within the Thread specification. This value SHALL only be reset upon a Node reboot.

11.13.6.19. AttachAttemptCount Attribute

The AttachAttemptCount attribute SHALL indicate the number of attempts that have been made to attach to a Thread network while the Node was detached from all Thread networks. This value SHALL only be reset upon a Node reboot.

11.13.6.20. PartitionIdChangeCount Attribute

The PartitionIdChangeCount attribute SHALL indicate the number of times that the Thread net work that the Node is connected to has changed its Partition ID. This value SHALL only be reset upon a Node reboot.

11.13.6.21. BetterPartitionAttachAttemptCount Attribute

The BetterPartitionAttachAttemptCount attribute SHALL indicate the number of times a Node has attempted to attach to a different Thread partition that it has determined is better than the parti tion it is currently attached to. This value SHALL only be reset upon a Node reboot.

11.13.6.22. ParentChangeCount Attribute

The ParentChangeCount attribute SHALL indicate the number of times a Node has changed its par ent. This value SHALL only be reset upon a Node reboot.

11.13.6.23. TxTotalCount Attribute

The TxTotalCount attribute SHALL indicate the total number of unique MAC frame transmission requests. The TxTotalCount attribute SHALL only be incremented by 1 for each MAC transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node reboot.

11.13.6.24. TxUnicastCount Attribute

The TxUnicastCount attribute SHALL indicate the total number of unique unicast MAC frame trans mission requests. The TxUnicastCount attribute SHALL only be incremented by 1 for each unicast MAC transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or retrans missions. This value SHALL only be reset upon a Node reboot.

11.13.6.25. TxBroadcastCount Attribute

The TxBroadcastCount attribute SHALL indicate the total number of unique broadcast MAC frame transmission requests. The TxBroadcastCount attribute SHALL only be incremented by 1 for each broadcast MAC transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node reboot.

11.13.6.26. TxAckRequestedCount Attribute

The TxAckRequestedCount attribute SHALL indicate the total number of unique MAC frame trans mission requests with requested acknowledgment. The TxAckRequestedCount attribute SHALL only be incremented by 1 for each MAC transmission request with requested acknowledgment regard less of the amount of CCA failures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node reboot.

11.13.6.27. TxAckedCount Attribute

The TxAckedCount attribute SHALL indicate the total number of unique MAC frame transmission requests that were acked. The TxAckedCount attribute SHALL only be incremented by 1 for each MAC transmission request that is acked regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node reboot.

11.13.6.28. TxNoAckRequestedCount Attribute

The TxNoAckRequestedCount attribute SHALL indicate the total number of unique MAC frame transmission requests without requested acknowledgment. The TxNoAckRequestedCount attribute SHALL only be incremented by 1 for each MAC transmission request that is does not request acknowledgement regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions.

11.13.6.29. TxDataCount Attribute

The TxDataCount attribute SHALL indicate the total number of unique MAC Data frame transmis sion requests. The TxDataCount attribute SHALL only be incremented by 1 for each MAC Data frame transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node reboot.

11.13.6.30. TxDataPollCount Attribute

The TxDataPollCount attribute SHALL indicate the total number of unique MAC Data Poll frame transmission requests. The TxDataPollCount attribute SHALL only be incremented by 1 for each MAC Data Poll frame transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node reboot.

11.13.6.31. TxBeaconCount Attribute

The TxBeaconCount attribute SHALL indicate the total number of unique MAC Beacon frame trans mission requests. The TxBeaconCount attribute SHALL only be incremented by 1 for each MAC Bea con frame transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions.

11.13.6.32. TxBeaconRequestCount Attribute

The TxBeaconRequestCount attribute SHALL indicate the total number of unique MAC Beacon Request frame transmission requests. The TxBeaconRequestCount attribute SHALL only be incre mented by 1 for each MAC Beacon Request frame transmission request regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node reboot.

11.13.6.33. TxOtherCount Attribute

The TxOtherCount attribute SHALL indicate the total number of unique MAC frame transmission requests that are not counted by any other attribute. The TxOtherCount attribute SHALL only be incremented by 1 for each MAC frame transmission request regardless of the amount of CCA fail ures, CSMA-CA attempts, or retransmissions. This value SHALL only be reset upon a Node reboot.

11.13.6.34. TxRetryCount Attribute

The TxRetryCount attribute SHALL indicate the total number of MAC retransmission attempts. The TxRetryCount attribute SHALL only be incremented by 1 for each retransmission attempt that may be triggered by lack of acknowledgement, CSMA/CA failure, or other type of transmission error. This value SHALL only be reset upon a Node reboot.

11.13.6.35. TxDirectMaxRetryExpiryCount Attribute

The TxDirectMaxRetryExpiryCount attribute SHALL indicate the total number of unique MAC transmission packets that meet maximal retry limit for direct packets. The TxDirectMaxRetryEx piryCount attribute SHALL only be incremented by 1 for each unique MAC transmission packets that meets the maximal retry limit for direct packets. This value SHALL only be reset upon a Node reboot.

11.13.6.36. TxIndirectMaxRetryExpiryCount Attribute

The TxIndirectMaxRetryExpiryCount attribute SHALL indicate the total number of unique MAC transmission packets that meet maximal retry limit for indirect packets. The TxIndirectMaxRetry ExpiryCount attribute SHALL only be incremented by 1 for each unique MAC transmission packets that meets the maximal retry limit for indirect packets. This value SHALL only be reset upon a Node reboot.

11.13.6.37. TxErrCcaCount Attribute

The TxErrCcaCount attribute SHALL indicate the total number of CCA failures. The TxErrCcaCount attribute SHALL only be incremented by 1 for each instance of a CCA failure. This value SHALL only be reset upon a Node reboot.

11.13.6.38. TxErrAbortCount Attribute

The TxErrAbortCount attribute SHALL indicate the total number of unique MAC transmission request failures caused by an abort error. The TxErrAbortCount attribute SHALL only be incre mented by 1 for each unique MAC transmission request failure caused by an abort error.

11.13.6.39. TxErrBusyChannelCount Attribute

The TxErrBusyChannelCount attribute SHALL indicate the total number of unique MAC transmis sion request failures caused by an error as the result of a busy channel (a CSMA/CA fail). The TxEr rBusyChannelCount attribute SHALL only be incremented by 1 for each unique MAC transmission request failure caused by a busy channel such as a CSMA/CA failure.

11.13.6.40. RxTotalCount Attribute

The RxTotalCount attribute SHALL indicate the total number of received unique MAC frames. This value SHALL only be reset upon a Node reboot.

11.13.6.41. RxUnicastCount Attribute

The RxUnicastCount attribute SHALL indicate the total number of received unique unicast MAC frames. This value SHALL only be reset upon a Node reboot.

11.13.6.42. RxBroadcastCount Attribute

The RxBroadcastCount attribute SHALL indicate the total number of received unique broadcast MAC frames. This value SHALL only be reset upon a Node reboot.

11.13.6.43. RxDataCount Attribute

The RxDataCount attribute SHALL indicate the total number of received unique MAC Data frames. This value SHALL only be reset upon a Node reboot.

11.13.6.44. RxDataPollCount Attribute

The RxDataPollCount attribute SHALL indicate the total number of received unique MAC Data Poll frames. This value SHALL only be reset upon a Node reboot.

11.13.6.45. RxBeaconCount Attribute

The RxBeaconCount attribute SHALL indicate the total number of received unique MAC Beacon frames. This value SHALL only be reset upon a Node reboot.

11.13.6.46. RxBeaconRequestCount Attribute

The RxBeaconRequestCount attribute SHALL indicate the total number of received unique MAC Beacon Request frames. This value SHALL only be reset upon a Node reboot.

11.13.6.47. RxOtherCount Attribute

The RxOtherCount attribute SHALL indicate the total number of received unique MAC frame requests that are not counted by any other attribute. This value SHALL only be reset upon a Node reboot.

11.13.6.48. RxAddressFilteredCount Attribute

The RxAddressFilteredCount attribute SHALL indicate the total number of received unique MAC frame requests that have been dropped as a result of MAC filtering. This value SHALL only be reset upon a Node reboot.

11.13.6.49. RxDestAddrFilteredCount Attribute

The RxDestAddrFilteredCount attribute SHALL indicate the total number of received unique MAC frame requests that have been dropped as a result of a destination address check. This value SHALL only be reset upon a Node reboot.

11.13.6.50. RxDuplicatedCount Attribute

The RxDuplicatedCount attribute SHALL indicate the total number of received MAC frame requests that have been dropped as a result of being a duplicate of a previously received MAC frame request. This value SHALL only be reset upon a Node reboot.

11.13.6.51. RxErrNoFrameCount Attribute

The RxErrNoFrameCount attribute SHALL indicate the total number of received unique MAC frame requests that have been dropped as a result of missing or malformed frame contents. This value SHALL only be reset upon a Node reboot.

11.13.6.52. RxErrUnknownNeighborCount Attribute

The RxErrUnknownNeighborCount attribute SHALL indicate the total number of received unique MAC frame requests that have been dropped as a result of originating from an unknown neighbor device. This value SHALL only be reset upon a Node reboot.

11.13.6.53. RxErrInvalidScrAddrCount Attribute

The RxErrInvalidScrAddrCount attribute SHALL indicate the total number of received unique MAC frame requests that have been dropped as a result of containing an invalid source address. This value SHALL only be reset upon a Node reboot.

11.13.6.54. RxErrSecCount Attribute

The RxErrSecCount attribute SHALL indicate the total number of received unique MAC frame requests that have been dropped as a result of an error with the security of the received frame. This value SHALL only be reset upon a Node reboot.

11.13.6.55. RxErrFcsCount Attribute

The RxErrFcsCount attribute SHALL indicate the total number of received unique MAC frame requests that have been dropped as a result of an error with the FCS of the received frame. This value SHALL only be reset upon a Node reboot.

11.13.6.56. RxErrOtherCount Attribute

The RxErrOtherCount attribute SHALL indicate the total number of received unique MAC frame requests that have been dropped as a result of an error that is not counted by any other attribute. This value SHALL only be reset upon a Node reboot.

11.13.6.57. ActiveTimestamp Attribute

This attribute SHALL be null when there is no dataset configured.

11.13.6.58. PendingTimestamp Attribute

This attribute SHALL be null when there is no dataset configured.

11.13.6.59. Delay Attribute

This attribute SHALL be null when there is no dataset configured.

11.13.6.60. SecurityPolicy Attribute

The SecurityPolicy attribute indicates the current security policies for the Thread partition to which a Node is connected. This attribute SHALL be null when there is no dataset configured.

11.13.6.61. ChannelPage0Mask Attribute

The ChannelPage0Mask attribute indicates the channels within channel page 0, in the 2.4GHz ISM band. The channels are represented in most significant bit order, with bit value 1 meaning selected, bit value 0 meaning unselected. For example, the most significant bit of the left-most byte indicates channel 0. If channel 0 and channel 10 are selected, the mask would be: 80 20 00 00. This attribute SHALL be null when there is no dataset configured.

11.13.6.62. OperationalDatasetComponents Attribute

The OperationalDatasetComponents attribute is a collection of flags to indicate the presence of vari ous operationally acquired values.

11.13.6.63. ActiveNetworkFaults Attribute

The ActiveNetworkFaults attribute SHALL indicate the set of faults currently detected by the Node.

When the Node detects a fault has been raised, the appropriate NetworkFaultEnum value SHALL be added to this list. This list SHALL NOT contain more than one instance of a specific NetworkFault Enum value. When the Node detects that all conditions contributing to a fault has been cleared, the corresponding NetworkFaultEnum value SHALL be removed from this list. An empty list SHALL indicate there are currently no active faults. The order of this list SHOULD have no significance. Clients interested in monitoring changes in active faults MAY subscribe to this attribute, or they MAY subscribe to NetworkFaultChange

11.13.7. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	ResetCounts	Client ⇒ Server	Y	M	ERRCNT

11.13.7.1. ResetCounts Command

Reception of this command SHALL reset the following attributes to 0:

OverrunCount

This command has no associated data. Upon completion, this command SHALL send a status code set to a value of SUCCESS back to the initiator.

11.13.8. Events

ID	Name	Priority	Access	Conformance
0x00	ConnectionStatus	INFO	V	O
0x01	NetworkFault Change	INFO	V	O

11.13.8.1. NetworkFaultChange Event

The NetworkFaultChange Event SHALL indicate a change in the set of network faults currently detected by the Node.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Current	list[Network FaultEnum]	max 4			M
1	Previous	list[Network FaultEnum]	max 4			M

Current Field

This field SHALL represent the set of faults currently detected, as per Section 11.13.5.1, “Network FaultEnum”.

Previous Field

This field SHALL represent the set of faults detected prior to this change event, as per Section 11.13.5.1, “NetworkFaultEnum”.

11.13.8.2. ConnectionStatus Event

The ConnectionStatus Event SHALL indicate that a Node’s connection status to a Thread network has changed.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Connection Status	Connection StatusEnum				M

11.14. Wi-Fi Network Diagnostics Cluster

The Wi-Fi Network Diagnostics Cluster provides a means to acquire standardized diagnostics met rics that MAY be used by a Node to assist a user or Administrator in diagnosing potential problems. The Wi-Fi Network Diagnostics Cluster attempts to centralize all metrics that are relevant to a potential Wi-Fi radio running on a Node.

11.14.1. Revision History

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

Revision	Description
1	Initial Release

11.14.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	DGWIFI

Cluster ID

ID	Name
0x0036	WiFi Network Diagnostics

Features

Bit	Code	Feature	Summary
0	PKTCNT	PacketCounts	Node makes available the counts for the num ber of received and transmitted packets on the Wi-Fi interface.
1	ERRCNT	ErrorCounts	Node makes available the counts for the num ber of errors that have occurred during the reception and transmis sion of packets on the Wi-Fi interface.

Data Types

11.14.5.1. SecurityTypeEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unspecified	Indicate the usage of an unspecified Wi-Fi secu rity type	M
1	None	Indicate the usage of no Wi-Fi security	M
2	WEP	Indicate the usage of WEP Wi-Fi security	M
3	WPA	Indicate the usage of WPA Wi-Fi security	M
4	WPA2	Indicate the usage of WPA2 Wi-Fi security	M
5	WPA3	Indicate the usage of WPA3 Wi-Fi security	M

11.14.5.2. WiFiVersionEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	a	Indicate the network interface is currently using 802.11a against the wireless access point.	M
1	b	Indicate the network interface is currently using 802.11b against the wireless access point.	M
2	g	Indicate the network interface is currently using 802.11g against the wireless access point.	M
3	n	Indicate the network interface is currently using 802.11n against the wireless access point.	M
4	ac	Indicate the network interface is currently using 802.11ac against the wireless access point.	M
5	ax	Indicate the network interface is currently using 802.11ax against the wireless access point.	M

11.14.5.3. AssociationFailureCauseEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unknown	The reason for the fail ure is unknown.	M
1	AssociationFailed	An error occurred dur ing association.	M
2	AuthenticationFailed	An error occurred dur ing authentication.	M

Value	Name	Summary	Conformance
3	SsidNotFound	The specified SSID could not be found.	M

11.14.5.4. ConnectionStatusEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Connected	Indicate the node is connected	M
1	NotConnected	Indicate the node is not connected	M

11.14.6. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	BSSID	octstr	6	X	null	R V	M
0x0001	Security Type	Security TypeEnum	all	X	null	R V	M
0x0002	WiFiVer sion	WiFiVer sionEnum	all	X	null	R V	M
0x0003	Channel Number	uint16	all	X	null	R V	M
0x0004	RSSI	int8	-120 to 0	X C	null	R V	M
0x0005	Beacon LostCount	uint32	all	X C	0	R V	ERRCNT
0x0006	BeaconRx Count	uint32	all	X C	0	R V	PKTCNT
0x0007	PacketMul ticastRx Count	uint32	all	X C	0	R V	PKTCNT
0x0008	PacketMul ticastTx Count	uint32	all	X C	0	R V	PKTCNT
0x0009	PacketUni castRx Count	uint32	all	X C	0	R V	PKTCNT
0x000a	PacketUni castTx Count	uint32	all	X C	0	R V	PKTCNT

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x000b	Current MaxRate	uint64	all	X C	0	R V	O
0x000c	Overrun Count	uint64	all	X C	0	R V	ERRCNT

For all attributes listed above, a null value SHALL be returned if the interface is not currently con figured or operational.

11.14.6.1. BSSID Attribute

The BSSID attribute SHALL indicate the BSSID for which the Wi-Fi network the Node is currently connected.

11.14.6.2. SecurityType Attribute

The SecurityType attribute SHALL indicate the current type of Wi-Fi security used.

11.14.6.3. WiFiVersion Attribute

The WiFiVersion attribute SHALL indicate the current 802.11 standard version in use by the Node, per the table below.

11.14.6.4. ChannelNumber Attribute

The ChannelNumber attribute SHALL indicate the channel that Wi-Fi communication is currently operating on.

11.14.6.5. RSSI Attribute

The RSSI attribute SHALL indicate the current RSSI of the Node’s Wi-Fi radio in dBm.

11.14.6.6. BeaconLostCount Attribute

The BeaconLostCount attribute SHALL indicate the count of the number of missed beacons the Node has detected. If the Node does not have an ability to count beacons expected and not received, this value MAY remain set to zero.

11.14.6.7. BeaconRxCount Attribute

The BeaconRxCount attribute SHALL indicate the count of the number of received beacons. The total number of expected beacons that could have been received during the interval since associa tion SHOULD match the sum of BeaconRxCount and BeaconLostCount. If the Node does not have an ability to report count of beacons received, this value MAY remain set to zero.

11.14.6.8. PacketMulticastRxCount Attribute

The PacketMulticastRxCount attribute SHALL indicate the number of multicast packets received by

the Node.

11.14.6.9. PacketMulticastTxCount Attribute

The PacketMulticastTxCount attribute SHALL indicate the number of multicast packets transmitted by the Node.

11.14.6.10. PacketUnicastRxCount Attribute

The PacketUnicastRxCount attribute SHALL indicate the number of unicast packets received by the Node.

11.14.6.11. PacketUnicastTxCount Attribute

The PacketUnicastTxCount attribute SHALL indicate the number of unicast packets transmitted by the Node.

11.14.6.12. CurrentMaxRate Attribute

The CurrentMaxRate attribute SHALL indicate the current maximum PHY rate of transfer of data in bits-per-second.

11.14.6.13. OverrunCount Attribute

The OverrunCount attribute SHALL indicate the number of packets dropped either at ingress or egress, due to lack of buffer memory to retain all packets on the network interface. The Overrun Count attribute SHALL be reset to 0 upon a reboot of the Node.

11.14.7. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	ResetCounts	Client ⇒ Server	Y	O	ERRCNT

11.14.7.1. ResetCounts Command

Reception of this command SHALL reset the following attributes to 0:

BeaconLostCount
BeaconRxCount
PacketMulticastRxCount
PacketMulticastTxCount
PacketUnicastRxCount
PacketUnicastTxCount

This command has no associated data.

11.14.8. Events

ID	Name	Priority	Access	Conformance
0x00	Disconnection	info	V	O
0x01	AssociationFail ure	info	V	O
0x02	ConnectionStatus	info	V	O

11.14.8.1. Disconnection Event

The Disconnection Event SHALL indicate that a Node’s Wi-Fi connection has been disconnected as a result of de-authenticated or dis-association and indicates the reason.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	ReasonCode	uint16				M

ReasonCode Field

This field SHALL contain the Reason Code field value for the Disassociation or Deauthentication event that caused the disconnection and the value SHALL align with Table 9-49 “Reason codes” of IEEE 802.11-2020.

11.14.8.2. AssociationFailure Event

The AssociationFailure event SHALL indicate that a Node has attempted to connect, or reconnect, to a Wi-Fi access point, but is unable to successfully associate or authenticate, after exhausting all internal retries of its supplicant.

ID	Name	Type	Constraint	Conformance
0	AssociationFail ureCause	AssociationFail ureCauseEnum	all	M
1	Status	uint16	all	M

AssociationFailureCause Field

The Status field SHALL be set to a value from the AssociationFailureCauseEnum.

Status Field

The Status field SHALL be set to the Status Code value that was present in the last frame related to association where Status Code was not equal to zero and which caused the failure of a last trial attempt, if this last failure was due to one of the following Management frames:

Association Response (Type 0, Subtype 1)
Reassociation Response (Type 0, Subtype 3)

Authentication (Type 0, Subtype 11)

Table 9-50 “Status codes” of IEEE 802.11-2020 contains a description of all values possible.

11.14.8.3. ConnectionStatus Event

The ConnectionStatus Event SHALL indicate that a Node’s connection status to a Wi-Fi network has changed. Connected, in this context, SHALL mean that a Node acting as a Wi-Fi station is success fully associated to a Wi-Fi Access Point.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Connection Status	Connection StatusEnum				M

11.15. Ethernet Network Diagnostics Cluster

The Ethernet Network Diagnostics Cluster provides a means to acquire standardized diagnostics metrics that MAY be used by a Node to assist a user or Administrator in diagnosing potential prob lems. The Ethernet Network Diagnostics Cluster attempts to centralize all metrics that are relevant to a potential Ethernet connection to a Node.

11.15.1. Revision History

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

Revision	Description
1	Initial Release

11.15.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	DGETH

Cluster ID

ID	Name
0x0037	Ethernet Network Diagnostics

Features

Bit	Code	Feature	Summary
0	PKTCNT	PacketCounts	Node makes available the counts for the num ber of received and transmitted packets on the ethernet interface.
1	ERRCNT	ErrorCounts	Node makes available the counts for the num ber of errors that have occurred during the reception and transmis sion of packets on the ethernet interface.

Data Types

11.15.5.1. PHYRateEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Rate10M	PHY rate is 10Mbps	M
1	Rate100M	PHY rate is 100Mbps	M
2	Rate1G	PHY rate is 1Gbps	M
3	Rate2_5G	PHY rate is 2.5Gbps	M
4	Rate5G	PHY rate is 5Gbps	M
5	Rate10G	PHY rate is 10Gbps	M
6	Rate40G	PHY rate is 40Gbps	M
7	Rate100G	PHY rate is 100Gbps	M
8	Rate200G	PHY rate is 200Gbps	M
9	Rate400G	PHY rate is 400Gbps	M

11.15.6. Attributes

Name

Type

Constraint

Quality

Default

Access

Confor mance

0x0000

PHYRate

PHYRa

teEnum

all

null

R V

0x0001

FullDu plex

bool

all

null

R V

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0002	PacketRx Count	uint64	all		0	R V	PKTCNT
0x0003	PacketTx Count	uint64	all	C	0	R V	PKTCNT
0x0004	TxEr rCount	uint64	all	C	0	R V	ERRCNT
0x0005	Collision Count	uint64	all	C	0	R V	ERRCNT
0x0006	Overrun Count	uint64	all	C	0	R V	ERRCNT
0x0007	CarrierDe tect	bool	all	X C	null	R V	O
0x0008	TimeSin ceReset	uint64	all	C	0	R V	O

11.15.6.1. PHYRate Attribute

The PHYRate attribute SHALL indicate the current nominal, usable speed at the top of the physical layer of the Node. A value of null SHALL indicate that the interface is not currently configured or operational.

11.15.6.2. FullDuplex Attribute

The FullDuplex attribute SHALL indicate if the Node is currently utilizing the full-duplex operating mode. A value of null SHALL indicate that the interface is not currently configured or operational.

11.15.6.3. PacketRxCount Attribute

The PacketRxCount attribute SHALL indicate the number of packets that have been received on the ethernet network interface. The PacketRxCount attribute SHALL be reset to 0 upon a reboot of the Node.

11.15.6.4. PacketTxCount Attribute

The PacketTxCount attribute SHALL indicate the number of packets that have been successfully transferred on the ethernet network interface. The PacketTxCount attribute SHALL be reset to 0 upon a reboot of the Node.

11.15.6.5. TxErrCount Attribute

The TxErrCount attribute SHALL indicate the number of failed packet transmissions that have occurred on the ethernet network interface. The TxErrCount attribute SHALL be reset to 0 upon a reboot of the Node.

11.15.6.6. CollisionCount Attribute

The CollisionCount attribute SHALL indicate the number of collisions that have occurred while attempting to transmit a packet on the ethernet network interface. The CollisionCount attribute SHALL be reset to 0 upon a reboot of the Node.

11.15.6.7. OverrunCount Attribute

11.15.6.8. CarrierDetect Attribute

The CarrierDetect attribute SHALL indicate the value of the Carrier Detect control signal present on the ethernet network interface. A value of null SHALL indicate that the interface is not currently configured or operational.

11.15.6.9. TimeSinceReset Attributes

The TimeSinceReset attribute SHALL indicate the duration of time, in minutes, that it has been since the ethernet network interface has reset for any reason.

11.15.7. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	ResetCounts	Client ⇒ Server	Y	M	PKTCNT \| ERRCNT

11.15.7.1. ResetCounts Command

Reception of this command SHALL reset the following attributes to 0:

PacketRxCount
PacketTxCount
TxErrCount
CollisionCount
OverrunCount

This command has no associated data.

11.16. Time Synchronization Cluster

Accurate time is required for a number of reasons, including scheduling, display and validating security materials.

This section describes a mechanism for Nodes to achieve and maintain time synchronization. The Time Cluster provides attributes for reading a Node’s current time. It also allows Administrators to

set current time, time zone and daylight savings time (DST) settings.

NOTE Support for Time Synchronization is provisional.

11.16.1. Revision History

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

Revision	Description
1	Initial Release

11.16.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	TIMESYNC

Cluster ID

ID	Name
0x0038	Time Sync

Terminology

DNS-SD – Domain name service – service discovery RFC 6763 – DNS-Based Service Discovery [https://tools.ietf.org/html/rfc6763]

DST – Daylight Savings Time.

GNSS – Global Navigation Satellite System. This is a satellite system that provides global geo-spatial positioning. GNSS systems include the NAVSTAR global positioning system (GPS), Galileo, GLONASS and BeiDou.

NTP – Network Time Protocol RFC 5905 – Network Time Protocol Version 4: Protocol and Algorithms Specification [https://tools.ietf.org/html/rfc5905].

NTS – Network Time Security RFC 8915 – Network time security for the network time protocol [https://tools.ietf.org/html/rfc8915].

PTP – Precision Time Protocol IEEE 1588-2008 – IEEE Standard for a Precision Clock Synchronization Protocol for Networked Measurement and Control Systems [https://standards.ieee.org/standard/1588- 2008.html].

SNTP – Simple Network Time Protocol. This is a simplified version of the Network Time Protocol. It is also covered by RFC 5905 [https://tools.ietf.org/html/rfc5905].

11.16.5. Features

Bit	Code	Feature	Summary
0	TZ	TimeZone	Server supports time zone.
1	NTPC	NTPClient	Server supports an NTP or SNTP client.
2	NTPS	NTPServer	Server supports an NTP server role.

11.16.5.1. TimeZone

Allows a server to translate a UTC time to a local time using the time zone and daylight savings time (DST) offsets. If a server supports the TimeZone feature, it SHALL support the TimeZone and DSTOffset attributes (Section 11.16.8.6, “TimeZone Attribute” and Section 11.16.8.7, “DSTOffset Attribute”) and SHALL expose the local time through the LocalTime attribute (Section 11.16.8.8, “LocalTime Attribute”). Use of the Name Field in the TimeZone attribute is optional for display pur poses, but it is not used in the calculation of the LocalTime.

11.16.5.2. NTPClient

Allows a server to use NTP/SNTP for time synchronization.

11.16.5.3. NTPServer

Allows a Node to host an NTP server for the network so that other Nodes can achieve a high accu racy time sync within the network. See Section 11.16.15, “Acting as an NTP Server”.

11.16.6. Data Types

11.16.6.1. GranularityEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	NoTimeGranularity	This indicates that the server is not currently synchronized with a UTC Time source and its clock is based on the Last Known Good UTC Time only.	M

Value	Name	Summary	Conformance
1	MinutesGranularity	This indicates the server was synchro nized to an upstream source in the past, but sufficient clock drift has occurred such that the clock error is now > 5 seconds.	M
2	SecondsGranularity	This indicates the server is synchronized to an upstream source using a low resolution protocol. UTC Time is accurate to ± 5 seconds.	M
3	MillisecondsGranular ity	This indicates the server is synchronized to an upstream source using high resolution time-synchronization protocol such as NTP, or has built-in GNSS with some amount of jitter applying its GNSS timestamp. UTC Time is accurate to ± 50ms.	M
4	MicrosecondsGranu larity	This indicates the server is synchronized to an upstream source using a highly precise time-synchronization protocol such as PTP, or has built-in GNSS. UTC time is accurate to ± 10 μs.	M

11.16.6.2. TimeSourceEnum

This data type is derived from enum8.

Value	Name	Description	Conformance
0	None	Server is not currently synchronized with a UTC Time source.	M

Value	Name	Description	Conformance
1	Unknown	Server uses an unlisted time source.	M
2	Admin	Server received time from the Section 11.16.9.1, “SetUtcTime Command”.	M
3	NodeTimeCluster	Synchronized time by querying the Time Clus ter of another Node.	M
4	NonFabricSntp	SNTP from a server not in the Fabric. NTS is not used.	M
5	NonFabricNtp	NTP from servers not in the Fabric. None of the servers used NTS.	M
6	FabricSntp	SNTP from a server within the Fabric. NTS is not used.	M
7	FabricNtp	NTP from a servers within the Fabric. None of the servers used NTS.	M
8	MixedNtp	NTP from multiple servers on Fabric and external. None of the servers used NTS.	M
9	NonFabricSntpNts	SNTP from a server not in the Fabric. NTS is used.	M
10	NonFabricNtpNts	NTP from servers not in the Fabric. NTS is used on at least one server.	M
11	FabricSntpNts	SNTP from a server within the Fabric. NTS is used.	M
12	FabricNtpNts	NTP from a server within the Fabric. NTS is used on at least one server.	M

Value	Name	Description	Conformance
13	MixedNtpNts	NTP from multiple servers on the Fabric and external. NTS is used on at least one server.	M
14	CloudSource	Time synchronization comes from a vendor cloud-based source (e.g. “Date” header in authenticated HTTPS connection).	M
15	Ptp	Time synchronization comes from PTP.	M
16	Gnss	Time synchronization comes from a GNSS source.	M

11.16.6.3. TimeZoneStruct

ID	Name	Type	Constraint	Quality	Access	Default	Confor mance
0	Offset	int32	-43200 to 50400				M
1	ValidAt	epoch-us	all				M
2	Name	string	0 to 64				O

Offset Field

The time zone offset from UTC in seconds.

ValidAt Field

The UTC time when the offset SHALL be applied.

Name Field

The time zone name SHOULD provide a human-readable time zone name and it SHOULD use the country/city format specified by the IANA time zone database [https://www.iana.org/time-zones].

11.16.6.4. DSTOffsetStruct

ID	Name	Type	Constraint	Quality	Access	Default	Confor mance
0	Offset	int32	desc				M

ID	Name	Type	Constraint	Quality	Access	Default	Confor mance
1	ValidStart ing	epoch-us	all				M
2	ValidUntil	epoch-us	all				M

Offset Field

The DST offset in seconds. Normally this is in the range of 0 to 3600 seconds (1 hour), but this field will accept any values in the int32 range to accommodate potential future legislation that does not fit with these assumptions.

ValidStarting Field

The UTC time when the offset SHALL be applied.

ValidUntil Field

The UTC time when the offset SHALL stop being applied. This value SHALL be larger than the Valid Starting time.

11.16.7. Status Codes

Status Code	Value	Summary
0x02	TimeNotAccepted	Server rejected the attempt to set the UTC time

Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	UTCTime	epoch-us	all	X C	null	R V	M
0x0001	Granular ity	Granulari tyEnum	desc		NoTime Granular ity	R V	M
0x0002	Time Source	Time SourceEnu m	desc		None	R V	O
0x0003	TrustedTi meNodeId	node-id	all	X	null	RW VA	M
0x0004	Default Ntp	string	max 128	X	null	RW VA	NTPC
0x0005	TimeZone	list[Time Zon eStruct]	1 to 2		{0,0}	RW VM	TZ

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0006	DSTOffset	list[DSTOff setStruct]	max 20		{}	RW VM	TZ
0x0007	LocalTime	epoch-us	all	X C	0	R V	TZ
0x0008	TimeZone Database	bool	all	F	false	R V	TZ
0x0009	NtpServer Port	uint16	all	X	null	R V	NTPS

11.16.8.1. UTCTime Attribute

If the server has achieved time synchronization, this SHALL indicate the current time as a UTC epoch-us (Epoch Time in Microseconds).

If the server has not achieved time synchronization, this SHALL be null. This attribute MAY be set when a Section 11.16.9.1, “SetUtcTime Command” is received.

11.16.8.2. Granularity Attribute

The granularity of the error that the server is willing to guarantee on the time synchronization. It is of type GranularityEnum.

11.16.8.3. TimeSource Attribute

The server’s time source. This attribute indicates what method the server is using to sync, whether the source uses NTS or not and whether the source is internal or external to the Fabric. This attribute MAY be used by a client to determine its level of trust in the UTCTime. It is of type Time SourceEnum.

If a server is unsure if the selected NTP server is within the Fabric, it SHOULD indicate the server is NonFabric.

11.16.8.4. DefaultNtp Attribute

The default NTP server the server’s Node may use if other time sources are unavailable. This attribute may contain a domain name or a static IPv6 address in text format as specified in RFC 5952 [https://tools.ietf.org/html/rfc5952]. See Section 11.16.13, “Time source prioritization”. This attribute is writeable only by an Administrator. It SHOULD be set by the Commissioner during com missioning. If no default NTP is available, the Commissioner MAY set this value to null.

11.16.8.5. TrustedTimeNodeId Attribute

The Node ID of a trusted Time Cluster. The TrustedTimeNodeId Node is used as a check on external time sync sources and MAY be used as the primary time source if other time sources are unavail able. See Section 11.16.13, “Time source prioritization”. This attribute is writeable only by an Administrator. It SHOULD be set by the Commissioner during commissioning. If no appropriate TrustedTimeNodeId is available, the commissioner MAY set this value to null.

11.16.8.6. TimeZone Attribute

A list of time zone offsets from UTC and when they SHALL take effect. This attribute uses a list of time offset configurations to allow Nodes to handle scheduled regulatory time zone changes. This attribute SHALL NOT be used to indicate daylight savings time changes (see Section 11.16.8.7, “DSTOffset Attribute” for daylight savings time).

The first entry SHALL have a ValidAt entry of 0. If there is a second entry, it SHALL have a non-zero ValidAt time.

If a server supports a TimeZoneDatabase, the server MAY update its own DSTOffset list (Section 11.16.8.7, “DSTOffset Attribute”) to add new DST change times as required, based on the Name fields of the TimeZoneStruct. Administrators MAY add additional entries to the DSTOffset of other Nodes with the same time zone, if required.

If a server does not support a TimeZoneDatabase, the Name field of the TimeZoneStruct is only applicable for client-side localization. In particular:

If the server does not support a TimeZoneDatabase, the Name field SHALL NOT be used to cal culate the local
If the server does not support a TimeZoneDatabase, the Name field SHALL NOT be used to cal culate DST start or end

Upon writing this attribute, the server SHALL recompute its LocalTime, taking into account the Off set of the currently used TimeZoneStruct.

When time passes, the server SHOULD remove any entries which are no longer active and change the ValidAt time for the currently used TimeZoneStruct list item to zero.

11.16.8.7. DSTOffset Attribute

A list of offsets to apply for daylight savings time, and their validity period. List entries SHALL be sorted by ValidStarting time.

A list entry SHALL NOT have a ValidStarting time that is smaller than the ValidUntil time of the pre vious entry.

Upon writing this attribute, the server SHALL recompute its LocalTime.

This list MAY hold up to 20 entries. If a server does not have sufficient storage for 20 entries, it MAY truncate the list by removing entries with the largest ValidStarting times. The server SHALL reserve sufficient storage for at least one entry.

Over time, the server SHOULD remove any entries which are no longer active from the list.

Over time, if the server supports a TimeZoneDatabase, it MAY update its own list to add additional entries.

11.16.8.8. LocalTime Attribute

The computed current local time of the server as a epoch-us (Epoch Time in Microseconds). The local time offset of the value is the sum of the currently used TimeZoneEntry’s offset and the cur rently used DST offset, if any.

If the server has not achieved time synchronization, this SHALL be null.

11.16.8.9. TimeZoneDatabase Attribute

Indicates whether the server has access to a time zone database. Nodes with a time zone database MAY update their own DSTOffset attribute to add new entries and MAY push DSTOffset updates to other Nodes in the same time zone as required.

11.16.8.10. NtpServerPort Attribute

If the server is running an NTP server, this value SHALL be the port number for the service. If the server is not currently running an NTP server, this value SHALL be null.

This attribute SHALL be present if this server is capable of providing an NTP server instance. See Section 11.16.15, “Acting as an NTP Server” for more information.

11.16.9. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	SetUtcTime	Client ⇒ Server	Y	A	M

11.16.9.1. SetUtcTime Command

The data for this command are as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	UtcTime	epoch-us	all		0	M
1	Granularity	Granulari tyEnum	all		NoTime Granularity	M
2	TimeSource	Time SourceEnum	all		None	O

This command MAY be issued by Administrator to set the time. If the Commissioner does not have a valid time source, it MAY send a Granularity of NoTimeGranularity.

Upon receipt of this command, the server MAY update its UTCTime attribute to match the time spec ified in the command, if the stated Granularity and TimeSource are acceptable. The server SHALL update its UTCTime attribute if its current Granularity is NoTimeGranularity.

If the time is updated, the server SHALL also update its Granularity attribute as appropriate (nor mally to one level lower than the stated command Granularity, or to MinutesGranularity if the

server does not plan to maintain time). It SHALL also update its TimeSource attribute to Admin. It SHALL also update its last known good UTC time.

If the server updates its UTCTime attribute, it SHALL accept the command with a status code of SUCCESS. If it opts to not update its time, it SHALL fail the command with a cluster specific Status Code of TimeNotAccepted.

UtcTime Field

This SHALL give the Client’s UTC Time.

Granularity Field

This SHALL give the Client’s Granularity, as described in Section 11.16.8.2, “Granularity Attribute”.

TimeSource Field

This SHALL give the Client’s TimeSource, as described in Section 11.16.8.3, “TimeSource Attribute”.

11.16.10. Events

ID	Name	Priority	Access	Conformance
0x00	DSTTableEmpty	INFO	V	TZ
0x01	DSTStatus	INFO	V	TZ
0x02	TimeZoneStatus	INFO	V	TZ

11.16.10.1. DSTTableEmpty Event

This event SHALL be generated when the server stops applying the current DSTOffset and there are no entries in the list with a larger ValidStarting time, indicating the need to possibly get new DST data.

There is no data for this event.

11.16.10.2. DSTStatus Event

This event SHALL be generated when the server starts or stops applying a DST offset.

This event contains a boolean predicate that indicates whether the server is applying the DST offset. When the value is “true”, the current DST offset is being applied (i.e, daylight savings time is applied, as opposed to standard time).

11.16.10.3. TimeZoneStatus Event

This event SHALL be generated when the server changes its time zone offset or name. It SHALL NOT be sent for DST changes that are not accompanied by a time zone change.

This event returns a structure as follows:

Name

Type

Constraint

Quality

Default

Confor mance

Offset

int32

-43200 to

50400

Name

string

0 to 64 bytes

Offset Field

Current time zone offset from UTC in seconds.

Name Field

Current time zone name. This name SHOULD use the country/city format specified by the IANA time zone database [https://www.iana.org/time-zones].

11.16.11. Time Synchronization at Commissioning

During commissioning, the Commissioner SHALL send the current UTCTime and Granularity using the Section 11.16.9.1, “SetUtcTime Command”. The Commissioner SHALL attempt to synchronize its time prior to commissioning. If it is unable to achieve time synchronization, the Commissioner MAY use a Granularity of NoTimeGranularity.

During commissioning, the Commissioner SHOULD set a TrustedTimeNodeId, and SHOULD set the DefaultNtp for Nodes that support the NTPClient (NTPC) feature. If no backup NTP server is avail able, the Commissioner SHOULD set DefaultNtp to null. If no trusted Node is available, the Commis sioner SHOULD set TrustedTimeNodeId to null.

11.16.12. Time Synchronization during operation

Nodes MAY perform time synchronization using a trusted external source, NTPv4 / SNTPv4 [https://tools.ietf.org/html/rfc5905] or by reading the UTC time from the Time Cluster of another Node with the desired Granularity and TimeSource. When using NTPv4 / SNTPv4, Nodes capable of exter nal communication SHOULD use network time security (NTS) if that is available on the server (RFC8915 [https://tools.ietf.org/html/rfc8915]). This specification DOES NOT mandate that Nodes should include a TCP/TLS stack and a set of adequate Root CA certificates solely to support NTS, but that if a Node already has these capabilities, then it SHOULD implement and attempt NTS for NTP.

Nodes SHOULD attempt to perform a time synchronization after a restart or upon any change of Node state where timekeeping was lost. Nodes SHOULD attempt this time synchronization prior to using any security material which may have expired. If a Node is unable to achieve time synchro nization using the steps outlined in Section 11.16.13, “Time source prioritization”, the Node MAY retry or fall back to the stored Last Known Good UTC Time (Section 3.5.6.1, “Last Known Good UTC Time”).

11.16.13. Time source prioritization

Nodes SHOULD prioritize time synchronization sources in the following order:

GNSS time source, if supported by the
Trusted, high-resolution, external time source (ex. network NTP, trusted cloud-based source), if supported by the Node and external connectivity is
If NTPClient (NTPC) feature: NTP server defined in the DHCPv6 NTP server option, if DHCPv6 is supported on the
If NTPClient (NTPC) feature: NTP server defined by DHCP if the Node supports
If NTPClient (NTPC) feature: NTP server identified by a DNS-SD query for _ntp._udp. If multiple servers respond, Nodes with full NTP support SHOULD query multiple servers. Nodes using SNTP SHOULD select any server from the list
Querying the Time Cluster of another Node in the network. Nodes SHOULD be queried in the following order:
1. TrustedTimeNodeID provided by an
2. Any of the Node’s current peers per any data model binding that support Time Cluster and have the desired Granularity and
3. Enumerate all Nodes using DNS-SD query for _matter._tcp and select one with matching Fab ricID that supports the Time Cluster and has the desired Granularity and
If NTPClient (NTPC) feature: Fallback NTP server defined during

Nodes that use GNSS or a trusted external source SHOULD check the remaining time synchroniza tion sources to determine if they SHOULD act as an NTP server (see Section 11.16.15, “Acting as an NTP Server”).

Nodes SHALL check their synchronized time against the Time Cluster of the TrustedTimeNodeId Node and SHALL use the TrustedTimeNodeId Node as its time source if the difference between the TrustedTimeNodeId Node’s UTCTime and the Node’s preferred time source is greater than 10 minutes.

11.16.14. Time synchronization maintenance

Nodes SHALL adjust their Granularity attribute based on their assessed time synchronization error. Nodes running an NTP server (Section 11.16.15, “Acting as an NTP Server”) SHALL maintain a Gran ularity of SecondsGranularity or better and SHOULD maintain an accuracy of MillisecondsGranu larity or better.

A Node with a Granularity of NoTimeGranularity SHALL attempt to sync its time at least once a day. Nodes SHALL NOT query the Time Cluster of another Node more than once per 15 minutes.

11.16.15. Acting as an NTP Server

Any capable Node with always-on power source that has and can maintain a time synchronization Granularity of MillisecondsGranularity or better, SHOULD act as an NTP server. Any capable Node that reaches the final stage in the server discovery mechanism (see Section 11.16.13, “Time source prioritization”) SHOULD act as an NTP server for the network.

A Node hosting an NTP server SHALL update the NtpServerPort attribute with the port number for

the service and SHOULD advertise an _ntp._udp DNS-SD service. A Node hosting an NTP server SHOULD support network time security (NTS). A Node hosting an NTP server SHOULD implement leap smearing.

11.16.16. Implementation Guidance

This specification offers several options for getting time in order to support Nodes with various capabilities. This section is not intended as a requirement, but is used to illustrate how various Nodes might implement this specification.

11.16.16.1. Example: Constrained Node with no schedule capabilities

All Nodes need to support the Time Cluster for the purposes of commissioning, to allow the Admin istrator to set the initial time. This type of Node would not need to support the TimeZone (TZ) fea ture or the NTPServer (NTPS) feature. Support for the NTPClient (NTPC) feature would be depen dent on the implementation, but would likely use an SNTP implementation if this feature was sup ported.

If the Node does support an SNTP client, it would mark the NTPClient (NTPC) feature as true and would have the following attributes:

UTCTime
Granularity
TimeSource
TrustedTimeNodeId
DefaultNtp

To achieve time synchronization, the Node would start at Step 3 of Section 11.16.13, “Time source prioritization” (Steps 1 and 2 do not apply). If the Node is maintaining time it would set its Granu larity attribute as appropriate (Usually either MillisecondsGranularity or SecondsGranularity depending on whether a Time Cluster or SNTP is used, and on the SNTP round trip delay). If the Node wishes to use a single time synchronization, but will not continue to synchronize to the upstream source, it may either set the Granularity as appropriate and downgrade as the clock drifts, or may simply opt to set the Granularity to MinutesGranularity. The TimeSource attribute would be set as appropriate. If the Node determines it does not require time synchronization for operation, it would set UTCTime to null, Granularity to NoTimeGranularity and TimeSource to None.

If the Node does not support an SNTP client, it would mark the NTPClient (NTPC) feature as false and would have the following attributes:

UTCTime
Granularity
TimeSource
TrustedTimeNodeId

To achieve time synchronization, the Node would start at step 6 (querying a Time Cluster) of Section

11.16.13, “Time source prioritization” (other steps do not apply). If the Node wishes to maintain time synchronization by re-querying, it would set its Granularity attribute as appropriate (Usually SecondsGranularity for a MillisecondsGranularity source). If the Node wishes to use a single time synchronization, it may either set the Granularity as appropriate and downgrade as the clock drifts, or may simply opt to set the Granularity to MinutesGranularity. In both cases, the TimeSource would be set to NodeTimeCluster. If the Node determines it does not require time synchronization for operation, it would set UTCTime to null, Granularity to NoTimeGranularity and TimeSource to None.

11.16.16.2. Example: Sleepy Node with schedule capability

This type of Node would need to support the TimeZone (TZ) feature to support scheduling, but would not support the NTPServer (NTPS) feature as it is a sleepy device and would not make a reli able server.

If the Node does support an SNTP client, it would mark the NTPClient (NTPC) feature as true and would have the following attributes:

UTCTime
Granularity
TimeSource
TrustedTimeNodeId
DefaultNtp

To achieve time synchronization, the Node would start at Step 3 of Section 11.16.13, “Time source prioritization” (Steps 1 and 2 do not apply). If the Node is maintaining time it would set its Granu larity attribute as appropriate (Usually either MillisecondsGranularity or SecondsGranularity depending on whether a Time Cluster or SNTP is used, and on the SNTP round trip delay). If the Node wishes to use a single time synchronization, but will not continue to synchronize to the upstream source, it may either set the Granularity as appropriate and downgrade as the clock drifts, or may simply opt to set the Granularity to ‘MinutesGranularity’. The TimeSource attribute would be set as appropriate. If the Node determines it does not require time synchronization for operation, it would set UTCTime to null, Granularity to NoTimeGranularity and TimeSource to None.

If the Node does not support an SNTP client, it would mark the NTPClient (NTPC) feature as false and would have the following attributes:

UTCTime
Granularity
TimeSource
TrustedTimeNodeId

To achieve time synchronization, the Node would start at step 6 (querying a Time Cluster) of Section 11.16.13, “Time source prioritization” (other steps do not apply). If the Node wishes to maintain time synchronization by re-querying, it would set its Granularity attribute as appropriate (Usually SecondsGranularity for a MillisecondsGranularity source). If the Node wishes to use a single time

synchronization, it may either set the Granularity as appropriate and downgrade as the clock drifts, or may simply opt to set the Granularity to MinutesGranularity. In both cases, the TimeSource would be set to NodeTimeCluster. If the Node determines it does not require time synchronization for operation, it would set UTCTime to null, Granularity to NoTimeGranularity and TimeSource to None.

11.16.16.3. Example: Hub-like Node

These types of Nodes are normally relatively capable, high-powered and always-on. These would most likely include time zone support for scheduling and display. Often these will have significant software beyond this specification and are likely to already have built-in mechanisms for time syn chronization. Such Nodes SHOULD support an NTP server to serve time to other Nodes in the net work. In most cases, these Nodes would support all the features of this Cluster and would have the following attributes.

UTCTime
Granularity
TimeSource
TrustedTimeNodeId
DefaultNtp
TimeZone
DSTOffset
LocalTime
TimeZoneDatabase
NtpServerPort

To achieve time synchronization, these Nodes would likely use Step 1 or Step 2 of Section 11.16.13, “Time source prioritization”, using the remaining options as fallback if necessary. The Node would then set its Granularity and TimeSource as appropriate, and would maintain its times, Granularity and TimeSource. The Node SHOULD also start an NTP server, publish the port in the NtpServerPort attribute and advertise using DNS-SD on _ntp._udp.

If a time-zone database is supported (Node can calculate DST times from TimeZone settings) These Nodes MAY subscribe to the DSTTableEmpty Events of Nodes with no TimeZoneDatabase support. Upon receipt of these events the Node SHOULD calculate and set new DST times for such Nodes by writing the DSTOffset attribute.

11.17. Node Operational Credentials Cluster

This cluster is used to add or remove Node Operational credentials on a Commissionee or Node, as well as manage the associated Fabrics.

11.17.1. Revision History

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

below.

Revision	Description
1	Initial Release

11.17.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	OPCREDS

11.17.3. Cluster ID

ID	Name
0x003E	Operational Credentials

Data Types

11.17.4.1. RESP_MAX Constant

A RESP_MAX constant appears in the description of some command fields in this cluster and within the description of some associated serialization schemes.

The value RESP_MAX SHALL be 900 bytes.

The current limit of 900 bytes was chosen to accommodate the maximum size of IPv6 frames, trans port headers, message layer headers and integrity protection and Interaction Model protocol encoding, while accounting for sufficient remaining space for signatures and to allow extensions to larger key and digest sizes in the future.

11.17.4.2. CertificateChainTypeEnum

This data type is derived from enum8.

This enumeration is used by the CertificateChainRequest command to convey which certificate from the device attestation certificate chain to transmit back to the client.

Value	Name	Summary	Conformance
1	DACCertificate	Request the DER- encoded DAC certificate	M
2	PAICertificate	Request the DER- encoded PAI certificate	M

11.17.4.3. NodeOperationalCertStatusEnum

This data type is derived from enum8.

This enumeration is used by the NOCResponse common response command to convey detailed out

come of several of this cluster’s operations.

Value	Name	Summary	Conformance
0	OK	OK, no error	M
1	InvalidPublicKey	Public Key in the NOC does not match the public key in the NOCSR	M
2	InvalidNodeOpId	The Node Operational ID in the NOC is not for matted correctly.	M
3	InvalidNOC	Any other validation error in NOC chain	M
4	MissingCsr	No record of prior CSR for which this NOC could match	M
5	TableFull	NOCs table full, cannot add another one	M
6	InvalidAdminSubject	Invalid CaseAdminSub ject field for an AddNOC command.	M
7		Reserved for future use	M
8		Reserved for future use	M
9	FabricConflict	Trying to AddNOC instead of UpdateNOC against an existing Fab ric.	M
10	LabelConflict	Label already exists on another Fabric.	M
11	InvalidFabricIndex	FabricIndex argument is invalid.	M

11.17.4.4. NOCStruct

This encodes a fabric sensitive NOC chain, underpinning a commissioned Operational Identity for a given Node.

Access Quality: Fabric Scoped
ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
1	NOC	octstr	max 400			S	M
2	ICAC	octstr	max 400	X		S	M

Note that the Trusted Root CA Certificate is not included in this structure. The roots are available in the TrustedRootCertificates attribute of the Node Operational Credentials cluster.

NOC Field

This field SHALL contain the NOC for the struct’s associated fabric, encoded using Matter Certificate Encoding.

ICAC Field

This field SHALL contain the ICAC or the struct’s associated fabric, encoded using Matter Certificate Encoding. If no ICAC is present in the chain, this field SHALL be set to null.

11.17.4.5. FabricDescriptorStruct

Access Quality: Fabric Scoped
ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
1	RootPub licKey	octstr	65				M
2	VendorID	vendor-id	desc				M
3	FabricID	fabric-id					M
4	NodeID	node-id					M
5	Label	string	max 32		“”		M

This structure encodes a Fabric Reference for a fabric within which a given Node is currently com missioned.

RootPublicKey Field

This field SHALL contain the public key for the trusted root that scopes the fabric referenced by FabricIndex and its associated operational credential (see Section 6.4.5.3, “Trusted Root CA Certifi cates”). The format for the key shall be the same as that used in the ec-pub-key field of the Matter Certificate Encoding for the root in the operational certificate chain.

VendorID Field

This field SHALL contain the value of AdminVendorID provided in the AddNOC command that led to the creation of this FabricDescriptorStruct. The set of allowed values is defined in Section 11.17.6.8.3, “AdminVendorID Field”.

The intent is to provide some measure of user transparency about which entities have Administer privileges on the Node.

FabricID Field

This field SHALL contain the FabricID allocated to the fabric referenced by FabricIndex. This field SHALL match the value found in the matter-fabric-id field from the operational certificate provid

ing the operational identity under this Fabric.

NodeID Field

This field SHALL contain the NodeID in use within the fabric referenced by FabricIndex. This field SHALL match the value found in the matter-node-id field from the operational certificate providing this operational identity.

Label Field

This field SHALL contain a commissioner-set label for the fabric referenced by FabricIndex. This label is set by the UpdateFabricLabel command.

11.17.4.6. Attestation Elements

The Attestation Elements contain the metadata related to attestation, encoded in Matter TLV.

Attestation Elements TLV

attestation-elements => STRUCTURE [ tag-order ]

{

certification_declaration[1] : OCTET STRING, attestation_nonce[2] : OCTET STRING [ length 32 ],

timestamp[3] : UNSIGNED INTEGER [ range 32-bits ], firmware_information[4, optional] : OCTET STRING,

}

Any context-specific tags not listed in the above schema for Attestation Elements SHALL be reserved for future use, and SHALL be silently ignored if seen by a Commissioner which cannot understand them.

11.17.4.7. Attestation Information

The Attestation Information is the combination of a Matter TLV payload, containing the Attestation Elements, as well as a signature over an attestation_tbs message containing the in-band-transmitted attestation_elements_message and a secret out-of-band Attestation Challenge.

The Attestation Information SHALL be computed as follows:

Encode the attestation-elements structure with an anonymous tag into an octet string called attestation_elements_message.
- The firmware_information field SHALL be an octet string, as described in Section 6.3.2, “Firmware Information”.
- The certification_declaration field SHALL be the DER-encoded octet string representation of a CMS(RFC5652)-encoded certification declaration, as described in Section 6.3, “Certification Declaration”.
- The timestamp field SHALL be in epoch-s.
- The attestation_nonce field SHALL match the AttestationNonce field provided in the Attesta tionRequest Command that triggered the generation of the Attestation

Vendor specific information, if present, SHALL be encoded using fully qualified tags. Such fields allow the Node taking part in the Device Attestation Procedure to communicate ven dor-specific information that MAY aid in device commissioning. Commissioners that do not understand the format of the data MAY ignore
The resulting attestation_elements_message, including optional fields, SHALL be no more than RESP_MAX bytes once

attestation_elements_message =

{

certification_declaration(1) = certification_declaration, attestation_nonce(2) = attestation_nonce, timestamp(3) = timestamp, firmware_information(4) = firmware_information,

… optional fields per attestation-elements ..

}

Obtain the AttestationChallenge from a CASE session, resumed CASE session, or PASE session depending on the method used to establish the current session. This is an octet string of length CRYPTO_SYMMETRIC_KEY_LENGTH_BITS. Save it for the next step as
Locally generate an attestation_tbs message as an octet string by concatenating the attesta tion_elements_message and the attestation_challenge:
- attestation_tbs = attestation_elements_message || attestation_challenge
Compute the attestation_signature and record it as an ec-signature octet string:

Fill the AttestationElements field of the AttestationResponse Command using the contents of the attestation_elements_message octet
Fill the AttestationSignature field of the AttestationResponse Command using the contents of the attestation_signature octet
Note that the attestation_challenge SHALL NOT be included in any of the payloads conveyed as part of the Attestation

See Section F.2, “Device Attestation Response test vector” for an example computation of the above messages and application payloads.

11.17.4.8. NOCSR Elements

The NOCSR Elements contain the metadata related to NOCSR, encoded in Matter TLV.

NOCSR Elements TLV

nocsr-elements => STRUCTURE [ tag-order ]

{

csr[1] : OCTET STRING,

CSRNonce[2] : OCTET STRING [ length 32 ],

vendor_reserved1[3, optional] : OCTET STRING, vendor_reserved2[4, optional] : OCTET STRING, vendor_reserved3[5, optional] : OCTET STRING

}

Any context-specific tags not listed in the above schema for NOCSR Elements SHALL be reserved for future use, and SHALL be silently ignored if seen by a Commissioner which cannot understand them.

11.17.4.9. NOCSR Information

The NOCSR Information is the combination of a Matter TLV payload, containing the NOCSR Ele ments, as well as a signature over an nocsr_tbs message containing the in-band-transmitted noc sr_elements_message and a secret out-of-band Attestation Challenge, using the Attestation Private Key that is unique to the device producing the NOCSR Information.

The NOCSR Information SHALL be computed as follows:

Encode the nocsr-elements structure with an anonymous tag into an octet string called noc sr_elements_message.
- The csr field SHALL be a DER-encoded octet string of a properly encoded PKCS #10 Certifi cate Signing Request (CSR), signed with the Node Operational Private Key associated with the Node Operational Public Key, which is the subjectPublicKey field of the CSR. See Section 6.4.6.1, “Node Operational Certificate Signing Request (NOCSR) Procedure” for details about the generation of the Node Operational Key Pair, and the contents of the
- The CSRNonce field SHALL match the CSR Nonce field in the corresponding CSRRequest Command.
- The vendor_reserved1 through vendor_reserved3 fields allow the Node taking part in the NOCSR Procedure to communicate vendor-specific information that MAY aid in device com missioning. Commissioners that do not understand the format of the data MAY ignore
- The resulting nocsr_elements_message, including optional fields, SHALL be no more than RESP_MAX bytes once

Obtain the AttestationChallenge from a CASE session, resumed CASE session, or PASE session depending on the method used to establish the current session. This is an octet string of length CRYPTO_SYMMETRIC_KEY_LENGTH_BITS. Save it for the next step as
Locally generate an nocsr_tbs message as an octet string by concatenating the nocsr_ele ments_message and the attestation_challenge:
- nocsr_tbs = nocsr_elements_message || attestation_challenge
Compute the attestation_signature and record it as an ec-signature octet string:

Fill the NOCSRElements field of the CSRResponse Command using the contents of the nocsr_ele ments_message octet
Fill the AttestationSignature field of the CSRResponse Command using the contents of the attes tation_signature octet
Note that the attestation_challenge SHALL NOT be included in any of the payloads conveyed as part of the NOCSR

See Section F.3, “Node Operational CSR Response test vector” for an example computation of the above messages and application payloads.

11.17.5. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	NOCs	list[NOC Struct]	max Sup portedFab rics	N C		R A F	M
0x0001	Fabrics	list[Fab ricDescrip torStruct]	max Sup portedFab rics	N		R V F	M
0x0002	Support edFabrics	uint8	5 to 254	F		R V	M
0x0003	Commis sioned Fabrics	uint8	max Sup portedFab rics	N		R V	M
0x0004	Trusted RootCer tificates	list[octstr]	max Sup portedFab rics[max 400]	N C		R V	M

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0005	Current FabricIn dex	uint8			0	R V	M

11.17.5.1. NOCs Attribute

This attribute contains all NOCs applicable to this Node, encoded as a read-only list of NOCStruct.

Operational Certificates SHALL be added through the AddNOC command, and SHALL be removed through the RemoveFabric command.

Upon Factory Data Reset, this attribute SHALL be set to a default value of an empty list.

The number of entries in this list SHALL match the number of entries in the Fabrics attribute.

11.17.5.2. Fabrics Attribute

This attribute describes all fabrics to which this Node is commissioned, encoded as a read-only list of FabricDescriptorStruct. This information MAY be computed directly from the NOCs attribute.

Upon Factory Data Reset, this attribute SHALL be set to a default value of an empty list.

The number of entries in this list SHALL match the number of entries in the NOCs attribute.

11.17.5.3. SupportedFabrics Attribute

This attribute contains the number of Fabrics that are supported by the device. This value is fixed for a particular device.

11.17.5.4. CommissionedFabrics Attribute

This attribute contains the number of Fabrics to which the device is currently commissioned. This attribute SHALL be equal to the following:

The number of entries in the NOCs
The number of entries in the Fabrics

Upon Factory Data Reset, this attribute SHALL be set to a default value of 0.

11.17.5.5. TrustedRootCertificates Attribute

This attribute SHALL contain a read-only list of Trusted Root CA Certificates installed on the Node, as octet strings containing their Matter Certificate Encoding representation.

These certificates are installed through the AddTrustedRootCertificate command.

Depending on the method of storage employed by the server, either shared storage for identical root certificates shared by many fabrics, or individually stored root certificate per fabric, multiple

identical root certificates MAY legally appear within the list.

To match a root with a given fabric, the root certificate’s subject and subject public key need to be cross-referenced with the NOC or ICAC certificates that appear in the NOCs attribute for a given fab ric.

Upon Factory Data Reset, this attribute SHALL be set to a default value whereby the list is empty.

11.17.5.6. CurrentFabricIndex Attribute

This attribute SHALL contain accessing fabric index.

This attribute is useful to contextualize Fabric-Scoped entries obtained from response commands or attribute reads, since a given Fabric may be referenced by a different Fabric Index locally on a remote Node.

11.17.6. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	AttestationRe quest	Client ⇒ Server	AttestationRe sponse	A	M
0x01	AttestationRe sponse	Server ⇒ Client	N		M
0x02	Certificate ChainRequest	Client ⇒ Server	Certificate ChainResponse	A	M
0x03	Certificate ChainRe sponse	Server ⇒ Client	N		M
0x04	CSRRequest	Client ⇒ Server	CSRResponse	A	M
0x05	CSRResponse	Server ⇒ Client	N		M
0x06	AddNOC	Client ⇒ Server	NOCResponse	A	M
0x07	UpdateNOC	Client ⇒ Server	NOCResponse	F A	M
0x08	NOCResponse	Server ⇒ Client	N		M
0x09	UpdateFabri cLabel	Client ⇒ Server	NOCResponse	F A	M
0x0a	RemoveFabric	Client ⇒ Server	NOCResponse	A	M
0x0b	AddTrusted RootCertifi cate	Client ⇒ Server	Y	A	M

11.17.6.1. AttestationRequest Command

This command SHALL be generated to request the Attestation Information, in the form of an Attes tationResponse Command. If the AttestationNonce that is provided in the command is malformed, a

recipient SHALL fail the command with a Status Code of INVALID_COMMAND. The Attestation Nonce field SHALL be used in the computation of the Attestation Information.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Attestation Nonce	octstr	32			M

11.17.6.2. AttestationResponse Command

This command SHALL be generated in response to an Attestation Request command.

See Section 11.17.4.7, “Attestation Information” for details about the generation of the fields within this response command.

See Section F.2, “Device Attestation Response test vector” for an example computation of an Attesta tionResponse.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Attesta tionEle ments	octstr	max RESP_ MAX			M
1	Attesta tionSigna ture	octstr	64			M

AttestationElements Field

This field SHALL contain the octet string of the serialized attestation_elements_message.

AttestationSignature Field

This field shall contain the octet string of the necessary attestation_signature as described in Sec tion 11.17.4.7, “Attestation Information”.

11.17.6.3. CertificateChainRequest Command

If the CertificateType is not a valid value per CertificateChainTypeEnum then the command SHALL fail with a Status Code of INVALID_COMMAND.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Certificate Type	Certificate ChainType Enum	desc			M

11.17.6.4. CertificateChainResponse Command

This command SHALL be generated in response to a CertificateChainRequest command.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Certificate	octstr	max 600			M

Certificate Field

This field SHALL be the DER encoded certificate corresponding to the CertificateType field in the CertificateChainRequest command.

11.17.6.5. CSRRequest Command

This command SHALL be generated to execute the Node Operational CSR Procedure and subse quently return the NOCSR Information, in the form of a CSRResponse Command.

The CSRNonce field SHALL be used in the computation of the NOCSR Information. If the CSRNonce is malformed, then this command SHALL fail with an INVALID_COMMAND status code.

If the IsForUpdateNOC field is present and set to true, but the command was received over a PASE session, the command SHALL fail with an INVALID_COMMAND status code, as it would never be possible to use a resulting subsequent certificate issued from the CSR with the UpdateNOC com mand, which is forbidden over PASE sessions.

If the IsForUpdateNOC field is present and set to true, the internal state of the CSR associated key pair SHALL be tagged as being for a subsequent UpdateNOC, otherwise the internal state of the CSR SHALL be tagged as being for a subsequent AddNOC. See Section 11.17.6.8, “AddNOC Command” and Section 11.17.6.9, “UpdateNOC Command” for details about the processing.

If a prior UpdateNOC or AddNOC command was successfully executed within the fail-safe timer period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini tiator.

If the Node Operational Key Pair generated during processing of the Node Operational CSR Proce dure is found to collide with an existing key pair already previously generated and installed, and that check had been executed, then this command SHALL fail with a FAILURE status code sent back to the initiator.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	CSRNonce	octstr	32			M
1	IsForUp dateNOC	bool			false	O

11.17.6.6. CSRResponse Command

This command SHALL be generated in response to a CSRRequest Command.

See Section 11.17.4.9, “NOCSR Information” for details about the generation of the fields within this response command.

See Section F.3, “Node Operational CSR Response test vector” for an example computation of a CSR Response.

Name

Type

Constraint

Quality

Default

Confor mance

NOCSREle

ments

octstr

max RESP_ MAX

Attesta tionSigna ture

octstr

NOCSRElements Field

This field SHALL contain the octet string of the serialized nocsr_elements_message.

AttestationSignature Field

This field SHALL contain the octet string of the necessary attestation_signature as described in Sec tion 11.17.4.9, “NOCSR Information”.

11.17.6.7. AddNOC and UpdateNOC Commands Overview

The AddNOC command is used to commission a Node into a Fabric by providing a usable NOC and ICAC, with associated Node Operational IDs.

The UpdateNOC command is used to update existing credentials within a Fabric, for the purposes of:

Rotating the Node Operational Key Pair in use
Updating the contents of the NOC and optionally the ICAC certificates (subjects, issuers, keys, etc) under the current root of trust and Fabric

Both of these commands receive an NOCValue and optional ICACValue fields and require some com mon validation in addition to their specific behavior.

NOCValue and ICACValue Fields

The NOCValue and ICACValue fields SHALL be octet strings that represent a certificate encoded using Matter Certificate Encoding.

Upon receipt, the NOCValue and ICACValue chain SHALL be validated in the following ways:

Verify the NOC using:

Crypto_VerifyChain(certificates = [NOCValue, ICACValue, RootCACertificate]) if ICACValue is present,
Crypto_VerifyChain(certificates = [NOCValue, RootCACertificate]) if ICACValue is not present. If this verification fails, the error status SHALL be

The public key of the NOC SHALL match the last generated operational public key on this ses sion, and therefore the public key present in the last CSRResponse provided to the Administra tor or Commissioner that sent the AddNOC or UpdateNOC If this check fails, the error status SHALL be InvalidPublicKey.
The DN Encoding Rules SHALL be validated for every certificate in the chain, including valid value range checks for identifiers such as Fabric ID and Node ID. If this validation fails, the error status SHALL be InvalidNodeOpId if the matter-node-id attribute in the subject DN of the NOC has a value outside the Operational Node ID range and InvalidNOC for all other

If any of the above validation checks fail, the server SHALL immediately respond to the client with an NOCResponse. The StatusCode field of the NOCResponse SHALL be set to the error status value specified in the above validation checks.

These certificate validation steps are performed to ensure that operational credentials installed match an operational key pair generated by the Device and respect the trust model assumptions expressed in Section 6.4.5.1, “Node Operational Certificate (NOC)”.

Handling Errors

For any error described in the following subsections, the device SHALL immediately respond to the client with an NOCResponse with the prescribed StatusCode field, and SHALL leave all non-volatile state of the device untouched, as if the AddNOC command had never been received. The informa tion about the last CSR state associated with this session SHALL also be untouched in this case, so that a valid AddNOC command MAY still be issued later that would match that CSR state. The DebugText field in the NOCResponse MAY be filled with debug information.

The following failed preconditions error cases apply to all invocations of AddNOC:

If the device already has the CommissionedFabrics attribute equal to the SupportedFabrics attribute, then the device’s operational credentials table is considered full and the device SHALL process the error by responding with a StatusCode of TableFull as described in Section 11.17.6.7.2, “Handling Errors”.
If no context or memory exists of a prior CSRRequest command having been invoked in the same secure session as that which is receiving this AddNOC or UpdateNOC invocation, then the Node SHALL process the error by responding with a StatusCode of MissingCsr as described in Section 11.17.6.7.2, “Handling Errors”.

11.17.6.8. AddNOC Command

This command SHALL add a new NOC chain to the device and commission a new Fabric association upon successful validation of all arguments and preconditions.

The new value SHALL immediately be reflected in the NOCs list attribute.

A Commissioner or Administrator SHALL issue this command after issuing the CSRRequest com mand and receiving its response.

A Commissioner or Administrator SHOULD issue this command after performing the Attestation Procedure.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	NOCValue	octstr	max 400			M
1	ICACValue	octstr	max 400			O
2	IPKValue	octstr	16			M
3	CaseAdmin Subject	SubjectID				M
4	AdminVen dorId	vendor-id				M

IPKValue Field

This field SHALL contain the value of the Epoch Key for the Identity Protection Key (IPK) to set for the Fabric which is to be added. This is needed to bootstrap a necessary configuration value for sub sequent CASE to succeed. See Section 4.13.2.6.1, “Identity Protection Key (IPK)” for details.

The IPK SHALL be provided as an octet string of length CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES.

On successful execution of the AddNOC command, the side-effect of having provided this field SHALL be equivalent to having done a GroupKeyManagement cluster KeySetWrite command invo cation using the newly joined fabric as the accessing fabric and with the following argument fields (assuming KeySetWrite allowed a GroupKeySetID set to 0):

KeySetWrite (

GroupKeySetStruct :=

{

GroupKeySetID := 0,

GroupKeySecurityPolicy := 0,

EpochKey0 := <Contents of IPKValue field>, EpochStartTime0 := 0,

EpochKey1 := null EpochStartTime1 := null EpochKey2 := null, EpochStartTime2 := null

}

)

CaseAdminSubject Field

If the AddNOC command succeeds according to the semantics of the following subsections, then the

Access Control SubjectID SHALL be used to atomically add an Access Control Entry enabling that Subject to subsequently administer the Node whose operational identity is being added by this com mand.

The format of the new Access Control Entry, created from this, SHALL be:

{

FabricIndex: **FabricIndex derived from current or new Fabric**, Privilege: Administer,

AuthMode: CASE,

Subjects: [**CaseAdminSubject provided in the AddNOC command**], Targets: [], // entire node

Extension: [] // empty

}

NOTE

Unless such an Access Control Entry is added atomically as described here, there would be no way for the caller on its given Fabric to eventually add another Access Control Entry for CASE authentication mode, to enable the new Administrator to administer the device, since the Fabric Scoping of the Access Control List prevents the current Node from being able to write new entries scoped to that Fabric, if the session is established from CASE. While a session established from PASE does gain Fabric Scope of a newly-joined Fabric, this argument is made mandatory to provide symmetry between both types of session establishment, both of which need to even tually add an “Administer Node over CASE” Access Control Entry to finalize new Fabric configuration and subsequently be able to call the CommissioningComplete command.

AdminVendorID Field

This field SHALL be set to the Vendor ID of the entity issuing the AddNOC command. This value SHALL NOT be one of the reserved Vendor ID values defined in Table 1, “Vendor ID Allocations”.

Effect When Received

If a prior UpdateNOC or AddNOC command was successfully executed within the fail-safe timer period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini tiator.

If the prior CSRRequest state that preceded AddNOC had the IsForUpdateNOC field indicated as true, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the initia tor.

If no prior AddTrustedRootCertificate command was successfully executed within the fail-safe timer period, then this command SHALL process an error by responding with a NOCResponse with a StatusCode of InvalidNOC as described in Section 11.17.6.7.2, “Handling Errors”. In other words,

AddNOC always requires that the client provides the root of trust certificate within the same Fail- Safe context as the rest of the new fabric’s operational credentials, even if some other fabric already uses the exact same root of trust certificate.

If the NOC provided in the NOCValue encodes an Operational Identifier for a <Root Public Key, Fab ricID> pair already present on the device, then the device SHALL process the error by responding with a StatusCode of FabricConflict as described in Section 11.17.6.7.2, “Handling Errors”.

If the device already has the CommissionedFabrics attribute equal to the SupportedFabrics attribute, then the device’s operational credentials table is considered full and the device SHALL process the error by responding with a StatusCode of TableFull as described in Section 11.17.6.7.2, “Handling Errors”.

If the CaseAdminSubject field is not a valid ACL subject in the context of AuthMode set to CASE, such as not being in either the Operational or CASE Authenticated Tag range, then the device SHALL process the error by responding with a StatusCode of InvalidAdminSubject as described in Section 11.17.6.7.2, “Handling Errors”.

Otherwise, the command is considered an addition of credentials, also known as “joining a fabric”, and the following SHALL apply:

A new FabricIndex SHALL be allocated, taking the next valid fabric-index value in monotoni cally incrementing order, wrapping around from 254 (0xFE) to 1, since value 0 is reserved and using 255 (0xFF) would prevent cluster specifications from using nullable fabric-idx
An entry within the Fabrics attribute table SHALL be added, reflecting the matter-fabric-id RDN within the NOC’s subject, along with the public key of the trusted root of the chain and the AdminVendorID
The operational key pair associated with the incoming NOC from the NOCValue, and generated by the prior CSRRequest command, SHALL be recorded for subsequent use during CASE within the fail-safe timer period (see Section 5.5, “Commissioning Flows”).
The incoming NOCValue and ICACValue (if present) SHALL be stored under the FabricIndex associated with the new Fabric Scope, along with the RootCACertificate provided with the prior successful AddTrustedRootCertificate command invoked in the same fail-safe
1. Implementation of certificate chain storage MAY separate or otherwise encode the compo nents of the array in implementation-specific ways, as long as they follow the correct format when being read from the NOCs list or used within other protocols such as CASE.
The NOCs list SHALL reflect the incoming NOC from the NOCValue field and ICAC from the ICAC Value field (if present).
The operational discovery service record SHALL immediately reflect the new Operational Iden tifier, such that the Node immediately begins to exist within the Fabric and becomes reachable over CASE under the new operational
The receiver SHALL create and add a new Access Control Entry using the CaseAdminSubject field to grant subsequent Administer access to an Administrator member of the new Fabric. It is RECOMMENDED that the Administrator presented in CaseAdminSubject exist within the same entity that is currently invoking the AddNOC command, within another of the Fabrics of which it is a

The incoming IPKValue SHALL be stored in the Fabric-scoped slot within the Group Key Man agement cluster (see KeySetWrite), for subsequent use during CASE.
The Fabric Index associated with the armed fail-safe context (see Section 11.9.6.2, “ArmFailSafe Command”) SHALL be updated to match the Fabric Index just
If the current secure session was established with PASE, the receiver SHALL:
1. Augment the secure session context with the FabricIndex generated above, such that subse quent interactions have the proper accessing fabric.
If the current secure session was established with CASE, subsequent configuration of the newly installed Fabric requires the opening of a new CASE session from the Administrator from the Fabric just This Administrator is the one listed in the CaseAdminSubject argument.

Thereafter, the Node SHALL respond with an NOCResponse with a StatusCode of OK and a FabricIn dex field matching the FabricIndex under which the new Node Operational Certificate (NOC) is scoped.

11.17.6.9. UpdateNOC Command

This command SHALL replace the NOC and optional associated ICAC (if present) scoped under the accessing fabric upon successful validation of all arguments and preconditions. The new value SHALL immediately be reflected in the NOCs list attribute.

A Commissioner or Administrator SHALL issue this command after issuing the CSRRequest Com mand and receiving its response.

A Commissioner or Administrator SHOULD issue this command after performing the Attestation Procedure.

Access Quality: Fabric Scoped
ID	Name	Type	Constraint	Quality	Default	Confor mance
0	NOCValue	octstr	max 400			M
1	ICACValue	octstr	max 400			O

Effect When Received

If a prior UpdateNOC or AddNOC command was successfully executed within the fail-safe timer period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini tiator.

If a prior AddTrustedRootCertificate command was successfully invoked within the fail-safe timer period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini tiator, since the only valid following logical operation is invoking the AddNOC command.

If the prior CSRRequest state that preceded UpdateNOC had the IsForUpdateNOC field indicated as false, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the initia tor.

If any of the following conditions arise, the Node SHALL process an error by responding with an NOCResponse with a StatusCode of InvalidNOC as described in Section 11.17.6.7.2, “Handling Errors”:

The NOC provided in the NOCValue does not refer in its subject to the FabricID associated with the accessing fabric.
The ICAC provided in the ICACValue (if present) has a FabricID in its subject that does not match the FabricID associated with the accessing fabric.

Otherwise, the command is considered an update of existing credentials for a given Fabric, and the following SHALL apply:

The Operational Certificate under the accessing fabric index in the NOCs list SHALL be updated to match the incoming NOCValue and ICACValue (if present), such that the Node’s Operational Identifier within the Fabric immediately
1. The operational key pair associated with the incoming NOC from the NOCValue, and gener ated by the prior CSRRequest command, SHALL be committed to permanent storage, for subsequent use during CASE.
2. The operational discovery service record SHALL immediately reflect the new Operational Identifier.
3. All internal data reflecting the prior operational identifier of the Node within the Fabric SHALL be revoked and removed, to an outcome equivalent to the disappearance of the prior Node, except for the ongoing CASE session context, which SHALL temporarily remain valid until the NOCResponse has been successfully delivered or until the next transport-layer error, so that the response can be received by the Administrator invoking the

Thereafter, the Node SHALL respond with an NOCResponse with a StatusCode of OK and a FabricIn dex field matching the FabricIndex under which the updated NOC is scoped.

11.17.6.10. NOCResponse Command

This command SHALL be generated in response to the following commands:

AddNOC
UpdateNOC
UpdateFabricLabel
RemoveFabric

It provides status information about the success or failure of those commands.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	StatusCode	NodeOpera tionalCert StatusEnum				M
1	FabricIndex	fabric-idx	1 to 254			O
2	DebugText	string	max 128			O

StatusCode Field

This field SHALL contain an NOCStatus value representing the status of an operation involving a NOC.

FabricIndex Field

This field SHALL be present whenever StatusCode has a value of OK. If present, it SHALL contain the Fabric Index of the Fabric last added, removed or updated.

DebugText Field

This field MAY contain debugging textual information from the cluster implementation, which SHOULD NOT be presented to user interfaces in any way. Its purpose is to help developers in trou bleshooting errors and the contents MAY go into logs or crash reports.

11.17.6.11. UpdateFabricLabel Command

This command SHALL be used by an Administrator to set the user-visible Label field for a given Fabric, as reflected by entries in the Fabrics attribute.

The Label SHOULD be used by Administrators to provide additional per-fabric context when opera tions such as RemoveFabric are used.

Access Quality: Fabric Scoped
ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Label	string	max 32			M

Label Field

This field SHALL contain the label to set for the fabric associated with the current secure session.

Effect on Receipt

If the Label field is identical to a Label already in use by a Fabric within the Fabrics list that is not the accessing fabric, then an NOCResponse with a StatusCode of LabelConflict SHALL be returned for the command and there SHALL NOT be any permanent changes to any Fabric data.

Otherwise, the Label field for the accesing fabric SHALL immediately be updated to reflect the

Label argument provided. Following the update, an NOCResponse with a StatusCode of OK SHALL be returned.

If the command was invoked within a fail-safe context after a successful UpdateNOC command, then the label update SHALL apply to the pending update state that will be reverted if fail-safe expires prior to a CommissioningComplete command. In other words, label updates apply to the state of the Fabrics Attribute as currently visible, even for an existing fabric currently in process of being updated.

11.17.6.12. RemoveFabric Command

This command is used by Administrators to remove a given Fabric and delete all associated fab ric-scoped data.

If the given Fabric being removed is the last one to reference a given Trusted Root CA Certificate stored in the Trusted Root Certificates list, then that Trusted Root Certificate SHALL be removed.

WARNING

This command, if referring to an already existing Fabric not under the control of the invoking Administrator, SHALL ONLY be invoked after obtaining some form of explicit user consent through some method executed by the Adminis trator or Commissioner. This method of obtaining consent SHOULD employ as much data as possible about the existing Fabric associations within the Fabrics list, so that likelihood is as small as possible of a user removing a Fabric unwit tingly. If a method exists for an Administrator or Commissioner to convey Fab ric Removal to an entity related to that Fabric, whether in-band or out-of-band, then this method SHOULD be used to notify the other Administrative Domain’s party of the removal. Otherwise, users may only observe the removal of a Fab ric association as persistently failing attempts to reach a Node operationally.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	FabricIndex	fabric-idx	1 to 254			M

FabricIndex Field

This field SHALL contain the Fabric Index reference (see fabric-index) associated with the Fabric which is to be removed from the device.

Effect on Receipt

If the FabricIndex field does not match the FabricIndex of any entry within the Fabrics list, then an NOCResponse with a StatusCode of InvalidFabricIndex SHALL be returned for the command and there SHALL NOT be any permanent changes to any device data.

Otherwise, one of the following outcomes SHALL occur:

If the FabricIndex matches the last remaining entry in the Fabrics list, then the device SHALL delete all Matter related data on the node which was created since it was commissioned. This includes all Fabric-Scoped data, including Access Control List, bindings, scenes, group keys,

operational certificates, etc. All Trusted Roots SHALL also be removed. Any Matter related data including logs, secure sessions, exchanges and interaction model constructs SHALL also be removed. Since this operation involves the removal of the secure session data that may under pin the current set of exchanges, the Node invoking the command SHOULD NOT expect a response before terminating its secure session with the target.

If the FabricIndex does not equal the accessing fabric index, then the device SHALL begin the process of irrevocably deleting all associated Fabric-Scoped data, including Access Control List, bindings, group keys, operational certificates, etc. Any remaining Trusted Roots no longer refer enced by any operational certificate SHALL also be removed. All secure sessions, exchanges and interaction model constructs related to the Operational Identity under the given Fabric SHALL also be removed. Following the removal, an NOCResponse with a StatusCode of OK SHALL be returned.
If the FabricIndex equals the accessing fabric index, then the device SHALL begin the process of irrevocably deleting all associated Fabric-Scoped data, including Access Control Entries, bind ings, group keys, operational certificates, etc. Any remaining Trusted Roots no longer refer enced by any operational certificate SHALL also be removed. All secure sessions, exchanges and interaction model constructs related to the Operational Identity under the given Fabric SHALL also be removed. Since this operation involves the removal of the secure session data that may underpin the current set of exchanges, the Node invoking the command SHOULD NOT expect a response before terminating its secure session with the

11.17.6.13. AddTrustedRootCertificate Command

This command SHALL add a Trusted Root CA Certificate, provided as its Matter Certificate Encoding representation, to the TrustedRootCertificates Attribute list and SHALL ensure the next AddNOC command executed uses the provided certificate as its root of trust.

If the certificate from the RootCACertificate field is already installed, based on exact byte-for-byte equality, then this command SHALL succeed with no change to the list.

If a prior AddTrustedRootCertificate command was successfully invoked within the fail-safe timer period, which would cause the new invocation to add a second root certificate within a given fail- safe timer period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the initiator.

If a prior UpdateNOC or AddNOC command was successfully executed within the fail-safe timer period, then this command SHALL fail with a CONSTRAINT_ERROR status code sent back to the ini tiator.

If the certificate from the RootCACertificate field fails any validity checks, not fulfilling all the requirements for a valid Matter Certificate Encoding representation, including a truncated or over size value, then this command SHALL fail with an INVALID_COMMAND status code sent back to the initiator.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	RootCACer tificate	octstr	max 400			M

Note that the only method of removing a trusted root is by removing the Fabric that uses it as its root of trust using the RemoveFabric command.

11.18. Administrator Commissioning Cluster

This cluster is used to trigger a Node to allow a new Administrator to commission it. It defines Attributes, Commands and Responses needed for this purpose.

For the management of Operational Credentials and Trusted Root Certificates, the Node Operational Credentials cluster is used.

11.18.1. Revision History

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

Revision	Description
1	Initial Release

11.18.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	CADMIN

Cluster ID

ID	Name
0x003C	Administrator Commissioning

Features

Bit	Code	Feature	Description
0	BC	Basic	Node supports Basic Commissioning Method.

11.18.4.1. Basic Commissioning

This method MAY be supported and is described in Section 5.6.2, “Basic Commissioning Method (BCM)”.

11.18.4.2. Enhanced Commissioning

This method SHALL be supported and is described in Section 5.6.3, “Enhanced Commissioning Method (ECM)”.

11.18.5. Data Types

11.18.5.1. CommissioningWindowStatusEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	WindowNotOpen	Commissioning win dow not open	M
1	EnhancedWin dowOpen	An Enhanced Commis sioning Method win dow is open	M
2	BasicWindowOpen	A Basic Commissioning Method window is open	BC

11.18.6. Status Codes

Status Code	Value	Summary
0x02	Busy	Could not be completed because another commissioning is in progress
0x03	PAKEParameterError	Provided PAKE parameters were incorrectly formatted or otherwise invalid
0x04	WindowNotOpen	No commissioning window was currently open

Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	Window	Commis				R V	M
	Status	sioning
		Window
		Sta
		tusEnum

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0001	Admin FabricIn dex	fabric-idx		X		R V	M
0x0002	Admin VendorId	vendor-id		X		R V	M

11.18.7.1. WindowStatus Attribute

This attribute SHALL indicate whether a new Commissioning window has been opened by an Administrator, using either the OCW command or the OBCW command.

This attribute SHALL revert to WindowNotOpen upon expiry of a commissioning window.

Note that an initial commissioning window is not opened using either the OCW command or the OBCW command, and therefore this attribute SHALL be set to WindowNotOpen on initial commis sioning.

11.18.7.2. AdminFabricIndex Attribute

When the WindowStatus attribute is not set to WindowNotOpen, this attribute SHALL indicate the FabricIndex associated with the Fabric scoping of the Administrator that opened the window. This MAY be used to cross-reference in the Fabrics attribute of the Node Operational Credentials cluster.

If, during an open commissioning window, the fabric for the Administrator that opened the win dow is removed, then this attribute SHALL be set to null.

When the WindowStatus attribute is set to WindowNotOpen, this attribute SHALL be set to null.

11.18.7.3. AdminVendorId Attribute

When the WindowStatus attribute is not set to WindowNotOpen, this attribute SHALL indicate the Vendor ID associated with the Fabric scoping of the Administrator that opened the window. This field SHALL match the VendorID field of the Fabrics attribute list entry associated with the Admin istrator having opened the window, at the time of window opening. If the fabric for the Administra tor that opened the window is removed from the node while the commissioning window is still open, this attribute SHALL NOT be updated.

When the WindowStatus attribute is set to WindowNotOpen, this attribute SHALL be set to null.

11.18.8. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	OpenCommis sioningWin dow	Client ⇒ Server	Y	A T	M

ID	Name	Direction	Response	Access	Conformance
0x01	OpenBasic Commission ingWindow	Client ⇒ Server	Y	A T	BC
0x02	RevokeCom missioning	Client ⇒ Server	Y	A T	M

Only one commissioning window can be active at a time. If a Node receives another open commis sioning command when one OCW is already active, it SHALL return a failure response (see Section 11.18.6, “Status Codes”).

11.18.8.1. OpenCommissioningWindow (OCW) Command

This command is used by a current Administrator to instruct a Node to go into commissioning mode. The Enhanced Commissioning Method specifies a window of time during which an already commissioned Node accepts PASE sessions. The current Administrator MUST specify a timeout value for the duration of OCW.

When OCW expires or commissioning completes, the Node SHALL remove the Passcode by deleting the PAKE passcode verifier as well as stop publishing the DNS-SD record corresponding to this com mand as described in Section 4.3.1, “Commissionable Node Discovery”. The commissioning into a new Fabric completes when the Node successfully receives a CommissioningComplete command, see Section 5.5, “Commissioning Flows”.

The parameters for OpenCommissioningWindow command are as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Commis sioning Timeout	uint16	desc			M
1	PAKEPass codeVeri fier	octstr	all			M
2	Discrimina tor	uint16	0 to 4095			M
3	Iterations	uint32	1000 to 100000			M
4	Salt	octstr	16 to 32			M

A current Administrator MAY invoke this command to put a node in commissioning mode for the next Administrator. On completion, the command SHALL return a cluster specific status code from the enumeration below reflecting success or reasons for failure of the operation. The new Adminis trator SHALL discover the Node on the IP network using DNS-based Service Discovery (DNS-SD) for commissioning.

If any format or validity errors related to the PAKEPasscodeVerifier, Iterations or Salt arguments arise, this command SHALL fail with a cluster specific status code of PAKEParameterError.

If a commissioning window is already currently open, this command SHALL fail with a cluster spe cific status code of Busy.

If the fail-safe timer is currently armed, this command SHALL fail with a cluster specific status code of Busy, since it is likely that concurrent commissioning operations from multiple separate Commis sioners are about to take place.

In case of any other parameter error, this command SHALL fail with a status code of COM MAND_INVALID.

CommissioningTimeout Field

This field SHALL specify the time in seconds during which commissioning session establishment is allowed by the Node. This is known as Open Commissioning Window (OCW). This timeout value SHALL follow guidance as specified in Announcement Duration. The CommissioningTimeout applies only to cessation of any announcements and to accepting of new commissioning sessions; it does not apply to abortion of connections, i.e., a commissioning session SHOULD NOT abort prema turely upon expiration of this timeout.

PAKEPasscodeVerifier Field

This field SHALL specify an ephemeral PAKE passcode verifier (see Section 3.10, “Password-Authen ticated Key Exchange (PAKE)”) computed by the existing Administrator to be used for this commis

sioning. The field is concatenation of two values (w0 || L) SHALL be (CRYPTO_GROUP_SIZE_BYTES + CRYPTO_PUBLIC_KEY_SIZE_BYTES)-octets long as detailed in Crypto_PAKEValues_Responder. It SHALL be

derived from an ephemeral passcode (See PAKE). It SHALL be deleted by the Node at the end of commissioning or expiration of OCW, and SHALL be deleted by the existing Administrator after sending it to the Node(s).

Discriminator Field

This field SHALL be used by the Node as the long discriminator for DNS-SD advertisement (see Commissioning Discriminator) for discovery by the new Administrator. The new Administrator can find and filter DNS-SD records by long discriminator to locate and initiate commissioning with the appropriate Node.

Iterations Field

This field SHALL be used by the Node as the PAKE iteration count associated with the ephemeral PAKE passcode verifier to be used for this commissioning, which SHALL be sent by the Node to the new Administrator’s software as response to the PBKDFParamRequest during PASE negotiation. The permitted range of values SHALL match the range specified in Section 3.9, “Password-Based Key Derivation Function (PBKDF)”, within the definition of the Crypto_PBKDFParameterSet.

Salt Field

This field SHALL be used by the Node as the PAKE Salt associated with the ephemeral PAKE pass code verifier to be used for this commissioning, which SHALL be sent by the Node to the new

Administrator’s software as response to the PBKDFParamRequest during PASE negotiation. The constraints on the value SHALL match those specified in Section 3.9, “Password-Based Key Deriva tion Function (PBKDF)”, within the definition of the Crypto_PBKDFParameterSet.

When a Node receives the Open Commissioning Window command, it SHALL begin advertising on DNS-SD as described in Section 4.3.1, “Commissionable Node Discovery” and for a time period as described in Section 11.18.8.1.1, “CommissioningTimeout Field”. When the command is received by a SED, it SHALL enter into active mode and set its fast-polling interval to SLEEPY_ACTIVE_INTER VAL for at least the entire duration of the CommissioningTimeout.

11.18.8.2. OpenBasicCommissioningWindow (OBCW) Command

This command MAY be used by a current Administrator to instruct a Node to go into commissioning mode, if the node supports the Basic Commissioning Method. The Basic Commissioning Method specifies a window of time during which an already commissioned Node accepts PASE sessions. The current Administrator SHALL specify a timeout value for the duration of OBCW.

If a commissioning window is already currently open, this command SHALL fail with a cluster spe cific status code of Busy.

In case of any other parameter error, this command SHALL fail with a status code of COM MAND_INVALID.

The commissioning into a new Fabric completes when the Node successfully receives a Commis sioningComplete command, see Section 5.5, “Commissioning Flows”. The new Administrator SHALL discover the Node on the IP network using DNS-based Service Discovery (DNS-SD) for commission ing.

The data for this command is as follows:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Commis sioning Timeout	uint16	desc			M

CommissioningTimeout Field

This field SHALL specify the time in seconds during which commissioning session establishment is allowed by the Node. This is known as Open Basic Commissioning Window (OBCW). This timeout SHALL follow guidance as specified in Announcement Duration.

When a Node receives the Open Basic Commissioning Window command, it SHALL begin advertis ing on DNS-SD as described in Section 4.3.1, “Commissionable Node Discovery” and for a time period as described in Section 11.18.8.2.1, “CommissioningTimeout Field”. When the command is received by a SED, it SHALL enter into active mode and set its fast-polling interval to SLEEPY_AC

TIVE_INTERVAL for at least the entire duration of the CommissioningTimeout.

11.18.8.3. RevokeCommissioning Command

This command is used by a current Administrator to instruct a Node to revoke any active Open Commissioning Window or Open Basic Commissioning Window command. This is an idempotent command and the Node SHALL (for ECM) delete the temporary PAKEPasscodeVerifier and associ ated data, and stop publishing the DNS-SD record associated with the Open Commissioning Window or Open Basic Commissioning Window command, see Section 4.3.1, “Commissionable Node Discov ery”.

If no commissioning window was open at time of receipt, this command SHALL fail with a cluster specific status code of WindowNotOpen.

11.19. Over-the-Air (OTA) Software Update

11.19.1. Scope & Purpose

The majority of IoT devices require security and/or functional feature updates during their lifetime.

This section describes a set of OTA software update capabilities which enable an “OTA Requestor” to be informed of, obtain, and install software updates from a Node fulfilling the role of an “OTA Provider”.

An “OTA Requestor” is any Node implementing the OTA Requestor Device Type (0x0012), which ful fills the client role for the OTA Software Update Provider cluster and the server role for the OTA Software Update Requestor cluster. An “OTA Provider” is any Node implementing the OTA Provider Device Type (0x0014), which fulfills the server role for the OTA Software Update Provider cluster and the client role for the OTA Software Update Requestor cluster.

The OTA updates capabilities are designed to support:

A mechanism to inform OTA Requestors about available OTA
A mechanism to allow OTA Requestors to acquire information about available OTA Software Images.
A mechanism to allow constrained OTA Requestors to obtain OTA Software Images through a local proxy, g. if they are not able or willing to proceed with a direct download from the Inter net.
A mechanism to allow OTA Requestors supporting legacy, non-native, or out-of-band update methods to notify an OTA Provider of having completed an update out-of-band.
A mechanism to allow deferred installation of a software update, based on administrative
A mechanism to allow user consent to be considered before offering Software Images to OTA

OTA Requestors wishing to update their software using these capabilities MAY need to use an appli cation bootloader and MAY require sufficient additional storage in order to download an OTA image.

Furthermore, to encourage interoperability and timely software updates, the OTA update mecha nisms provide means of obtaining Software Images which can be uniformly implemented across OTA Requestors on devices from a variety of different vendors. The OTA Providers SHOULD provide services to OTA Requestors from vendors other than its own, as long as the location of Software Update images for these vendors is found. The Distributed Compliance Ledger is one such central ized source of software update image locations that MAY allow OTA Providers to provide OTA Soft ware Update Images generically to devices from many vendors.

11.19.2. Functional overview

An OTA Requestor SHALL query the OTA Provider periodically to determine the availability of new Software Images. The OTA Provider MAY learn, from backend systems inside or outside of Fabric scope, of the availability of a new Software Image for an OTA Requestor.

An OTA Requestor which has been updated using a mechanism beyond this Cluster MAY report to an OTA Provider that a Software Image update has been completed.

The OTA Provider MAY announce its presence to OTA Requestors on the Fabric to assist in discovery of this service (see Section 11.19.7.6.1, “AnnounceOTAProvider Command”).

Nodes SHALL NOT rely solely on unsolicited OTA Provider announcements to discover available OTA Providers and SHALL instead employ other means such as using OTA Provider records provi sioned during Commissioning, or dynamic discovery of OTA Providers.

OTA Requestors SHALL only upgrade to numerically newer versions and OTA Providers SHALL only ever provide a numerically newer Software Image than a Node’s current version number (see Section 11.1.5.10, “SoftwareVersion Attribute”). Any functional rollback SHALL be affected by the Vendor creating a Software Image with a newer (higher) version number, but whose binary con tents may match prior functionality.

All OTA Requestors SHALL support usage of a polling mechanism to send a query command to the OTA Provider in order to determine if the OTA Provider has any new Software Images for it. Polling simplifies processing for OTA Requestors that MAY need to perform special setup to get ready to receive a Software Images, such as unlocking flash or allocating space for a new Software Images.

It is ideal to have OTA Providers maintain as little state as possible since this will scale better when there are hundreds of OTA Requestors in a given Fabric. The OTA Provider is not required to keep track of what pieces of an image that a particular OTA Requestor has received.

The flow for querying the availability of a new version is done using commands of the OTA Provider Cluster. In case of a new image available matching an OTA Requestor’s request, the response to the QueryImage command SHALL contain a URI where the given image can be down loaded.

The download protocol is separate from the Cluster commands. All OTA Providers SHALL support the BDX Protocol to allow for the downloading of OTA images by both sleepy End Devices and more capable devices, without requiring access to the public Internet from the OTA Requestor. OTA Requestors SHOULD support the BDX Protocol.

In order to maximize the interoperable combinations of deployed products and Fabric Administra

tors, the CSA’s Distributed Compliance Ledger (DCL) MAY contain sufficient OTA Software Update information to cover a large number of products, using a federated mechanism of data mainte nance. See Section 11.22, “Distributed Compliance Ledger” for details on the Distributed Compli ance Ledger common data schemas. See Section 11.19.3.3.2, “Conceptual algorithm for matching OTA Software Images applicable to a query” for the conceptual algorithm recommended for imple mentation by OTA Providers to match records available in the DCL to incoming queries.

11.19.3. Software update workflow

The software update workflow consists of several steps executed in a sequence from an OTA Requestor towards an OTA Provider. When a newer Software Image for an OTA Requestor is avail able on the OTA Provider this results in an updated Software Image being acquired and applied by said OTA Requestor.

The steps, in order, and assuming each step successfully leads to the next, are the following, with each numbered according to Figure 74, “Detailed OTA Software Update Workflow”:

[10] OTA Provider optionally announces its presence to nodes (see Section 11.19.7.6.1, “AnnounceOTAProvider Command”). This MAY be used in addition to other OTA Provider dis covery
[11] OTA Requestor determines OTA Provider to
[11] OTA Requestor queries the OTA Provider for availability of an updated Software Image ver sion.
[30..34] OTA Provider obtains consent from user to apply the OTA
[40..41] OTA Provider obtains a copy of the new Software Image, either in real time or in a time- deferred manner, to provide to the OTA Requestor over BDX Protocol, or over an alternate sup ported protocol that both OTA Provider and OTA Requestor support. If the Software Image hap pens to be already available in the OTA Provider’s cache, this step can be
[52] OTA Requestor downloads the update, either over BDX Protocol from OTA Provider acting as a proxy, or over an alternate protocol that both OTA Provider and OTA Requestor
[60] OTA Requestor notifies the OTA Provider that the download is complete and that it is ready to apply the downloaded
[61] OTA Provider responds with an authorization to apply the update, after an optional
[62] OTA Requestor applies the update and starts executing updated
[63] OTA Requestor notifies the OTA Provider of having successfully applied the

In order to illustrate more specifically these steps, Figure 74, “Detailed OTA Software Update Work flow” below depicts a detailed sequence showing the following illustrative (not normative) aspects:

[10..21] Determining the availability of an OTA software
[22] Deferral of download by OTA Provider responding with a “Busy” condition, while it obtains user consent and obtains the Software Image from a vendor server based on information in the OTA Provider’s OTA Software Update
Obtaining user consent in one of these ways:

[30..31] Out-of-band notification through some externally-provided user interface, such as a mobile device terminal operated by an authorized user, and connected to OTA Provider’s logic in some
[32..34] Reuse of prior user consent, perhaps from a continued but revokable authorization, sent back to the OTA Provider by OTA Software Update
Via the OTA Provider delegating to the OTA Requestor Node (see Section 11.19.3.4.1, “User consent delegation to Nodes”). Note that this case is not illustrated in the sequence

[40..41] Downloading and temporarily storing a Software Image by the OTA Provider, from a Vendor’s server, over the public Internet, for the purposes of eventual proxied local download by the OTA
[50..51] Responding positively to a subsequent query by the OTA Requestor, since an OTA soft ware update is now definitely
[52] Downloading of the Software Image from the OTA Provider by the OTA Requestor, using the BDX Protocol against the temporary storage of the OTA
[60..63] OTA Requestor performs the update (after permission from OTA Provider)

Figure 74. Detailed OTA Software Update Workflow

Given that some of the above steps MAY fail to complete, and that some MAY provide a variety of outcomes or replies, the following subsections give the necessary normative details describing the sequence.

11.19.3.1. Determining the OTA Provider to query

The discovery of available OTA Providers is necessary for OTA Requestors to be able to query for new software images. Each OTA Requestor SHALL keep a list of OTA Provider Operational Identi fiers (see Section 2.5.5, “Node Identifier”) that it could query.

A given OTA Requestor SHALL have sufficient storage to maintain one OTA Provider entry per Fab ric within the DefaultOTAProviders default list. This default OTA Provider list MAY be augmented by any means deemed acceptable by a given OTA Requestor, such that the internal list of possible locations to query contains at least the DefaultOTAProviders, but it MAY contain more. For example, it may contain cached locations that arose from the AnnounceOTAProvider command.

When an OTA Requestor determines that it is time to query an OTA Provider, it MAY use any method of its choosing to determine which OTA Provider to contact for its next query.

An OTA Requestor MAY expunge OTA Providers from its OTA Provider list if it determines that the entry is stale or obsolete.

Discovery of additional OTA Providers MAY be done by handling the arrival of AnnounceO TAProvider commands invoked by OTA Providers.

Commissioners SHOULD add an entry to the DefaultOTAProviders list attribute, if an OTA Provider is known at commissioning time, to reduce the delay between commissioning and first QueryImage command.

Whenever communicating with an OTA Provider location obtained either through the DefaultO TAProviders attribute, or the AnnounceOTAProvider command, an OTA Requestor SHALL target all interactions with that Node by interacting with the given Endpoint on the given ProviderNodeID obtained from these sources.

Discovery of additional OTA Providers MAY be done using runtime service discovery, which is out side the scope of this specification.

Nodes MAY attempt to contact OTA Providers that are known to them in any order if failing to reach a default OTA Provider from an entry in the DefaultOTAProviders list. This approach would assist in maximizing likelihood of eventual success.

11.19.3.2. Querying the OTA Provider

Query of the OTA Provider SHALL be done using the QueryImage command. The arguments for this command provide sufficient information to allow the OTA Provider to determine the availability of a new image for the querying OTA Requestor.

An OTA Requestor SHALL NOT query more frequently than once every 120 seconds, unless a Node loses its timekeeping state, due to events such as power loss or restart, that prevent applying such a delay. This reduces the burden on both the OTA Providers providing the service to a large number

of nodes and the supporting networking infrastructure. It is recommended for OTA Requestors to attempt a daily QueryImage command, if capable, to ensure timely access to updated software, including security-critical updates.

The OTA Provider SHALL use an algorithm deemed satisfactory by its implementer to determine the availability of a newer Software Image in response to a QueryImage command. This algorithm will be called the “OTA Image Selection Logic” thereafter.

The OTA Image Selection Logic MAY use any data it deems useful, either local to the equipment or Node hosting the OTA Provider, or remote through external networks, to determine whether an updated Software Image is available (see Section 11.19.3.3, “Availability of Software Images”).

OTA Provider requests are idempotent. In cases where an OTA Requestor is repeating a request it has already done, and the OTA Provider can detect this, it SHALL NOT behave differently on any subsequent attempt compared to the first, unless a new Software Image has become available in the meantime. That is, an OTA Provider SHALL NOT prevent an OTA Requestor from trying to make the same query more than once. This requirement is critical to ensure that OTA Requestors which encounter error conditions during OTA Image Query or OTA Image Transfer can eventually succeed through retrying the same operation more than once.

Upon final determination of the outcome of the QueryImage command, the OTA Provider SHALL reply with a QueryImageResponse command.

If an OTA Provider employs synchronous proxying (e.g. proxy-while-downloading) method to reach off-Fabric Software Images and provide them over BDX Protocol to OTA Requestors, it SHALL respond with a Status of DownloadProtocolNotSupported to an OTA Requestor in the QueryIm ageResponse command if all the following conditions apply:

A new Software Image is determined to be
The Software Image to proxy is served by a remote server that does NOT support range-based transfers.
The OTA Requestor only supports
The OTA Provider does not support asynchronous proxying (e.g. download-then-proxy).

The fields of the QueryImageResponse command convey the next steps to take. The primary indica tion of action to be taken by the OTA Requestor is expressed in the Status field, with the other fields providing the necessary details as described in the following subsections.

Failure to receive an application-layer response from the OTA Provider after invoking the QueryIm age command SHOULD be considered equivalent to having received a QueryImageResponse com mand with a Status field containing NotAvailable (see Section 11.19.3.2.4, “Handling NotAvailable value in Status field”).

Access Control Requirements

Commissioners or Administrators SHOULD install necessary ACL entries at Commissioning time or later to enable the handling of the AnnounceOTAProvider commands by OTA Requestors.

Below is an exemplary ACL entry for a Node implementing the OTA Requestor cluster server to sup

port the processing of the AnnounceOTAProvider command:

{

FabricIndex: <Fabric Index of the fabric in question>, Privilege: Operate,

AuthMode: CASE,

Subjects: [ <Node ID of the node implementing OTA Requestor cluster client> ], Targets: [ <Endpoint hosting the OTA Requestor cluster server> ]

}

Commissioner or Administrator SHOULD install necessary ACL Entries at Commissioning time or later to enable processing of QueryImage commands from OTA Requestors on their Fabric, other wise that OTA Provider will not be usable by OTA Requestors.

Below is an exemplary ACL entry for a Node implementing the OTA Provider cluster server to sup port the processing of the QueryImage command:

{

FabricIndex: <Fabric Index of the fabric in question>, Privilege: Operate,

AuthMode: CASE,

Subjects: [ ], // Empty for “any” Node wildcard

Targets: [ <Endpoint hosting the OTA Provider cluster server> ]

}

Note that there may be a variety of ACL entry configurations that fulfill the necessary goals, includ ing wildcard entries for the Administrators on a given Fabric. The examples above are for illustra tion purposes only.

Handling UpdateAvailable value in Status field

The UpdateAvailable status indicates that the OTA Provider has an update available.

The remaining fields within the QueryImageResponse command SHALL contain the information necessary to allow the OTA Requestor to obtain an updated Software Image.

The field ImageURI SHALL be set to a location from where the image can be downloaded. The URI provided SHALL be for a protocol within the list of supported protocols provided in the request (see Section 11.19.6.5.1.4, “ProtocolsSupported Field”). Selection of the URI is based on the information available in the OTA Provider’s Software Images data set.

The field UpdateToken SHALL be populated by the OTA Provider with a value of its choosing, to allow tracking of the flow from a given OTA Requestor when it sends further requests. The valid length of the UpdateToken is between 8 and 32 bytes, inclusively. The token SHALL be recorded by the OTA Requestor, until an OTA Software Update Image is either applied or discarded. This value SHALL be provided to any subsequent ApplyUpdateRequest and NotifyUpdateApplied commands.

The field SoftwareVersion SHALL be set to the version number matching the new Software Image.

Handling of SoftwareVersion and ImageURI fields SHALL follow these rules:

If the SoftwareVersion field matches the version indicated in the header of a previously down loaded OTA Software Image, one of two cases applies:

Image was fully downloaded and verified: the OTA Requestor SHOULD skip the transfer step (see Section 11.19.3.5, “Transfer of OTA Software Update images”), and move directly to the apply step (see Section 11.19.3.6, “Applying a software update”).
Image was partially downloaded: the OTA Requestor SHOULD attempt to continue the trans fer from where it left off, if it is capable, otherwise it SHALL start the transfer See Sec tion 11.19.3.5, “Transfer of OTA Software Update images” for a description of complete and restarted downloads.
- If the SoftwareVersion field indicates a newer (numerically higher) version than the version currently installed on the OTA Requestor, the OTA Requestor SHOULD proceed with OTA Image Transfer (see Section 11.19.3.5, “Transfer of OTA Software Update images”), after awaiting at least the delay stated by the DelayedActionTime field, if
- If the SoftwareVersion field indicates the same or an older (numerically lower) version, or if the ImageURI field somehow contains information which cannot be used by the OTA Requestor, then the OTA Requestor SHALL go back to awaiting its next OTA Software Update query oppor tunity, following the rules previously stated in Section 11.19.3.2, “Querying the OTA Provider”. In that case, the OTA Requestor MAY attempt to select a different OTA Provider according to Sec tion 11.19.3.1, “Determining the OTA Provider to query”, which MAY cause the OTA Requestor to immediately try another query, but to a different OTA Provider, thus not violating daily allowance of a given OTA Requestor towards a given OTA

Handling Busy value in Status field

The Busy status indicates that the OTA Provider is busy for any reason and that it can only provide a definite answer at a later time. This MAY be because the OTA Provider is currently determining whether an update is available for the OTA Requestor that made the query. An OTA Requestor SHOULD attempt to query the same OTA Provider again later at least once more if a Busy response is obtained, rather than querying a different OTA Provider in its list, so that the OTA Provider that replied Busy could have had resources available to determine availability.

After a Busy status, the OTA Requestor SHALL NOT re-query the OTA Provider which was the sub ject of the command sooner than the longest of either:

2 minutes (120 seconds) from the last QueryImage command;
the delay stated by the DelayedActionTime field, if

Note that if a Node loses its timekeeping state due to events such as power loss or restart, the above timing constraint MAY be ignored, however, the previously stated overriding constraint of a mini mum delay of 120 seconds between queries to any single OTA Provider by a given OTA Requestor has to be respected.

Handling NotAvailable value in Status field

The NotAvailable status indicates that there is definitely no update currently available from the queried OTA Provider.

The OTA Requestor MAY choose to attempt a QueryImage command on a different OTA Provider in its OTA Provider List to determine if an update is available from that other OTA Provider.

Otherwise, if there are no other OTA Providers available to query, the OTA Requestor SHALL NOT re-query the OTA Provider which was the subject of the command sooner than 2 minutes (120 sec onds) from the last QueryImage command. Note that if a Node loses its timekeeping state due to events such as power loss or restart, the above timing constraint MAY be ignored, however, the pre viously stated overriding constraint of a minimum delay of 120 seconds between queries to any sin gle OTA Provider by a given OTA Requestor have to be respected.

Handling errors from QueryImage Command

If an OTA Requestor hits error conditions of any kind in invoking the QueryImage command, including receiving DownloadProtocolNotSupported in Status, there are two possible outcomes:

If the OTA Requestor has a Software Image it had previously successfully downloaded and veri fied, the OTA Requestor SHOULD skip the Query step, and move directly to the Apply step (see Section 11.19.3.6, “Applying a software update”). This increases the likelihood that the OTA Requestor will eventually succeed to apply a previously transferred Software
If the OTA Requestor is still attempting to discover an OTA Update, it MAY choose to attempt a QueryImage command on a different OTA Provider in its OTA Provider List, in which case the timing for the query SHALL match the query timing constraints expressed in the previous para graphs of this section. Otherwise, it SHALL continue to query the same OTA Provider, again fol lowing the query timing constraints previously

11.19.3.3. Availability of Software Images

The algorithm used by the Image Selection Logic to determine availability of a new Software Image SHALL consider all fields provided by the OTA Requestor and attempt to provide the newest match ing Software Image. The OTA Image Selection Logic SHALL only provide newer (numerically higher) SoftwareVersion than the SoftwareVersion sent in the query. See Section 11.19.3.3.2, “Con ceptual algorithm for matching OTA Software Images applicable to a query” for more details.

The OTA Provider MAY provide a Software Image that only conveys data for a subset of updateable components within the OTA Requestor’s Node. These cases of partial or componentized software updates are determined purely by the entity generating the OTA Software Image, and the OTA Provider SHALL never mutate the contents of an OTA Software Image.

The original provider of a Software Image SHOULD be able to assume the contents of the Software Image will remain unchanged and signatures would remain valid. Therefore, an OTA Provider SHALL NOT modify the contents of any Software Images other than allowing that OTA Requestor to index into the Software Image using the BDX Protocol or other supported download protocol, such that the OTA Requestor may obtain only the desired parts of the Software Image.

The OTA Provider SHALL NOT hide or otherwise mask the contents of a Software Image available for transfer to a requestor.

In order for different vendors to participate as widely as possible in the distribution of Software Images for the widest variety of products without requiring bilateral distribution agreements

between each pair, it is RECOMMENDED for vendors to participate in distribution schemes that maximize availability across other vendors and OTA Providers.

Vendors SHOULD build data sets aggregating the metadata and payloads of Software Images to sup port their OTA Image Selection Logic by any means they deem satisfactory. Vendors SHOULD refer to canonical databases, such as the Distributed Compliance Ledger.

Given that most Fabrics likely will contain a reduced subset of Nodes capable of acting as OTA Providers compared to the larger set of vendors represented in the many deployed Nodes, it is advantageous to end-users that Vendors attempt to cover as many other vendors with their data sets. This will ensure that the majority of Software Image queries can be fulfilled if a vendor has released a newer version than that installed on the querying OTA Requestor.

Download Protocol selection

The OTA Image Selection Logic SHALL consider the OTA Requestor’s supported download protocols to determine whether to respond to a QueryImage command.

If either the BDXSynchronous or BDXAsynchronous protocols are supported by the OTA Requestor, the OTA Provider SHALL prefer to respond to the OTA Requestor with a BDX protocol URI, as long as it can fulfill the role of BDX server for the OTA Requestor.

Otherwise, if the HTTPS protocol is supported by the OTA Requestor, and the OTA Provider deter mines that an OTA Software Image is available to fulfill the request from a server supporting HTTPS, it SHOULD respond with the direct source URI, so that the OTA Requestor MAY download it directly.

Otherwise, if the VendorSpecific protocol is supported by the OTA Requestor, and the OTA Provider has sufficient knowledge of the OTA Requestor’s capabilities based on the QueryImage command arguments, it SHOULD respond with a URI which is known to be understood by the OTA Requestor. It is RECOMMENDED to limit usage of this modality and prefer BDXSynchronous and BDXAsynchro nous.

Conceptual algorithm for matching OTA Software Images applicable to a query

An OTA Provider MAY use any of the fields of the QueryImage command in any way it deems applicable to determine whether an appropriate OTA Software image is available for the OTA Requestor.

However, to increase interoperability, OTA Providers which have access to the data present in the Distributed Compliance Ledger (DCL), whether from cached subset or from a full replica, SHOULD employ at least the common conceptual algorithm provided in this section to determine whether an OTA Image is available.

The information to access OTA Software Image locations for certified software versions is available in the DCL DeviceSoftwareVersionModel Schema, which is indexed by VendorID, ProductID and SoftwareVersion.

The inputs to the conceptual algorithm are:

A subset of the fields of the QueryImage command as a structure named requestor:

VendorID of the requestor as vendorID
ProductID of the requestor as productID
Current SoftwareVersion of the requestor as softwareVersion
The list of all current entries for the given VendorID and ProductID from the DeviceSoftwareVer sionModel schema, ordered by SoftwareVersion, accounting for the following fields, as an array candidates[]
- SoftwareVersion of the entry as softwareVersion
- SoftwareVersionValid of the entry as softwareVersionValid
- MinApplicableSoftwareVersion of the entry as minApplicableSoftwareVersion
- MaxApplicableSoftwareVersion of the entry as maxApplicableSoftwareVersion

The output of the conceptual algorithm is a tuple of:

candidateWasFound, a boolean predicate indicating whether a newer version candidate was found
softwareVersionFound, the version of the newer version candidate, if candidateWasFound was true, 0

The algorithm is as follows:

Assume no matching candidate found
- candidateWasFound := False
- softwareVersionFound := 0
Obtain candidates from a DCL replica or from a DCL-based dataset for the given vendorID and

productID in the query, keeping only entries where softwareVersionValid is true.

An OTA Provider MAY as well filter available versions by certification compliance status (see Section 11.22.7, “DeviceSoftwareCompliance / Compliance test result Schema”).

Sort all candidates by ascending softwareVersion.
Iterate through all candidates to find all positive matches within the sorted candidates. A “posi tive match” is a candidate which fullfills every condition in the following list:
- softwareVersion < candidate.softwareVersion
- softwareVersion ≥ candidate.minApplicableSoftwareVersion
- softwareVersion ≤ candidate.maxApplicableSoftwareVersion
From the positive matches, select the very last one of list, which will be the newest (numerically highest) possible softwareVersion that could be used. If no positive matches were found, no new software version is

A pseudocode of the conceptual algorithm is presented below:

# Get candidates for VendorID/ProductID from DCL DeviceSoftwareVersionModel # schema (e.g. from a replica)

candidates = obtain_candidates_from_dcl(requestor.vendorID, requestor.productID)

def find_newer_version(candidates, requestor):

# Ensure all candidate records are in monotonic increasing numerical order sort(candidates, key=”softwareVersion”, order=”ASCENDING”)

currentCandidate = None

for candidate in candidates:

# Current version already newer: skip

if requestor.softwareVersion >= candidate.softwareVersion: continue

# Candidate requires higher version than already installed: skip

if requestor.softwareVersion < candidate.minApplicableSoftwareVersion: continue

# Candidate requires lower version than already installed: skip

if requestor.softwareVersion > candidate.maxApplicableSoftwareVersion: continue

# Update potential candidate since it is applicable currentCandidate = candidate

if currentCandidate is not None:

# Last value of currentCandidate is highest matching value candidateWasFound = True

softwareVersionFound = currentCandidate.softwareVersion else:

candidateWasFound = False softwareVersionFound = 0

return (candidateWasFound, softwareVersionFound)

If candidateWasFound was true, then a version matching (softwareVersionFound) was found and its location and associated metadata can be found in the DeviceSoftwareVersionModel schema of the DCL.

While the QueryImage command MAY also contain the Location, HardwareVersion and Meta dataForProvider fields, they are optional to use by an OTA provider. These additional fields MAY assist an OTA provider in supporting field trial and development policies. The certified releases present in the DCL, however, are only indexed by VendorID, ProductID and SoftwareVersion, based on the associated certification.

Once an OTA software update file location (OtaUrl) and digest (OtaChecksum) are found for the associated version candidate, an OTA provider MAY omit re-downloading the file, and serve a cached copy if a local copy of a file exists which matches all of the following constraints from the candidate:

It has the same OtaChecksum
It has the same OtaChecksumType

It has the same OtaFileSize

11.19.3.4. Obtaining user consent for updating software

In the following subsections, the word “User” SHALL be construed to mean “an entity with suffi cient privileges associated with the Fabric”. For instance, this could be a home dweller having pre viously configured Nodes or other services and currently having privilege to further affect such configuration. The exact scope for what an “entity” for such a “User” role may be, and what “suffi cient privilege” means, SHALL be implementation-dependent.

An OTA Provider SHOULD obtain some form of “User Consent” prior to responding with a URI for a Software Image or letting an OTA Requestor proceed with applying a previously downloaded update. In the context of the OTA Cluster, “User Consent” SHALL be defined as any signal that an OTA Provider may obtain through its implementation-specific logic, that conveys consent to pro ceed from a User administratively allowed to give such consent in an informed manner.

Example of “User Consent” include:

Triggering a notification to an interactive application user interface, where at least one User is notified of the availability of new software for a given node, and where a signal of approval to continue with the downloading and applying of that update can be conveyed back to the OTA
- Example: An OTA Provider detects the local presence of a mobile device with an application supporting required User accounts through out-of-band means. The OTA Provider makes an implementation-specific request over a protocol of its choice, in-band or out-of-band of the Fabric, to obtain consent. The User is notified on screen with “An ExampleCompany Light Bulb needs update to version 1.2.3. Tap here for release notes. Do you want to proceed?”. The User then selects “Agree to Update” and the signal is relayed back to the OTA Provider, which then
Relaying of a previously stored consent signal, previously provided by a User at some point in the past. The original capture of the stored consent signal should have been made after having provided sufficient information to the User to understand the consequences of such stored con sent. Multiple signals, covering different Nodes, Vendors or Device Classes, may be stored inde pendently to affect a variety of deferred consent
- Example: An OTA Provider contacts an implementation-specific server with metadata about the OTA Requestor and details for available Software Images, and obtains a consent signal based on an Administrator having previously stated an account preference to “Always apply software updates to light bulbs”. The OTA Provider then proceeds

User consent delegation to Nodes

Some capable Nodes MAY have sufficient hardware capabilities to request user consent by means such as display or voice, and subsequently recover user consent feedback through input mecha nisms. These devices MAY request optional delegation of user consent by the following method:

The OTA Requestor SHALL set the RequestorCanConsent field in the QueryImageRequest to True, indicating ability to obtain
The OTA Provider, if it determines that the best way to obtain user consent is to delegate to the

OTA Requestor Node, SHALL include the UserConsentNeeded field, with a value set to True in the QueryImageResponse, indicating that user consent was not previously obtained, and that delegation SHALL occur.

The OTA Requestor, upon observing presence of UserConsentNeeded field set to True and the availability of an image in the QueryImageResponse SHOULD proceed to obtain user consent using its onboard means, prior to transferring the OTA Software Image reported. If the UserCon sentNeeded field is set to False or absent, the OTA Requestor SHALL assume that the OTA Provider already obtained sufficient user consent during the querying

The above method of obtaining User Consent at the OTA Requestor level SHALL NOT be used if a Node is configured with the LocalConfigDisabled attribute set to True as reflected by the Basic Information Cluster.

User consent recommendations

Because of the variety of Vendors and Devices, the concept of “User Consent” will necessarily take many different forms. Therefore, it is RECOMMENDED that every implementer of OTA Provider logic implement a transparent and easy-to-use set of functionality to allow Users to provide or deny consent for software updates, in a way that functionally integrates with their products and respects the general requirements stated above. Implementation of this feature is expected to improve “user experience” and assist with building trust regarding the installation of new software on Nodes.

It is RECOMMENDED that any method of consent that stores consent signals also provide a way to revoke this consent in the future.

It is RECOMMENDED that metadata from Software Images be used to convey as much information as required within the available set, so that a User can make an informed decision based on the nature of the product being updated, the human-readable instance of the new version number (e.g. SoftwareVersionString in OTA Image Header), the changes made available, and their side-effects on product functionality. Any URL for online contents conveyed during this process SHOULD point to content that can be localized at the time of delivery, whenever possible. The responsibility for the maintenance of such version information is on the Vendor providing the URL and metadata. The OTA Provider and associated implementation-specific logic SHALL allow a User to consent to an update, even if errors occur while trying to provide additional release information, as the metadata within the Software Image should suffice to provide a first-order description of the new version, which could then be researched or cross-referenced by the User.

It is RECOMMENDED that Vendor-provided Software Update metadata, such as release note URLs, be maintained in the long-term with stable locations, preferably in a manner allowing historical caching by common online search engines, where applicable. See Section 11.22.6.11, “ReleaseNotesUrl” and Section 11.20.2.4.8, “ReleaseNotesUrl field” for sources of such information.

11.19.3.5. Transfer of OTA Software Update images

Execution of an OTA Software Update image’s transfer depends on the protocol provided in the ImageURI field of the query response.

The following are OTA Software Image transfer examples:

An OTA Requestor invokes a QueryImage command stating only support for BDX in its Proto colsSupported. The OTA Provider, using its OTA Image Selection Logic, determines that a Soft ware Image is available. There are several cases to be considered:

The Software Image is at a URI referring to a resource on the public Internet (e.g.

https://domain.example/images/software.bin).

The OTA Provider MAY completely download the Software Image, temporarily, to local

storage. It would then reply to the OTA Requestor with a locally-accessible BDX URI, such as bdx://8899AABBCCDDEEFF/software_8ce40aa1.bin. In that case, the OTA Requestor SHALL proceed with the download from the OTA Provider using the BDX protocol.

The OTA Provider MAY employ a variety of buffering and proxying schemes of underly ing HTTPS transfers to support the OTA Requestor downloading in real-time as a form of direct It would immediately reply to the OTA Requestor with a locally-accessible

BDX URI, such as bdx://8899AABBCCDDEEFF/software_8ce40aa1.bin. In that case, the OTA

Requestor SHALL proceed with the download from the OTA Provider using the BDX pro

tocol. The only difference with the previous case is the fact that the transfer uses data directly proxied in real-time, as opposed to the OTA Requestor downloading a pre-stored cached copy of the same Software Image.

The Software Image is already cached on the OTA Provider, either from pre-seeding over some implementation-specific scheme, or from having previously served this software update to another OTA In that case, the OTA Provider SHALL reply to the OTA

Requestor with a locally-accessible BDX URI, such as bdx://8899AABBCCDDEEFF/soft ware_8ce40aa1.bin. In that case, the OTA Requestor SHALL proceed with the download from

the OTA Provider using the BDX protocol.

An OTA Requestor invokes a QueryImage command stating support for BDX and HTTPS in its ProtocolsSupported. The OTA Provider, using its OTA Image Selection Logic, determines that a Software Image is The Software Image is at a URI referring to a resource on the public

Internet (e.g. https://domain.example/images/software.bin). In the case of support for both

HTTPS and BDX, all of the above cases are applicable, in addition to the following:

The OTA Provider knows that the OTA Requestor supports HTTPS from the QueryImage com mand. The OTA Provider MAY then respond directly to the OTA Requestor with the

https://domain.example/images/software.bin URI. The OTA Requestor SHALL proceed to

download from the public Internet using the HTTPS protocol.

As described above, an OTA Provider SHALL either proxy synchronously or asynchronously the actual Software Image data for BDX Protocol clients, when a Software Image is determined to be available from the public Internet or from local storage.

Upon receipt of a QueryImageResponse command containing a DelayedActionTime field, the OTA Requestor SHALL wait for at least the stated delay time before initiating the first part of a file trans fer for the URI provided.

The OTA Provider MAY expunge any previously cached Software Image downloaded on behalf of other OTA Requestors, to save storage, at any time, as long as no transfer is currently in active progress. It is RECOMMENDED that OTA Providers on a given Fabric maintain as much Software Image cache as practical, to improve availability of software image and reduce latency between QueryImage requests and availability of the matching QueryImageResponse for a new Software

Image ready to be downloaded.

In order to support non-BDX protocols relying on the public Internet, or intranets, the OTA Requestor SHALL only report support for protocols requiring public Internet access if it has deter mined that it does indeed have access to the necessary network domains beyond the Fabric. The OTA Requestor MAY employ any method it deems satisfactory to determine public Internet reacha bility. Because of the variety of firewall and security policies on network infrastructure, it is REC OMMENDED that all Nodes whose primary networking interactions lie within protocols in-band of this wider specification support the BDX method, so that even if a Node cannot access the public Internet, it MAY still obtain OTA Software Images by relying on a local OTA Provider which can.

For BDX transfers, the following BDX-specific constraints SHALL be followed:

Receiver-Drive mode SHALL be used by the OTA Provider for any transfers initiated from a secure channel on non-TCP
Asynchronous mode SHALL be used by the OTA Provider for any transfer initiated from a secure channel on TCP
Idle time-out SHALL be no less than 5 minutes for either Receiver-Driver or Asynchronous mode, before aborting a
Block sizes constraints SHALL be as follows:

Maximum Block Size over all transports SHALL be a power of two if the OTA Requestor requests a value larger than 128
For an OTA Requestor-requested Maximum Block Size value between 16 and 128, the exact requested value SHALL be This constraint allows low-power Nodes to precisely control the block sizes to ensure their power constraints are respected, including enabling single- frame block transfers over communication mediums where MTU is very small.
Maximum Block Size requested by OTA Requestors over non-TCP transports SHALL be no larger than 1024 (2^10) bytes. OTA Providers SHALL support the Maximum Block Size of at least 1024 bytes in those
Maximum Block Size requested by OTA Requestors over TCP transport SHALL be no larger than 8192 (2 ^ 13) bytes. OTA Providers SHALL support a Maximum Block Size of at least 4096 (2^12) bytes in this case and MAY support 8192
Actual Block Size used over all transports SHALL be the negotiated Maximum Block Size for every block except the last one, which may be of any size less or equal to the Maximum Block Size (including zero).
- The OTA Requestor SHALL NOT rely on the ReceiveAccept message from the OTA Provider hav ing the RC[DEFLEN] bit set (see Section 11.21.5.4.2.1, “ReceiveAccept RC[DEFLEN]: definite length present”) and the associated LEN field Instead, OTA Requestors SHALL rely on OTA

Software Image metadata to determine the expected size to download.

The ReceiveInit message from the OTA Requestor MAY have the RC[STARTOFS] bit set and asso ciated STARTOFS field set to indicate the resumption of a transfer previously aborted, or to affect partial windowed access to the portion of a Software Image
The ReceiveInit message from the OTA Requestor MAY have the RC[DEFLEN] bit set and associ ated DEFLEN field set to state the desired maximum size of the

Since OTA Requestors MAY need to read Software Image in parts, it is RECOMMENDED that OTA Providers maintain cached Software Images for at least 5 minutes after closure of the last OTA Requestor transfer, so that the OTA Requestor MAY come back to read different parts of an OTA file.

In the case of very large Fabrics, it often occurs that there is a large number of the same model of Node within a given location. Because of this, OTA Providers SHOULD avoid downloading the same Software Image repeatedly for proxying if it can determine that multiple OTA Requestors are requesting, or can be expected to request, the same Software Image.

It is RECOMMENDED to keep Software Images cached for as long as practical to reduce having to reach external off-Fabric resources frequently to address the update needs of a large fleet of identi cal Nodes that could share a single pre-downloaded cached copy in the OTA Provider. This reduces burden on content delivery servers for Software Images and reduces the amount of data trans ferred by an OTA Provider from external off-Fabric servers to fulfill software update requirements.

It is RECOMMENDED that Sleepy End Devices make their best effort to optimize their sleep intervals during the OTA Software Image transfer process over BDX to ensure that the download completes in a timely manner. However, it is acknowledged that some Sleepy End Devices MAY not be able to do so, due to limitations related to their batteries or other constrained power sources. Therefore, such devices MAY take much longer to complete the download process.

In the case where a BDX transfer is aborted due to unforeseen circumstances (e.g. power loss, crash, battery drain on either side), the OTA Requestor MAY try to use a partial (i.e. range-based) transfer to recover and continue the download without having to start from the beginning of a given Soft ware Image. An OTA Requestor SHALL abort retrying a transfer after three attempts in a row where each yielded no forward progress.

It is RECOMMENDED for the OTA Provider to validate the length and digest of proxied images whenever possible (see OTA software update file Header field) to avoid continuing a transfer if the data is obviously corrupted.

In any situation where an OTA Requestor reaches a terminal failure point for a Software Image transfer and all possible retries or alternate OTA Providers have been exhausted, that OTA Requestor SHALL reset its entire software updating state and revert to doing a future query at the next possible scheduled time, so that perhaps a new Software Image may be available again.

The above situation may occur, for example, if an OTA Provider had cleared its Software Update Image File cache for any reason, or if there is a transient network failure of sufficient duration to prevent a complete transfer to take place.

Once the entirety of a Software Image has been downloaded and is ready to apply, the OTA Requestor SHALL execute the “Applying a software update” sequence of the next section.

11.19.3.6. Applying a software update

Once a Software Image has been fully downloaded based on a QueryImageResponse command, the OTA Requestor SHALL proceed with a sequence to determine when to apply the update by invoking the ApplyUpdateRequest command.

UpdateToken usage

The OTA Requestor SHALL provide an UpdateToken to the OTA Provider with the ApplyUp dateRequest command. This token SHALL be a previously provided UpdateToken from the last QueryImageResponse, unless the token was lost by the OTA Requestor. In case of token loss, the OTA Requestor SHALL use its Operational Node ID encoded as a 64-bit value in network byte order. This UpdateToken MAY be used by an OTA Provider to track deferred OTA application or otherwise allow short-term tracking of OTA Requestors for algorithmic bookkeeping. The OTA Provider SHALL not consider an invalid UpdateToken as a reason to continuously deny or delay an OTA Requestor’s request to apply a Software Image.

Update application process

On receipt of the ApplyUpdateRequest command, the OTA Provider SHALL respond with an action to be taken by the OTA Requestor before activating the new version. The method used to determine the Action field of the response MAY be based on implementation-specific rules and logic.

Note that the DelayedActionTime field is a relative time delay from the moment of receipt, which needs to be computed by the OTA Provider to reflect the difference between the OTA Provider’s cur rent time and the desired time for execution of the Action.

In case of a successful invocation, the following actions to be taken by the OTA Requestor are possi ble, based on the Action field in the ApplyUpdateResponse command:

Proceed: Apply the update, taking in account the delay time stated in

If the DelayedActionTime is zero, then the OTA Requestor SHALL apply the update without additional
If the DelayedActionTime is non-zero, the OTA Requestor SHALL await at least DelayedAc tionTime seconds prior to applying the software update. An example use of this Action by an OTA Provider is to schedule application of a Software Image based on a user’s preferred update time for Nodes of a certain type (e.g. light bulbs or window coverings) to occur at a time when the user is not at home, or when the temporary unavailability of the Node during the update would not pose a
When the Proceed action is given, the OTA Requestor SHALL NOT invoke the ApplyUp dateRequest command again, unless the OTA Requestor suffers an error or unexpected con dition while proceeding to apply the new Software
- AwaitNextAction: Await at least the given delay time in DelayedActionTime before re-invoking an ApplyUpdateRequest to get a new
If the DelayedActionTime is less than 120 seconds (2 minutes), the OTA Requestor SHALL assume a value of 120
An example use of this Action by an OTA Provider is to schedule application of a Software Image based on non-occupancy of a room, which Nodes collaborating with the OTA Provider may be able to ascertain, but which may require several attempts over
It is RECOMMENDED to keep usage of this Action to a practical minimum, as it may cause OTA Requestors to be delayed in their application of a Software
The AwaitNextAction action SHALL NOT be emitted in such a way as to cause more than 24

hours of delay in applying an available Software Image. It is expected that user consent hav ing been previously granted should satisfy the overall scheduling constraint this imposes.

Discontinue: The OTA Provider is conveying a desire to rescind a previously provided Software Image.
- The DelayedActionTime SHALL be ignored by the OTA Requestor if
- The OTA Requestor SHOULD clear its previously downloaded and verified Software Image, if it had been obtained from the same OTA Provider as the one providing the Discontinue action.
- This action SHALL only be used as a stopgap when it is known that a given Software Image previously provided may cause significant negative side-effects to an OTA Requestor, such as unrecoverable loss of functionality, or other
- In case of receiving this action unexpectedly (e.g. from a different OTA Provider than the one where a Software Image was downloaded), an OTA Requestor MAY ignore it and con sider it the same way as if the ApplyUpdateRequest command had proceeded with an

It is RECOMMENDED that for any OTA Requestor invoking the ApplyUpdateRequest command with an unknown UpdateToken, the OTA Provider SHOULD assume that the OTA Requestor has a Soft ware Image ready to apply and thus respond with the Proceed or Await action, rather than responding with an error or Discontinue action.

In case of time-out or any error in obtaining an answer to the ApplyUpdateRequest command, or in case of a restart or other unrecoverable situation while awaiting the DelayedActionTime for a Pro ceed or Await action, the OTA Requestor SHOULD retry to execute the “Querying the OTA Provider” flow (see Section 11.19.3.2, “Querying the OTA Provider”) again, whenever the OTA Requestor deems it possible.

In case of failure of every possible retry mechanism for at least 3 total attempts, or over more than 24 hours, an OTA Requestor having successfully downloaded and verified a Software Image MAY apply the update. This measure of last recourse is to avoid situations where a critical issue affecting a particular software version would prevent an OTA Requestor or OTA Provider from properly exe cuting the “Applying a Software Update” flow, thus leaving an OTA Requestor in reduced or a for ever-impaired state that could otherwise be resolved by applying the Software Image it had suc cessfully downloaded and verified.

After completion of an update, an OTA Requestor SHOULD invoke a NotifyUpdateApplied command to the OTA Provider which provided the initial query response to indicate that the OTA Requestor has successfully applied the OTA Software Update Image. The OTA Requestor SHALL NOT retry at the application level to invoke this command if a response is not received.

11.19.4. Security considerations

Security for the OTA Software Update capabilities encompasses these areas: Software Image verifi cation, Software Image transport, and Software Image encryption. Security mechanisms in given applications dictate the security level of OTA upgrading. For example, an application with strict security policies (such as a smart lock) MAY support Software Image encryption at rest beyond the secure channel data-in-transit encryption, while other applications MAY only support data-in-tran sit encryption. Each Vendor SHALL decide the list of required security policies for their use of the

OTA Software Update capabilities for a particular product.

11.19.4.1. Image Encryption

A Vendor MAY apply at-rest encryption to Software Image bodies, excluding the Software Update Image Header, using any algorithm of its choosing.

It is out of scope of this specification to mandate such means of protecting the confidentiality of the Software Images.

11.19.4.2. Image Verification

Asymmetric Verification of Authenticity and Integrity

The verification of the authenticity and integrity of Software Images by OTA Requestors is manda tory for security reasons. This is most often accomplished through asymmetric encryption technolo gies where only one entity is able to create a digital signature but many entities are able to verify it. Software Images SHALL be signed by a private key used by the Vendor for software image signing purposes, with that signature attached to the Software Image that is transported to the OTA Requestor. Once the complete Software Image has been received, the signature SHALL be verified using a matching public key known to the OTA Requestor performing the validation. See Section 13.5, “Firmware” for the associated security requirements. The format and algorithms used for code signatures verification are out of scope of this specification. The OTA Provider SHOULD NOT expect to be able to validate OTA Software Image signatures on its own.

OTA Requestors MAY be pre-installed with the certificate (public key) of the entity that created the signature, or they MAY receive the certificate over-the-air. How the signer’s security data is obtained is considered outside the scope of the OTA Software Update Cluster and is Vendor Specific. When signer certificates are sent over-the-air, they SHALL be securely transferred from a trusted source to reduce the chance an attacker MAY inject their own signer certificate into the OTA Requestor.

Software Images with verification mechanisms built in MAY be transported over insecure commu nication mechanisms while still maintaining their authenticity and integrity. In fact, it is likely that the originator of the Software Image (a Vendor) will not be directly connected to any Fabric and therefore distribute the Software Image across other mediums (such as the Internet) before arriv ing on the Fabric. Therefore, it is crucial that the Software Image verification be independent of the communication medium. Any attempts to tamper with the signature or the data itself SHALL be detected and SHALL cause the Software Image to be rejected by the target OTA Requestor. A Soft ware Image from an attacker that crafts its own signed image and tries to have it accepted would be rejected since that image will not be signed by the Vendor’s signing authority.

Since Software Images MAY contain software for multiple sub-components (e.g. main processor firmware, radio firmware, graphical/audio assets) which MAY each employ different code signing keys, Software Images SHOULD provide at least an overall authenticity and integrity validation for the entire image, regardless of how it is segmented.

Individual Vendors MAY augment the basic security and authenticity schemes provided by the Soft ware Images and provide their own extensions within the payloads. Those extensions are outside the scope of the OTA Software Update Cluster.

Software Images MAY be encrypted with symmetric keys such that only those OTA Requestors that need to decrypt the Software Image have access to the key. This MAY be used to mask or obfuscate the contents of Software Images from intermediate network participants conveying the Software Images, while in transit and at rest. However, the security of this system is dependent on the secu rity of all OTA Requestors that have access to the symmetric key and the method of storage of the final Software Image at rest on a given OTA Requestor. The schemes employed by different Vendors to encrypt the body of Software Images in transit and at rest, is outside of the scope of this specifica tion.

11.19.5. Some special situations

With the mechanisms provided by this Cluster, roll-out of new Software Images applies equally to all OTA Requestors of matching a given <VendorID, ProductID> tuple, uniformly across the world. The subsections below describe two situations where finer-grained roll-out can be achieved for some regions or to distribute special non-standard versions.

11.19.5.1. Regional roll-out of Software Images

Some Manufacturers have a policy of rolling-out by region (i.e. set of countries), to provide world- wide release schedule differentiation, as well as to test roll-outs gradually, among other reasons. These regional roll-outs may only be feasible using manufacturer-specific schemes that are in addi tion to the common flows described in this cluster. Common recommended behavior (see Section 11.19.3.3.2, “Conceptual algorithm for matching OTA Software Images applicable to a query”) does not support regional roll-out since there does not exist a location tagging attribute in the Distrib uted Compliance Ledger (DCL). For regional rolls-outs prior to full roll-out, refer to the overall tech niques described in Section 11.19.5.2, “Roll-out of non-standard Software Images”.

11.19.5.2. Roll-out of non-standard Software Images

Many Manufacturers conduct field trials to test different versions of software (e.g. A/B-testing, beta testing), or provide dedicated Software Images to a subset of Nodes to affect particular diagnosis tasks, etc. The mechanism described in this cluster is not particularly well-suited for such fine- grained deployment (unless the OTA Provider is provided by, or associated with, the Manufacturer).

To achieve more targeted roll-out, Vendors MAY commission a Node on the same Fabric as the devices requiring the special rules, so that it MAY provide OTA Provider capabilities beyond the core interoperable aspects of this Cluster. Finer-grained selection MAY be applied by special OTA Software Image Selection logic in a given OTA Provider, using the MetadataForProvider field and MetadataForRequestor fields of the QueryImage command. Furthermore, such special OTA Provider may identify itself by including the MetadataForNode field in a given AnnounceO TAProvider command.

If such a special Software Image is running on an OTA Requestor, the OTA Requestor MAY reject Software Images provided to it by an OTA Provider on the Fabric, to prevent loss of the non-stan dard Software Image. A Factory Data Reset of the OTA Requestor SHALL remove such override.

11.19.5.3. Other considerations

While it is expected that Nodes fulfilling the role of OTA Provider will likely have high availability

within the Fabric, it may be possible some will be battery-operated or be power-cycled frequently. It is RECOMMENDED that an OTA Provider Node that determines it cannot reliably stay available to service OTA Requestors SHOULD avoid responding with an available OTA Software Image when responding to a QueryImage command (see Section 11.19.6.5.2, “QueryImageResponse Command”) unless it has sufficient availability to allow a long-running BDX Protocol transfer to finish. In gen eral, OTA Provider role SHOULD be fulfilled by a Node with a reliable network availability and sta ble power, especially if it is set as a default in the DefaultOTAProviders attribute.

11.19.6. OTA Software Update Provider Cluster

11.19.6.1. Revision History

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

Revision	Description
1	Initial Release

11.19.6.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	OTAP

Cluster ID

ID	Name
0x0029	OTA Software Update Provider

Data Types

StatusEnum

This data type is derived from enum8.

See Section 11.19.3.2, “Querying the OTA Provider” for the semantics of these values.

Value	Name	Summary	Conformance
0	UpdateAvailable	Indicates that the OTA Provider has an update available.	M
1	Busy	Indicates OTA Provider may have an update, but it is not ready yet.	M

Value	Name	Summary	Conformance
2	NotAvailable	Indicates that there is definitely no update currently available from the OTA Provider.	M
3	DownloadProtocol NotSupported	Indicates that the requested download protocol is not sup ported by the OTA Provider.	M

ApplyUpdateActionEnum

This data type is derived from enum8.

See Section 11.19.3.6, “Applying a software update” for the semantics of the values. This enumera tion is used in the Action field of the ApplyUpdateResponse command. See (Section 11.19.6.5.4.1, “Action Field”).

Value	Name	Summary	Conformance
0	Proceed	Apply the update.	M
1	AwaitNextAction	Wait at least the given delay time.	M
2	Discontinue	The OTA Provider is conveying a desire to rescind a previously provided Software Image.	M

DownloadProtocolEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	BDXSynchronous	Indicates support for synchronous BDX.	M
1	BDXAsynchronous	Indicates support for asynchronous BDX.	O
2	HTTPS	Indicates support for HTTPS.	O
3	VendorSpecific	Indicates support for vendor specific proto col.	O

Note that only HTTP over TLS (HTTPS) is supported (see RFC 7230). Using HTTP without TLS SHALL

NOT be supported, as there is no way to authenticate the involved participants.

11.19.6.5. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	QueryImage	Client ⇒ Server	QueryImageRe sponse		M
0x01	QueryImageRe sponse	Server ⇒ Client	N		M
0x02	ApplyUp dateRequest	Client ⇒ Server	ApplyUp dateResponse		M
0x03	ApplyUp dateResponse	Server ⇒ Client	N		M
0x04	NotifyUp dateApplied	Client ⇒ Server	Y		M

QueryImage Command

Upon receipt, this command SHALL trigger an attempt to find an updated Software Image by the OTA Provider to match the OTA Requestor’s constraints provided in the payload fields.

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	VendorID	vendor-id	all			M
1	ProductID	uint16	all			M
2	SoftwareVer sion	uint32	all			M
3	Proto colsSup ported	list[Down loadProto colEnum]	max 8			M
4	Hardware Version	uint16	all			O
5	Location	string	2			O
6	Requestor CanConsent	bool	all		False	O
7	Meta dataFor Provider	octstr	max 512			O

VendorID Field

The value SHALL be the Vendor ID applying to the OTA Requestor’s Node and SHALL match the value reported by the Basic Information Cluster VendorID attribute.

ProductID Field

The value SHALL be the Product ID applying to the OTA Requestor’s Node and SHALL match the value reported by the Basic Information Cluster ProductID attribute.

SoftwareVersion Field

The SoftwareVersion included in the request payload SHALL provide the value representing the current version running on the OTA Requestor invoking the command. This version SHALL be equal to the Software Version attribute of the Basic Information Cluster.

ProtocolsSupported Field

This field SHALL contain a list of all download protocols supported by the OTA Requestor.

This field SHALL be used by the OTA Provider to generate the correct URI for the location of the Software Image when one is found to be available. The values of BDX Synchronous and BDX Asyn chronous SHALL always be supported by an OTA Provider. Furthermore, OTA Providers with access to external networking SHOULD support the HTTPS protocol. OTA Providers MAY support other protocols.

The algorithm to select the specific protocol to use in a given Software Image URI is implementa tion-dependent, provided that the rules in Section 11.19.3.3.1, “Download Protocol selection” are fol lowed.

See Section 11.19.3.2, “Querying the OTA Provider” and Section 11.19.3.5, “Transfer of OTA Software Update images” for more details about usage of this field.

HardwareVersion Field

The value of this field, if present, SHALL contain the OTA Requestor’s hardware version, and SHALL be equal to the HardwareVersion attribute of the Basic Information Cluster.

Location Field

The location, if present, SHALL provide the same value as the Basic Information Cluster Location attribute for the OTA Requestor as configured. This MAY be used by the OTA Provider logic to allow per-region selection of the Software Image.

RequestorCanConsent Field

This field SHALL be set to true by an OTA Requestor that is capable of obtaining user consent for OTA application by virtue of built-in user interface capabilities. Otherwise, it SHALL be false.

See Section 11.19.3.4, “Obtaining user consent for updating software” for application details about usage.

MetadataForProvider Field

ufacturer-specific payload, which the OTA Requestor invoking this command wants to expose to the receiving OTA Provider. This payload MAY be used for any purpose and SHOULD be as small as practical.

The use of this field SHOULD be restricted to Vendor-specific usage and SHALL NOT be used as a selector required to match for the selection of a Software Image in production environments, unless absolutely necessary, as the interpretation of this field may be ambiguous to OTA Providers implementing the Cluster in a compliant but divergent way from the sender.

An example of usage for this field is for an OTA Requestor to provide specific data about grouping or authentication in field trial environments, where the OTA Provider is likely to understand it and be able to act upon it, either for special selection of image, or recording of activity.

An OTA Provider SHALL report the availability of Software Images, if one is found to be applicable using the other provided fields, even if the MetadataForProvider field is deemed to contain invalid or unknown information. That is, the contents of the MetadataForProvider field SHALL NOT be used to deny a software update to an OTA Requestor, unless both OTA Requestor and OTA Provider have an externally agreed-upon policy whereby strictly correct additional MetadataForProvider is expected to fulfill the OTA Software Update process.

Usage of the QueryImage Command

OTA Requestors SHALL send a QueryImage command to the OTA Provider to determine the avail ability of a new Software Image.

See Section 11.19.3.2, “Querying the OTA Provider” for full details about the OTA Software Update Query flow which makes use of this command.

QueryImageResponse Command

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Status	StatusEnum	all			M
1	DelayedAc tionTime	uint32	all			O
2	ImageURI	string	max 256			O
3	SoftwareVer sion	uint32	all			O
4	SoftwareVer sionString	string	1 to 64			O
5	UpdateToken	octstr	8 to 32			O
6	UserConsent Needed	bool	all		False	O
7	Meta dataForRe questor	octstr	max 512			O

Status Field

This field SHALL contain the primary response regarding the availability of a Software Image.

See Section 11.19.3.2, “Querying the OTA Provider” for details about the possible values for this field and their meaning.

DelayedActionTime Field

This field SHALL convey the minimum time to wait, in seconds from the time of this response, before sending another QueryImage command or beginning a download from the OTA Provider. OTA Requestors SHALL respect this minimum delay, unless they had previously restarted and lost track of it. OTA Providers SHOULD expect OTA Requestors to follow this value to their best capabil ity, however, a restarting Node MAY come back sooner, due to having lost track of this state response.

The DelayedActionTime field SHALL only be present if the Status field is set to Busy.

See Section 11.19.3.2, “Querying the OTA Provider” for details about the rules regarding this field.

ImageURI Field

This field, when present, SHALL contain a URI where the OTA Requestor SHOULD download a Soft ware Image. The syntax of the ImageURI field SHALL follow the URI syntax as specified in RFC 3986.

This field SHALL be present if it appears in a QueryImageResponse with a Status of UpdateAvail able.

If the ImageURI specifies a BDX Protocol bdx: scheme, then the following rules describe the location to be used for download:

The URI’s scheme field SHALL be exactly bdx in lowercase
The URI’s authority field SHALL contain only the host portion and SHALL use string representa tion of the Operational Node ID of the Node where to proceed with the download, on the same Fabric on which the OTA Requestor received the
The encoding of the Node ID in the host field SHALL use an uppercase hexadecimal format, using exactly 16 characters to encode the network byte order value of the NodeID, in a similar fashion as the Node Identifier portion of the Operational Instance Name.
1. The Operational Node ID in the host field SHALL match the NodeID of the OTA Provider responding with the QueryImageResponse. The usage of a different Node ID than that of the provider is reserved for future This constraint reduces the number of independent

CASE secure channel sessions that have to be maintained to proceed with OTA software updates, thus reducing energy and resource utilization for the software update process.

The user section of the authority field SHALL be absent, as there are no “users” to be
The port section of the authority field SHALL be absent, as the port for transport SHALL be determined through Operational Discovery of the target
The URI SHALL not contain a query

The URI SHALL not contain a fragment
The path field SHALL employ absolute path representation and SHALL contain the file designa tor of the software image to download at the BDX server. When used with the BDX server, the leading / separating the URI authority from the path SHALL be omitted. When contacting the BDX server, further processing of the file designator SHALL NOT be done, including handling of

URL-encoded escape sequences. Rather, the exact octets of the path, as received SHALL be the values used by both client and server in handling the file designator.

The path SHALL only contain valid URI characters.

These rules above for BDX URIs simplify parsing for OTA Requestors receiving Image URIs. The fol lowing example procedure shows how the format constraints simplify the extraction of the neces sary data to reach the BDX server for download.

Verify that the URI is 24 characters or longer, which is the minimum length of a valid BDX URI with all elements present, for example bdx://00112233AABBCCDD/0.
Verify the presence of prefix bdx:// indicating a BDX URI.
Extract the next 16 characters and convert from uppercase hexadecimal to a 64-bit scalar value, considering network byte order. This is the destination Node
Verify the presence of a path separator / and skip it.
Extract the remaining characters of the string as the file designator to employ when initiating the BDX

Example ImageURI values are below, and illustrate some but not all of valid and invalid cases:

Synchronous or Asynchronous BDX Protocol:
- Valid: bdx://8899AABBCCDDEEFF/the_file_designator123
  - Node ID: 0x8899AABBCCDDEEFF
  - File designator: the_file_designator123
- Valid: bdx://0099AABBCCDDEE77/the%20file%20designator/some_more
  - Node ID: 0x0099AABBCCDDEE77
  - File designator: the%20file%20designator/some_more. Note that the %20 are retained and not converted to ASCII 0x20 (space). The file designator is the path as received verbatim, after the first ‘/’ (U+002F / SOLIDUS) following the
- Invalid: bdx://99AABBCCDDEE77/the_file_designator123
  - Node ID: Invalid since it is not exactly 16 characters long, due to having omitted leading zeros.
- Invalid: bdx://0099aabbccddee77/the_file_designator123
  - Node ID: Invalid since lowercase hexadecimal was
- Invalid: bdx:8899AABBCCDDEEFF/the_file_designator123
  - Invalid since bdx scheme does not contain an authority, that is, it does not have // after the first :.

HTTP over TLS:
- Valid: https://example.domain:8466/software/image.bin

See Section 11.19.3.2, “Querying the OTA Provider” for additional details about the flow.

SoftwareVersion Field

This field indicates the version of the image being provided to the OTA Requestor by the OTA Provider when the Status is UpdateAvailable.

This field SHALL be present if it appears in a QueryImageResponse with a Status of UpdateAvail able.

See Section 11.19.3.2, “Querying the OTA Provider” for additional details about the flow and accept able values.

SoftwareVersionString Field

This field provides a string version of the image being provided to the OTA Requestor by the OTA Provider when the Status is UpdateAvailable.

This field SHALL be present if it appears in a QueryImageResponse with a Status of UpdateAvail able.

See Section 11.19.3.2, “Querying the OTA Provider” for additional details about the flow and accept able values.

UpdateToken Field

This optional field SHALL be present when the Status field contains UpdateAvailable.

See Section 11.19.3.6.1, “UpdateToken usage” for additional details about the generation and usage of UpdateToken.

UserConsentNeeded Field

This field, if present, SHALL only be interpreted if the OTA Requestor had previously indicated a value of True in the RequestorCanConsent field of the QueryImageRequest. This field, when present and set to True, SHALL indicate that a capable OTA Requestor must obtain user-visible consent prior to downloading the OTA Software Image.

See Section 11.19.3.4, “Obtaining user consent for updating software” for application details about usage.

MetadataForRequestor Field

This optional field, if present, SHALL consist of a top-level anonymous list; each list element SHALL have a profile-specific tag encoded in fully-qualified form. Each list element SHALL contain a man ufacturer-specific payload, which the OTA Provider wants to expose to the receiving OTA Requestor. This payload MAY be used for any purpose and SHOULD be as small as practical.

The presence of this field SHALL NOT be required for correct operation of any OTA Provider com pliant with this Cluster specification.

The data for this field does not exist in any Distributed Compliance Ledger record and SHOULD only be emitted by an OTA Provider with this additional knowledge if it has knowledge that the receiving OTA Requestor MAY be able to use it.

ApplyUpdateRequest Command

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	UpdateToken	octstr	8 to 32			M
1	NewVersion	uint32	all			M

UpdateToken Field

This field SHALL contain the UpdateToken as specified in Section 11.19.3.6.1, “UpdateToken usage”. This field MAY be used by the OTA Provider to track minimal lifecycle state to allow finer-grained scheduling of the application of Software Images by OTA Requestors.

NewVersion Field

The NewVersion field included in the request payload SHALL provide the SoftwareVersion value of the new Software Image which the OTA Requestor is ready to start applying. The OTA Provider MAY use this new version to track or record Software Image application by OTA Requestors.

When Generated

The ApplyUpdateRequest Command SHALL be invoked by an OTA Requestor once it is ready to apply a previously downloaded Software Image.

Effect on Receipt

Upon receipt of this command the OTA Provider SHALL respond with an Action field consistent with the next action the OTA Requestor should take, including any possible time delay.

The OTA Provider SHALL NOT refer to previously stored state about any download progress to reply. If any state keeping is done by the OTA Provider, it SHALL only relate to the UpdateToken and the history of prior ApplyUpdateRequest commands.

See Section 11.19.3.6, “Applying a software update” for a description of the flow in response to an OTA Provider receiving an invocation of this command.

Handling Error Cases

See Section 11.19.3.6, “Applying a software update” for all error-handling information.

ApplyUpdateResponse Command

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Action	ApplyUp dateActio nEnum	all			M
1	DelayedAc tionTime	uint32	all			M

Action Field

The Action field SHALL express the action that the OTA Provider requests from the OTA Requestor. See Section 11.19.3.6, “Applying a software update” for a description of the Action values provided in response to an OTA Provider receiving an invocation of this command.

DelayedActionTime Field

The minimum time period the OTA Requestor SHALL wait before executing the Action, in seconds from receipt.

If this field has a value higher than 86400 seconds (24 hours), then the OTA Requestor MAY assume a value of 86400, in order to reduce undue Software Image application delays.

NotifyUpdateApplied Command

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	UpdateToken	octstr	8 to 32			M
1	SoftwareVer sion	uint32	all			M

UpdateToken Field

This field SHALL contain the UpdateToken as specified in Section 11.19.3.6.1, “UpdateToken usage”.

SoftwareVersion Field

The SoftwareVersion included in the request payload SHALL provide the same value as the Soft wareVersion attribute in the invoking OTA Requestor’s Basic Information Cluster, and SHOULD be consistent with the value representing a new version running on the Node invoking the command.

When Generated

The NotifyUpdateApplied command SHOULD be invoked in the following two circumstances:

An OTA Requestor has just successfully applied a Software Image it had obtained from a previ ous QueryImage response.
An OTA Requestor has just successfully applied a Software Image it had obtained through means different than those of this

An OTA Provider MAY use the state of invocation of this command to help track the progress of update for OTA Requestors it knows require a new OTA Software Image. However, due to the possi bility that an OTA Requestor MAY never come back (e.g. device removed from Fabric altogether, or a critical malfunction), an OTA Provider SHALL NOT expect every OTA Requestor to invoke this command for correct operation of the OTA Provider.

This command SHALL be considered optional and SHALL not result in reduced availability of the OTA Provider functionality if OTA Requestors never invoke this command.

Effect on Receipt

An OTA Provider receiving an invocation of this command MAY log it internally.

On receiving this command, an OTA Provider MAY use the information to update its bookkeeping of cached Software Images, or use it for other similar administrative purposes.

11.19.7. OTA Software Update Requestor Cluster

11.19.7.1. Revision History

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

Revision	Description
1	Initial Release

11.19.7.2. Classification

Hierarchy	Role	Scope	PICS Code
Base	Utility	Node	OTAR

Cluster ID

ID	Name
0x002A	OTA Software Update Requestor

Data Types

AnnouncementReasonEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	SimpleAnnouncement	An OTA Provider is announcing its pres ence.	M

Value	Name	Summary	Conformance
1	UpdateAvailable	An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software Image MAY be available.	M
2	UrgentUpdateAvail able	An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software Image MAY be available, which contains an update that needs to be applied urgently.	M

SimpleAnnouncement Value

An OTA Provider is announcing its presence, but there is no implication that an OTA Requestor would have a new Software Image available if it queried immediately.

UpdateAvailable Value

An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software Image MAY be available. The details may only be obtained by executing a OTA Software Update Query procedure. A receiving OTA Requestor SHOULD only query the indicated OTA Provider at the ProviderLocation at its next upcoming OTA Provider query.

UrgentUpdateAvailable Value

An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software Image MAY be available, which contains an update that needs to be applied urgently. The details may only be obtained by executing a OTA Software Update Query procedure. A receiving OTA Requestor SHOULD query the indicated OTA Provider at the ProviderLocation after a random jitter delay between 1 and 600 seconds. This particular reason SHOULD only be employed when an urgent update is available, such as an important security update, or just after initial commissioning of a device, to assist OTA Requestors in more rapidly obtaining updated software.

UpdateStateEnum

This data type is derived from enum8.

Value	Name	Summary	Conformance
0	Unknown	Current state is not yet determined.	M

Value	Name	Summary	Conformance
1	Idle	Indicate a Node not yet in the process of soft ware update.	M
2	Querying	Indicate a Node in the process of querying an OTA Provider.	M
3	DelayedOnQuery	Indicate a Node waiting after a Busy response.	M
4	Downloading	Indicate a Node cur rently in the process of downloading a soft ware update.	M
5	Applying	Indicate a Node cur rently in the process of verifying and applying a software update.	M
6	DelayedOnApply	Indicate a Node waiting caused by AwaitNex tAction response.	M
7	RollingBack	Indicate a Node in the process of recovering to a previous version.	M
8	DelayedOnUserCon sent	Indicate a Node is capa ble of user consent.	M

Unknown Value

This value SHALL indicate that the current state is not yet determined. Nodes SHOULD attempt a better state reporting.

Idle Value

This value SHALL indicate a Node not yet in the process of software update, for example because it is awaiting the moment when a query will be made.

Querying Value

This value SHALL indicate a Node in the process of querying an OTA Provider with QueryImage command, including during the process of awaiting a response to that command.

DelayedOnQuery Value

This value SHALL indicate a Node waiting because it received a prior QueryImageResponse with a Status field indicating Busy.

Downloading Value

This value SHALL indicate a Node currently in the process of downloading a software update.

Applying Value

This value SHALL indicate a Node currently in the process of verifying and applying a software update.

DelayedOnApply Value

This value SHALL indicate a Node waiting because it received a prior ApplyUpdateResponse with an Action field set to AwaitNextAction.

RollingBack Value

This value SHALL indicate a Node in the process of recovering to a previous version from a new version that was applied, but that could not remain in force, for reasons such as invalid data detected on boot, or significant runtime issues such as reboot loops. Eventually, the next state seen SHOULD be Unknown or Idle.

DelayedOnConsent Value

This value SHALL indicate a Node is capable of obtaining user consent through its own means, but is currently awaiting that consent after having determined from a prior QueryImageResponse that an update was available.

ChangeReasonEnum

The ChangeReasonEnum Data Type is derived from enum8.

Value	Name	Summary	Conformance
0	Unknown	The reason for a state change is unknown.	M
1	Success	The reason for a state change is the success of a prior operation.	M
2	Failure	The reason for a state change is the failure of a prior operation.	M
3	TimeOut	The reason for a state change is a time-out.	M
4	DelayByProvider	The reason for a state change is a request by the OTA Provider to wait.	O

Unknown Value

This value SHALL indicate that the reason for a state change is unknown.

Success Value

This value SHALL indicate that the reason for a state change is the success of a prior operation.

Failure Value

This value SHALL indicate that the reason for a state change is the failure of a prior operation.

TimeOut Value

This value SHALL indicate that the reason for a state change is a time-out condition as determined by the OTA Requestor.

DelayByProvider Value

This value SHALL indicate that the reason for a state change is a request by the OTA Provider to await for a delay.

ProviderLocationStruct

This structure encodes a fabric-scoped location of an OTA provider on a given fabric.

Access Quality: Fabric Scoped
ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
1	ProviderN odeID	node-id					M
2	Endpoint	endpoint- no					M

ProviderNodeID Field

This field SHALL contain the Node ID of the OTA Provider to contact within the Fabric identified by the FabricIndex.

Endpoint Field

This field SHALL contain the endpoint number which has the OTA Provider device type and OTA Software Update Provider cluster server on the ProviderNodeID. This is provided to avoid having to do discovery of the location of that endpoint by walking over all endpoints and checking their Descriptor Cluster.

11.19.7.5. Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Confor mance
0x0000	DefaultO TAProvide rs	list[Provid erLoca tionStruct]	desc		[]	RW F VA	M
0x0001	UpdatePos sible	bool	all		True	R V	M
0x0002	UpdateS tate	UpdateSta teEnum	all		Unknown	R V	M
0x0003	UpdateS tateProgre ss	uint8	0 to 100	X	null	R V	M

DefaultOTAProviders Attribute

This field is a list of ProviderLocationStruct whose entries SHALL be set by Administrators, either during Commissioning or at a later time, to set the Provider Location for the default OTA Provider Node to use for software updates on a given Fabric.

There SHALL NOT be more than one entry per Fabric. On a list update that would introduce more than one entry per fabric, the write SHALL fail with CONSTRAINT_ERROR status code.

Provider Locations obtained using the AnnounceOTAProvider command SHALL NOT overwrite val ues set in the DefaultOTAProviders attribute.

UpdatePossible Attribute

This field SHALL be set to True if the OTA Requestor is currently able to be updated. Otherwise, it SHALL be set to False in case of any condition preventing update being possible, such as insufficient capacity of an internal battery. This field is merely informational for diagnostics purposes and SHALL NOT affect the responses provided by an OTA Provider to an OTA Requestor.

UpdateState Attribute

This field SHALL reflect the current state of the OTA Requestor with regards to obtaining software updates. See Section 11.19.7.4.2, “UpdateStateEnum” for possible values.

This field SHOULD be updated in a timely manner whenever OTA Requestor internal state updates.

UpdateStateProgress Attribute

This field SHALL reflect the percentage value of progress, relative to the current UpdateState, if applicable to the state.

The value of this field SHALL be null if a progress indication does not apply to the current state.

A value of 0 SHALL indicate that the beginning has occurred. A value of 100 SHALL indicate com pletion.

This field MAY be updated infrequently. Some care SHOULD be taken by Nodes to avoid over- reporting progress when this attribute is part of a subscription.

11.19.7.6. Commands

ID	Name	Direction	Response	Access	Conformance
0x00	AnnounceO TAProvider	Client ⇒ Server	Y	A	O

AnnounceOTAProvider Command

This command MAY be invoked by Administrators to announce the presence of a particular OTA Provider.

This command SHALL be scoped to the accessing fabric.

If the accessing fabric index is 0, this command SHALL fail with an UNSUPPORTED_ACCESS status code.

Access Quality: Fabric Scoped
ID	Name	Type	Constraint	Quality	Default	Confor mance
0	ProviderN odeID	node-id				M
1	VendorID	vendor-id				M
2	Announce mentReason	Announce mentReaso nEnum				M
3	Meta dataForNode	octstr	max 512			O
4	Endpoint	endpoint-no				M

ProviderNodeID Field

This field SHALL contain the Node ID of a Node implementing the OTA Provider cluster server, on the accessing fabric.

VendorID Field

This field SHALL contain the assigned Vendor ID of the Node invoking this command, as it would appear in that Node’s Basic Information Cluster VendorID attribute.

AnnouncementReason Field

This field SHALL contain a value expressing the reason for the announcement.

MetadataForNode Field

This optional field, if present, SHALL consist of a top-level anonymous list; each list element SHALL have a profile-specific tag encoded in fully-qualified form. Each list element SHALL contain a man ufacturer-specific payload, which the Node invoking this command wants to expose to the receiving Node. This payload MAY be used for any purpose and SHOULD be as small as practical, especially if invoked to groups, in order to reduce networking burden of these payloads.

This field SHOULD only be included if the sending OTA Provider has knowledge that some recipient can make use of it.

Endpoint Field

When Generated

An OTA Provider MAY invoke this command directly to an OTA Requestor, to announce its presence as an OTA Provider on the Fabric.

These announcements, if made, SHOULD be made at most once every 24 hours for any given target Node, to assist OTA Requestors in discovering available OTA Provider resources, unless the AnnouncementReason is UrgentUpdateAvailable, in which case this command MAY be more fre quent.

Any invocation SHALL be made with a delay of at least 1 second between invocations from a given OTA Provider, to reduce burden on the networking infrastructure and affect a form of serialized jit ter. It is RECOMMENDED to offset the first announcement of a round (i.e. new set of announce ments after a previous complete set) by a random delay time with a distribution span of >= 60 sec onds to jitter announcement schedules over time.

Effect on Receipt

On receipt of this command, an OTA Requestor SHOULD consider the new ProviderNodeID and AnnouncementReason to possibly query for new software sooner than it would have with its default behavior.

The OTA Requestor SHOULD NOT update entries in the DefaultOTAProviders list based on announcements.

The receiving Node MAY ignore the content of the announcement if it is unable or unwilling to fur ther query OTA Providers temporarily, or if its provider list is full. If the announcement is ignored, the response SHOULD be SUCCESS.

Depending on the value of the AnnouncementReason field, the OTA Requestor MAY have to query the OTA Provider. See Section 11.19.7.6.1.3, “AnnouncementReason Field” for the different values and their meaning.

If present, the MetadataForNode field’s MAY be used by a receiving OTA Requestor in any way it deems satisfactory. The MetadataForNode field SHOULD be empty under most normal operational circumstance, but can be useful in environments such as field trials or integration test environ ments to hint at additional capabilities which OTA Requestors MAY use in a particular Vendor-spe cific context.

11.19.7.7. Events

ID	Name	Priority	Access	Conformance
0x00	StateTransition	INFO	V	M
0x01	VersionApplied	CRITICAL	V	M
0x02	DownloadError	INFO	V	M

StateTransition Event

This event SHALL be generated when a change of the UpdateState attribute occurs due to an OTA Requestor moving through the states necessary to query for updates.

The data of this event SHALL contain the following information:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Previ ousState	UpdateSta teEnum			Unknown	M
1	NewState	UpdateSta teEnum				M
2	Reason	ChangeRea sonEnum				M
3	TargetSoft wareVer sion	uint32		X	null	M

PreviousState Field

This field SHALL be set to the state that preceded the transition causing this event to be generated, if such a state existed. If no previous state exists, the value SHALL be Unknown.

NewState Field

This field SHALL be set to the state now in effect through the transition causing this event to be gen erated.

Reason Field

This field SHALL be set to the reason why this event was generated.

TargetSoftwareVersion Field

This field SHALL be set to the target SoftwareVersion which is the subject of the operation, when ever the NewState is Downloading, Applying or RollingBack. Otherwise TargetSoftwareVersion SHALL be null.

VersionApplied Event

This event SHALL be generated whenever a new version starts executing after being applied due to a software update. This event SHOULD be generated even if a software update was done using means outside of this cluster.

The data of this event SHALL contain the following information:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Software Version	uint32				M
1	ProductID	uint16				M

SoftwareVersion Field

This field SHALL be set to the same value as the one available in the Software Version attribute of the Basic Information Cluster for the newly executing version.

ProductID Field

This field SHALL be set to the ProductID applying to the executing version, as reflected by the Basic Information Cluster. This can be used to detect a product updating its definition due to a large-scale functional update that may impact aspects of the product reflected in the DeviceModel schema of the Distributed Compliance Ledger.

DownloadError Event

This event SHALL be generated whenever an error occurs during OTA Requestor download opera tion.

The data of this event SHALL contain the following information:

ID	Name	Type	Constraint	Quality	Default	Confor mance
0	Software Version	uint32				M
1	BytesDown loaded	uint64				M
2	Pro gressPer cent	uint8	0 to 100	X	null	M

ID	Name	Type	Constraint	Quality	Default	Confor mance
3	Platform Code	int64		X	null	M

SoftwareVersion Field

This field SHALL be set to the value of the SoftwareVersion being downloaded, matching the Soft wareVersion field of the QueryImageResponse that caused the failing download to take place.

BytesDownloaded Field

This field SHALL be set to the number of bytes that have been downloaded during the failing trans fer that caused this event to be generated.

ProgressPercent Field

This field SHALL be set to the nearest integer percent value reflecting how far within the transfer the failure occurred during the failing transfer that caused this event to be generated, unless the total length of the transfer is unknown, in which case it SHALL be null.

PlatformCode Field

This field SHOULD be set to some internal product-specific error code, closest in temporal/func tional proximity to the failure that caused this event to be generated. Otherwise, it SHALL be null. This event field MAY be used for debugging purposes and no uniform definition exists related to its meaning.

11.20. Over-the-Air (OTA) Software Update File Format

11.20.1. Scope & Purpose

The majority of devices will undergo an over-the-air (OTA) software update at some point during their operational lifecycle. It cannot be assumed that the Node responsible for serving OTA updates (OTA Provider) has any specific knowledge about the internals of OTA Requestor Nodes that are receiving OTA updates. This section provides a standardized header that SHALL be included in all OTA Software Images, in order to provide the necessary information for OTA Providers to validate images available for a given OTA Requestor.

It should be noted that while this specification standardizes an OTA Software Image header that SHALL be used by all OTA Software Images, this specification does not further attempt to standard ize the remaining contents of those files.

11.20.2. General Structure

The OTA Software Image file format is composed of a header followed by an opaque body. The header describes general information about the file such as software version, and the Vendor ID and Product ID for which the image applies, see Section 11.19.3.3.2, “Conceptual algorithm for

matching OTA Software Images applicable to a query”).

OTA Software Image files SHALL use a fixed encoding. Individual fields of the OTA Software Image file may be comprised of more complex data types that utilize other encoding schemes.

The fields that comprise an OTA Software Image file, listed in the sequential order in which they SHALL appear, are provided below.

Table 77. OTA Software Image File Layout

Name	Type
FileIdentifier	uint32
TotalSize	uint64
HeaderSize	uint32
Header	Appendix A, Tag-length-value (TLV) Encoding Format
Payload	N/A

11.20.2.1. FileIdentifier field

The FileIdentifier field is a fixed-width, little-endian-encoded, unsigned 32-bit value that SHALL be included at the beginning of all OTA software image files in order to quickly identify and distin guish the file as being of that format, without having to examine the contents of the whole file. This helps distinguishing the file from other file types in storage. The fixed constant value is defined to

be 0x1BEEF11E.

11.20.2.2. TotalSize field

The TotalSize field is a fixed-width, little-endian-encoded, unsigned 64-bit value that SHALL indi cate the total size, in bytes, of the entire file, including all fields and Payload. This field SHALL match the total stored size of the file. It SHALL match the sum of:

The sizes of the FileIdentifier, TotalSize, and HeaderSize
The value of the HeaderSize field of this header.
The value of the PayloadSize field of the Header For example, given:
Size of total Header structure is 105 bytes, reflected as HeaderSize = 105
Payload size is 128KiB = 128 * 1024 bytes = 131072 bytes, reflected as PayloadSize = 131072

Then the TotalSize would be the sum of:

the size of the FileIdentifier, TotalSize, and HeaderSize fields: 4 + 8 + 4 = 16 bytes
the HeaderSize value = 105 bytes
the PayloadSize value = 131072 bytes

This would give a total of 16 + 105 + 131072 = 131193 bytes. The overall file SHALL have this size and no more, and the TotalSize field SHALL contain that value.

11.20.2.3. HeaderSize field

The HeaderSize field is fixed-width, little-endian-encoded, unsigned 32-bit value that SHALL indi cate the total size, in bytes, of the TLV-encoded Header field.

11.20.2.4. Header field

The Header is a TLV structure, encoded with anonymous outer tag, with the following format:

ota-image-header-struct => STRUCTURE [ tag-order ]

{

VendorID [0] : UNSIGNED INTEGER [ range 16bits ],

ProductID [1] : UNSIGNED INTEGER [ range 16bits ], SoftwareVersion [2] : UNSIGNED INTEGER [ range 32bits ], SoftwareVersionString [3] : STRING [ length 1..64 ], PayloadSize [4] : UNSIGNED INTEGER [ range 64bits ],

MinApplicableSoftwareVersion [5, optional] : UNSIGNED INTEGER [ range 32bits ], MaxApplicableSoftwareVersion [6, optional] : UNSIGNED INTEGER [ range 32bits ], ReleaseNotesURL [7, optional] : STRING [ length 1..256 ],

ImageDigestType [8] : UNSIGNED INTEGER [ range 8bits ], ImageDigest [9] : OCTET STRING [ length 0..64 ]

}

VendorID field

The VendorID field SHALL be used by an OTA Provider to determine if a Node is the intended recip ient of the OTA software update file by checking that the VendorID field in the OTA software update file matches the VendorID received in the Query Image command from the OTA Requestor. This VendorID field MAY be zero, in which case this OTA software update file MAY apply to more than one vendor.

ProductID field

The ProductID field MAY be used by an OTA Provider to determine if a Node is the intended recipi ent of the OTA software update file by checking that the ProductID field in the OTA software update file matches the ProductID received in the Query Image command from the OTA Requestor. This ProductID field MAY be zero, in which case this OTA software update file MAY apply to more than one product.

SoftwareVersion field

The SoftwareVersion field SHALL contain a totally orderable scalar representation of the version for the software contained within the file. The SoftwareVersion value SHOULD not be displayed to an end-user.

For a given version, this SoftwareVersion field SHALL match what the Node will report in its Soft wareVersion attribute in the Basic Information Cluster, once executing the version.

SoftwareVersionString field

The SoftwareVersionString field SHALL contain a human readable (displayable) representation of the version for the software contained within the file. The SoftwareVersionString value SHALL NOT be used by an OTA Provider to determine if the OTA software update file contains a newer image than what is currently running on a Node. The SoftwareVersionString value SHOULD be displayed to an end-user when communicating an identification for the software version.

Format constraints for this field SHALL match the constraints of the SoftwareVersionString attribute in the Basic Information Cluster.

For a given version, this SoftwareVersionString field SHALL match what the Node will report in its SoftwareVersionString attribute in the Basic Information Cluster, once executing the version.

PayloadSize field

The PayloadSize field SHALL indicate the total size, in bytes, of the payload contained within this OTA software update file, beyond the header. The length of all data beyond the terminating byte of the header structure SHALL be equal to this field’s value.

MinApplicableSoftwareVersion field

The MinApplicableSoftwareVersion field, if present, SHALL be used by an OTA Provider to deter mine if the OTA Software Image is suitable for the Node, by checking that the MinApplicableSoft wareVersion field in the OTA software update file is less than or equal to the SoftwareVersion received in the Query Image command from the OTA Requestor.

MaxApplicableSoftwareVersion field

The MaxApplicableSoftwareVersion field, if present, SHALL be used by an OTA Provider to deter mine if the OTA Software Image is suitable for the Node, by checking that the MaxApplicableSoft wareVersion field in the OTA software update file is greater than or equal to the SoftwareVersion received in the Query Image command from the OTA Requestor.

ReleaseNotesUrl field

The ReleaseNotesUrl field, if present, SHOULD specify a link to a product specific web page that contains release notes for the OTA software update file. The syntax of the ReleaseNotesUrl field SHALL follow the syntax as specified in RFC 3986 [https://tools.ietf.org/html/rfc3986]. The specified URL SHOULD resolve to a maintained web page available at that URL for the lifetime of the software version’s availability. The maximum length of the ReleaseNoteUrl attribute is 256 ASCII characters.

ImageDigestType field

The ImageDigestTypeField SHALL contain the algorithm used to compute the ImageDigest field.

The value of this field SHALL be a supported numerical identifier value from the IANA Named Information Hash Algorithm Registry [https://www.iana.org/assignments/named-information/named-informa

tion.xhtml#hash-alg] established as part of RFC 6920. For example, a value of 1 would match the sha- 256 identifier, which maps to the SHA-256 digest algorithm per Section 6.2 of FIPS 180-4

It is RECOMMENDED that a digest algorithm be chosen that has a minimum digest length of 256 bits, such as sha-256 (ID 1 in the registry).

ImageDigest field

The ImageDigestField SHALL contain the digest of the entire payload of length PayloadSize that fol lows the header. The digest SHALL be computed using the algorithm indicated in the ImageDigest Type field. This digest SHOULD be used by OTA Providers to ensure they have obtained the entire image expected, and that the contents matches the expectations.

11.20.3. Security considerations

The OTA Software Image file format does not specify the mechanisms that an OTA Requestor should use to validate that a software image is valid for itself. Considerations relative to OTA Software Image Signing are presented in Section 11.19.4.2, “Image Verification”.

11.21. Bulk Data Exchange Protocol (BDX)

11.21.1. Overview

Nodes need the ability to transfer “files” between nodes. For example, uploading sensor data or diagnostics data to another node or downloading software update images from a software update server both require such a protocol.

This document defines a Bulk Data Exchange (BDX) protocol, where files are modeled as collections of bytes with some attached metadata. For the purposes of this protocol, files are opaque, and no attempt is made to specify their format. However, the protocol allows for extensible metadata so that higher-level applications can participate in the decision whether to proceed with a requested file transfer.

The Bulk Data Exchange (BDX) protocol has some semantic elements influenced by the Trivial File Transfer Protocol (TFTP):

RFC1350, The TFTP Protocol (Revision 2) [https://tools.ietf.org/html/rfc1350]

One major difference is that TFTP is defined to run over UDP only, while Bulk Data Transfers can

proceed over various reliable transports including both TCP and UDP, using the Message Reliablility Protocol (see Section 4.11, “Message Reliability Protocol (MRP)”). Therefore, BlockAck and BlockQuery fulfill the role of application-layer control flow and acknowledgement rather than providing a relia

bility and retransmission mechanism. The availability of application-level flow control enables highly power-constrained nodes to pace transfers in a way that respects their power limitations.

11.21.2. Terminology

11.21.2.1. BDX Sender

The node that has bulk data to send to another node.

11.21.2.2. BDX Receiver

The node that receives bulk data from a Sender.

11.21.2.3. BDX Initiator

The node that initiates a bulk data transfer. The Initiator of a data transfer can either be the Sender (for “upload”, which starts with a SendInit) or the Receiver (for “download”, which starts with a ReceiveInit).

11.21.2.4. BDX Responder

The node that responds to the initiator by either accepting or rejecting the proposed bulk data

transfer and choosing parameters of the transfer compatible with those proposed by the Initiator. It can also either be the Sender (for “download”, which is when the Responder receives a ReceiveInit) or the Receiver (for “upload”, which is when the Responder receives a SendInit).

11.21.2.5. BDX Synchronous / Asynchronous Modes

Bulk data transfers can operate in synchronous (“driven”) or asynchronous mode. When operating in synchronous mode, one party (the Driver) is responsible for controlling the rate at which the transfer proceeds, and each message in the bulk data transfer protocol SHALL be acknowledged before the next message will be sent.

In asynchronous mode, there is no driver and successive messages are freely sent without waiting for BlockAck responses from the Receiver. In asynchronous mode, flow control is provided by the underlying transport (e.g. Matter over TCP).

11.21.2.6. BDX Driver

The node (either Sender or Receiver) that controls the rate at which a synchronous data transfer proceeds by sending Block or BlockQuery messages to advance the transfer. This facility allows for sleepy end-devices operating in RX-off-when-idle or online-offline mode (e.g. due to battery con

straints) to complete a bulk data transfer without requiring them to stay awake continuously dur ing the transfer. In every synchronous bulk data transfer, exactly one device acts as Driver, and the transfer consists of a series of request/responses, each one initiated by the Driver.

BDX utilizes features of the underlying message layer to provide reliability and at-most-once deliv ery semantics. If the transport fails to deliver the message within the specified parameters, the BDX session SHOULD be aborted. For synchronous transfers, if the Driver fails to receive the response to any given request that is not received within a particular application-determined time, it SHOULD abort the session.

11.21.2.7. BDX Follower

The node (either Sender or Receiver) that “follows” the driver in the protocol flow. The protocol defines the followers as devices that can never be sleepy. Follower either receives a BlockQuery to send the data upon request from the driver or receives a new Block message and acknowledges it with a BlockAck message (in synchronous mode).

11.21.2.8. BDX Session

A bulk data transfer Session is a series of messages passed between a Sender and Receiver that begins with the Initiator starting the transfer negotiation, and ends with a BlockAckEOF from the Receiver which indicates receipt of all transmitted data and ends the session. All messages in a ses

sion SHALL be sent within the scope of a single Exchange. Only one bulk data transfer session can be in progress at any time during a Exchange.

11.21.3. Protocol Opcodes and Status Report Values

11.21.3.1. BDX Protocol Messages

Each message in the BDX protocol is mapped to a unique Protocol Opcode, namespaced under the

PROTOCOL_ID_BDX Protocol ID:

Vendor ID = 0x0000 (Matter Common)
Protocol ID = PROTOCOL_ID_BDX

Table 78. BDX Protocol Opcodes

Protocol Opcode	Message
0x01	SendInit
0x02	SendAccept
0x03	Reserved for future use
0x04	ReceiveInit
0x05	ReceiveAccept
0x06 … 0x0F	Reserved for future use
0x10	BlockQuery
0x11	Block
0x12	BlockEOF
0x13	BlockAck
0x14	BlockAckEOF
0x15	BlockQueryWithSkip

11.21.3.2. BDX Status Codes

The list of status codes used in StatusReport messages to signify a reason for failing or rejecting a transfer is provided in Table 79, “BDX Status reports”. For StatusReport messages, the protocol needs to be defined as the BDX protocol, i.e. StatusReport(GeneralCode: FAILURE, ProtocolId: {Ven dorID=0x0000, ProtocolId=BDX}, ProtocolCode: <value>).

Table 79. BDX Status reports

Status code value	Error	Description
0x0012	LENGTH_TOO_LARGE	Definite length too large to support. For exam ple, trying to SendInit with too large of a file.
0x0013	LENGTH_TOO_SHORT	Definite length proposed for transfer is too short for the context based on the responder’s knowledge of expected size.
0x0014	LENGTH_MISMATCH	Pre-negotiated size of transfer was not fulfilled prior to BlockAckEOF.
0x0015	LENGTH_REQUIRED	Responder can only support proposed transfer if definite length is provided.
0x0016	BAD_MESSAGE_CONTENTS	Received a malformed protocol message.
0x0017	BAD_BLOCK_COUNTER	Received block counter out of order from expectation.
0x0018	UNEXPECTED_MESSAGE	Received a well-formed message that was con textually inappropriate for the current state of the transfer.
0x0019	RESPONDER_BUSY	Responder is too busy to proceed with a new transfer at this moment.
0x001F	TRANSFER_FAILED_UN KNOWN_ERROR	Other error occurred, such as perhaps an input/output error occurring at one of the peers.
0x0050	TRANSFER_METHOD_NOT_ SUPPORTED	Received a message that mismatches the cur rent transfer mode.
0x0051	FILE_DESIGNATOR_UN KNOWN	Attempted to request a file whose designator is unknown to the responder.
0x0052	START_OFFSET_NOT_SUP PORTED	Proposed transfer with explicit start offset is not supported in current context.
0x0053	VERSION_NOT_SUPPORTED	Could not find a common supported version between initiator and responder.
0x005F	UNKNOWN	Other unexpected error.

The following StatusReport message ProtocolCode values MAY occur at any time in response to any BDX message:

UNEXPECTED_MESSAGE: When a peer receives a well-formed message that was contextually inappropriate for the current state of the transfer. For example, receiving a Block message before a SendAccept message, or other logical inconsistencies.
BAD_MESSAGE_CONTENTS: When a peer receives a malformed protocol
TRANSFER_FAILED_UNKNOWN_ERROR: Other error occurred, such as perhaps an input/output error occurring at either

UNKNOWN: Internal error beyond the usual error

If any such StatusReport message is received, or any other unexpected StatusReport is received, the receiving peer SHALL terminate its processing of the transfer and invalidate the exchange.

11.21.4. Security and Transport Constraints

In order to maintain data-in-transit confidentiality, and ensure authenticated message flows, the BDX protocol SHALL only be executed over PASE or CASE encrypted session. This is enforced by the fact that the only messages allowed to be transmitted without message security are the actual PASE and CASE session establishment messages.

The BDX protocol MAY be carried over any supported Matter messaging transport, such as BTP, TCP or MRP, as long as the messages appear in a PASE or CASE session.

Furthermore, the BDX protocol relies on transport-level reliability. Therefore, BDX SHALL always be used over reliable transports. For example, usage with Matter messaging over UDP without MRP reliability, that is, without using the R Flag in the Exchange Flags, would prevent the necessary reli ability.

11.21.5. Transfer Management Messages

SendInit and ReceiveInit Messages

A SendInit message is sent by an Initiator to propose a BDX Transfer session where the Initiator wants to be a Sender and deliver information to another node.

A ReceiveInit message is sent by an Initiator to propose a BDX Transfer session where the Initiator wants to be a Receiver and obtain information from another node.

Any BDX transfer exchange begins with one of these two messages.

Both SendInit and ReceiveInit initiate a negotiation for a number of parameters:

the Initiator (sender of the message) proposes the transfer parameters and the block size;
the Responder (receiver of the message) responds with a set of parameters compatible with the Initiator’s proposal, according to the Responder’s subset of capabilities in common with the Ini tiator.

The Responder SHALL indicate all the supported modes of operation applicable to the session by replying, upon success, with SendAccept (in response to SendInit) or ReceiveAccept (in response to ReceiveInit).

The parameters in the SendAccept/ReceiveAccept message MUST be used in the transfer. If those parameters are unacceptable to the Initiator, it MUST abort the transfer with an appropriate error per Table 79, “BDX Status reports”.

Possible replies for SendInit (See Section 11.21.7, “Synchronous Transfers Message Flows” for exam ples):

Success: SendAccept, if the transfer is accepted by the Responder
Failure: StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: <error-specific>), if the transfer is rejected by the Responder, or anything that prevents the Responder from being able to proceed with the transfer as
- FILE_DESIGNATOR_UNKNOWN: The file designator field was present and contained a file designator not supported by the
- START_OFFSET_NOT_SUPPORTED: The start offset field contained an invalid start offset, or presence of start offset indicated by RC[STARTOFS] is not supported by the
- LENGTH_TOO_LARGE: The definite length field was present, but too large for the
- LENGTH_TOO_SHORT: The definite length field was present, but contextually too short based on the responder’s knowledge of expected
- LENGTH_REQUIRED: The responder can only support the proposed transfer if the definite length field is
- TRANSFER_METHOD_NOT_SUPPORTED: The responder does not support the proposed transfer control
- RESPONDER_BUSY: The responder is too busy to process another transfer. An initiator SHOULD wait at least 60 seconds before attempting to initiate a new SendInit with this responder.

Possible replies for ReceiveInit (See Section 11.21.7, “Synchronous Transfers Message Flows” for examples):

Success: ReceiveAccept, if the transfer is accepted by the Responder
Failure: StatusReport(GeneralCode: FAILURE, ProtocolId: PROTOCOL_ID_BDX, ProtocolCode:

<error-specific>), if the transfer is rejected by the Responder, or anything that prevents the

Responder from being able to proceed with the transfer as requested:

FILE_DESIGNATOR_UNKNOWN: The file designator field was present and contained a file designator not found or supported by the
START_OFFSET_NOT_SUPPORTED: The start offset field contained an invalid start offset, or presence of start offset indicated by RC[STARTOFS] is not supported by the
LENGTH_TOO_LARGE: The definite length field was present, but too large for the
LENGTH_REQUIRED: The responder can only support the proposed transfer if the definite length field is
TRANSFER_METHOD_NOT_SUPPORTED: The responder does not support the proposed transfer control
RESPONDER_BUSY: The responder is too busy to process another transfer. An initiator SHOULD wait at least 60 seconds before attempting to initiate a new ReceiveInit with this responder.

The format of the SendInit and ReceiveInit messages is enumerated in Table 80, “Sen dInit/ReceiveInit message fields”.

Table 80. SendInit/ReceiveInit message fields

Field	Size	Notes
Message ID: SendInit(0x01), ReceiveInit(0x04)
Proposed Transfer Con trol (PTC)	1 octet
Range Control (RC)	1 octet
Proposed Max Block Size (PMBS)	2 octets	Unsigned little-endian
Start Offset	4/8 octets	Optional.
(STARTOFS)		• Present if RC[STARTOFS] = 1
		• Size = 4 if RC[WIDERANGE] = 0
		• Size = 8 if RC[WIDERANGE] = 1
Proposed Max	4/8 octets	Optional.
Length (LEN)		• Present if RC[DEFLEN] = 1
		• Size = 4 if RC[WIDERANGE] = 0
		• Size = 8 if RC[WIDERANGE] = 1
File Designator Length (FDL)	2 octets	Unsigned little-endian
File Designator (FD)	variable length
Metadata (MDATA)	variable	Optional, TLV.

The following subsections describe the fields composing the SendInit and `ReceiveInit messages.

Proposed Transfer Control (PTC)

The Proposed Transfer Control (PTC) field specifies, as subfields, the highest version of the protocol and the transfer modes supported by the Initiator of the transfer. All PTC subfields are Initiator-pro posed. It is up to the Responder to decide what version and modes it will use. The first version, as of

Matter specification 1.0 is BDX Version 0.

At least one of the PTC[RECEIVER_DRIVE] or PTC[SENDER_DRIVE] field bits SHALL be set in order for the Responder to set the final transfer control. If neither PTC[RECEIVER_DRIVE] or PTC[SENDER_DRIVE] is set, the transfer SHALL be rejected by the Responder.

The PTC[ASYNC] bit is an optimization of the transfer and is subject to negotiation with the Respon der. In general if the Initiator proposes an ASYNC transfer, it SHOULD also be prepared to accept a synchronous transfer, and SHOULD at least list one of PTC[RECEIVER_DRIVE] or PTC[SENDER_DRIVE] in the request.

Multiple transfer modes can be specified, which signifies that the Initiator can support any of those transfer modes. For example, if PTC[ASYNC], PTC[RECEIVER_DRIVE] and PTC[SENDER_DRIVE] bits are set on a SendInit, it indicates that the Initiator supports 3 distinct transfer modes: synchronous Sender

drive, synchronous Receiver drive and asynchronous (drive is implied). Only one transfer mode SHALL be used in the actual transfer. The Responder SHALL choose which one to use. If the Responder supports both Sender and Receiver drive, it SHOULD prefer to use Sender drive to retain the request/response semantics.

Table 81. SendInit/ReceiveInit Proposed Transfer Control (PTC) field structure

bit 7

RFU

ASYNC

RECEIVER

_DRIVE

SENDER_ DRIVE

VERSION

The fields for PTC are:

SendInit/ReceiveInit PTC[VERSION]: proposed protocol version

Width: 4 bits
Values: 0x00-0x0F proposed protocol version

SendInit/ReceiveInit PTC[SENDER_DRIVE]: sender drive supported

Width: 1 bit
Values:
- 0 if Sender drive is not supported
- 1 if Sender drive is supported by Initiator

SendInit/ReceiveInit PTC[RECEIVER_DRIVE]: receiver drive supported

Width: 1 bit
Values:
- 0 if Receiver drive is not supported
- 1 if Receiver drive is supported by Initiator

SendInit/ReceiveInit PTC[ASYNC]: asynchronous mode supported

Width: 1 bit
Values:
- 0 if asynchronous mode is not supported
- 1 if asynchronous mode is supported by Initiator
- NOTE: Synchronous mode is always implicitly

Range Control (RC)

The Range Control (RC) field specifies parameters related to offset and length of the transfer:

whether the transfer has a definite length (DEFLEN);
whether an offset is present (STARTOFS);
the width of the length and offset fields (WIDERANGE).

Table 82. SendInit/ReceiveInit Range Control (RC) field structure

bit 7	6	5	4	3	2	1	0
RFU			WIDERA NGE	RFU		STARTOF S	DEFLEN

The fields for RC are:

SendInit/ReceiveInit RC[DEFLEN]: definite length present

Width: 1 bit
- Values:
  - 0 if no length is present (indefinite length)
  - 1 if a definite length is present (see DEFLEN field)

SendInit/ReceiveInit RC[STARTOFS]: start offset present

Width: 1 bit
- Values:
  - 0 if a start offset is not present
  - 1 if a start offset is present

SendInit/ReceiveInit RC[WIDERANGE]: wide (64-bit) range enable for values

Width: 1 bit
- Values:
  - 0 to indicate that offset (STARTFOFS) and length (DEFLEN) are 4 octets (32-bit) little-endian unsigned
  - 1 to indicate that offset (STARTFOFS) and length (DEFLEN) are 8 octets (64-bit) little-endian unsigned

Proposed Max Block Size (PMBS)

The Proposed Max Block Size (PMBS) field specifies the maximum data size (in bytes) of the block that the Initiator supports, exclusive of block header fields, such as a block counter.

Start Offset (STARTOFS)

The Start Offset (STARTOFS) field is an optional 32-bit/64-bit length that specifies the offset in bytes from start of the file from which the Sender would start the transfer. This allows large file transfers to be segmented into multiple bulk transfer sessions. The RC[STARTOFS] bit indicates whether this start offset is present in the message. The RC[WIDERANGE] bit defines the size of start offset quantity

(32-bit or 64-bit). Receivers are not required to accept non-zero start offset transfers. Devices

SHOULD make every attempt to support non-zero start offset. If a Responder cannot accept a given start offset, it MUST reject the SendInit with a StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: START_OFFSET_NOT_SUPPORTED). See Table 79, “BDX Status reports”.

Length (DEFLEN)

The optional length (DEFLEN) field specifies a predetermined definite length for the transfer. For a SendInit message, this field defines the number of bytes the Sender commits to sending to the Receiver. For a ReceiveInit message, this field defines the maximum number of bytes that the Receiver wishes to receive from the Sender. The SendAccept or ReceiveAccept response will then con tain the expected length for the transfer. A Receiver receiving a premature BlockEOF would have to

consider the transfer failed. A length of 0 or a missing length field signifies an indefinite length. The RC(DEFLEN) bit indicates the presence of this field. The RC[WIDERANGE] bit indicates the width of this field.

File Designator Length (FDL)

The File Designator Length (FDL) field is a 16-bit unsigned little-endian field over 2 octets that speci fies the length of the upcoming file designator (FD) field, which has variable length.

File Designator (FD)

The File Designator (FD) field is a variable-length identifier chosen by the Initiator to identify the payload to be transferred. In some applications, this identifier will need to be negotiated in advance, so that the Responder will know how to handle the file designator. In other applications,

the file designator and optional metadata will be sufficient for the Responder to determine whether to accept the file transfer and how to handle the data, allowing the transfer to proceed without any additional message exchanges.

The length of this field in bytes is provided by the previous File Designator Length (FDL) field.

Metadata (MDATA)

The Metadata (MDATA) field is an optional field, and allows the Initiator to send additional applica tion-specific information about the file to be transferred. The contents of this field are not specified here; applications can use it to avoid needing a separate round-trip negotiation of the file designa

tor, as described above. The TLV metadata consumes the rest of the payload for the SendInit

/ReceiveInit message, after all previous fields.

11.21.5.2. SendAccept Message

A SendAccept message is sent by the Responder as a response to SendInit in order to accept a BDX Transfer session where the Initiator wants to be a Sender and deliver information (upload) to the

Responder. The final transfer parameters used are decided by the Responder, given the Initiator proposals in the SendInit message.

Responds to (See Section 11.21.7, “Synchronous Transfers Message Flows” for examples):

SendInit – to accept the proposed transfer.

Possible replies (See Section 11.21.7, “Synchronous Transfers Message Flows” for examples):

Block – if the Initiator accepts the parameters from the SendAccept message, and the transfer method is Sender
StatusReport – If there was another error the Initiator encountered.

Possible follow-ups (See Section 11.21.7, “Synchronous Transfers Message Flows” for examples):

BlockQuery – if the proposed method is Receiver drive. If the Initiator does not accept the para meters, it SHOULD ignore this and send a StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: TRANSFER_METHOD_NOT_SUPPORTED) to end the transfer.

11.21.5.3. ReceiveAccept Message

A ReceiveAccept message is sent by the Responder as a response to ReceiveInit in order to accept a BDX Transfer session where the Initiator wants to be a Receiver and receive information (down

load) from the Responder. The final transfer parameters used are decided by the Responder, given the Initiator proposals in the ReceiveInit message.

Responds to (See Section 11.21.7, “Synchronous Transfers Message Flows” for examples):

ReceiveInit – to accept the proposed transfer. Possible replies (See Message Flows for examples):
BlockQuery – if the Initiator accepts the parameters from the ReceiveAccept message, and the transfer method is Receiver
StatusReport – If there was another error the Initiator encountered.

Possible follow-ups (See Section 11.21.7, “Synchronous Transfers Message Flows” for examples):

Block – if the proposed method is Sender drive. If the Initiator does not accept the parameters, it SHOULD ignore this and send a StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, Protocol Code: TRANSFER_METHOD_NOT_SUPPORTED) to end the transfer.

11.21.5.4. SendAccept and ReceiveAccept message fields

The format of the SendAccept message is enumerated in Table 83, “SendAccept message fields”.

The format of the ReceiveAccept message is enumerated in Table 84, “ReceiveAccept message fields”.

Since the meaning of many fields overlap in these messages, they are described only once following the ReceiveAccept message fields.

Table 83. SendAccept message fields

Field	Size	Notes
Message ID: SendAccept(0x02)

Field	Size	Notes
Transfer Con trol (TC)	1 octet	Must specify exactly one of: • TC[ASYNC] • TC[RECEIVER_DRIVE] • TC[SENDER_DRIVE]
Max Block Size (MBS)	2 octets	Unsigned little-endian. Must be <= PMBS.
Metadata (MDATA)	variable	Optional, TLV.

Table 84. ReceiveAccept message fields

Field	Size	Notes
Message ID: ReceiveAccept(0x05)
Transfer Con trol (TC)	1 octet	Must specify exactly one of: • TC[ASYNC] • TC[RECEIVER_DRIVE] • TC[SENDER_DRIVE]
Range Control (RC)	1 octet
Max Block Size (MBS)	2 octets	Unsigned little-endian. Must be <= PMBS.
Length (LEN)	4/8 octets	Optional. • Present if RC[DEFLEN] = 1 • Size = 4 if RC[WIDERANGE] = 0 • Size = 8 if RC[WIDERANGE] = 1
Metadata (MDATA)	variable	Optional, TLV.

The following subsections describe the fields composing the SendAccept and ReceiveAccept mes sages.

Transfer control (TC)

The Transfer Control (TC) field specifies, as subfields, the transfer mode and protocol version.

For the transfer mode (TC[SENDER_DRIVE], TC[RECEIVER_DRIVE]), exactly one mode SHALL be chosen for this transfer, which MUST be one of the original proposed transfer methods sent by the Initia tor.

The version SHALL be the newest version that is supported by the Responder and is not newer than

the proposed version sent by the Initiator. If the Responder cannot support a version equal or older to the proposed version, the Responder MUST send a StatusReport(GeneralCode: FAILURE, Proto colId: BDX_, ProtocolCode: VERSION_NOT_SUPPORTED) to end the transfer.

The Responder MAY reject a proposed asynchronous transfer (PTC[ASYNC] = 1) by sending a Status Report(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: TRANSFER_METHOD_NOT_SUPPORTED) to end the transfer. If the Initiator proposed both the PTC[RECEIVER_DRIVE] and PTC[SENDER_DRIVE], the

Responder SHALL select exactly one of those options. In that case, in order to retain the request/response semantics, the Responder MUST default to TC[SENDER_DRIVE].

Table 85. SendAccept/ReceiveAccept Transfer Control (TC) field structure

bit 7

RFU

ASYNC

RECEIVER

_DRIVE

SENDER_ DRIVE

VERSION

The fields for TC are:

SendAccept/ReceiveAccept TC[VERSION]: protocol version

Width: 4 bits
Values: 0x00-0x0F accepted protocol version

SendAccept/SendAccept TC[SENDER_DRIVE]: sender drive enabled

Width: 1 bit
Values:
- 0 if Sender drive was not chosen
- 1 if Sender drive was chosen (if this is set, TC[RECEIVER_DRIVE] MUST be 0)

SendAccept/ReceiveAccept TC[RECEIVER_DRIVE]: receiver drive enabled

Width: 1 bit
Values:
- 0 if Receiver drive was not chosen
- 1 if Receiver drive was chosen (if this is set, TC[SENDER_DRIVE] MUST be 0)

SendAccept/ReceiveAccept TC[ASYNC]: asynchronous mode enabled

Width: 1 bit
Values:
- 0 if synchronous mode was chosen for the
- 1 if asynchronous mode was chosen for the
- NOTE: Synchronous mode is always implicitly

ReceiveAccept Range Control (RC)

NOTE This field is only present in ReceiveAccept messages.

The Range Control (RC) field specifies parameters related to offset and length of the transfer:

whether the transfer has a definite length (DEFLEN);
the width of the length and offset fields (WIDERANGE).

Table 86. ReceiveAccept Range Control (RC) field structure

bit 7	6	5	4	3	2	1	0
RFU			WIDERA NGE	RFU			DEFLEN

The fields for RC are:

ReceiveAccept RC[DEFLEN]: definite length present

Width: 1 bit
- Values:
  - 0 if no length is present (indefinite length)
  - 1 if a definite length is present (see LEN field)

ReceiveAccept RC[WIDERANGE]: wide (64-bit) range enable for values

Width: 1 bit
- Values:
  - 0 to indicate that length LEN is a 4 octets (32-bit) little-endian unsigned
  - 1 to indicate that length LEN is a 8 octets (64-bit) little-endian unsigned

Max Block Size (MBS)

The Max Block Size (MBS) field specifies the maximum size, in bytes, of each block for this transfer. The maximum whole block payload size will be the sum of the Max Block Size and the size of the block parameters (such as the block counter). This value MUST be less than or equal to the pro

posed max block size (PMBS).

Length (LEN)

NOTE This field is only present in ReceiveAccept messages, and only if `RC[DEFLEN] = 1.

The Length (LEN) field specifies the length of the transfer. If the Initiator indicated a definite length, this length SHALL either be:

equal to the proposed definite length, if the remaining data in the file beyond the Start Offset (STARTOFS) is larger or equal to the proposed length;

smaller than the proposed definite length, if the remaining data in the file beyond the Start Off set (STARTOFS) is smaller than the proposed

If this field is present, and the Initiator indicated an indefinite length (i.e. RC[DEFLEN] = 0 in ReceiveInit), this Length field SHALL be equal to the size of the file remaining (if known), or 0, for indefinite. The absence of the Length (LEN) field implies indefinite length.

Metadata (MDATA)

The Metadata (MDATA) field is optional and allows the Responder to provide application-specific metadata about the transfer in TLV format. The TLV metadata consumes the rest of the payload for the SendAccept/ReceiveAccept message, after all previous fields.

11.21.6. Data Transfer Messages

11.21.6.1. Block Ordering Rules

The following behavior applies to all messages containing a Block Counter field.

Queries (BlockQuery message) MUST be made in ascending and sequential Block Counter order. If the arriving Block Counter at the recipient is not exactly equal to the previous `BlockQuery’s Block Counter, plus 1 (i.e. next block is being directly asked), a block counter SHALL be considered out-of-

order by the recipient.

Blocks (Block, BlockEOF message) MUST be sent in ascending and sequential Block Counter order. If the arriving Block Counter at the recipient is not exactly equal to current expected Block Counter, the block counter SHALL be considered out-of-order by the recipient.

Block acknowledgements (BlockAck, BlockAckEOF messages) MUST be sent with the same Block Counter as the previously received Block/BlockEOF, since they convey a direct acknowledgement. If

the arriving Block Counter at the recipient is not exactly equal to the last sent Block Counter, the Block Counter SHALL be considered out-of-order by the recipient.

On any out-of-order block counter condition described above, the recipient of the out-of-order mes sage MUST send a StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: BAD_BLOCK_ COUNTER) and abort the transfer. On receiving a StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: BAD_BLOCK_COUNTER), the recipient MUST abort the transfer.

Since Block Counter fields are always 32-bit unsigned integer values, but file sizes may be specified over 64-bit lengths to support very large transfers, the ordering for a “next block counter” SHALL use modulo 2^32 integer arithmetic. Therefore, if the last Block Counter was 0xFFFF_FFFF, the next expected Block Counter would be 0x0000_0000.

NOTE

Since the data length of blocks does not need to exactly match the Max Block Size in Block/BlockEOF messages, it is application-dependent whether Block Counters can be used to statelessly track the offset within a span of initiated transfer. That is, the relationship: current_offset = start_offset + (max_block_size * block_counter) is true only if it is contextually known that this usage applies for a given transfer

application. This relationship, is MUST NOT be assumed, since it may not apply, such

as when variable-sized blocks are being sent to optimize a given data transfer flow.

11.21.6.2. BlockQuery Message

The BlockQuery message is sent by the driving Receiver to the follower to request the next block of data. This message implies a BlockAck of the previous block if no BlockAck was explicitly sent. The block counter SHOULD start at 0 at the start of the transfer, and increment by one for each subse

quent block.

In asynchronous transfers, no BlockQuery messages are sent. The fields of the BlockQuery message are:

Table 87. BlockQuery message fields

Field	Size	Notes
Message ID: BlockQuery(0x10)
BlockCounter	4 octets	Unsigned little-endian

11.21.6.3. BlockQueryWithSkip Message

The BlockQueryWithSkip message MAY be sent by a driving Receiver to the follower to request the next block of data, after skipping an amount forward within the stream. This message implies a BlockAck of the previous block if no BlockAck was explicitly sent.

This message is semantically equivalent to a BlockQuery, but with the following additions:

Before the next Block is sent by the Sender, the cursor within the underlying data transferred by the Sender SHALL be advanced by BytesToSkip
If, after skipping BytesToSkip bytes, the cursor reaches the end of the file, or beyond, then the next message from the Sender SHALL be a BlockEOF with empty contents. In other words, there SHALL be no error indicated when receiving a request to skip past the end of the transferable

data.

The amount of BytesToSkip MAY be a size that does not match the current transfer’s maximum block

This message enables seeking forward in BDX transfers without requiring the termination of a transfer followed by the re-opening of a new one with a different STARTOFS field specified.

In asynchronous transfers, no BlockQueryWithSkip messages are sent. The fields of the BlockQueryWithSkip message are:

Table 88. BlockQueryWithSkip message fields

Field	Size	Notes
Message ID: BlockQueryWithSkip(0x15)
BlockCounter	4 octets	Unsigned little-endian

Field	Size	Notes
BytesToSkip	8 octets	Unsigned little-endian

11.21.6.4. Block Message

The Block message is the container for the actual bulk transfer data.

Blocks MUST be sent ascending and sequential block counter order (see Section 11.21.6.1, “Block Ordering Rules”). Block data payload length does not need to exactly match the Max Block Size for the transfer.

The fields of the Block message are:

Table 89. Block message fields

Field	Size	Notes
Message ID: Block(0x11)
Block Counter	4 octets	Unsigned little-endian
Data	Variable Length	• The data field’s length is that of the remain der of the message payload after the Block Counter field, since Matter messages have definite length. • The length MUST be in the range [0 < Length <= Max Block Size], where Max Block Size is the negotiated Max Block Size matching the SendAccept / ReceiveAccept message that initiated the transfer.

11.21.6.5. BlockEOF Message

The BlockEOF message represents the final block in a data transfer.

Note that, unlike a Block, BlockEOF MAY have a data length of zero. If the entire transfer fits within the negotiated block size, the BlockEOF SHALL be the one and only message sent in the exchange and no Block messages will be sent. In that trivial case, the Block Counter would be 0 in the Block EOF.

On receipt of this message, the recipient SHALL verify that the pre-negotiated file size was trans ferred, if a definite size had been given. If the Receiver finds a discrepancy between the pre-negoti ated size of the file and the amount of data that the Sender has sent, then it MAY consider the trans

fer failed. In that case, the Receiver MAY respond with a StatusReport(GeneralCode: FAILURE, Proto colId: BDX, ProtocolCode: LENGTH_MISMATCH) message.

Table 90. BlockEOF message fields

Field	Size	Notes
Message ID: BlockEOF(0x12)
Block Counter	4 octets	Unsigned little-endian
Data	Variable Length	• The data field’s length is that of the remain der of the message payload after the Block Counter field, since Matter messages have definite length. • The length MUST be in the range [0 <= Length <= Max Block Size], where Max Block Size is the negotiated Max Block Size matching the SendAccept / ReceiveAccept message that initiated the transfer. In con trast to the Block message, a length of 0 is permissible to indicate an empty file.

11.21.6.6. BlockAck

The BlockAck message is an application-level acknowledgement that a Block was received, and not necessarily that the Block’s data was stored.

If the Sender is driving in a synchronous transfer, the Receiver MUST send a BlockAck in response to each block of data received. If the Receiver is driving in a synchronous transfer, the Receiver MAY send a BlockAck after receipt of a Block, and before its next BlockQuery. For example, the Receiver

SHOULD send a BlockAck if it knows it will be going to sleep for some time before the next Block

Query, so that the Sender can free resources associated with the last block.

In asynchronous transfers, no BlockAck messages are sent.

The Block Counter in a BlockAck MUST correspond to the Block Counter which was embedded in the

Block being acknowledged (see Section 11.21.6.1, “Block Ordering Rules”).

Table 91. BlockAck message fields

Field	Size	Notes
Message ID: BlockAck(0x13)
BlockCounter	4 octets	Unsigned little-endian

11.21.6.7. BlockAckEOF

The BlockAckEOF message is sent in response to BlockEOF to indicate that the Receiver has received all data.

This message MUST be sent in both synchronous and asynchronous transfers. This signals the end of the ongoing bulk data transfer session and a successful transfer of the file. The table below enu merates the contents of the message

The Block Counter in a BlockAckEOF MUST correspond to the Block Counter which was embedded in

the BlockEOF being acknowledged (see Section 11.21.6.1, “Block Ordering Rules”).

Table 92. BlockAckEOF message fields

Field	Size	Notes
Message ID: BlockAckEOF(0x14)
BlockCounter	4 octets	Unsigned little-endian

11.21.7. Synchronous Transfers Message Flows

Figure 75. Version negotiation: both participants support V1 of the protocol

Figure 76. Version negotiation: Initiator supports V2 of the protocol, while Responder supports V1

Figure 77. Synchronous file sending from sleepy device acting as driving Sender

Figure 78. Synchronous file sending to sleepy device acting as driving Receiver

Figure 79. Synchronous file receiving by sleepy device acting as driving Receiver

Figure 80. Synchronous file receiving by device acting as driving Receiver, including BlockQueryWithSkip

Figure 81. Synchronous file receive from sleepy device acting as driving Sender

In the following flow, the Initiator wants to continue downloading (receiving) a file after the first 200 bytes were received in a previous transfer. The entire remaining contents is desired until the

end of the file. Therefore, the proposed start offset (STARTOFS) is set to the offset of the first byte desired in the first block transferred. The proposed length (PLEN) is set to 0 (or omitted) to announce

desire to receive as much as is available from the Sender.

During negotiation, the length (LEN) field of ReceiveAccept is set to the known remaining file size by the Sender. This could have also been omitted in case the Sender could not or would not state the maximal amount of data to read. Observe that block numbering begins at 0 for every transfer, even if the start offset is not 0. Block indices are always 0-based for every transfer.

Figure 82. Re-started receive from sleepy device acting as driving Sender

In the following flow, the Initiator wants to download (receive) only a section of a file, starting at

offset 200, and of length 1000.

During negotiation, the length (LEN) field of ReceiveAccept is set to match the proposed desired region length by the Sender. The range is fully-specified by the [startOffset .. startOffset + length] span.

Figure 83. Range-based receive from sleepy device acting as driving Sender

11.21.8. Asynchronous Tranfers Message Flows

Figure 84. Asynchronous file sending

Figure 85. Asynchronous file receiving

11.22. Distributed Compliance Ledger

11.22.1. Scope & Purpose

The CSA’s DCL (Distributed Compliance Ledger) is a distributed store of information used for track ing certification status and Vendor maintained information such as, but not limited to, product name, product description, and firmware URL. This information is cryptographically secured by digital signatures and is made available via CSA approved synchronized servers or nodes that are

geographically distributed.

The Policies, Procedure and Governance of DCL is maintained by Board approved committees that comprise Test Certification Oversight Committee (TCOC) and Security Advisory Group (SEC AG).

Distributed Compliance Ledger [https://github.com/zigbee-alliance/distributed-compliance-ledger] is an open- source project designed to:

Act as a data store for device models’ information and their compliance
Act as a secure distribution point of device meta data as made available by
Act as a secure distribution point of Product Attestation Authorities certificates.

The DCL is owned and hosted by CSA members in a way that,

Write access to Ledger is restricted
- Vendors role can add new device models that belong to the VendorID that is associated with the public key of that vendor. VendorID is associated to the vendor public key during vendor account creation
- Vendor role can update a subset of existing device model information, such as product name, product description, firmware and hardware info. Updates are only allowed if the device is associated with the same vendor
- A TestHouse role can write the test status for each device to the
- A ZBCertificationCenter role can write the confirmation of the Compliance or revoke the Compliance status of a device model to the
Read access from DCL is public
- Read DeviceModel info, including firmware and hardware versions from the
- Read the Device compliance state from the
- Read the Product Attestation Authorities certificates.

The DCL is cryptographically secure, machine-readable, and distributed. More details about the Ledger can be found here [https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/ DCL-Overview.pdf].

While the DCL repository [https://github.com/zigbee-alliance/distributed-compliance-ledger/] functionality MAY contain more features which MAY evolve independently from those described in this section, this section SHALL be the normative source of truth for usage of the DCL within this specification.

The DCL best practice guidelines are available in Section 13.6.9, “Distributed Compliance Ledger”.

11.22.2. Schemas

Ledger data is available in following schemas.

Vendor Schema
- Provide general information about a Vendor such as Company legal name, Preferred brand name associated with VendorID, Landing page URL for vendor,

PAA Schema
- Provide a list of Product Attestation Authorities Certificates for the approved
DeviceModel Schema
- Provide general information about a device, and the information is shared across all soft ware
- g ProductName, ProductLabel, PartNumber, Commissioning info, etc.