페이지 선택
Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
Search in pages

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 exists a Group Key Set associated with the accessing fabric which has the same GroupKey­ SetID as that provided in the GroupKeySetID field, then the contents of that Group Key Set SHALL be removed, including all epoch keys it contains.

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

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

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

 

11.2.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
0 2G4

2.4GHz – 2.401GHz to

2.495GHz

(802.11b/g/n/ax)

O.a+
1 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 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 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.

 

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.

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.

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

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.

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:

  1. 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
  2. Sufficient time to account for possible message-layer retries when a response is
  3. Sufficient time to allow operational discovery on the new network by a Commissioner or Administrator.
  4. Sufficient time to establish a CASE session after operational discovery
  5. Not so long that, in error situations, the delay to reverting back to being discoverable for com­ missioning with a previous configuration would cause significant user-perceived

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:

  1. If the Network Commissioning cluster’s InterfaceEnabled attribute is set to false, skip the processing the interface
  2. Set all configurations of the Networks attribute entry’s Connected field to false
  3. 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
  4. Attempt to connect to the technology, using the current iteration’s network configuration
  5. On success, set the Connected state of the list entry to true, and stop attempting further connec­ tion. Otherwise, on failure, move to the next

 

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:

  1. Terminate any open PASE secure session by clearing any associated Secure Session Context at the
  2. 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
  3. If an AddNOC or UpdateNOC command has been successfully invoked, terminate all CASE ses­ sions associated with the Fabric whose Fabric Index is recorded in the Fail-Safe context (see Sec­ tion 11.9.6.2, “ArmFailSafe Command”) by clearing any associated Secure Session Context at the Server.
  4. Reset the configuration of all Network Commissioning Networks attribute to their state prior to the Fail-Safe being
  5. If an UpdateNOC command had been successfully invoked, revert the state of operational key pair, NOC and ICAC for that Fabric to the state prior to the Fail-Safe timer being armed, for the Fabric Index that was the subject of the UpdateNOC
  6. If an AddNOC command had been successfully invoked, achieve the equivalent effect of invok­ ing the RemoveFabric command against the Fabric Index stored in the Fail-Safe Context for the Fabric Index that was the subject of the AddNOC command. This SHALL remove all associations to that Fabric including all fabric-scoped data, and MAY possibly factory-reset the device depending on current device state. This SHALL only apply to Fabrics added during the fail-safe period as the result of the AddNOC command.
  7. Remove any RCACs added by the AddTrustedRootCertificate command that are not currently referenced by any entry in the Fabrics attribute.
  8. Reset the Breadcrumb attribute to
  9. 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:

  1. The Fail-Safe timer associated with the current Fail-Safe context SHALL be
  2. The commissioning window at the Server SHALL be
  3. 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”).
  4. The Secure Session Context of any PASE session still established at the Server SHALL be
  5. 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

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0000 PHYRate

PHYRa­

teEnum

all X null R V O
0x0001 FullDu­ plex bool all X null R V O

 

 

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

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

 

 

ID Name Type Constraint Quality Default Confor­ mance
0 Offset int32

-43200 to

50400

    M
1 Name string 0 to 64 bytes     O

 

Offset Field

 

Current time zone offset from UTC in seconds.

 

Name Field

 

Current time zone name. This name SHOULD use the country/city format specified by the IANA time zone database [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:

 

  1. GNSS time source, if supported by the
  2. Trusted, high-resolution, external time source (ex. network NTP, trusted cloud-based source), if supported by the Node and external connectivity is
  3. If NTPClient (NTPC) feature: NTP server defined in the DHCPv6 NTP server option, if DHCPv6 is supported on the
  4. If NTPClient (NTPC) feature: NTP server defined by DHCP if the Node supports
  5. 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
  6. 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
  7. 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:

 

  1. Encode the attestation-elements structure with an anonymous tag into an octet string called attestation_elements_message.
    • The firmware_information field SHALL be an octet string, as described in Section 6.3.2, “Firmware Information”.
    • The certification_declaration field SHALL be the DER-encoded octet string representation of a CMS(RFC5652)-encoded certification declaration, as described in Section 6.3, “Certification Declaration”.
    • The timestamp field SHALL be in epoch-s.
    • The attestation_nonce field SHALL match the AttestationNonce field provided in the Attesta­ tionRequest Command that triggered the generation of the Attestation

 

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

}

  1. 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
  2. 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
  3. Compute the attestation_signature and record it as an ec-signature octet string:
 
   

 

  1. Fill the AttestationElements field of the AttestationResponse Command using the contents of the attestation_elements_message octet
  2. Fill the AttestationSignature field of the AttestationResponse Command using the contents of the attestation_signature octet
  3. 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:

 

  1. Encode the nocsr-elements structure with an anonymous tag into an octet string called noc­ sr_elements_message.
    • The csr field SHALL be a DER-encoded octet string of a properly encoded PKCS #10 Certifi­ cate Signing Request (CSR), signed with the Node Operational Private Key associated with the Node Operational Public Key, which is the subjectPublicKey field of the CSR. See Section 6.4.6.1, “Node Operational Certificate Signing Request (NOCSR) Procedure” for details about the generation of the Node Operational Key Pair, and the contents of the
    • 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
 
   

 

  1. 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
  2. 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
  3. Compute the attestation_signature and record it as an ec-signature octet string:
 
   

 

  1. Fill the NOCSRElements field of the CSRResponse Command using the contents of the nocsr_ele­ ments_message octet
  2. Fill the AttestationSignature field of the CSRResponse Command using the contents of the attes­ tation_signature octet
  3. 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 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.

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.

 

ID Name Type Constraint Quality Default Confor­ mance
0

NOCSREle­

ments

octstr max RESP_­ MAX     M
1 Attesta­ tionSigna­ ture octstr 64     M

 

NOCSRElements Field

 

This field SHALL contain the octet string of the serialized nocsr_elements_message.

 

AttestationSignature Field

 

This field SHALL contain the octet string of the necessary attestation_signature as described in Sec­ tion 11.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:

 

  1. Verify the NOC using:

 

  1. Crypto_VerifyChain(certificates = [NOCValue, ICACValue, RootCACertificate]) if ICACValue is present,
  2. Crypto_VerifyChain(certificates = [NOCValue, RootCACertificate]) if ICACValue is not present. If this verification fails, the error status SHALL be
  1. 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.
  2. 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 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.

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:

  1. A new FabricIndex SHALL be allocated, taking the next valid fabric-index value in monotoni­ cally incrementing order, wrapping around from 254 (0xFE) to 1, since value 0 is reserved and using 255 (0xFF) would prevent cluster specifications from using nullable fabric-idx
  2. An entry within the Fabrics attribute table SHALL be added, reflecting the matter-fabric-id RDN within the NOC’s subject, along with the public key of the trusted root of the chain and the AdminVendorID
  3. The operational key pair associated with the incoming NOC from the NOCValue, and generated by the prior CSRRequest command, SHALL be recorded for subsequent use during CASE within the fail-safe timer period (see Section 5.5, “Commissioning Flows”).
  4. The incoming NOCValue and ICACValue (if present) SHALL be stored under the FabricIndex associated with the new Fabric Scope, along with the RootCACertificate provided with the prior successful AddTrustedRootCertificate command invoked in the same fail-safe
    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.
  5. The NOCs list SHALL reflect the incoming NOC from the NOCValue field and ICAC from the ICAC­ Value field (if present).
  6. The operational discovery service record SHALL immediately reflect the new Operational Iden­ tifier, such that the Node immediately begins to exist within the Fabric and becomes reachable over CASE under the new operational
  7. The receiver SHALL create and add a new Access Control Entry using the CaseAdminSubject field to grant subsequent Administer access to an Administrator member of the new Fabric. It is RECOMMENDED that the Administrator presented in CaseAdminSubject exist within the same entity that is currently invoking the AddNOC command, within another of the Fabrics of which it is a

 

  1. 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.
  2. 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
  3. 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.
  4. 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 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.

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:

  1. The Operational Certificate under the accessing fabric index in the NOCs list SHALL be updated to match the incoming NOCValue and ICACValue (if present), such that the Node’s Operational Identifier within the Fabric immediately
    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:

 

  1. If the FabricIndex matches the last remaining entry in the Fabrics list, then the device SHALL delete all Matter related data on the node which was created since it was commissioned. This includes all Fabric-Scoped data, including Access Control List, 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.

  1. 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.
  2. 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 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.

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.

If the fail-safe timer is currently armed, this command SHALL fail with a cluster specific status code of Busy, since it is likely that concurrent commissioning operations from multiple separate Commis­ sioners are about to take place.

In case of any other parameter error, this command SHALL fail with a status code of COM­ MAND_INVALID.

The commissioning into a new Fabric completes when the Node successfully receives a Commis­ sioningComplete command, see Section 5.5, “Commissioning Flows”. The new Administrator SHALL discover the Node on the IP network using DNS-based Service Discovery (DNS-SD) for commission­ ing.

The data for this command is as follows:

 

ID Name Type Constraint Quality Default Confor­ mance
0 Commis­ sioning­ Timeout uint16 desc     M

 

CommissioningTimeout Field

 

This field SHALL specify the time in seconds during which commissioning session establishment is allowed by the Node. This 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:

  1. A new Software Image is determined to be
  2. The Software Image to proxy is served by a remote server that does NOT support range-based transfers.
  3. The OTA Requestor only supports
  4. The OTA Provider does not support asynchronous proxying (e.g. download-then-proxy).

 

The fields of the QueryImageResponse command convey the next steps to take. The primary indica­ tion of action to be taken by the OTA Requestor is expressed in the Status field, with the other fields providing the necessary details as described in the following subsections.

Failure to receive an application-layer response from the OTA Provider after invoking the QueryIm­ age command SHOULD be considered equivalent to having received a QueryImageResponse com­ mand with a Status field containing NotAvailable (see Section 11.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:
  1. 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”).
  2. Image was partially downloaded: the OTA Requestor SHOULD attempt to continue the trans­ fer from where it left off, if it is capable, otherwise it SHALL start the transfer 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:

  1. If the OTA Requestor has a Software Image it had previously successfully downloaded and veri­ fied, the OTA Requestor SHOULD skip the Query step, and move directly to the Apply step (see Section 11.19.3.6, “Applying a software update”). This increases the likelihood that the OTA Requestor will eventually succeed to apply a previously transferred Software
  2. If the OTA Requestor is still attempting to discover an OTA Update, it MAY choose to attempt a QueryImage command on a different OTA Provider in its OTA Provider List, in which case the timing for the query SHALL match the query timing constraints expressed in the previous para­ graphs of this section. Otherwise, it SHALL continue to query the same OTA Provider, again fol­ lowing the query timing constraints previously

 

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:

 

  1. Assume no matching candidate found
    • candidateWasFound := False
    • softwareVersionFound := 0
  2. Obtain candidates from a DCL replica or from a DCL-based dataset for the given vendorID and

productID in the query, keeping only entries where softwareVersionValid is true.

  • An OTA Provider MAY as well filter available versions by certification compliance status (see Section 11.22.7, “DeviceSoftwareCompliance / Compliance test result Schema”).
  1. Sort all candidates by ascending softwareVersion.
  2. 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
  3. 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:

  1. The OTA Requestor SHALL set the RequestorCanConsent field in the QueryImageRequest to True, indicating ability to obtain
  2. The OTA Provider, if it determines that the best way to obtain user consent is to delegate to the

 

OTA Requestor Node, SHALL include the UserConsentNeeded field, with a value set to True in the QueryImageResponse, indicating that user consent was not previously obtained, and that delegation SHALL occur.

  1. 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:
  1. The Software Image is at a URI referring to a resource on the public Internet (e.g.

https://domain.example/images/software.bin).

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

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

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

This optional field, if present, SHALL consist of a top-level anonymous list; each list element SHALL have a profile-specific tag encoded in fully-qualified form. Each list element SHALL contain a man­

 

ufacturer-specific payload, which the OTA Requestor invoking this command wants to expose to the receiving OTA Provider. This payload MAY be used for any purpose and SHOULD be as small as practical.

The use of this field SHOULD be restricted to Vendor-specific usage and SHALL NOT be used as a selector required to match for the selection of a Software Image in production environments, unless absolutely necessary, as the interpretation of this field may be ambiguous to OTA Providers implementing the Cluster in a compliant but divergent way from the sender.

An example of usage for this field is for an OTA Requestor to provide specific data about grouping or authentication in field trial environments, where the OTA Provider is likely to understand it and be able to act upon it, either for special selection of image, or recording of activity.

An OTA Provider SHALL report the availability of Software Images, if one is found to be applicable using the other provided fields, even if the MetadataForProvider field is deemed to contain invalid or unknown information. That is, the contents of the MetadataForProvider field SHALL NOT be used to deny a software update to an OTA Requestor, unless both OTA Requestor and OTA Provider have an externally agreed-upon policy whereby strictly correct additional MetadataForProvider is expected to fulfill the OTA Software Update process.

 

Usage of the QueryImage Command

OTA Requestors SHALL send a QueryImage command to the OTA Provider to determine the avail­ ability of a new Software Image.

See Section 11.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:

  1. The URI’s scheme field SHALL be exactly bdx in lowercase
  2. The URI’s authority field SHALL contain only the host portion and SHALL use string representa­ tion of the Operational Node ID of the Node where to proceed with the download, on the same Fabric on which the OTA Requestor received the
  3. The encoding of the Node ID in the host field SHALL use an uppercase hexadecimal format, using exactly 16 characters to encode the network byte order value of the NodeID, in a similar fashion as the Node Identifier portion of the Operational Instance Name.
    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.

  1. The user section of the authority field SHALL be absent, as there are no “users” to be
  2. The port section of the authority field SHALL be absent, as the port for transport SHALL be determined through Operational Discovery of the target
  3. The URI SHALL not contain a query

 

  1. The URI SHALL not contain a fragment
  2. 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.

  1. The path SHALL only contain valid URI characters.

These rules above for BDX URIs simplify parsing for OTA Requestors receiving Image URIs. The fol­ lowing example procedure shows how the format constraints simplify the extraction of the neces­ sary data to reach the BDX server for download.

 

  1. Verify that the URI is 24 characters or longer, which is the minimum length of a valid BDX URI with all elements present, for example bdx://00112233AABBCCDD/0.
  2. Verify the presence of prefix bdx:// indicating a BDX URI.
  3. Extract the next 16 characters and convert from uppercase hexadecimal to a 64-bit scalar value, considering network byte order. This is the destination Node
  4. Verify the presence of a path separator / and skip it.
  5. Extract the remaining characters of the string as the file designator to employ when initiating the BDX

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:

 

  1. An OTA Requestor has just successfully applied a Software Image it had obtained from a previ­ ous QueryImage response.
  2. An OTA Requestor has just successfully applied a Software Image it had obtained through means different than those of this

 

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

This field SHALL contain the endpoint number which has the OTA Provider device type and OTA Software Update Provider cluster server on the ProviderNodeID. This is provided to avoid having to do discovery of the location of that endpoint by walking over all endpoints and checking their Descriptor Cluster.

 

When Generated

An OTA Provider MAY invoke this command directly to an OTA Requestor, to announce its presence as an OTA Provider on the Fabric.

These announcements, if made, SHOULD be made at most once every 24 hours for any given target Node, to assist OTA Requestors in discovering available OTA Provider resources, unless the AnnouncementReason is UrgentUpdateAvailable, in which case this command MAY be more fre­ 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):

 

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 6 5 4 3 2 1 0
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 6 5 4 3 2 1 0
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.

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.

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.
  • DeviceSoftwareVersionModel Schema
    • Provide software version specific
    • g Release Notes URL, FirmwareInformation, OTA Software Image URL (OtaURL), etc.
  • Compliance / Compliance test result Schema
    • Provide compliance and test result data about a software

 

HardwareVersion and HardwareVersionString are NOT part of the schemas. If there is different software for a VendorID/ProductID/HardwareVersion, then it SHALL be a new VendorID/ProductID.

 

11.22.3.  Vendor Schema

Vendor Schema provides contact information associated with the vendor for a given VendorID. Information in the Vendor schema is populated by the respective vendors as part of onboarding a vendor account on the DCL.

 

Name Type Constraint Conformance Mutable
VendorID vendor-id all M No
VendorName string max 128 M Yes
CompanyLegal­ Name string max 256 M Yes
CompanyPre­ ferredName string max 256 O Yes
VendorLanding­ PageUrl string max 256 O Yes

 

11.22.3.1.  VendorID

This field SHALL uniquely identify this Vendor Schema entry and it SHALL match the Vendor’s assigned Vendor ID.

 

11.22.3.2.  VendorName

This field SHALL provide a human readable (displayable) name for the product manufacturer asso­ ciated with this record.

 

11.22.3.3.  CompanyLegalName

The CompanyLegalName field SHALL specify the legal name for the product manufacturer.

 

11.22.3.4.  CompanyPreferredName

The CompanyPreferredName field, if provided, SHALL specify the Preferred Name that MAY be used for display purposes instead of the CompanyLegalName.

 

11.22.3.5.  VendorLandingPageUrl

The VendorLandingPageUrl field (when provided) SHALL contain a link to a maintained web page containing more information about the device manufacturer, such as contact information, address, etc. The syntax of the VendorLandingPageUrl attribute SHALL follow the syntax as specified in

RFC 3986. All HTTP based URLs SHALL use the https scheme.

 

11.22.4.  PAA Schema

The PAA Schema allows approved Product Attestation Authorities Certificates to be uploaded and made available via DCL queries. Information in the PAA schema is populated by the respective ven­ dors who have approved PAAs.

 

Name Type Constraint Conformance Mutable
PAACert string all M No
PAASubject string all M No
PAASubjectKeyID string all M No

 

11.22.4.1.  PAACert

This field uniquely identifies a root-level product attestation authority (PAA) certificate and SHALL contain the body of a certificate that has received the requisite number of approvals to be included in the DCL. It SHALL be encoded in PEM format. The certificate SHALL respect the format con­ straints provided in Section 6.2.2.5, “Product Attestation Authority (PAA) Certificate”.

 

11.22.4.2.  PAASubject

This field SHALL contain the PAA certificate’s Subject field, as defined in PAA in PAA Certificate. This is encoded as defined in DCL repository [https://github.com/zigbee-alliance/distributed-compliance- ledger/].

 

11.22.4.3.  PAASubjectKeyID

This field SHALL uniquely identify the PAA certificate’s Subject Key Identifier mandatory exten­ sion. It is defined in PAA Certificate. This is encoded as defined in DCL repository [https://github.com/ zigbee-alliance/distributed-compliance-ledger/].

 

11.22.5.  DeviceModel Schema

A unique combination of the VendorID and ProductID is used to identify a DeviceModel. The record schema available to vendors to provide general information shared across all software versions of a given product is presented below.

 

Name Type Constraint Conformance Mutable
VendorID vendor-id all M No
ProductID uint16 all M No
DeviceTypeID devtype-id all M No
ProductName string max 128 M Yes
ProductLabel string max 256 M Yes
PartNumber string max 32 M Yes
Commissioning­ CustomFlow uint8 0 to 2 M No
Commissioning­ CustomFlowUrl string max 256 desc Yes
Commissioning­ ModeInitial­ StepsHint map32 desc M No
Commissioning­ ModeInitial­ StepsInstruction string max 1024 desc Yes
Commissioning­ ModeSecondaryS­ tepsHint map32 desc M No
Commissioning­ ModeSecondaryS­ tepsInstruction string max 1024 desc Yes
UserManualUrl string max 256 O Yes
SupportUrl string max 256 O Yes
ProductURL string max 256 O Yes
LsfUrl string max 256 O Yes
LsfRevision uint16 all desc Yes

 

11.22.5.1.  VendorID

This field SHALL identify the vendor of the product by its Vendor ID and SHALL match the Ven­ dorID field in the Basic Information Cluster of a device running the software referenced by this DeviceModel/DeviceSoftwareVersionModel record.

 

11.22.5.2.  ProductID

This field SHALL identify the Product ID of the product instance to which a certification declara­ tion, and thus a DCL entry, applies. This field SHALL match the ProductID field in the Basic Informa­ tion Cluster of a device running the software referenced by this DeviceModel/DeviceSoftwareVer­ sionModel record.

 

11.22.5.3.  DeviceTypeID

DeviceTypeID is the device type identifier (see Data Model Device Types) for the device. For exam­ ple, DeviceTypeID is 10 (0x000a), which is the device type identifier for a Door Lock.

 

In case the device combines multiple device types, device type identifier of the primary function of the device SHOULD be chosen. See _T subtype in Section 4.3.1.3, “Commissioning Subtypes”.

 

11.22.5.4.  ProductName

This field SHOULD match the ProductName field in the Basic Information Cluster of a device running the software referenced by this DeviceModel record.

 

11.22.5.5.  ProductLabel

This field SHOULD match the ProductLabel field in the Basic Information Cluster of a device running the software referenced by this DeviceModel record.

 

11.22.5.6.  PartNumber

This field SHALL match the PartNumber field in the Basic Information Cluster of a device running the software referenced by this DeviceModel record.

Multiple products (and hence PartNumbers) can share a ProductID. For instance, there may be dif­ ferent packaging (with different PartNumbers) for different regions; also different colors of a prod­ uct might share the ProductID but may have a different PartNumber. In such cases, the choice of a single PartNumber out of the available set of PartNumbers using this ProductID SHALL be used to populate this field.

 

11.22.5.7.  Commissioning

 

CommissioningCustomFlow

 

CommissioningCustomFlow SHALL identify the device’s commissioning flow with encoding as described in Custom Flow.

 

CommissioningCustomFlowUrl

 

This field SHALL identify a vendor-specific commissioning URL for the device model when the CommissioningCustomFlow field is set to ‘2’, and MAY be set for other values of CommissioningCus­ tomFlow. See Custom Commissioning Flow section for how this URL is used. During the lifetime of the product, the specified URL SHOULD resolve to a maintained web page. The syntax of this field SHALL follow the syntax as specified in RFC 3986. The maximum length of this field is 256 ASCII

characters. All HTTP based URLs SHALL use the https scheme.

 

CommissioningModeInitialStepsHint

 

This field SHALL identify a hint for the steps that MAY be used to put a device that has not yet been commissioned into commissioning mode. This field is a bitmap with values defined in the Pairing Hint Table. For example, a value of 1 (bit 0 is set) indicates that a device that has not yet been com­ missioned will enter Commissioning Mode upon a power cycle.

Devices that implement Extended Discovery SHALL reflect this value in the Pairing Hint field of Commissionable Node Discovery when they have not yet been commissioned.

 

CommissioningModeInitialStepsInstruction

 

This field SHALL be populated with the appropriate Pairing Instruction for those values of Commis­ sioningModeInitialStepsHint, for which the Pairing Hint Table indicates a Pairing Instruction (PI) dependency.

Devices that implement Extended Discovery SHALL reflect this value in the Pairing Instruction field of Commissionable Node Discovery when they have not yet been commissioned.

 

CommissioningModeSecondaryStepsHint

 

This field SHALL identify a hint for the steps that MAY be used to put a device that has already been commissioned into commissioning mode. This field is a bitmap with values defined in the Pairing Hint Table. At least bit 2 SHALL be set, to indicate that a current Administrator can be used to put a device that has already been commissioned into commissioning mode (see Section 5.6.3, “Enhanced Commissioning Method (ECM)”). Devices which implement additional mechanisms to put a device that has already been commissioned into commissioning mode SHALL reflect these mechanism by setting the corresponding bits in this field.

Devices that implement Extended Discovery SHALL reflect this value in the Pairing Hint field of Commissionable Node Discovery when they have already been commissioned.

 

CommissioningModeSecondaryStepsInstruction

 

This field SHALL be populated with the appropriate Pairing Instruction for those values of Commis­ sioningModeSecondaryStepsHint, for which the Pairing Hint Table indicates a Pairing Instruction (PI) dependency.

Devices that implement Extended Discovery SHALL reflect this value in the Pairing Instruction field of Commissionable Node Discovery when they have already been commissioned.

 

11.22.5.8.  UserManualUrl

This field (when provided) SHALL identify a product-specific web page containing a user manual for the device model. During the lifetime of the product, the specified URL SHOULD resolve to a maintained web page. The syntax of this field SHALL follow the syntax as specified in RFC 3986. The

maximum length of this field is 256 ASCII characters. All HTTP based URLs SHALL use the https

scheme.

 

11.22.5.9.  SupportUrl

This field (when provided) SHALL identify a product specific support web page. During the lifetime of the product, the specified URL SHOULD resolve to a maintained web page. The syntax of this field SHALL follow the syntax as specified in RFC 3986. The maximum length of this field is 256

 

ASCII characters. All HTTP based URLs SHALL use the https scheme.

 

11.22.5.10.  ProductURL

This field (when provided) SHALL identify a link to a product specific web page. This field SHALL match the ProductURL field in the Basic Information Cluster of a device running the software refer­

enced by this DeviceModel record. All HTTP based URLs SHALL use the https scheme.

 

11.22.5.11.  LsfUrl

This field (when provided) SHALL identify a link to the Localized String File of this product. During the lifetime of the product, the specified URL SHOULD resolve to a maintained Localized String File. The syntax of this field SHALL follow the syntax as specified in RFC 3986. The maximum length of

this field is 256 ASCII characters. All HTTP based URLs SHALL use the https scheme. This field

SHALL NOT have a localized string identifier.

 

11.22.5.12.  LsfRevision

LsfRevision is a monotonically increasing positive integer indicating the latest available version of Localized String File. Any client can use this field to check whether it has the latest version of the Localized String File cached. When the first version of the Localized String File is published, the value of this field SHOULD be 1. When a new revision of the Localized String File is published, this value SHALL monotonically increase by 1. When a client of this information finds this to be greater than its currently stored LSF revision number, it SHOULD download the latest version of the LSF from the LsfUrl, and update its local value of this field.

This field SHALL be provided if and only if when LsfUrl is provided.

 

11.22.6.  DeviceSoftwareVersionModel Schema

A unique combination of the VendorID, ProductID and SoftwareVersion is used to identify a Device­ SoftwareVersionModel. The record schema available to vendors to provide information specific to a particular software version for a given product is presented below.

 

Name – (Matching Basic Informa­ tion Cluster Field) Type Constraint Conformance Mutable
VendorID vendor-id all M No
ProductID uint16 all M No
SoftwareVersion uint32 all M No
SoftwareVersion­ String string 1 to 64 M No
CDVersionNumber uint16 all M No
FirmwareInfor­ mation string max 512 O No

 

 

Name – (Matching Basic Informa­ tion Cluster Field) Type Constraint Conformance Mutable
SoftwareVersion­ Valid boolean all M Yes
OtaUrl string max 256 desc Yes
OtaFileSize uint64 all OtaUrl No
OtaChecksum string max 64 OtaUrl No
OtaChecksumType uint16 desc OtaUrl No
MinApplicable­ SoftwareVersion uint32 all M Yes
MaxApplicable­ SoftwareVersion uint32 all M Yes
ReleaseNotesUrl string max 256 O Yes

 

11.22.6.1.  VendorID

See Section 11.22.5.1, “VendorID”.

 

11.22.6.2.  ProductID

See Section 11.22.5.2, “ProductID”.

 

11.22.6.3.  SoftwareVersion

SoftwareVersion SHALL identify the software version number for the device model consistent with the value found in Section 11.20.2.4.3, “SoftwareVersion field”. The SoftwareVersionNumber value SHOULD NOT be displayed to an end-user. SoftwareVersion is not editable, but it would be possible to create a new device model for the same VendorID/ProductID for different versions. Both Soft­

wareVersion and SoftwareVersionString SHALL be included. This field SHALL match the Software­ Version field in the Basic Information Cluster of a device running the software certified by this

DeviceModel record.

 

11.22.6.4.  SoftwareVersionString

This field SHALL match the Software Version String field in the Basic Information Cluster of a device running the software referenced by this DeviceModel record, including format constraints on that field.

 

11.22.6.5.  CDVersionNumber

 

CDVersionNumber SHALL identify the CD Version Number of the Certification that applies to this Software Image. The CDVersionNumber maps to version_number defined in Certification Elements TLV structure.

 

11.22.6.6.  FirmwareInformation

The FirmwareInformation field, if present, SHALL match the firmware_information field in attesta­ tion-elements field included in the Device Attestation response when this Software Image boots on the device. It is an OPTIONAL field that MAY be present only for devices that meet the requirements

listed in Section 6.3.2, “Firmware Information”.

 

11.22.6.7.  SoftwareVersionValid

This field SHALL indicate whether this SoftwareVersion is valid. When creating an entry for a new SoftwareVersion, this typically is set to True. When the manufacturer later finds out there is some reason that this version should no longer be used (e.g. due to some bugs), the field SHALL be updated to False. Note: this mechanism is for “withdrawal” of a SoftwareVersion by the manufac­ turer, not to be confused with certification revocation by CSA (see SoftwareVersionCertificationSta­ tus).

 

11.22.6.8.  OTA

 

OtaUrl

 

OtaUrl SHALL identify the URL where to obtain the OTA image. The OtaUrl field SHALL be popu­ lated unless the device manufacturer provides alternative means to update the product’s firmware. The syntax of this field SHALL follow the syntax as specified in RFC 3986. The specified URL

SHOULD be available for the relevant lifetime of the corresponding software. The maximum length of this field is 256 ASCII characters. All HTTP based URLs SHALL use the https scheme.

 

OtaFileSize

 

OtaFileSize is the total size of the OTA software image in bytes. This field SHALL be provided if the OtaUrl field is populated.

 

OtaChecksum

 

OtaChecksum SHALL contain the digest of the entire contents of the associated OTA Software Update Image under the OtaUrl field, encoded in base64 string representation. The digest SHALL have been computed using the algorithm specified in OtaChecksumType. This field SHALL be provided

if the OtaUrl field is populated.

 

OtaChecksumType

 

OtaChecksumType SHALL identify the type of OtaChecksum. This field SHALL be provided if the OtaUrl field is populated.

The value of this field SHALL be a supported numerical identifier value from the IANA Named Information Hash Algorithm Registry [https://www.iana.org/assignments/named-information/named-informa­

tion.xhtml#hash-alg] established as part of RFC 6920. For example, a value of 1 would match the sha- 256 identifier, which maps to the SHA-256 digest algorithm per Section 6.2 of FIPS 180-4.

The digest algorithm chosen SHALL have a minimum digest length of 256 bits, such as sha-256 (ID 1 in the registry).

 

To increase interoperability, OtaChecksumType SHALL be within the list of [1, 7, 8, 10, 11, 12].

 

11.22.6.9.  MinApplicableSoftwareVersion

MinApplicableSoftwareVersion SHALL be equal to the lowest SoftwareVersion for which this image can be applied. Also see Section 11.20.2.4.6, “MinApplicableSoftwareVersion field”.

 

11.22.6.10.  MaxApplicableSoftwareVersion

MaxApplicableSoftwareVersion SHALL be equal to the highest SoftwareVersion for which this image can be applied. Also see Section 11.20.2.4.7, “MaxApplicableSoftwareVersion field”.

 

11.22.6.11.  ReleaseNotesUrl

ReleaseNotesUrl SHALL identify a product specific web page that contains release notes for the device model software. The syntax of this field SHALL follow the syntax as specified in RFC 3986. The specified URL SHOULD resolve to a maintained web page available for the lifetime of the corre­ sponding software being relevant. The maximum length of this field is 256 ASCII characters. All

HTTP based URLs SHALL use the https scheme.

 

11.22.7.  DeviceSoftwareCompliance / Compliance test result Schema

A unique combination of the VendorID, ProductID and SoftwareVersion is used to identify a Device­ SoftwareCompliance record. This record schema is available to the CSA to provide information spe­ cific to certification of a particular software version for a given product is presented below. Note that this schema is writable and mutable by CSA, not by the manufacturer.

 

Name – (Matching Basic Informa­ tion Cluster Field) Type Constraint Conformance Mutable
VendorID vendor-id all M No
ProductID uint16 all M No
SoftwareVersion uint32 all M No
SoftwareVersion­ String string 1 to 64 M No
CDVersionNumber uint16 all M Yes
SoftwareVersion­ CertificationStatus SoftwareVersion­ CertificationSta­ tusEnum all M Yes
CDCertificateID string 19 M Yes

For the description of the first five fields, see the corresponding fields in DeviceSoftwareVersion­ Model Schema.

 

11.22.7.1.  SoftwareVersionCertificationStatus

This field SHALL have a value from SoftwareVersionCertificationStatusEnum reflecting the current certification status of this SoftwareVersion.

 

11.22.7.2.  SoftwareVersionCertificationStatusEnum

This data type is derived from enum8 and has its values listed below.

 

Value Name Description Conformance
0 dev-test used for development and test purposes (Note: these will typi­ cally not be placed in DCL) M
1 provisional used for a SoftwareVer­ sion when going into certification testing (Note: these might or might not be placed in DCL, depending on CSA policy and procedures) M
2 certified used for a SoftwareVer­ sion which has been certified M
3 revoked used for a SoftwareVer­ sion which has been revoked M

The values 0 through 2 SHALL correspond to the values 0 through 2 used in certification_type in the Certification Declaration.

 

11.22.7.3.  CDCertificateID

 

This field SHALL have the CSA certification’s certificate ID for the Certification that applies to this record. The value of this field is used in the Certification Declaration’s certificate_id field (see Cer­ tification Elements TLV structure) for products using the VendorID, ProductID and SoftwareVersion

in this schema entry.

 

11.22.8.  APIs / CLI

The Ledger comes with a set of secure APIs and CLI. More details available here [https://github.com/zig­

bee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md].

 

 

Adsense

 

 WiFi IoT Module

 

www.mxchip.com

 

 

 Bluetooth Module

www.feasycom.com

 

 

 5G/LTE/CAT-M1/NB-IoT

 

www.simcom.com

 

Viewed Page List