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

Chapter 9. System Model Specification

 

 

9.1.  Practical Information

 

9.1.1.  Revision History 

Revision Description
1 Initial Release of this specification

 

 

9.1.2.  Scope and Purpose

This is part of a package of Data Model specifications that are agnostic to underlying layers (encod­ ing, message, network, transport, etc.). Each specification below may be independently maintained. This package, as a whole, shall be independently maintained as agnostic and decoupled from lower layers. This package may be referenced by inclusion in a set of protocol stack specifications for a complete vertical standard.

Data Model                      Defines first order elements and namespace for endpoints, clusters, attributes, data types, etc.

Interaction Model        Defines interactions, transactions and actions between nodes.

 

System Model                 Defines relationships that are managed between endpoints and clusters.

 

Cluster Library             Reference library of cluster specifications.

 

Device Library               Reference library of devices type definitions.

 

9.1.3.  Origin Story

The origin of this section is the Dotdot Architecture Model and parts of Chapter 2 of the Zigbee Clus­ ter Library specification that define the data model.

The purpose is that this document will align with current cluster specifications in the ZCL and still support cluster updates and evolution into a single set of data models.

 

9.1.4.  Overview

This specification defines persistent relationships between local and remote instances of data model elements, that support a system of operational communication between such instances. A system is a set of nodes and persistent relationships that automate data flow and control based on local or external stimulus.

 

 

 

9.2.   Endpoint Composition

 

  • Endpoint composition SHALL be indicated by these Descriptor cluster attributes:
    • DeviceTypeList SHALL list the device type(s) that the endpoint supports

 

  • PartsList SHALL indicate the endpoints that support these device type(s)
    • Each simple endpoint SHALL support only one Application device type with these exceptions:
  • The endpoint MAY support additional device types which are subsets of the Application device type (the superset).
  • The endpoint MAY support additional device types (application, utility or node device types) as defined by each additional device

 

For Example: A Color Temperature Light device type may support device type IDs for both a Dimmable Light and On/Off Light, because those are subsets of a Color Temperature Light (the superset).

For Example: A Room Temperature Sensor device type and a Room Humidity Sensor device type must be on separate endpoints because they are both Simple device types and neither is a subset of the other.

For example: The Bridged Node device type may be added to an endpoint, which means it represents a node behind a bridge, and requires one or more extra clusters.

A leaf device type is not composed of other device types.

 

For example: The Temperature Sensor device type mandates the Temperature Measurement server cluster, and does not require additional device types or endpoints.

Most device types define leaf endpoints without the need for composition.

 

For example: A Dimmer Switch device type mandates these clusters: On/Off, Level Control, Identify, and does not require additional device types or endpoints.

A composed device type is composed of one or more other device types.

 

For example: An endpoint supporting a Freezer device type which has 2 temperature sensors (freezer temperature, and ice tray temperature) would have a PartsList containing 2 tempera­ ture sensor leaf endpoints (one for each of the sensors). Those leaf endpoints would indicate and conform to the temperature sensor device type.
  • Endpoint composition SHALL be defined in the device type

 

There are two patterns for endpoint composition supported by a device type:

  • Tree pattern of endpoints directly below the composed
  • Flat list of all descendent endpoints below the the composed

 

The tree pattern supports a general tree of endpoints, each of which supports the pattern defined by the endpoint’s device type. The tree pattern is commonly used for composed application device

 

types. The tree pattern is commonly used for device types that support physical device composition (e.g. a Refrigerator).

  • The tree pattern of composition SHALL be defined by a table of conformant device types, in the device type specification, of which the device type is
  • Each device type in the table SHALL be represented by an endpoint in the PartsList attribute of the Descriptor cluster on the endpoint of the parent device

Utility device types, like Root Node and Aggregator device types, use a flat list of all descendent end­ points, with no imposed hierarchy, to indicate a flat collection of endpoints.

  • The flat pattern of endpoint composition SHALL be defined in the device type
  • An endpoint SHALL support the flat pattern, if the endpoint’s device type requires the flat pat­ tern.
  • For the endpoint that supports a flat pattern, the flat list of endpoints SHALL be represented in the PartsList attribute of the Descriptor cluster on the
  • An endpoint SHALL NOT include itself in its PartsList attribute and cycles SHALL NOT occur where an endpoint is an ancestor of
  • A root node device type SHALL be a singleton on the root node
  • The PartsList of the Descriptor cluster on the root node endpoint SHALL list all endpoints on the node, except the root node
  • The root node endpoint SHALL NOT exist in any other endpoint’s PartsList on the
  • The root node endpoint requirements are defined by a node scoped device
  • There SHALL be only one root node endpoint for the
  • Each device type that is part of a composed device type indicated in the Descriptor cluster DeviceTypeList attribute, SHALL each be supported by an endpoint in the

 

For example: A Refrigerator/Freezer endpoint has a PartsList with the Refrigerator and Freezer endpoint, but not the parts of the Refrigerator or Freezer. The Refrigerator and Freezer endpoints each have a PartsList that includes temperature sensor and control end­ points.
  • Extra endpoints MAY be in the PartsList that extend the device type

 

9.2.1.  Dynamic Endpoint allocation

Some nodes MAY require a dynamic number of endpoints, since the functionality they expose can change at run-time, e.g.

  • a Bridge on which Bridged Devices are added or
  • a Casting Video Player in which Content Apps are added or deleted (see Device Library, section 10).

 

Such dynamic entities which need to be exposed with an endpoint, will be referred to as an “exposed entity” in the following description.

For such nodes with dynamic endpoints, the endpoint addresses SHALL be allocated according to the following rules:

  • When such exposed entity is exposed for the first time, it SHALL be allocated a new endpoint address (or set of endpoint addresses), incrementing from the highest previously (ever) used endpoint
    • For the situation where a node following these mechanisms has exhausted all available 65535 endpoint addresses for exposed entities, it MAY wrap around to the lowest unused endpoint
  • For existing exposed entities, the endpoint addresses SHALL NOT be
    • This persistency requirement also holds for the case of restart/reboot of the

 

As a result of these mechanisms, endpoint addresses that were used for exposed entities that were once exposed but now have been removed will not be reused in the future (apart from the excep­ tional wrap-around corner case mentioned above), in order to avoid the possibility of confusing other nodes by re-assigning (reusing) an endpoint address for a different exposed entity. Other nodes using the exposed entities from this node SHOULD remove information related to exposed entities no longer being exposed.

Other nodes that wish to be notified of changes of the exposed entities SHOULD monitor changes of the PartsList attribute in the Descriptor cluster on the root node endpoint.

 

 

 

9.3.   Interaction Model Relationships

 

This section define some of the system behaviors and their constraints as they apply to interactions specified in the Interaction Model.

 

9.3.1.  Subscription

 

9.3.1.1.  Persistency

A subscription is an ephemeral ‘session’ between a subscriber and a publisher. A subscription can lose synchronization for a variety of reasons, including (but not limited to):

  • Inability to send reports due to network connectivity issues
  • Factory-reset of the publisher
  • Reboot of either the subscriber or publisher
  • Decision by either publisher or subscriber to tear down the subscription to reclaim resources

 

In all cases, the subscriber can eventually discover the loss of synchronization by not receiving a sync report or data report in the agreed upon sync interval, or through some other failure to com­ municate with the publisher.

  • When a subscriber discovers the loss of synchronization, it MAY then initiate a re-subscription

 

to resume the subscription.

  • An implementation MAY choose to persist the details of a subscription across reboots, but it is not

In all cases, the publisher eventually discovers the loss of synchronization by not receiving a Status Response to a Report Data message that expects a response, or by receiving an error Status Response.

 

 

 

9.4.   Binding Relationship

 

This relationship occurs because a simple client endpoint does not know which endpoints will be the target for the client generated actions, on one or more remote nodes.

 

For example: A light switch that controls one or more light bulbs, does not know the remote node endpoints of the bulbs.

For example: A thermostat that subscribes to an occupancy sensor, does not know the remote node endpoint of the sensor.

In such cases, a binding is used to direct the local endpoint to the remote endpoint. The existence of the Binding cluster on an endpoint, allows a director to create one or more binding entries (bind­ ings) in the Binding cluster. A director is a remote client that is given access to create such bindings.

Each binding indicates either a remote node’s endpoint or cluster on a remote node’s endpoint. Multiple bindings are allowed, depending on the interaction. A binding is either a unicast binding, where the binding target is a remote endpoint, or a groupcast binding, where the binding target is a group of remote endpoints.

Please see the Binding Cluster specification for more specification detail.

 

 

 

9.5.   Descriptor Cluster

 

NOTE         The Descriptor cluster is meant to replace the support from the Zigbee Device Object (ZDO) for describing a node, its endpoints and clusters.

 

This cluster describes an endpoint instance on the node, independently from other endpoints, but also allows composition of endpoints to conform to complex device type patterns.

This cluster supports a list of one or more device type identifiers that represent conformance to device type specifications.

 

For Example: An Extended Color Light device type may support device type IDs for both a Dimmable Light and On/Off Light, because those are subsets of an Extended Color Light (the superset).

 

The cluster supports a PartsList attribute that is a list of zero or more endpoints to support a com­ posed device type.

 

For Example: A Refrigerator/Freezer appliance device type may be defined as being com­ posed of multiple Temperature Sensor endpoints, a Metering endpoint, and two Thermostat endpoints.

 

9.5.1.  Revision History

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

 

Revision Description
1 Initial Release

 

9.5.2.  Classification

 

Hierarchy Role Scope PICS Code
Base Utility Endpoint DESC

 

  • Cluster ID

 

ID Name
0x001D Descriptor

 

  • Data Types

 

9.5.4.1.  DeviceTypeStruct

The device type and revision define endpoint conformance to a release of a device type definition. See the Data Model specification for more information.

 

ID Name Type Constraint Quality Default Access Confor­ mance
0 Device­ Type devtype-id         M
1 Revision uint16 min 1       M

 

DeviceType Field

 

This SHALL indicate the device type definition. The endpoint SHALL conform to the device type def­ inition and cluster specifications required by the device type.

 

Revision Field

 

This is the implemented revision of the device type definition. The endpoint SHALL conform to this revision of the device type.

 

9.5.5.  Attributes

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0000 Device­ TypeList list[Device­ Type­ Struct] min 1 F desc R V M
0x0001 ServerList list[cluster- id]   F empty R V M
0x0002 ClientList list[cluster- id]   F empty R V M
0x0003 PartsList list[end­ point-no]     empty R V M

 

9.5.5.1.  DeviceTypeList Attribute

This is a list of device types and corresponding revisions declaring endpoint conformance (see DeviceTypeStruct). At least one device type entry SHALL be present.

An endpoint SHALL conform to all device types listed in the DeviceTypeList. A cluster instance that is in common for more than one device type in the DeviceTypeList SHALL be supported as a shared cluster instance on the endpoint.

 

9.5.5.2.  ServerList Attribute

This attribute SHALL list each cluster ID for the server clusters present on the endpoint instance.

 

9.5.5.3.  ClientList Attribute

This attribute SHALL list each cluster ID for the client clusters present on the endpoint instance.

 

9.5.5.4.  PartsList Attribute

This attribute indicates composition of the device type instance. Device type instance composition SHALL include the endpoints in this list. See Endpoint Composition for more information which endpoints to include in this list.

 

 

 

9.6.   Binding Cluster

 

 

 

NOTE

This scope of this document is the Binding cluster as part of the Cluster Library. The Binding cluster is meant to replace the support from the Zigbee Device Object (ZDO) for supporting the binding table.

 

A binding represents a persistent relationship between an endpoint and one or more other local or remote endpoints. A binding does not require that the relationship exists. It is up to the node appli­ cation to set up the relationship.

A binding is used to inform a client endpoint of one or more targets for a potential interaction. For example: a light switch that controls one or more light bulbs, needs to be told the nodes and end­ points of the bulbs, or told a group in which the bulbs are members. For example: A client that needs to subscribe to an occupancy sensor, needs to know the node and endpoint of the sensor.

In such cases, a binding is used to direct a local endpoint to a target. The existence of the Binding cluster on the client endpoint, allows the creation of one or more binding entries (bindings) in the Binding cluster.

Each binding indicates another endpoint or cluster on another endpoint. Multiple bindings are allowed, depending on the interaction.

A binding is either a unicast binding, where the target is a single endpoint on a single node, or a groupcast binding, where the target is a group, which may indicate multiple endpoints on multiple nodes. The binding may also target a single cluster on the target endpoint(s).

When a client cluster requires a target for an interaction, the Binding cluster SHALL exist on the same endpoint.

Once a binding entry is created on the Binding cluster, the client endpoint MAY initiate interactions to the binding target.

 

  • Binding Mutation

If, during the creation of multiple bindings, there are no available resources to create an entry, or to establish a binding relationship, the client SHALL respond with a status of RESOURCE_EX­ HAUSTED, and the binding SHALL NOT be created.

The number of bindings supported is left to the implementation. However, a device type definition MAY prescribe the minimum number of bindings supported on an endpoint. In this case, the num­ ber prescribed by the device type SHALL be supported for each fabric the node supports, unless the device type specifies otherwise. The total number of bindings supported SHALL be the sum of the requirements for each endpoint, unless the device types involved specify otherwise.

  • For example, if a node supports 6 fabrics and a device type specifies at least 3 bindings must be supported, the node would need to support at least 18 bindings and ensure that at least 3 were available to every

A binding SHALL only be created with the Cluster field if the indicated client cluster exists on the endpoint.

When a binding is removed, the client endpoint SHALL end the binding relationship with the removed binding target.

 

9.6.2.  Revision History

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

 

Revision Description
1 Initial Release

 

9.6.3.  Classification

 

Hierarchy Role Scope PICS Code
Base Utility Endpoint BIND

 

  • Cluster ID

 

ID Name
0x001E Binding

 

  • Data Types

 

9.6.5.1. TargetStruct

 

Access Quality: Fabric Scoped
ID Name Type Constraint Quality Default Access Confor­ mance
1 Node node-id all       Endpoint
2 Group group-id all       !Endpoint
3 Endpoint endpoint- no all       !Group
4 Cluster cluster-id all       O

 

Node Field

 

This field is the remote target node ID. If the Endpoint field is present, this field SHALL be present.

 

Group Field

 

This field is the target group ID that represents remote endpoints. If the Endpoint field is present, this field SHALL NOT be present.

 

Endpoint Field

 

This field is the remote endpoint that the local endpoint is bound to. If the Group field is present, this field SHALL NOT be present.

 

Cluster Field

 

This field is the cluster ID (client & server) on the local and target endpoint(s). If this field is present, the client cluster SHALL also exist on this endpoint (with this Binding cluster). If this field is present, the target SHALL be this cluster on the target endpoint(s).

 

9.6.6.  Attributes

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0000 Binding list[Target­ Struct] desc N [] RW F VM M

 

9.6.6.1. Binding Attribute

Each entry SHALL represent a binding. Here are some examples:

Endpoint Device Type Node Group Cluster Endpoint Example Description
Light Switch Client omit 1234 omit omit switch end­ point sends On/Off, Level & Color Control cluster com­ mands to group 1234
Temp Sensor Client 456789 omit 1026 3

temperature sensor client subscribes to node 456789

endpoint 3 temperature measurement cluster

 

 

 

9.7.   Label Cluster

 

This cluster provides a feature to tag an endpoint with zero or more labels. This is a base cluster that requires a derived cluster to create an instance.

 

9.7.1.  Revision History

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

 

 

Revision Description
1 Initial Release

 

9.7.2.  Classification

 

Hierarchy Role Scope PICS Code
Base Utility Endpoint LABEL

 

9.7.3.  Cluster ID

This is a base cluster with no cluster ID. Please see derived clusters for more information.

 

ID Name
n/a Label

 

9.7.4.  Data Types

 

9.7.4.1. LabelStruct

This is a string tuple with strings that are user defined.

 

ID Name Type Constraint Quality Default Access Confor­ mance
0 Label string max 16   empty   M
1 Value string max 16   empty   M

 

Label Field

 

The Label or Value semantic is not defined here. Label examples: “room”, “zone”, “group”, “direc­ tion”.

 

Value Field

 

The Label or Value semantic is not defined here. The Value is a discriminator for a Label that may have multiple instances. Label:Value examples: “room”:”bedroom 2″, “orientation”:”North”, “floor”:”2″, “direction”:”up”

 

9.7.5.  Attributes

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0000 LabelList list[Label­ Struct] derived derived empty derived M

 

9.7.5.1.  LabelList Attribute

This is a list of string tuples. Each entry is a LabelStruct.

 

 

 

9.8.   Fixed Label Cluster

 

This cluster provides a feature for the device to tag an endpoint with zero or more read only labels. Examples:

  • A bridge can use this to indicate grouping of bridged devices. For example: All bridged devices whose endpoints have an entry in their LabelList “room”:”bedroom 2″ are in the same (bed)room.
  • A manufacturer can use this to identify a characteristic of an endpoint. For example to identify the endpoints of a luminaire, one pointing up, the other pointing down, one of the endpoints would have a LabelList entry “orientation”:”up” while the other would have “orienta­ tion”:”down”. Using such indication, the user interface of a Node controlling this luminaire knows which of the endpoints is which of the

 

9.8.1.  Revision History

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

 

Revision Description
1 Initial Release

 

9.8.2.  Classification

 

Hierarchy Role Scope PICS Code
Derived from Label Utility Endpoint FLABEL

 

9.8.3.  Cluster ID

 

ID Name
0x0040 Fixed Label

 

9.8.4.  Attributes

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0000 LabelList list[Label­ Struct]   N empty R V M

 

 

 

9.9.   User Label Cluster

 

This cluster provides a feature to tag an endpoint with zero or more labels.

 

9.9.1.  Revision History

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

 

Revision Description
1 Initial Release

 

9.9.2.  Classification

 

Hierarchy Role Scope PICS Code
Derived from Label Utility Endpoint ULABEL

 

9.9.3.  Cluster ID

 

ID Name
0x0041 User Label

 

9.9.4.  Attributes

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0000 LabelList list[Label­ Struct] min 4 per node N empty RW VM M

 

9.9.4.1. LabelList

An implementation SHALL support at least 4 list entries per node for all User Label cluster instances on the node.

 

 

 

9.10.   Access Control Cluster

 

The Access Control Cluster exposes a data model view of a Node’s Access Control List (ACL), which codifies the rules used to manage and enforce Access Control for the Node’s endpoints and their associated cluster instances. Access to this Access Control Cluster itself requires a special Adminis­ ter privilege level, such that only Nodes granted such privilege (hereafter termed “Administrators”) can manage the Access Control Cluster.

The Access Control Cluster SHALL be present on the root node endpoint of each Node, and SHALL NOT be present on any other Endpoint of any Node.

 

9.10.1.  Revision History

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

 

Revision Description
1 Initial Release

 

9.10.2.  Classification

 

Hierarchy Role Scope PICS Code
Base Utility Node ACL

 

9.10.3.  Cluster ID

 

ID Name
0x001F AccessControl

 

9.10.4.  Data Types

 

9.10.4.1.  ChangeTypeEnum

This data type is derived from enum8.

 

Value Name Summary Conformance
0 Changed Entry or extension was changed M
1 Added Entry or extension was added M
2 Removed Entry or extension was removed M

 

9.10.4.2.  AccessControlEntryPrivilegeEnum

This data type is derived from enum8.

 

Value Name Summary Conformance
1 View Can read and observe all (except Access Con­ trol Cluster and as seen by a non-Proxy) M
2 Proxy View Can read and observe all (as seen by a Proxy) P, M

 

 

Value Name Summary Conformance
3 Operate View privileges, and can perform the pri­ mary function of this Node (except Access Control Cluster) M
4 Manage Operate privileges, and can modify persistent configuration of this Node (except Access Control Cluster) M
5 Administer Manage privileges, and can observe and mod­ ify the Access Control Cluster M

 

Proxy View Value

 

This value implicitly grants View privileges

 

Operate Value

 

This value implicitly grants View privileges

 

Manage Value

 

This value implicitly grants Operate & View privileges

 

Administer Value

 

This value implicitly grants Manage, Operate, Proxy View & View privileges

 

9.10.4.3.  AccessControlEntryAuthModeEnum

This data type is derived from enum8.

 

Value Name Summary Conformance
1 PASE Passcode authenticated session M
2 CASE Certificate authenti­ cated session M
3 Group Group authenticated session M

 

9.10.4.4.  AccessControlTargetStruct

 

 

ID Name Type Constraint Quality Default Access Confor­ mance
0 Cluster cluster-id all X     M
1 Endpoint endpoint- no all X     M
2 Device­ Type devtype-id all X     M

 

  • AccessControlEntryStruct

 

Access Quality: Fabric Scoped
ID Name Type Constraint Quality Default Access Confor­ mance
1 Privilege AccessCon­ trolEn­ tryPrivi­ legeEnum all     S M
2 AuthMode AccessCon­ trolEn­ tryAuth­ Mod­ eEnum all     S M
3 Subjects list[Subjec­ tID] max Sub­ jectsPerAc­ cessCon­ trolEntry X   S M
4 Targets list[Access­ Con­ trolTarget­ Struct] max Tar­ getsPerAc­ cessCon­ trolEntry X   S M

 

Privilege Field

 

The privilege field SHALL specify the level of privilege granted by this Access Control Entry.

 

NOTE         The Proxy View privilege is provisional.

 

Each privilege builds upon its predecessor, expanding the set of actions that can be performed upon a Node. Administer is the highest privilege, and is special as it pertains to the administration of privileges itself, via the Access Control Cluster.

When a Node is granted a particular privilege, it is also implicitly granted all logically lower privi­ lege levels as well. The following diagram illustrates how the higher privilege levels subsume the lower privilege levels:

 

Figure 39. Access Control Privilege Levels

 

Individual clusters SHALL define whether attributes are readable, writable, or both readable and writable. Clusters also SHALL define which privilege is minimally required to be able to perform a particular read or write action on those attributes, or invoke particular commands. Device type specifications MAY further restrict the privilege required.

The Access Control Cluster SHALL require the Administer privilege to observe and modify the Access Control Cluster itself. The Administer privilege SHALL NOT be used on Access Control Entries which use the Group auth mode.

 

E.g. A Fan Control Cluster may require Operate privilege to write to a level attribute (low/medium/high), and to configure each level’s RPM setting via a command. The Fan Con­ trol Cluster may also expose a current RPM attribute, which requires only View privilege to read. Clients granted Operate privilege will be able to both change the level, and configure each level’s RPM. Clients granted View privilege will be able to read the current RPM, but will not be granted sufficient privilege to change the level or configure each level’s RPM.

 

E.g. A Fan Control Cluster may be included in a more industrial device type. To ensure proper operation, this device type may restrict configuration of fan level RPM settings to require Manage privilege. Clients granted Manage privilege will have sufficient privilege to configure each level’s RPM; clients granted Operate privilege will not be able to perform such configu­ ration, but will still be able to change the level. This additional restriction would apply only to the Fan Control Cluster as included in this particular device type; a client granted Operate privilege may still be able to perform configuration in Fan Control Clusters included in other device types on the same Node.

 

AuthMode Field

 

The AuthMode field SHALL specify the authentication mode required by this Access Control Entry.

 

Subjects Field

 

The subjects field SHALL specify a list of Subject IDs, to which this Access Control Entry grants access.

Device types MAY impose additional constraints on the minimum number of subjects per Access Control Entry.

An attempt to create an entry with more subjects than the node can support SHALL result in a RESOURCE_EXHAUSTED error and the entry SHALL NOT be created.

Subject ID SHALL be of type uint64 with semantics depending on the entry’s AuthMode as follows:

 

Subject Semantics

 

AuthMode Subject
PASE Lower 16-bits → Passcode ID Upper 48-bits → all bits clear
CASE 64-bits → Node ID or CASE Authenticated Tag
Group Lower 16-bits → Group ID Upper 48-bits → all bits clear

An empty subjects list indicates a wildcard; that is, this entry SHALL grant access to any Node that successfully authenticates via AuthMode. The subjects list SHALL NOT be empty if the entry’s Auth­ Mode is PASE.

The PASE AuthMode is reserved for future use (see Section 6.6.2.8, “Bootstrapping of the Access Con­ trol Cluster”). An attempt to write an entry with AuthMode set to PASE SHALL fail with a status code of CONSTRAINT_ERROR.

For PASE authentication, the Passcode ID identifies the required passcode verifier, and SHALL be 0 for the default commissioning passcode.

For CASE authentication, the Subject ID is a distinguished name within the Operational Certificate shared during CASE session establishment, the type of which is determined by its range to be one of:

  • a Node ID, which identifies the required source node directly (by ID)
  • a CASE Authenticated Tag, which identifies the required source node indirectly (by tag)

 

E.g. an ACL entry with CASE AuthMode that grants privileges to Subject IDs [ 0x0000_0000_1111_1111, 0x0000_0000_2222_2222, 0x0000_0000_3333_3333 ] (which are Node IDs) will grant access to Nodes with Node ID 0x0000_0000_1111_1111, 0x0000_0000_2222_2222, or 0x0000_0000_3333_3333, but will not grant access to Nodes with

 

 

Node ID 0x0000_0000_4444_4444 or 0x0000_0000_5555_5555.

 

E.g. an ACL entry with CASE AuthMode that grants privileges to Subject IDs [ 0x0000_0000_6666_6666, 0xFFFF_FFFD_ABCD_0002 ] (which are a Node ID and a CASE Authenticated Tag) will grant access to the Node with Node ID 0x0000_0000_6666_6666 and any Nodes with CAT identifier value 0xABCD if the CAT’s version is 0x0002 or higher. It will not grant access to Nodes with other CAT values such as 0x9999_9999. Any node with CAT identifier value of 0xABCD but version less than 0x0002 (for example: 0xFFF­ F_FFFD_ABCD_0001) will not be granted access.

 

For Group authentication, the Group ID identifies the required group, as defined in the Group Key Management Cluster.

 

E.g. an entry with Group AuthMode that grants privileges to Subject IDs [ 0x0000_0000_1111_1111, 0x0000_0000_2222_2222 ] (which are Group IDs) will grant access to Nodes in Group 0x1111_1111 or 0x2222_2222, but will not grant access to Nodes in Group 0x3333_3333, even if they share Operational Group Keys.

 

Targets Field

 

The targets field SHALL specify a list of AccessControlTargetStruct, which define the clusters on this Node to which this Access Control Entry grants access.

Device types MAY impose additional constraints on the minimum number of targets per Access Control Entry.

An attempt to create an entry with more targets than the node can support SHALL result in a RESOURCE_EXHAUSTED error and the entry SHALL NOT be created.

A single target SHALL contain at least one field (Cluster, Endpoint, or DeviceType), and SHALL NOT contain both an Endpoint field and a DeviceType field.

A target grants access based on the presence of fields as follows:

 

Target Semantics

 

Cluster Endpoint DeviceType Target
      Invalid
    D All clusters on any end­ point with Descriptor containing device type D
  E   All clusters on only endpoint E
  E D Invalid

 

 

Cluster Endpoint DeviceType Target
C     Only cluster C on all endpoints
C   D Only cluster C on any endpoint with Descrip­ tor containing device type D
C E   Only cluster C on only endpoint E
C E D Invalid

 

An empty targets list indicates a wildcard: that is, this entry SHALL grant access to all cluster instances on all endpoints on this Node.

 

E.g. an entry that grants privileges to the Color Light Bulb Device Type will grant privileges to any cluster on any endpoint that contains the Color Light Bulb device type (whether that clus­ ter is in the Color Light Bulb device type or not), and will not grant privileges to any other cluster on any other endpoint.

E.g. an entry that grants privileges to Endpoint 1 will grant privileges to any cluster on End­ point 1, and will not grant privileges to any other cluster on any other endpoint.

E.g. an entry that grants privileges to the On/Off Cluster on any endpoint will not grant privi­ leges to any other cluster on any endpoint.

E.g. an entry that grants privileges to the On/Off Cluster with Color Light Bulb Device Type will grant privileges to just the On/Off Cluster on any endpoint that contains the Color Light Bulb device type, and will not grant privileges to any other cluster on any other endpoint (including other clusters in the Color Light Bulb device type, or the On/Off cluster on end­ points that do not contain the Color Light Bulb device type).

E.g. an entry that grants privileges to the On/Off Cluster on Endpoint 1 will not grant privi­ leges to any other cluster on Endpoint 1, or to any other cluster (including the On/Off cluster) on any other endpoint.

 

9.10.4.6.  AccessControlExtensionStruct

 

Access Quality: Fabric Scoped
ID Name Type Constraint Quality Default Access Confor­ mance
1 Data octstr max 128     S M

 

Data Field

 

This field MAY be used by manufacturers to store arbitrary TLV-encoded data related to a fabric’s

 

Access Control Entries.

 

The contents SHALL consist of a top-level anonymous list; each list element SHALL include a pro­ file-specific tag encoded in fully-qualified form.

Administrators MAY iterate over this list of elements, and interpret selected elements at their dis­ cretion. The content of each element is not specified, but MAY be coordinated among manufactur­ ers at their discretion.

 

E.g. a manufacturer could use this field to store structured data, including various metadata and cryptographic signatures. The manufacturer could then verify a fabric’s Access Control List by generating a canonical bytestream from the Access Control Entries for the fabric, then verifying the signature against it. Such a canonical bytestream could be generated by encod­ ing specific entry fields and sub-fields (such as lists) in specific order and specific format (e.g. TLV).

 

9.10.5.  Attributes

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0000 ACL list[Access­ ControlEn­ tryStruct] desc   desc RW F A M
0x0001 Extension list[Access­ ControlEx­ tension­ Struct] desc   desc RW F A O
0x0002 Sub­ jectsPerAc­ cessCon­ trolEntry uint16 min 4 F 4 R V M
0x0003 TargetsPer­ AccessCon­ trolEntry uint16 min 3 F 3 R V M
0x0004 AccessCon­ trolEntries­ PerFabric uint16 min 4 F 4 R V M

 

9.10.5.1.  Default Value

The default value of the Access Control Cluster is empty; that is, devoid of contents, with each list attribute containing zero elements.

The Access Control List is able to have an initial entry added because the Access Control Privilege Granting algorithm behaves as if, over a PASE commissioning channel during the commissioning

 

phase, the following implicit Access Control Entry were present on the Commissionee (but not on the Commissioner):

 

Access Control Cluster: { ACL: [

0: {                                                 // implicit entry only; does not explicitly exist!

FabricIndex: 0,                        // not fabric-specific Privilege: Administer,

AuthMode: PASE, Subjects: [],

Targets: []                                // entire node

}

],

Extension: []

}

 

9.10.5.2.  Administration Guidelines

The Access Control Cluster is passive in nature and is only responsible for maintaining entries in the Access Control List. It is the responsibility of Administrators to create and maintain Access Con­ trol policy by managing the list and its entries. The Access Control Cluster SHALL NOT change or remove Access Control Entries of its own volition.

Administrators SHOULD strive to minimize resource usage by combining entries where appropri­ ate. For example, if an Administrator is responsible for an entry that grants privilege to subject Node A, and wishes to grant the same privilege to Node B under the same conditions, then that Administrator SHOULD update the existing entry to apply to subject Node B as well as Node A, instead of creating a new entry. If a set of Nodes is commonly used in entries, then an Administra­ tor MAY consider using CASE Authenticated Tags (CATs) for those entries, especially if membership in the set of Nodes changes over time.

Administrators SHOULD carefully consider the effect of Access Control Entries they manage, partic­ ularly when targeting entire Endpoints (either directly, or indirectly by Device Type), to ensure that granted privileges are appropriate for the set of Clusters that may entail. Administrators SHOULD be mindful that targeting by Device Type grants privileges to all Clusters on all Endpoints with Descriptor containing that Device Type (thereby including Clusters not part of that specified Device Type), now and in the future. Administrators SHOULD consider whether targeting specific End­ points, or Clusters, or both, might be a more appropriate policy for the given Subjects; studying the Descriptor Cluster for affected Endpoints may help in this determination.

Administrators SHOULD be careful to avoid inadvertently removing their own administrative access. For example, an Administrator SHOULD change its own administrative access entry by updating the existing entry or by creating a new entry before removing the old entry, and SHOULD NOT remove the old entry before creating any new entry.

 

9.10.5.3.  ACL Attribute

An attempt to add an Access Control Entry when no more entries are available SHALL result in a RESOURCE_EXHAUSTED error being reported and the ACL attribute SHALL NOT have the entry

 

added to it. See access control limits.

 

See the AccessControlEntriesPerFabric attribute for the actual value of the number of entries per fabric supported by the server.

Each Access Control Entry codifies a single grant of privilege on this Node, and is used by the Access Control Privilege Granting algorithm to determine if a subject has privilege to interact with targets on the Node.

 

9.10.5.4.  Extension Attribute

If present, the Access Control Extensions MAY be used by Administrators to store arbitrary data related to fabric’s Access Control Entries.

The Access Control Extension list SHALL support a single extension entry per supported fabric.

 

9.10.5.5.  SubjectsPerAccessControlEntry Attribute

This attribute SHALL provide the minimum number of Subjects per entry that are supported by this server.

Since reducing this value over time may invalidate ACL entries already written, this value SHALL NOT decrease across time as software updates occur that could impact this value. If this is a con­ cern for a given implementation, it is recommended to only use the minimum value required and avoid reporting a higher value than the required minimum.

 

9.10.5.6.  TargetsPerAccessControlEntry Attribute

This attribute SHALL provide the minimum number of Targets per entry that are supported by this server.

Since reducing this value over time may invalidate ACL entries already written, this value SHALL NOT decrease across time as software updates occur that could impact this value. If this is a con­ cern for a given implementation, it is recommended to only use the minimum value required and avoid reporting a higher value than the required minimum.

 

9.10.5.7.  AccessControlEntriesPerFabric Attribute

This attribute SHALL provide the minimum number of ACL Entries per fabric that are supported by this server.

Since reducing this value over time may invalidate ACL entries already written, this value SHALL NOT decrease across time as software updates occur that could impact this value. If this is a con­ cern for a given implementation, it is recommended to only use the minimum value required and avoid reporting a higher value than the required minimum.

 

9.10.6.  Error handling

Administrators SHALL use regular actions to administer the Access Control Cluster (by reading and writing entries in the list). Administrators SHOULD take care to use DataVersion conditional writes when administering the list or its contents.

 

The Access Control Cluster SHALL fail to write, and return an appropriate error, if an attempt is made to create or update an Access Control Entry or Access Control Extension such that it would have invalid contents.

For example, the following Access Control Entry conditions will result in an error of CONSTRAIN­ T_ERROR:

  • Privilege enum value invalid
  • AuthMode enum value invalid
  • AuthMode is PASE (reserved for future use)
  • Subjects element invalid
    • g. illegal CAT with CASE AuthMode
  • Targets element invalid
    • g. no field present
    • g. both Endpoint and DeviceType fields present
  • Field combinations invalid
    • g. Administer Privilege with Group AuthMode

 

For example, the following Access Control Extension conditions will result in an error of CON­ STRAINT_ERROR:

  • There is an attempt to add more than 1 entry associated with the given accessing fabric index in the extension list
  • Data value exceeds max length
  • Data value not valid TLV-encoded data

 

The Access Control Cluster MAY fail to write, and return a RESOURCE_EXHAUSTED error, if an attempt is made to create or update an entry or extension such that storage is exhausted.

 

9.10.7.  Events

 

ID Name Priority Access Conformance
0x00 AccessControlEn­ tryChanged INFO S A M
0x01 AccessControlEx­ tensionChanged INFO S A M

 

9.10.7.1.  AccessControlEntryChanged Event

The cluster SHALL send AccessControlEntryChanged events whenever its ACL attribute data is changed by an Administrator.

  • Each added entry SHALL generate an event with ChangeType
  • Each changed entry SHALL generate an event with ChangeType

 

  • Each removed entry SHALL generate an event with ChangeType

 

Access Quality: Fabric-Sensitive
ID Name Type Constraint Quality Default Confor­ mance
1 AdminN­ odeID node-id desc X   M
2 AdminPass­ codeID uint16 desc X   M
3 ChangeType ChangeType­ Enum all     M
4 LatestValue AccessCon­ trolEntryS­ truct all X   M

 

AdminNodeID Field

 

The Node ID of the Administrator that made the change, if the change occurred via a CASE session.

 

Exactly one of AdminNodeID and AdminPasscodeID SHALL be set, depending on whether the change occurred via a CASE or PASE session; the other SHALL be null.

 

AdminPasscodeID Field

 

The Passcode ID of the Administrator that made the change, if the change occurred via a PASE ses­ sion. Non-zero values are reserved for future use (see PasscodeId generation in PBKDFParamRe­ quest).

 

Exactly one of AdminNodeID and AdminPasscodeID SHALL be set, depending on whether the change occurred via a CASE or PASE session; the other SHALL be null.

 

ChangeType Field

 

The type of change as appropriate.

 

LatestValue Field

 

The latest value of the changed entry.

 

This field SHOULD be set if resources are adequate for it; otherwise it SHALL be set to NULL if resources are scarce.

 

9.10.7.2.  AccessControlExtensionChanged Event

The cluster SHALL send AccessControlExtensionChanged events whenever its extension attribute data is changed by an Administrator.

  • Each added extension SHALL generate an event with ChangeType

 

  • Each changed extension SHALL generate an event with ChangeType
  • Each removed extension SHALL generate an event with ChangeType

 

Access Quality: Fabric-Sensitive
Id Field Type Constraint Quality Default Confor­ mance
1 AdminN­ odeID node-id desc X   M
2 AdminPass­ codeID uint16 desc X   M
3 ChangeType ChangeType­ Enum all     M
4 LatestValue AccessCon­ trolExten­ sionStruct all X   M

 

AdminNodeID Field

 

The Node ID of the Administrator that made the change, if the change occurred via a CASE session.

 

Exactly one of AdminNodeID and AdminPasscodeID SHALL be set, depending on whether the change occurred via a CASE or PASE session; the other SHALL be null.

 

AdminPasscodeID Field

 

The Passcode ID of the Administrator that made the change, if the change occurred via a PASE ses­ sion. Non-zero values are reserved for future use (see PasscodeId generation in PBKDFParamRe­ quest).

 

Exactly one of AdminNodeID and AdminPasscodeID SHALL be set, depending on whether the change occurred via a CASE or PASE session; the other SHALL be null.

 

ChangeType Field

 

The type of change as appropriate.

 

LatestValue Field

 

The latest value of the changed extension.

 

This field SHOULD be set if resources are adequate for it; otherwise it SHALL be set to NULL if resources are scarce.

 

 

 

9.11.   Group Relationship

 

A group is a collection of one or more endpoints on one or more nodes. A group is identified by a unique group ID. If the network supports fabrics, each group, its group ID, and nodes that are mem­

 

bers of the group, are all scoped to a single fabric.

 

Conceptually, there is a Group Table on each node that represents endpoint group membership. Each Group Table entry maps a group ID to one or more endpoints on that node, and any endpoint on a node MAY be assigned to one or more groups.

A group relationship, that is contained in the Group Table, is managed through the endpoints using the Groups cluster.

The Interaction Model allows a group identifier to be used as the destination of a message or action. If a message received by a node has a group destination, the Group Table is checked to see which endpoints on the node are members of the group. Then, the message will be delivered to those end­ points.

Note that there is a risk that multiple clients allocate the same group identifier for their own pur­ pose. This likely leads to undesired behavior. For this reason, a client SHOULD discover the unique­ ness of their ‘candidate’ group ID.

Also note that groupcast relies on its support by the underlying network layer. Depending on this network layer, groupcast may not work to “sleepy” devices that have their radio turned off when idle to preserve battery lifetime.

 

 

 

9.12.   Bridge for non-Matter devices

 

9.12.1.  Introduction

A Bridge serves to allow the use of non-Matter IoT devices (e.g. devices on a Zigbee or Z-Wave net­ work, or any other non-Matter connectivity technology) in a Matter Fabric, with the goal to enable the consumer to keep using these non-Matter devices together with their Matter devices.

This is illustrated in the figure below: the non-Matter devices are exposed as Bridged Devices to Nodes on the Fabric. The Matter Nodes can communicate with both the (native) Matter devices as well as the Bridged Devices (by virtue of the Bridge which performs the translation between Matter and the other protocol).

 

 

 

 

 

 

 

 

  Acts as an    
   
interpreter Assumes  
   
Presents for Bridged responsibility  
a Matter Devices for securing  
interface and and certifying  
to the presents the communi-  
Matter them as cation link to  
apps Matter each Bridged  
Devices to Device  
   
the various    
   
Matter apps  

 

 

 

 

 

 

 

 

 
  Matter Device 1
  Matter Device 2
  Matter Device 3
  Matter Device 4

 

Figure 40. principle of bridging

 

 

 

NOTE

The bridging-concept described here is NOT intended to be used to expose Matter Nodes (which are not on the Fabric) to a Fabric, since direct connection of those Matter Nodes to the Fabric would provide a better experience.

 

This section will describe how the Data Model concepts can be used by a Bridge to expose the Bridged Devices in such a way that they can be discovered and used by Nodes on the Matter Fabric.

 

9.12.2.  Exposing functionality and metadata of Bridged Devices

After Commissioning, the Bridge SHALL expose (at least) one Node to the Fabric. The device imple­ menting the Bridge MAY have more than one Node. This, however, is orthogonal to the bridging concept and will not be discussed further here.

  • On this Node, the Bridge SHALL expose a set of endpoints representing the various Bridged Devices on the non-Matter side of the
  • Additionally, it SHALL expose an endpoint with the device type Aggregator which has a Descrip­ tor cluster with a PartsList attribute containing all the endpoints representing those Bridged Devices, using the flat pattern defined in Endpoint Composition. See the “Endpoint Composition” sections in the specifications of the Aggregator and Bridged Node device
  • Each Bridged Device corresponds to an endpoint listed in this PartsList (see examples below). The Descriptor cluster on the corresponding endpoint provides information about the particu­ lar Bridged Device, such as its device type(s).

 

 

 

The PartsList on endpoint 1 lists all endpoints for bridged devices; each endpoint 11..16 represents one device at the non-Matter side of the bridge.

 

 

 

 

 

Descriptor cluster:

EP 11

Descriptor cluster:

EP 14

 

DeviceTypeList: Extended Color Light, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “dining table”

DeviceTypeList: Generic Switch, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “living room entrance”

 

 

Descriptor cluster:

EP 12

Descriptor cluster:

EP 15

 

DeviceTypeList: Extended Color Light, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “kitchen”

DeviceTypeList: Temperature Sensor, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “outdoor temperature”

 

 

 

Figure 41. example of endpoints representing Bridged Devices

 

In case the Bridge is bridging to/from multiple technologies (or has some other logical distinction between groups of bridged devices), it MAY expose such groups as two or more such hierarchical trees each with their Aggregator device type (e.g. one for each technology, see figure below); it MAY also combine all bridged devices in one hierarchical tree (see figure above). Both figures have the same set of bridged devices – the difference is in how the bridge manufacturer decides to expose them as one or multiple sets.

 

 

Descriptor cluster:

DeviceTypeList: Root Node PartsList: EP 1,2, 11,12,13,14,15,16

Basic Information cluster:

..

EP 0

This implementation chooses to expose two instances of the Aggregator device type, each with their own hierarchy of devices, to be able to expose which bridged device is on which technology.

 

 

Descriptor cluster: DeviceTypeList: Aggregator PartsList: EP 11,12,13

Fixed Label cluster:

LabelList: [[” bridge”,”Zigbee”]]

 

Descriptor cluster:

EP 1

 

 

EP 11

 

DeviceTypeList: Extended Color Light, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “dining table”

 

 

Descriptor cluster:

EP 12

 

DeviceTypeList: Extended Color Light, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “kitchen”

 

 

Descriptor cluster:

DeviceTypeList: Dimmable Light, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “hallway”

EP 13

 

Zigbee devices

 

Figure 42. example of endpoints representing Bridged Devices from two technologies

 

9.12.2.1.  Topology or logical grouping

A Bridge typically has information on topology or logical grouping of the Bridged Devices, which can be of use to Nodes on the Matter Fabric.

  • For example, consider a Bridge with 50 lights. If this exposure of grouping, and their naming, would not be present, the user would just see a flat list of 50 lights on their controller and would not know which of those physical lights would be in which location/group.

If a Bridge has such information on topology or logical grouping, it SHOULD expose such informa­ tion in the EndpointLists attribute of an Actions cluster (the ActionLists of which MAY be empty if

 

no actions are exposed). A Bridge MAY make it possible (e.g., through a Bridge Manufacturer’s app) for its users to restrict whether all or some of such information is exposed to the Fabric. The Node on the Fabric using the Bridged Devices which is interested in using such topology or logical group­ ing (e.g. to show the grouping of lights per room in an overview to the user), SHOULD derive such grouping (and associated naming) from this EndpointLists attribute.

In the example below, the devices are split over two rooms, as exposed in the EndpointLists attribute. This example also illustrates a composed endpoint for a composed Bridged Device, in this case a lighting device (Bridged Device at EP 24,25,26) which has an up- and downlighter which can

be controlled separately, and which have their own set of lighting-related clusters on an individual endpoint (EP 25,26). Note that the Bridged Device Basic Information cluster is at the top of the hier­ archy for this composed device (EP 24), while the application device types and application clusters

are at the leaf endpoints (EP 25,26).

Since EP 25,26 are listed in the PartsList of EP 24, they ‘inherit’ the Bridged Node device type and information in the Bridged Device Basic Information cluster of EP 24.

 
   

Figure 43. example of endpoints representing Bridged Devices using grouping

 

 
   

 

 

Figure 44. impression of app UI indicating information for the Bridged Devices

 

9.12.2.2.  Native Matter functionality in Bridge

The Bridge MAY also contain native Matter functionality, i.e. non-bridged functionality, such as in the example below, which shows a smart speaker device having, in addition to a Wi-Fi connection, also a Zigbee connection towards a number of Zigbee lights. The speaker functionality (EP 31) is native Matter functionality (and could have a Controller role to allow sending Matter commands upon receiving voice commands), while the remainder of the non-zero endpoints represent the Bridged Devices.

 

 

 

Descriptor cluster: DeviceTypeList: Aggregator PartsList: EP 12,13,14,22,24

Actions cluster:

ActionList: [ ] EndpointLists: [

[0xE001, “living room”, room, [12,13,14] ],

[0xE002, “bedroom”, room, [22,24,31] ]

 

EP 1

In this example, the EndPointLists attribute of the Actions cluster is used to indicate grouping (e.g. all devices in one room – irrespective whether they are bridged or not).

EP31 is a component of the device itself which is not bridged,

i.e. native Matter; it is in the bedroom along with some bridged devices.

 

]

 

 

 

Descriptor cluster:

EP 12

EP 31

 

DeviceTypeList: Extended Color Light, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “dining table”

Descriptor cluster:

DeviceTypeList: Speaker

 

 

Descriptor cluster:

EP 13

Descriptor cluster:

 

EP 22

 

DeviceTypeList: Color Temperature Light, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “kitchen light”

DeviceTypeList: Color Temperature Light, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “ceiling light”

 

 

Descriptor cluster:

DeviceTypeList: Generic Switch, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “living room entrance”

living room

EP 14

Descriptor cluster:

DeviceTypeList: Generic Switch, Bridged Node

Bridge Device Basic Information cluster:

NodeLabel: “bedside switch”

bedroom

 

EP 24

 

Figure 45. example of Bridge with native Matter functionality

 

9.12.2.3.  Information about Bridged Devices

For each Bridged Device, the Bridge SHALL include a Bridged Device Basic Information cluster on the endpoint which represents this Bridged Device.

Furthermore, the Bridge SHALL include a Descriptor cluster with

  • a DeviceTypeList attribute containing device type Bridged Node plus the device type(s) of the Bridged Device, and
  • a PartsList attribute listing any other endpoints which jointly expose the functionality of this Bridged

In case a Bridged Device is represented by multiple endpoints, the Bridged Device Basic Informa­ tion and Descriptor clusters SHALL only be present on the endpoint which is the top level of the hierarchy representing this Bridged Device (example: endpoint 24 in Figure 43, “example of end­

points representing Bridged Devices using grouping”).

 

In case the Bridged Device contains a power source such as battery or mains power feed, and infor­ mation about the state of that power source is available to the Bridge, the Bridge SHALL also

include a Power Source Configuration cluster and a Power Source cluster on the endpoint represent­

ing the Bridged Device. An example of this is shown for the battery-powered temperature sensor on

endpoint 23 in Figure 43, “example of endpoints representing Bridged Devices using grouping”. Two special cases:

  • In case such Bridged Device is represented by multiple endpoints, and the Bridged Device con­

 

tains only one power source, the Power Source Configuration cluster SHALL be present on the endpoint which is the top level of the hierarchy representing this Bridged Device, while the Power Source cluster SHALL be present on the endpoint which corresponds to the part of the Bridged Device containing the power source.

  • In case a Bridged Device contains multiple power sources, each of these power sources SHALL be represented by a Power Source cluster on the endpoint which corresponds to the part of the Bridged Device containing the power source (no more than one such cluster per endpoint). The Power Source Configuration cluster SHALL be present on the endpoint which is the top level of

the hierarchy representing this Bridged Device, referencing the endpoints where the Power

Source clusters for this Bridged Device are present.

In case a Bridged Device does not contain a power source such as battery or mains power feed, or

information about the state of that power source is not available to the Bridge, the Bridge SHALL NOT include a Power Source Configuration cluster and a Power Source cluster on the endpoint repre­ senting the Bridged Device.

 

9.12.2.4.  Clusters for Bridged Device functionality (device types)

For each Bridged Device, the Bridge SHALL expose the clusters required for a device of the indi­ cated Matter device type(s).

This allows the Matter Nodes to recognize the device type of the Bridged Device and interact with its clusters in the same manner as with a native Matter Node of that device type.

 

9.12.3.  Discovery of Bridged Devices

A Node which discovers another Node with device type Aggregator on one of its endpoints SHOULD walk the entire tree of endpoints via the PartsList attributes and endpoints to discover the list of Bridged Devices, including their device types and other attributes, as well as any native Matter

functionality potentially present on the Node.

Each endpoint found containing a Bridged Node device type represents a Bridged Device of the device type(s) specified at this endpoint, or one of the endpoints found via its PartsList. If the dis­

covering Node supports this device type, it MAY add this Bridged Device to the list of devices which it could interact with, or could set up configuration for.

This discovering Node SHALL use the acquired information on the available Bridged Devices to set up (configure) (likely with input from the user) how the Bridged Devices can be used with the Mat­ ter Nodes (e.g. which switch controls which light, or how to control a light from an app on the user’s phone).

Since the Bridge may expose a large number of Bridged Devices, the discovering Node SHALL use the NodeLabel attribute in the Bridged Device Basic Information cluster of each of the Bridged Devices to allow the user to easily identify and recognize the various Bridged Devices, and expedite

the setup/configuration process, rather than present the user with an unannotated list of, for exam­ ple, 20 lights, 3 sensors and 4 switches. These labels have likely been populated by the user when interacting previously with the Bridge e.g. through means provided by the Bridge Manufacturer, such as a Bridge Manufacturer app.

If power source-related information regarding the Bridged Device is provided in the Power Source

cluster on the associated endpoint, the discovering Node SHOULD use this information in a similar manner as power source-related information acquired from a Matter Node’s  Power Source cluster.

 

Such information can then be used to inform the user about the state of the power source (e.g. warn about low batteries) in a Bridged Device in a similar manner as done for Matter Nodes.

 

9.12.4.  Configuration of Bridged Devices

For configuration of the discovered Bridged Devices, two basic archetypes are described in the fol­ lowing sections: one for actuators and one for sensors/switches.

Since a Bridged Device of a certain device type has the same set of application clusters as a native Matter device of the same device type, this process is similar to configuring a native Matter device of that device type.

 

9.12.4.1.  Sending commands from a Matter controller to a Bridged Device

For Bridged Devices that are actuators and hence have a Controlee role, a Controller Node on the Fabric MAY send commands to the associated clusters on one or more endpoints on the Bridge’s

Node, such as an On command to the On/Off cluster of a Bridged Device. The Bridge SHALL forward

this command to the relevant Bridged Device after conversion between the Matter protocol and the

non-Matter device’s native protocol. Example:

A Controller creates a Group containing some Matter lights as well as some non-Matter lights, by sending an Add Group command to the instances of the Group cluster on both the endpoints of the Matter lights as well as on the Bridge’s Node endpoints representing the targeted bridged lights.

Similarly, the Controller creates one or more Scenes using the instances of the Scene cluster on these

endpoints.

The Controller then sends a (single) On command (On/Off cluster) to this group to switch on all these lights in a single operation. This (single) multicast message will be received (and interpreted) by the

Matter lights which are part of this group as well as by the Bridge, which will forward it (after appropriate protocol conversion) to the relevant bridged lights.

Similarly, the Controller sends a (single) Move to Level (Level Control cluster) or sends a (single)

Recall Scene (Scene cluster) to this group, to set the brightness resp. recall a scene contents on all

these lights in a single operation.

 

 

Matter controllers & apps              Bridge Manufacturer app

 

 

 

 

 

 

Living room

Uplighter Downlighter

lights

 

 

 

 

 

 

 

 

 

 

 

Matter lights

 

 

Matter network

bridge Matter

<=>

Zigbee

 

bridged lights

 

 

Zigbee network

 

Matter light control                                              Zigbee light control

 

 

Figure 46. example of bridging lights

 

9.12.4.2.  Receiving status/events/commands from a Bridged Device

For Bridged Devices like sensors and switches, the Bridge will receive value updates (e.g. Zigbee attribute reports), events and/or commands from those devices, and SHALL (after conversion from the native protocol of the non-Matter devices towards Matter protocol) represent those as attributes, events and/or commands in the appropriate clusters on the associated endpoints of the Bridge.

Interactions with those attributes/events/commands on the Matter side (e.g., towards a Controller using the sensor/switch data) SHOULD be identical to interactions with corresponding attributes/events/commands in native Matter sensors and switches (e.g., attribute readout and sub­ scription, proxying and eventing).

Examples:

 

  • A temperature sensor sends a status report to the Bridge over a non-Matter interface. The logic in the Bridge processes this as an update to the Measured Value attribute of the Temperature Mea­ surement cluster on the endpoint associated with this bridged sensor.

Nodes on the Fabric which have an interest in this value can read the updated attribute value, and can configure a subscription on this attribute. This is identical to reading an attribute value or setting up an attribute subscription on a native-Matter temperature sensor Node.

  • A user presses a button on a (push-button) switch device. The switch device sends a message to the Bridge over a non-Matter interface. The logic in the Bridge processes this to generate an Ini­ tialPress event (Switch cluster) on the endpoint representing the

Nodes on the Fabric which have an interest in the switch operation can setup eventing from this cluster.

 

 

Matter controllers & apps            Bridge Manufacturer app

 

 

 

 

Living room

Uplighter

Downlighter

Reading light

Switch 1 ON

Switch 2 OFF

Temp: 20 °C

 

 

Living room

Uplighter

Downlighter

Reading light

Switch 1 ON

Switch 2 OFF

Temp: 20 °C

Kitchen

Ceiling

Cooking island

lights

 

 

 

 

 

 

 

 

 

 

 

Matter lights

 

 

Matter network

bridge Matter

<=>

Zigbee                               Zigbee

network

bridged switches/sensors

sensors & switches

 

 

 

Matter switch/sensor state              Zigbee switch/sensor state

 

 

Figure 47. example of bridging switches and sensors

 

9.12.5.  New features for Bridged Devices

Bridged Devices can have their software updated independently of the Bridge, through Bridge Man­ ufacturer-specific means. These updates MAY result in one or more changes to their capabilities, such as supported clusters and/or attributes, for an endpoint. Like every Matter Node, every end­

point on the Bridge’s Node contains a Descriptor cluster that contains attributes for the device types

(DeviceTypeList), endpoints (PartsList) and supported clusters (ServerList and ClientList). Nodes

that wish to be notified of such changes SHOULD monitor changes of these attributes.

 

9.12.6.  Changes to the set of Bridged Devices

Bridged Devices can be added to or removed from the Bridge through Bridge-specific means. For example, the user can use a Manufacturer-provided app to add/remove Zigbee devices to/from their Matter-Zigbee Bridge.

When an update to the set of Bridged Devices (which are exposed according to the Section 9.12.11, “Best practices for Bridge Manufacturers”) occurs, the Bridge SHALL

  • on the Descriptor clusters of the root node endpoint and of the endpoint which holds the Aggre­ gator device type: update the PartsList attribute (add/remove entries from this list)
  • update the exposed endpoints and their descriptors according to the new set of Bridged Devices

 

Nodes that wish to be notified of added/removed devices SHOULD monitor changes of the PartsList attribute in the Descriptor cluster on the root node endpoint and the endpoint which holds the

Aggregator device type.

Allocation of endpoints for Bridged Devices SHALL be performed as described in Dynamic End­ point allocation.

 

9.12.7.  Changes to device names and grouping of Bridged Devices

Typically, the user has some means (e.g. a Manufacturer-provided app) to assign names to the Bridged Devices, or names could be assigned automatically by the Bridge. The Bridge SHALL expose such names in the NodeLabel attribute of the Bridged Device Basic Information cluster on the applicable endpoint.

Similarly, the user typically has some means to group the Bridged Devices (e.g. via a room/zone-con­ cept) and provide names to such groups, or grouping could be applied automatically by the Bridge. The Bridge SHOULD expose such grouping using the EndpointLists attribute of the Actions cluster as described above.

For such exposed information, when there is a change in naming/grouping (e.g. the user makes changes via a Manufacturer-provided app), the Bridge SHALL update the appropriate attributes.

Nodes that wish to be notified of a change in such a name or grouping SHOULD monitor changes of this attribute or cluster.

 

9.12.8.  Setup flow for a Bridge (plus Bridged Devices)

As described above, the Bridge together with its Bridged Devices is exposed as a single Node with a list of endpoints. Consequently, a single Node ID and a single Operational Certificate is assigned during Commissioning and a single pass through the commissioning flow is required to bring the Bridge (along with its Bridged Devices) onto a Fabric. This provides for a simple user experience, since the user only needs to go through the commissioning flow for the Bridge, and not separately for each of the Bridged Devices.

 

9.12.9.  Access Control

The Bridge is a Matter node, therefore it has a single Access Control Cluster for the entire Node, like every other Matter Node. This cluster contains all Access Control Entries for each of its endpoints, including for all Bridged Devices and other native Matter functionality exposed by the Bridge Node. A typical setup of Access Control would reflect which privilege level a Matter Controller needs to have for one or more Bridged Devices. This overall access set may be a subset of all the Bridged Devices on the Bridge, rather than all endpoints on a Bridge. This can be accomplished by setting an Access Control Entry containing as targets a list of those endpoints representing a Bridged Device or a set of Bridged Devices. As defined in the ACL model, it is also possible to specify access towards

specific Targets, for example all Bridged Devices of device type Extended Color Light.

 

9.12.10.  Software update (OTA)

The Bridge is a Matter device and its Matter-related functionality MAY be updated using the mecha­ nism described in Section 11.19, “Over-the-Air (OTA) Software Update”.

The Bridged Devices, on the other hand, are not native Matter devices, do not have a Product ID, and are not listed in the Distributed Compliance Ledger. They are typically updated using a mecha­ nism defined and deployed by the Bridge Manufacturer. That same mechanism is typically used to update the parts of the Bridge which are not related to Matter, which is particularly relevant to allow synchronization of updates to the non-Matter part of the Bridge with updates to the Bridged Devices. Obviously, such mechanism MAY also be employed to update the entire Bridge firmware, including the Matter-related functionality.

 

9.12.11.  Best practices for Bridge Manufacturers

This section summarizes (in order of priority) the process to determine which non-Matter devices the Bridge exposes to the Fabric.

  1. Choice of supported device types
    • A Manufacturer MAY choose which of the Matter device types they can or want to support in the Bridge. After implementation of support for bridging of those device types, they SHALL certify the Bridge for those device
    • By default, a Bridge SHOULD expose to the Fabric all its connected non-Matter devices which can be mapped to a Matter device type for which that Bridge is

E.g., if a Bridge is certified for Matter light bulbs, it SHOULD NOT hide any light bulb on the non-Matter side from the Fabric by default (some situations where the Bridge MAY deviate from this recommendation are in the following text).

  • Given the wide variety of device types on a wide variety of standards, there may be device types on the non-Matter side that do not have a corresponding Matter device type. Such devices cannot be bridged to a Matter device type. The Manufacturer MAY choose to not expose such devices with the Bridge or MAY expose them with a manufacturer-specific device type and/or manufacturer-specific
  1. Compatibility issues
    • For the device types for which a Bridge is certified, a Bridge Manufacturer MAY decide to not expose certain devices based on any reason, including compatibility and interoperabil­ ity reasons, or to expose them in a ‘best-effort’ manner as
      • The Bridge Manufacturer may choose to not expose a device that does not support cer­ tain functions or features which are mandatory for a Matter device type, but which are defined as optional, or not defined at all, in the specification for the corresponding device type on the non-Matter side of the bridge. Such a Bridge would expose to the Fab­ ric only Bridged Devices of device types which support those particular control functions or features which are
      • The Bridge Manufacturer may also choose to map or emulate such features which are not available in the Bridged Device; example: for a bridged colored light connected via a protocol which does not support scenes, the Bridge could emulate the scene function by storing the scenes in the Bridge and sending corresponding brightness and color com­ mands to the light when a Scene Recall command is received from a Matter
  1. User choice
    • A Bridge MAY make it possible (e.g., through a Bridge Manufacturer’s app) for its users to further restrict which devices are exposed to the

For example, a user may decide to prevent exposure to the Fabric of certain Devices Types, such as all occupancy sensors, or of only certain devices of a certain device type, such as only their bedroom occupancy sensor.

 

9.12.12.  Best practices for Administrators

An Administrator MAY indicate to users which devices are native Matter and which ones are Bridged Devices, as determined using the presence of a Bridged Node device type on the endpoint, in

 

order to ensure the user does not make assumptions about the Bridged Devices having the same security requirements as native Matter devices.

 

 

 

9.13.   Bridged Device Basic Information Cluster

 

This Cluster serves two purposes towards a Node communicating with a Bridge:

 

  • Indicate that the functionality on the Endpoint where it is placed (and its Parts) is bridged from a non-Matter technology, and
  • Provide a centralized collection of attributes that the Node MAY collect to aid in conveying information regarding the Bridged Device to a user, such as the vendor name, the model name, or user-assigned

This cluster SHALL be exposed by a Bridge on the Endpoint representing each Bridged Device. When the functionality of a Bridged Device is represented using a set of Endpoints, this cluster SHALL only be exposed on the Endpoint which is at the top of the hierarchy for the functionality of that Bridged Device.

This cluster SHALL NOT be used on an endpoint that is not in the Descriptor cluster PartsList of an endpoint with an Aggregator device type.

This cluster has been derived from the Basic Information Cluster, and provides generic information about the Bridged Device. Not all of the attributes in the Basic Information Cluster are relevant for a Bridged Device (e.g. ProductID since it is not a Matter device). For other attributes, the informa­ tion which is listed as Mandatory for the Basic Information Cluster, may not be available when the Bridged Device does not provide it to the Bridge, and the Bridge has no other means to determine it. For such cases where the information for a particular attribute is not available, the Bridge SHOULD NOT include the attribute in the cluster for this Bridged Device. See below for Conformance details.

 

9.13.1.  Revision History

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

 

Revision Description
1 Initial Release

 

9.13.2.  Classification

 

Hierarchy Role Scope PICS Code
Derived from Basic Information Utility Endpoint BRBINFO

 

  • Cluster ID

 

 

ID Name
0x0039 Bridged Device Basic Information

 

  • Attributes

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0000 DataMod­ elRevision           X
0x0001 Vendor­ Name           O
0x0002 VendorID           O
0x0003 Product­ Name           O
0x0004 ProductID           X
0x0005 NodeLabel           O
0x0006 Location           X
0x0007 Hardware­ Version           O
0x0008 Hardware­ Version­ String           O
0x0009 Software­ Version           O
0x000a Software­ Version­ String           O
0x000b Manufac­ turing­ Date           O
0x000c PartNum­ ber           O
0x000d Produc­ tURL           O
0x000e Product­ Label           O
0x000f Serial­ Number           O

 

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0010 LocalCon­ figDis­ abled           X
0x0011 Reachable           M
0x0012 UniqueID           O
0x0013 Capabili­ tyMinima           X

 

Since this cluster has been derived from the Basic Information Cluster, the identifiers of the attributes, their range, quality and default characteristics and their descriptions correspond to those in that Cluster and those descriptions are not repeated here. Several attributes from the Basic Information Cluster which are not relevant or applicable for a Bridged Device have been marked with X in column Conformance and SHALL NOT be used in the Bridged Device Basic Information Cluster.

The Conformance characteristics of several attributes in this cluster have changed from M to O compared to their Conformance in the Basic Information Cluster, and SHALL be used according to the table above.

The Bridge SHOULD fill these attributes with the available information, which could e.g. come from the Bridged Device provided to the Bridge over the non-Matter interface (e.g. VendorName and Ven­ dorID) or could have been provided by the user (e.g. assigned name of a device for NodeLabel).

If the manufacturer of a Bridged Device is known to the Bridge, the Bridge SHALL provide this name (in attribute VendorName), otherwise it SHALL NOT include this attribute.

If the manufacturer of a Bridged Device and the associated Alliance-assigned Vendor ID are known to the Bridge (e.g. by copying the Manufacturer Code from the Node Descriptor of a Zigbee device), the Bridge SHALL provide this identifier (in attribute VendorID), otherwise it SHALL NOT include this attribute.

The Reachable attribute SHALL be used to indicate whether the bridged device is reachable by the bridge over the non-Matter network, so a Matter Node which wants to communicate with a bridged device can get an indication that this might fail (when the attribute is False). Determination of reachability MAY not be perfect (e.g. depending on technology employed), so the Matter Node SHOULD be aware of the risk of false positives and negatives on reachability determination. For  example, a bridged device MAY be marked as unreachable while it could actually be reached, and vice-versa.

Also see event ReachableChanged below.

 

The UniqueID attribute (when present) for a Bridged Device SHOULD be updated when the Bridge is factory reset.

 

9.13.5.  Events

This cluster SHALL support these events:

 

 

ID Name Priority Access Conformance
0x00 StartUp     O
0x01 ShutDown     O
0x02 Leave     O
0x03 Reach­ ableChanged     M

 

9.13.5.1. ReachableChanged Event

This event SHALL be generated when there is a change in the Reachable attribute. Its purpose is to provide an indication towards interested parties that the reachability of a bridged device (over the non-Matter network) has changed, so they MAY take appropriate action.

After (re)start of a bridge this event MAY be generated.

 

 

 

9.14.   Actions Cluster

 

This cluster provides a standardized way for a Node (typically a Bridge, but could be any Node) to expose

  • Information about logical grouping of endpoints on the Node (example: lights in a room)
  • Information about named actions that can be performed on such a group of endpoints (exam­ ple: recall a scene for a group of lights by its name)
  • Commands to trigger such actions
  • Events to receive feedback on the state of such

 

The information on grouping and available actions is typically provided by the user or Bridge man­ ufacturer via some means not defined in Matter, and therefore provided as read-only to Nodes. For example: a manufacturer-provided app allows a user to set up logical grouping and create/assign scene for such groups.

Using this cluster, a Node can learn about such logical grouping, provided actions, and trigger such actions.

While the origin of this cluster stems from use cases with a Bridge, its server side may also be implemented on any Node which can expose certain grouping, actions or automations to other users.

After defining the attributes, commands and events for this cluster, and the associated data types, several examples are provided to illustrate the capabilities of this cluster.

Actions can be defined in a flexible manner to suit the needs of the various nodes implementing this cluster. For each action, the commands available for that particular action are defined.

This cluster can be used to expose only the grouping of endpoints without any actions defined by populating the EndpointList attribute accordingly and providing an empty list for ActionList.

 

The term ‘action’ in the description of this cluster should not be confused with the term ‘action’ as used in the Interaction Model.

 

9.14.1.  Revision History

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

 

Revision Description
1 Initial Release

 

9.14.2.  Classification

 

Hierarchy Role Scope PICS Code
Base Application Node ACT

 

  • Cluster ID

 

ID Name
0x0025 Actions

 

  • Data Types

 

9.14.4.1.  CommandBits

This data type is derived from map16.

 

Bit Name Summary
0 InstantAction Indicate support for InstantAc­ tion command
1 InstantActionWithTransition Indicate support for InstantAc­ tionWithTransition command
2 StartAction Indicate support for StartAction command
3 StartActionWithDuration Indicate support for StartAc­ tionWithDuration command
4 StopAction Indicate support for StopAction command
5 PauseAction Indicate support for PauseAc­ tion command
6 PauseActionWithDuration Indicate support for PauseAc­ tionWithDuration command

 

 

Bit Name Summary
7 ResumeAction Indicate support for ResumeAc­ tion command
8 EnableAction Indicate support for EnableAc­ tion command
9 EnableActionWithDuration Indicate support for EnableAc­ tionWithDuration command
10 DisableAction Indicate support for DisableAc­ tion command
11 DisableActionWithDuration Indicate support for DisableAc­ tionWithDuration command

 

Note – The bit allocation of this bitmap SHALL follow the ID’s of the Commands of this cluster.

 

9.14.4.2.  ActionTypeEnum

This data type is derived from enum8.

 

Value Name Summary Conformance
0 Other Use this only when none of the other val­ ues applies M
1 Scene Bring the endpoints into a certain state M
2 Sequence A sequence of states with a certain time pat­ tern M
3 Automation Control an automation (e.g. motion sensor con­ trolling lights) M
4 Exception Sequence that will run when something doesn’t happen M
5 Notification Use the endpoints to send a message to user M
6 Alarm Higher priority notifi­ cation M

 

Scene Value

 

Can be used to set a static state of the associated endpoints (typically using InstantAction or Instan­ tActionWithTransition), or to bring these endpoints into a more dynamic state (typically using Star­ tAction), where the endpoints would e.g. gradually cycle through certain colors for a pleasing effect. A voice controller could use “set” (to map to InstantAction) or “play” (to map to StartAction) to trig­

 

ger such actions.

Example: see examples 1 and 2.

 

Sequence Value

 

Indicates an action which involves a sequence of events/states of the associated endpoints, such as a wake-up experience.

Example: see example 4.

 

Automation Value

 

Indications an automation (e.g. a motion sensor controlling lights, an alarm system) which can be

e.g. started, stopped, paused, resumed. Example: see example 3.

 

Exception Value

 

Indicates some action which the server will execute when a certain condition (which normally does not happen) is not met.

Example: lock the doors when the server’s system has detected no one is at home while the doors are in the ‘unlocked’ state.

 

Notification Value

 

Indicates an action that can be triggered (e.g. by InstantAction) to notify the user.

Example: play a pattern on the lights in the living room if there is someone in the garden in the evening.

 

Alarm Value

 

Similar to Notification but with a higher priority (and might override other endpoint states which Type=Notification would not override).

Example: flash all lights in the house when CO sensor triggers.

 

9.14.4.3.  ActionStateEnum

This data type is derived from enum8.

 

Value Name Summary Conformance
0 Inactive The action is not active M
1 Active The action is active M
2 Paused The action has been paused M
3 Disabled The action has been disabled M

Note that some of these states are applicable only for certain actions, as determined by their Sup­ portedCommands.

 

9.14.4.4.  ActionErrorEnum

This data type is derived from enum8.

 

Value Name Summary Conformance
0 Unknown Other reason not listed in the row(s) below M
1 Interrupted The action was inter­ rupted by another com­ mand or interaction M

 

9.14.4.5.  EndpointListTypeEnum

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

 

Value Name Summary Conformance
0 Other Another group of end­ points M
1 Room User-configured group of endpoints where an endpoint can be in only one room M
2 Zone User-configured group of endpoints where an endpoint can be in any number of zones M

The Room and Zone values are provided for the cases where a user (or the system on behalf of the user) has created logical grouping of the endpoints (e.g. bridged devices) based on location.

 

Other Value

 

This value is provided for the case of an endpoint list which is tied specifically to this action i.e. not independently created by the user. For Type=Other the Name MAY be empty. A Matter controller would typically not use this for anything else than just to know which endpoints would be affected by the action.

 

Room Value

 

Is used for the situation where an endpoint can only be part of one such rooms (e.g. physical map­ ping). Using these exposed logical groups, a Matter controller who has a similar grouping concept can use it to place each endpoint (bridged device) in the right room automatically, without user having to redo that setup for each device in each system – both at first contact and upon later updates to the endpoints (e.g. user adds a bridged device or creates a new room).

 

Zone Value

 

Is a more general concept where an endpoint can be part of multiple zones, e.g. a light in the living

 

room can be part of the “reading corner” zone (subset of the lights in the living room) but also part of the “downstairs” zone which contains all the lights on a floor, e.g. combining living room, kitchen and hallway. This indicates that a user has defined this list of endpoints as something they logically would like to control as a group, so Matter controllers could provide the user with a way to do as such.

 

9.14.4.6.  ActionStruct

This data type holds the details of a single action, and contains the data fields below.

 

ID Name Type Constraint Quality Default Access Confor­ mance
0 ActionID uint16 all     R M
1 Name string

max 32

[128]

    R M
2 Type Action­ TypeEnum all     R M
3 End­ pointListID uint16 all     R M
4 Supported­ Commands Command­ Bits 0 to 0x0fff     R M
5 State ActionSta­ teEnum all     R M

 

ActionID Field

 

This field SHALL provide an unique identifier used to identify an action.

 

Name Field

 

This field SHALL indicate the name (as assigned by the user or automatically by the server) associ­ ated with this action. This can be used for identifying the action to the user by the client. Example: “my colorful scene”.

 

Type Field

 

This field SHALL indicate the type of action. The value of Type of an action, along with its Support­ edCommands can be used by the client in its UX or logic to determine how to present or use such action. See ActionTypeEnum for details and examples.

 

EndPointListID Field

 

This field SHALL provide a reference to the associated endpoint list, which specifies the endpoints on this Node which will be impacted by this ActionID.

 

SupportedCommands Field

 

This field is a bitmap which SHALL be used to indicate which of the cluster’s commands are sup­

 

ported for this particular action, with a bit set to 1 for each supported command according to the ta­ ble below. Other bits SHALL be set to 0.

 

State Field

 

This field SHALL indicate the current state of this action.

 

9.14.4.7.  EndpointListStruct

This data type holds the details of a single endpoint list, which relates to a set of endpoints that have some logical relation, and contains the data fields below.

 

ID Name Type Constraint Quality Default Access Confor­ mance
0 End­ pointListID uint16 all     R M
1 Name string

max 32

[128]

    R M
2 Type End­ pointList­ TypeEnum all     R M
3 Endpoints list[end­ point-no] max 256     R M

 

EndPointListID Field

 

This field SHALL provide an unique identifier used to identify the endpoint list.

 

Name Field

 

This field SHALL indicate the name (as assigned by the user or automatically by the server) associ­ ated with the set of endpoints in this list. This can be used for identifying the action to the user by the client. Example: “living room”.

 

Type Field

 

This field SHALL indicate the type of endpoint list, see EndpointListTypeEnum.

 

EndPoints Field

 

This field SHALL provide a list of endpoint numbers.

 

9.14.5.  Attributes

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0000 ActionList list[Action­ Struct] max 256   empty R V M

 

 

ID Name Type Constraint Quality Default Access Confor­ mance
0x0001 End­ pointLists list[End­ pointList­ Struct] max 256   empty R V M
0x0002 SetupURL string max 512   empty R V O

 

9.14.5.1.  ActionList Attribute

The ActionList attribute holds the list of actions. Each entry SHALL have an unique ActionID, and its EndpointListID SHALL exist in the EndpointLists attribute.

 

9.14.5.2.  EndpointLists Attribute

The EndpointLists attribute holds the list of endpoint lists. Each entry SHALL have an unique End­ pointListID.

 

9.14.5.3.  SetupURL Attribute

The SetupURL attribute (when provided) SHALL indicate a URL; its syntax SHALL follow the syntax as specified in RFC 3986, max. 512 ASCII characters. The location referenced by this URL SHALL provide additional information for the actions provided:

  • When used without suffix, it SHALL provide information about the various actions which the cluster
  • When used with a suffix of “/?a=” and the decimal value of ActionID for one of the actions, it MAY provide information about that particular action. This could be a deeplink to manufac­ turer-app/website (associated somehow to the server node) with the information/edit-screen for this action so that the user can view and update details of the action, e.g. edit the scene, or change the wake-up experience time

 

9.14.6.  Commands

 

ID Name Direction Response Access Conformance
0x00 InstantAction client ⇒ server Y O desc
0x01 InstantAction­ WithTransi­ tion client ⇒ server Y O desc
0x02 StartAction client ⇒ server Y O desc

 

 

ID Name Direction Response Access Conformance
0x03 StartAction­ WithDuration client ⇒ server Y O desc
0x04 StopAction client ⇒ server Y O desc
0x05 PauseAction client ⇒ server Y O desc
0x06 PauseAction­ WithDuration client ⇒ server Y O desc
0x07 ResumeAction client ⇒ server Y O desc
0x08 EnableAction client ⇒ server Y O desc
0x09 EnableAction­ WithDuration client ⇒ server Y O desc
0x0a DisableAction client ⇒ server Y O desc
0x0b DisableAction­ WithDuration client ⇒ server Y O desc

 

Conformance: a server SHALL support a command when it is listed in the SupportedCommands data field of one or more actions listed in the ActionList provided by the server.

Some general requirements and data fields for all the commands:

 

  • The ActionID data field SHALL indicate the action If there is no entry the in ActionList holding the same action identifier, a response shall be generated with the StatusCode NOT_­ FOUND.
  • The InvokeID data field MAY be provided by the client when invoking a command. When this value is provided, the server SHALL generate a StateChanged event when the action changes to a new state or an ActionFailed event when execution of the action fails; in the data of such events, the value of the InvokeID data field from the invoke will be provided, so that the client can relate the event back to the corresponding command. It is up to the client to determine which value is provided in InvokeID. When sending multiple commands for the same action, with different InvokeID, the server SHALL provide in the event the InvokeID value from the most recent command for a particular
  • If the command refers to an action which currently is not in a state where the command applies, a response shall be generated with the StatusCode
  • Actions are typically mapped to state changes of the involved endpoints. Those endpoints can also be controlled with commands from other clusters, controlled by other nodes and impacted by non-Matter interactions (e.g. local controls). Such other interactions can cause the state of the endpoints to differ from the results of the command which triggered the action. A client inter­ ested in such changes can use the InvokeID data field (see above) to receive events State­ Changed and ActionFailed for feedback for such

 

9.14.6.1.  InstantAction Command

This command SHALL have the following data fields:

 

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O

 

This command triggers an action (state change) on the involved endpoints, in a “fire and forget” manner. Afterwards, the action’s state SHALL be Inactive.

Example: recall a scene on a number of lights.

 

9.14.6.2.  InstantActionWithTransition Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O
2 Transition­ Time uint16 all   MS M

It is recommended that, where possible (e.g., it is not possible for attributes with Boolean data type), a gradual transition SHOULD take place from the old to the new state over this time period. How­ ever, the exact transition is manufacturer dependent.

This command triggers an action (state change) on the involved endpoints, with a specified time to transition from the current state to the new state. During the transition, the action’s state SHALL be Active. Afterwards, the action’s state SHALL be Inactive.

Example: recall a scene on a number of lights, with a specified transition time.

 

TransitionTime Field

 

This field SHALL indicate the transition time in 1/10th of seconds.

 

9.14.6.3.  StartAction Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O

This command triggers the commencement of an action on the involved endpoints. Afterwards, the action’s state SHALL be Active.

 

Example: start a dynamic lighting pattern (such as gradually rotating the colors around the set­ points of the scene) on a set of lights.

Example: start a sequence of events such as a wake-up experience involving lights moving through several brightness/color combinations and the window covering gradually opening.

 

9.14.6.4.  StartActionWithDuration Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O
2 Duration uint32 all   MS M

This command triggers the commencement of an action on the involved endpoints, and SHALL change the action’s state to Active. After the specified Duration, the action will stop, and the action’s state SHALL change to Inactive.

Example: start a dynamic lighting pattern (such as gradually rotating the colors around the set­ points of the scene) on a set of lights for 1 hour (Duration=3600).

 

Duration Field

 

This field SHALL indicate the requested duration in seconds.

 

9.14.6.5.  StopAction Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O

This command stops the ongoing action on the involved endpoints. Afterwards, the action’s state SHALL be Inactive.

Example: stop a dynamic lighting pattern which was previously started with StartAction.

 

9.14.6.6.  PauseAction Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M

 

 

ID Name Type Constraint Quality Default Confor­ mance
1 InvokeID uint32 all     O

 

This command pauses an ongoing action, and SHALL change the action’s state to Paused.

 

Example: pause a dynamic lighting effect (the lights stay at their current color) which was previ­ ously started with StartAction.

 

9.14.6.7.  PauseActionWithDuration Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O
2 Duration uint32 all   MS M

This command pauses an ongoing action, and SHALL change the action’s state to Paused. After the specified Duration, the ongoing action will be automatically resumed. which SHALL change the action’s state to Active.

Example: pause a dynamic lighting effect (the lights stay at their current color) for 10 minutes (Duration=600).

The difference between Pause/Resume and Disable/Enable is on the one hand semantic (the former is more of a transitionary nature while the latter is more permanent) and on the other hand these can be implemented slightly differently in the implementation of the action (e.g. a Pause would be automatically resumed after some hours or during a nightly reset, while an Disable would remain in effect until explicitly enabled again).

 

Duration Field

 

This field SHALL indicate the requested duration in seconds.

 

9.14.6.8.  ResumeAction Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O

This command resumes a previously paused action, and SHALL change the action’s state to Active.

 

The difference between ResumeAction and StartAction is that ResumeAction will continue the action from the state where it was paused, while StartAction will start the action from the begin­ ning.

Example: resume a dynamic lighting effect (the lights’ colors will change gradually, continuing from the point they were paused).

 

9.14.6.9.  EnableAction Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O

This command enables a certain action or automation. Afterwards, the action’s state SHALL be Active.

Example: enable a motion sensor to control the lights in an area.

 

9.14.6.10.  EnableActionWithDuration Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O
2 Duration uint32 all   MS M

This command enables a certain action or automation, and SHALL change the action’s state to be Active. After the specified Duration, the action or automation will stop, and the action’s state SHALL change to Disabled.

Example: enable a “presence mimicking” behavior for the lights in your home during a vacation; the Duration field is used to indicated the length of your absence from home. After that period, the presence mimicking behavior will no longer control these lights.

 

Duration Field

 

This field SHALL indicate the requested duration in seconds.

 

9.14.6.11.  DisableAction Command

This command SHALL have the following data fields:

 

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O

 

This command disables a certain action or automation, and SHALL change the action’s state to Inac­ tive.

Example: disable a motion sensor to no longer control the lights in an area.

 

9.14.6.12.  DisableActionWithDuration Command

This command SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16 all     M
1 InvokeID uint32 all     O
2 Duration uint32 all   MS M

This command disables a certain action or automation, and SHALL change the action’s state to Dis­ abled. After the specified Duration, the action or automation will re-start, and the action’s state SHALL change to either Inactive or Active, depending on the actions (see examples 4 and 6).

Example: disable a “wakeup” experience for a period of 1 week when going on holiday (to prevent them from turning on in the morning while you’re not at home). After this period, the wakeup experience will control the lights as before.

 

Duration Field

 

This field SHALL indicate the requested duration in seconds.

 

9.14.7.  Events

This cluster SHALL support these events:

 

ID Name Priority Access Conformance
0x00 StateChanged INFO V M
0x01 ActionFailed INFO V M

 

9.14.7.1.  StateChanged Event

This event SHALL be generated when there is a change in the State of an ActionID during the execu­ tion of an action and the most recent command using that ActionID used an InvokeID data field.

It provides feedback to the client about the progress of the action.

 

Example: When InstantActionWithTransition is invoked (with an InvokeID data field), two State­ Changed events will be generated:

  • one when the transition starts (NewState=Active)
  • one when the transition completed (NewState=Inactive) This event SHALL have the following data fields:
ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16       M
1 InvokeID uint32       M
2 NewState ActionSta­ teEnum       M

 

ActionID Field

 

This field SHALL be set to the ActionID of the action which has changed state.

 

InvokeID Field

 

This field SHALL be set to the InvokeID which was provided to the most recent command referenc­ ing this ActionID.

 

NewState Field

 

This field SHALL be set to state that the action has changed to.

 

9.14.7.2.  ActionFailed Event

This event SHALL be generated when there is some error which prevents the action from its nor­ mal planned execution and the most recent command using that ActionID used an InvokeID data field.

It provides feedback to the client about the non-successful progress of the action.

 

Example: When InstantActionWithTransition is invoked (with an InvokeID data field), and another controller changes the state of one or more of the involved endpoints during the transition, thus interrupting the transition triggered by the action, two events would be generated:

  • StateChanged when the transition starts (NewState=Active)
  • ActionFailed when the interrupting command occurs (NewState=Inactive, Error=interrupted)

 

Example: When InstantActionWithTransition is invoked (with an InvokeID data field = 1), and the same client invokes an InstantAction with (the same or another ActionId and) InvokeID = 2, and this second command interrupts the transition triggered by the first command, these events would be generated:

  • StateChanged (InvokeID=1, NewState=Active) when the transition starts

 

  • ActionFailed (InvokeID=2, NewState=Inactive, Error=interrupted) when the second command interrupts the transition
  • StateChanged (InvokeID=2, NewState=Inactive) upon the execution of the action for the second command

This event SHALL have the following data fields:

 

ID Name Type Constraint Quality Default Confor­ mance
0 ActionID uint16       M
1 InvokeID uint32       M
2 NewState ActionSta­ teEnum       M
3 Error Action­ ErrorEnum       M

 

ActionID Field

 

This field SHALL be set to the ActionID of the action which encountered an error.

 

InvokeID Field

 

This field SHALL be set to the InvokeID which was provided to the most recent command referenc­ ing this ActionID.

 

NewState Field

 

This field SHALL be set to state that the action is in at the time of generating the event.

 

Error Field

 

This field SHALL be set to indicate the reason for non-successful progress of the action.

 

9.14.8.  Examples

This section provides some examples how the attributes and commands in this cluster can be used in practical situations. Details of the behavior typically depend on the details of the logic built into the server.

 

9.14.8.1.  Example 1: Scene recall

User has defined a scene on a number of lights. The corresponding action would have these data fields describing it:

  • Name=”sunset”
  • Type=Scene
  • EndpointListID references a struct referencing the set of involved endpoints

 

  • Name=”living room”
  • Type=Room
  • Endpoints=list of the endpoints of the lights in this room
  • SupportedCommands: InstantAction, InstantActionWithTransition

 

The InstantAction command (e.g. triggered by a voice command “set sunset in living room”) will trigger the server to activate that scene on those lights.

When a slow fade-in is preferred, the InstantActionWithTransition can be used, with a Transition­ Time parameter of e.g. 50 (denoting 5 s).

 
   

Figure 48. State diagram for example ‘scene recall’

 

9.14.8.2.  Example 2: Set dynamic light effect

User has defined a scene on a number of lights. The corresponding action would have these data fields describing it:

  • Name=”sunset”
  • Type=Scene
  • EndpointListID references a struct referencing the set of involved endpoints (same as in Exam­ ple 1)
  • SupportedCommands: StartAction, StartActionWithDuration, StopAction

 

The StartActionWithDuration command (e.g. triggered by a voice command “play sunset in living room for 1 hour”) will trigger the server to activate a dynamic pattern with colors inspired by sun­ set on the associated lights. At any time, the StopAction can be used to stop the effect.

Please note that the most of the data fields in the ActionStruct for this example are identical to those in example 1 – except for the SupportedCommands. The different sets of supported commands indicate whether it is an instant scene recall (example 1) vs. a long-term dynamic effort (example 2). A server could expose this action also as a single action with the combined set of supported com­

 

mands.

 
   

Figure 49. State diagram for example ‘dynamic light effect’

 

9.14.8.3.  Example 3: Pause sensor automation

User has defined an automation: a motion sensor controls the lights in a certain room. Sometimes, they want to override that automatic behavior, e.g. when having a party.

The action for this example would refer to such automation, which is typically active, but can be paused (=temporarily disabled).

The corresponding action would have these data fields describing it:

 

  • Name=”motion sensor”
  • Type=Automation
  • EndpointListID references a struct referencing the set of involved endpoints (same as in Exam­ ple 1)
  • SupportedCommands: EnableAction, DisableAction, PauseAction, PauseActionWithDuration, ResumeAction

Typically, the action has been started when the user defines the motion sensor behavior, so without a Matter command the action’s state would be ‘Active’. The PauseActionWithDuration command (e.g. triggered by a voice command “disable the motion sensor in living room for 2 hours”) will trig­ ger the server to disable the behavior associated with the motion sensor for the specified time. A ResumeAction command would make this behavior active again. The automation could also have internal logic to abort the disabling after several hours or during the night-time reset, to accommo­ date for the case the user ‘paused’ and forgot to ‘resume’.

 

 

Figure 50. State diagram for example ‘pause sensor automation’

 

9.14.8.4.  Example 4: Wake-up routine

User has defined a wake-up routine: the lights in the bedroom will gradually become brighter and change in color temperature to simulate a sunrise. The sequence lasts for e.g. 30 minutes. Near the end of the sequence, the window coverings would be (partially) opened as well.

The corresponding action would have these data fields describing it:

 

  • Name=”wakeup”
  • Type=Sequence
  • EndpointListID references a struct referencing the set of involved endpoints (lights and window coverings in the bedroom)
  • SupportedCommands: EnableAction, DisableAction, DisableActionWithDuration, PauseAction, PauseActionWithDuration

When the user wants to snooze some more, he can use a voice command to trigger the PauseAction command (which could automatically timeout after e.g. 10 minutes). The StopAction command could similarly be used to cancel the remainder of the whole sequence. The DisableActionWithDu­ ration (with parameter 172,800 =2*24*60*60 s) can be used on Friday evening to disable the sequence for the weekend.

When such action has been defined, a Matter node which is aware of the user’s calendar for the day, can use the StartAction command to trigger this sequence of events.

 

 

Figure 51. State diagram for example ‘wake-up experience’

 

9.14.8.5.  Example 5: Scheduled scene recall

User has setup a scene to be recalled at a certain time of day (e.g. colorful garden lighting to switch on around sunset) and switching off those lights (e.g. at midnight). The server’s automation system takes care of this. On certain occasions (e.g. garden party), the user wants to override this behavior (i.e. the scene should not be recalled at sunset because another scene has been set for the party).

The corresponding action would have these data fields describing it:

 

  • Name=”colorful evening garden”
  • Type=Automation
  • EndpointListID references a struct referencing the set of involved endpoints (lights in the gar­ den)
  • SupportedCommands: EnableAction, DisableAction, DisableActionWithDuration

 

After installation, this action is in Inactive state. At the scheduled “on” time, the colorful garden lighting scene is activated and the action’s state changes to the Active state. At the scheduled “off” time, the lights are switched off, and the action’s state changes to the Inactive state. Using the Dis­ ableAction, the user can prevent these automated steps to occur – the action’s state changes to the Disabled state. Using the DisableActionWithDuration, the user can do similarly, but also indicate an automatic re-enabling after the specified time period. Using the EnableAction, the user can re- enable the automation.

 

 

 

Figure 52. State diagram for example ‘scheduled scene recall’

 

9.14.8.6.  Example 6: Alarm system

User has an alarm system which exposes this cluster, with an action that allows to arm/disarm the system by voice commands from a Matter node which is a client to this cluster.

The corresponding action would have these data fields describing it:

 

  • Name=”alarm system”
  • Type=Automation
  • EndpointListID references a struct referencing the set of involved endpoints (elements of the alarm system)
  • SupportedCommands: EnableAction, DisableAction, DisableActionWithDuration

 

After installation, this action could be in Inactive state (assume user is at home installing so system is not armed). Using the EnableAction, the alarm system would be armed. Using the DisableAction, the alarm system would be disarmed (or disarmed for a period with DisableWithDuration).

 

 

Figure 53. State diagram for example ‘alarm system’

 

 

 

9.15.   Proxy Architecture

 

 

NOTE         Proxy Architecture, Proxy clusters, and Proxy support, are provisional.

 

9.15.1.  Motivation

Constrained devices might not support more than a handful of subscriptions. This is usually attributable to a limited memory or battery. However, there might be a large number of clients who desire to subscribe to that device.

 

9.15.2.  Subscription Proxy: Overview

A subscription proxy is a type of Node that is capable of multiplexing subscriptions from multiple subscribers onto a single subscription to a given publisher.

The term ‘proxy’ is a convenient shorthand that refers to this type of Node.

 

The term ‘source’ SHALL refer to a node that serves as the original source of truth for a set of data. The source acts as a publisher of that data.

The term ‘client’ SHALL refer to a node that wants to subscribe to some source.

 

A proxy subscribing to a source SHALL surface an identical ‘mirror’ of the source’s data to down­ stream clients without the clients having to alter their interaction regardless of whether they are interacting with a proxy or the source itself.

The proxy SHALL be identified by the Subscription Proxy Device Type.

 

 

 

 

Figure 54. Digital twin acting as a proxy re-publishing clusters

 

This multiplexing of subscriptions allows the source to delegate all subscriptions to its proxy, only needing to support a single subscription from that proxy. This reduces the demands placed on energy and memory resources. Consequently, that single subscription will encompass the union of all client interest sets. If the combined set of attribute/event paths becomes fairly large, proxies can leverage the use of wildcards to merge multiple localized paths into a single, broader path with wildcards.

 

 
   

 

Figure 55. Proxy multiplexing interest sets from 3 distinct clients

 

A proxy SHALL only proxy subscribe interactions. It SHALL NOT proxy any other type of interac­ tion.

 

9.15.3.  Composition & Paths

A client subscribing to a proxy SHALL specify the Node ID of the source it wishes to subscribe to in the Path. This SHALL be different from the logical destination Node ID of the message, which

 

SHALL be the Node ID of the proxy.

 

 
   

 

Figure 56. Sample paths when subscribing to a proxy vs the source

 

9.15.4.  Proxy Subscriptions

 

9.15.4.1.  Overview

A proxy only attempts to subscribe to a source when there is a current, valid subscription from a client to the proxy for that source’s data.

The term ‘upstream subscription’ refers to the subscription from the proxy either directly to the source, or indirectly to another proxy for that source’s data.

The term ‘downstream subscription’ refers to the subscription from either a client or another proxy to the proxy in question.

Consequently, when that ‘downstream’ subscription disappears, the ‘upstream’ subscription will either be torn down (if there are no other clients interested in that source) or be amended.

This does not require a priori knowledge of a client’s interest set.

 

9.15.4.2.  Upstream/Downstream Subscription Mechanics

Upstream and downstream subscriptions have the following properties:

 

  • Both subscriptions are independent, but weakly
    • Data is received on the client side, stored on the server side, and used to generate a different set of reports to downstream client(s).
  • It is data that is being proxied, not the actual subscription messages
  • The termination of a downstream subscription will automatically result in an amendment of the upstream subscription to remove the relevant paths that were in the downstream, with a

 

complete termination of the upstream subscription if there was only 1 downstream subscriber present.

  • The disappearance of an upstream subscription will not automatically cancel the downstream subscription.
    • Upstream subscriptions MAY disappear due to network connectivity issues. If an upstream sync report is not received, the proxy SHALL attempt once to re-subscribe to the upstream source; if that re-subscription attempt fails, the proxy SHALL terminate any associated downstream
    • If an upstream subscription is positively terminated by the source as a whole, that will result in a similar termination of the downstream
  • In addition to forwarding status codes embedded in the ReportData from the source, the proxy will convey a special ‘NO_UPSTREAM_SUBSCRIPTION’ IM status code to the downstream client if it has not established a subscription to the

The diagram below gives a sample sequence show-casing the two subscriptions:

 

 

 
   

 

Figure 57. Upstream/Downstream subscription sequences

 

9.15.4.3.  Sync/Liveness

Since subscriptions provide a ‘sync’ message to infer health of the subscription on both sides, it allows a client to monitor the health of its source peer.

Conveyance of this is preserved in downstream subscription through the ‘NO_UPSTREAM_SUB­ SCRIPTION’ status code. This conveys effectively the same information as the sync message would had the client directly subscribed to the source.

 

9.15.4.4.  Upstream Subscription Parameter Derivation

Since the proxy multiplexes all downstream subscriptions onto a single upstream subscription, it has to have logic to harmonize the various parameters from each client subscription.

The following logic table describes what the proxy SHOULD do:

 

Parameter Suggested Logic
Attribute/EventPaths UNION of all paths. Proxy MAY use wildcards if needed to simplify this logic.
DataVersionList MIN
EventNumberList MIN
MinimumSyncInterval MIN
MaximumSyncInterval MAX
MinimumReportingIntervalList MIN
ReportableChangeList MIN

Since each client’s interest is different from the final multiplexed subscription, the proxy has to appropriately filter the data being received from the source before sending it to a given client.

 

9.15.5.  Schemas and Data Serialization/Deserialization

Unlike clients that need to semantically interpret data in addition to deserializing/serializing to/from its internal data stores, a proxy only needs to do the latter.

As a result, proxies MAY achieve proxy functionality with a single firmware image built to handle any client, any cluster, any type of device.

 

9.15.6.  Indirect Proxies

A proxy MAY subscribe to another proxy instead of subscribing directly to the source. This creates proxy chains that allow a single source to be proxied by multiple proxies, allowing better use of available proxy capacity.

 

9.15.7.  Proxy Discovery & Assignment Flow

The following flow describes the process by which a client:

 

  • Discovers that a source needs a proxy
  • Finds an appropriate proxy on the network that is able to handle its request
  • Sets up the proxy to subscribe to the source

 

9.15.7.1.  Step 0: Proxy Setup

A device indicates its ability to act as a certified proxy through stating support for the Subscription Proxy device type.

 

When such a device is commissioned, the commissioner SHALL recognize this ability and MAY write the NodeIds of all the sources that need proxying into the Proxy Configuration Cluster on the proxy device. Alternatively, it MAY configure the proxy to wildcard proxy all devices, removing the need to specify a particular set of NodeIds.

Additionally, the commissioner MAY write the Node ID of the newly added proxy to the Valid Prox­ ies Cluster on source devices that needs proxying. This cluster stores the static list of candidate proxies for a given device. Only devices that support the cluster would need to have this configura­ tion written.

 

9.15.7.2.  Step 1: Rejection

There unfortunately isn’t any a priori heuristic that MAY be applied to deduce if a source needs proxying. This is usually a function of the number of clients subscribed to a source, the number of paths in those subscriptions, as well as the sync intervals.

When a source cannot handle any more incremental subscriptions, that is when proxying is

needed. This is discovered when a client tries to subscribe to the source and is sent back a StatusRe­ sponse containing a RESOURCE_EXHAUSTED IM status code, indicating the source’s inability to handle further subscriptions:

 

 

 
   

 

Figure 58. Rejection

 

In the diagram above, the constraints of the source have been simplified down to having 3 available subscription slots that get filled up.

Upon receipt of the RESOURCE_EXHAUSTED error, the client SHALL invoke the Get Valid Proxies Request command on the source Node. In response, it SHALL receive a Get Valid Proxies Response message containing the NodeIds of valid, candidate proxies.

 

9.15.7.3.  Step 2: Proxy Discovery

After the client has received the list of possible valid proxies, the client MAY attempt to discover a valid proxy that is able to proxy its request.

To do so, the client sends out a Proxy Discover Request Command as a groupcast message to the All

 

Proxies universal group. Before it transmits this message, the client SHALL momentarily subscribe to the IPv6 address that maps to the All Proxies universal group to appropriately receive all responses.

 

 
   

 

Figure 59. Discovery Request

 

9.15.7.4.  Step 3: Proxy Response

Proxies respond to the request with a Proxy Discover Response Command sent as a groupcast message to the All Proxies universal group. A proxy SHALL only send this message when it can handle the subscription request, regardless of whether it is currently subscribed to the source. The response

will contain metadata about its ability to handle the subscription.

The Proxy Discover Response Command SHALL be sent as a completely separate, un-related transac­ tion to the original request. The client SHALL correlate the two using the SourceNodeId present in both messages.

 

Proxies SHALL stagger their responses by waiting for a random interval between 0 and PROXY_S­ CAN_RESPONSE_JITTER before sending the Proxy Discover Response Command to prevent overwhelm­ ing the network or the client, which can be constrained and can have limited buffers.

 

 

 

Figure 60. Proxies send back responses

 

9.15.7.5.  Step 4: Proxy Selection

Client SHALL wait for PROXY_SCAN_PERIOD to aggregate all responses and SHALL filter the set of responses received. Specifically, the client SHALL discard:

  • Responses containing a Source Node ID for other unintended sources
  • Responses containing a Source Node ID in the message that does not match any in the Valid­ ProxyList.

It SHALL then select a proxy from this filtered set based on implementation-chosen policies. One suggested approach would involve selecting the proxy with the least number of hops to the source, followed by largest available capacity.

Clients MAY unsubscribe from the IPv6 multicast group that maps to the All Proxies universal group after aggregating the responses.

 

 

 

Figure 61. Selecting a Proxy

 

9.15.7.6.  Step 5: Proxy Subscription

The client then subscribes to the proxy it has selected. The proxy will do one of two things:

Option 1: If there isn’t another proxy already subscribed to the source, the proxy subscribes to the source directly:

 

 

 

Figure 62. Primary proxy subscription

 

Option 2: If there is already another proxy subscribed to that source, the selected proxy subscribes to that proxy instead.

 

 
   

 

Figure 63. Primary proxy subscription

 

It doesn’t attempt to subscribe directly to the source since it does not know if the source has any free slots available to support the subscription, risking a potential subscription failure if it did so.

Proxies MAY select between the two options by ‘sniffing’ the `Proxy Discover Response Command mes­ sages that were emitted by other proxies. This allows the candidate proxy to determine whether there is another proxy already subscribed to the source.

 

A proxy SHALL have only one subscription to a given source regardless of the number of subscrip­ tion requests from clients for that source. This is necessary to ensure timely ACL enforcement in the case where a client no longer has access to the source, and subsequent state changes will not be made available to that client (see ACL Enforcement for more details).

 

9.15.7.7.  Step 6: Eviction

At this point, the source might not be able to handle another subscription. If so, it SHALL evict non- proxy subscriptions to make space for the proxy subscription. This is acceptable since those clients that got evicted MAY eventually subscribe to a proxy as well.

To make this possible, proxies have to express the type of subscription (proxy or not proxy) in the

SubscribeRequest itself.

 

 
   

 

Figure 64. C3 gets evicted

 

9.15.7.8.  Step 7: Re-Assignment

The evicted clients undergo the same proxy discovery/selection process, and eventually settle on a set of proxies.

 

 

 

Figure 65. C3 gets reassigned to P1

 

9.15.7.9.  Notable Characteristics

This algorithm has the following notable characteristics:

 

  • The system ‘auto-balances’ based on the needs of clients and the capabilities of the source
  • No persistent state or a priori configuration is needed on any node
  • No a priori heuristics are needed to figure out if a node should be
  • Robust to proxy failure by leveraging the liveness construct of subscriptions to accelerate dis­ covery
  • No centralized proxy management/assignment service is
    • There is no single point of No need for an election, state backup, or fail-over.
  • Low complexity on server (which are usually the more constrained device), slightly more on the client

 

9.15.8.  Constraints

 

9.15.8.1.  Eviction Rules

A source SHALL NOT evict an existing proxy already subscribed to it to make way for a new sub­ scription regardless of whether that new subscription emanates from a proxy or not. This prevents instability in the system since it might result in ping-ponging proxies subscribing to that source.

 

9.15.8.2.  Number of Direct Proxies

There SHOULD only be one proxy node directly subscribed to a source in a single-fabric setting. This is not enforced by the source but rather, by proxies themselves.

 

9.15.8.3.  Multi-Fabric

In a multi-fabric setting, a source node MAY be subscribed to by clients commissioned into different fabrics. It is highly desirable that a single proxy interacting with a source support clients from mul­ tiple fabrics. To make this possible, a proxy SHOULD when possible, be commissioned into all fab­ rics that contain sources that need proxying.

If a proxy is not commissioned into all fabrics, it might not see another proxy’s Proxy Discover Response Command messages, nor will it be capable of directly subscribing to that proxy even if it did, since it doesn’t have credentials to do so. This MAY result in multiple proxies attempting to sub­

scribe directly to the source, resulting in potential rejection by the source and consequently, an inability for a client’s subscription to be served indirectly through that chosen proxy. This might be unpredictable depending on which proxy was able to subscribe first to that source.

 

9.15.9.  Certification

To ensure a consistent expectation of behavior from a proxy device, the proxy SHOULD be certified by the Connectivity Standards Alliance against the expectations of a proxy. Once certified, it MAY claim compatibility against the Subscription Proxy device type.

 

9.15.10.  Security & Privacy

 

9.15.10.1.  Authentication

To prevent malicious or unattested devices from acting as proxies to clients, the Valid Proxies Clus­ ter provides a scheme for admins to specify the NodeIds of valid, attested proxies to the source

itself, which is in turn conveyed to clients. This allows for filtering of the ensuing Proxy Discover Response Command messages to only select valid, trusted proxies.

 

9.15.10.2.  Multicast Messages

 

The proxy discovery commands SHALL be encrypted with a fabric-provided group key. An Admin­ istrator that wishes to enable proxy functionality on a set of clients SHALL bind the All Proxies group to a specific group key in the Group Key Management cluster.

Consequently, a Proxy Discover Request Command message SHALL be sent for every All Proxies

GroupID instance specified in the Group Keys Management cluster.

 

9.15.10.3.  ACL Enforcement

 

Administrators SHOULD configure source nodes to grant the ‘Proxy View’ privilege to proxy clients. If this privilege is not granted for at least the Access Control cluster, the proxy will not function. This privilege SHOULD be granted for the entire source node for a proxy to be most effective, since

neither the proxy nor the Administrator can predict which source clusters may be subscribed by other clients.

 

The proxy SHALL subscribe to the Access Control Cluster on the source and SHALL enforce the source’s ACLs on behalf of the source when serving its downstream client subscriptions.

The proxy MAY enforce the source’s ACLs eagerly (i.e. at first ACL change), lazily (i.e. at next data report), or by some combination of these approaches. The key guarantee is that the proxy SHALL apply the latest source ACLs from its upstream subscription at the time it generates associated downstream subscription reports.

The proxy SHALL enforce the source’s ACLs on a path by path basis, in a similar manner to how the Access Control Privilege Granting algorithm enforces access. Downstream subscription paths that

are not granted access by the proxy SHALL cause the proxy to generate an UNSUPPORTED_ACCESS error

for that subscription path.

If all report data paths in a downstream subscription result in UNSUPPORTED_ACCESS error, the proxy SHALL tear down that downstream subscription.

 

If the proxy is not able to view the source’s Access Control Cluster due to insufficient privileges, it SHALL NOT generate any downstream subscription data reports for that source. Instead, the proxy

SHALL generate a report containing UNSUPPORTED_ACCESS errors for each path in the downstream

subscription and tear down the downstream subscription.

 

9.15.11.  Parameters and Constants

Table 74, “Glossary of constants” is a glossary of constants used in this section, along with a brief description and example default for each constant.

Table 74. Glossary of constants

 

Constant Name Description Default Value
PROXY_SCAN_RESPONSE_JITTER The maximum amount of time to ran­ domly wait before sending a Proxy Dis­ cover Response Command message. 1000 millisec­ onds
PROXY_SCAN_PERIOD The maximum amount of time initiator of proxy discovery will wait to collect Proxy Discover Response Command messages after sending a Proxy Discover Request Command message. 1100 millisec­ onds

 

9.15.12.  Clusters

 

  • Proxy Discovery Cluster

This cluster contains commands needed to do proxy discovery as defined in the Section 9.15.7.3, “Step 2: Proxy Discovery” and Section 9.15.7.4, “Step 3: Proxy Response” steps of the overall Section 9.15.7, “Proxy Discovery & Assignment Flow”.

 

9.15.13.1.  Revision History

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

 

below.

 

Rev i­ sio n Description
1 Initial Release

 

9.15.13.2.  Classification

 

Hierarchy Role Context PICS Code
Base Utility Node PXDSC

 

  • Cluster Identifiers

 

Iden­ tifier Name

0x004

3

ProxyDiscovery

 

  • Attributes

None

 

9.15.13.5.  Commands

 

Id Name Direction Response Access Conformance
0x00 Proxy Discover Request Client ⇒ Server N O M
0x01 Proxy Discover Response Server ⇒ Client N   M

 

  • Proxy Discover Request Command

 

This command is used during proxy discovery, as specified in Section 9.15.7, “Proxy Discovery & Assignment Flow”.

 

Id Field Type Constraint Quality Default Confor­ mance
0 SourceNode Id node-id all     M
1 NumAt­ tribut­ ePaths uint16 desc     M
2 NumEvent­ Paths uint16 desc     M

 

SourceNodeId

This is the Node ID of the source for which a client seeks to find a Proxy.

 

NumAttributePaths

The number of attribute paths the client will have in the subscription request. This is a heuris­ tic/hint to allow a Proxy to better ascertain whether it can support the ensuing subscription.

 

NumEventPaths

The number of event paths the client will have in the subscription request. This is a heuristic/hint to allow a Proxy to better ascertain whether it can support the ensuing subscription.

 

  • Proxy Discover Response Command

 

This command is used during proxy discovery, as specified in Section 9.15.7, “Proxy Discovery & Assignment Flow”.

 

Id Field Type Constraint Quality Default Confor­ mance
0 SourceNode Id node-id all     M
1 NumHop­ sToSource uint16 desc     M
2 Available­ Capacity uint16 desc     M

 

SourceNodeId

 

This is the Node ID of the source the proxy can proxy for. This SHALL match the node id in the cor­ responding Proxy Discover Request Command message.

 

NumHopsToSource

If the proxy currently subscribes to the source (either directly or indirectly), this indicates the num­ ber of hops to the source. Sensible values start at 1, with 1 being used for a proxy that subscribes directly to the source. If the proxy is not subscribed directly to the source, this value SHALL be one greater than the NumHopsToSource for the given Node ID of the proxy it is subscribed to.

0 indicates that the proxy currently does not have a subscription to the source.

 

AvailableCapacity

A number indicating the number of Cluster Attribute Paths the proxy has space for support. This allows for an absolute comparison of different memory capacities of candidate proxies by the client in selecting the best possible candidate.

 

9.15.14.  Proxy Configuration Cluster

This cluster provides a means for a proxy-capable device to be told the set of Nodes it SHALL proxy.

 

9.15.14.1.  Revision History

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

 

Rev i­ sio n Description
1 Initial Release

 

9.15.14.2.  Classification

 

Hierarchy Role Context PICS Code
Base Utility Node PXCFG

 

  • Cluster Identifiers

 

Iden­ tifier Name

0x004

2

ProxyConfiguration

 

  • Data Types

 

9.15.14.4.1. ConfigurationStruct

 

Quality: Fabric-Scoped
Id Name Type Constraint Quality Access Default Confor­ mance
1 Prox­ yAllNodes bool desc   RW false M
2 SourceList list[node- id] desc   RW empty M

 

ProxyAllNodes

 

This field SHALL be set to to ‘true’ to indicate to the proxy that it SHALL proxy all nodes. When ‘true’, the SourceList attribute is ignored.

 

SourceList

When ProxyAllNodes is ‘false’, this list contains the set of NodeIds of sources that this proxy SHALL specifically proxy.

 

9.15.14.5.  Attributes

Table 75. Cluster Server Attributes

 

Id Name Type Range Quality Access Default Confor­ mance
0 Configura­ tionList list[Config­ ura­ tionStruct] all N RW empty M

 

9.15.14.5.1. ConfigurationList

 

List of proxy configurations. There SHALL NOT be multiple entries in this list for the same fabric.

 

9.15.15.  Valid Proxies Cluster

This cluster provides a means for a device to be told of the valid set of possible proxies that can proxy subscriptions on its behalf as per Section 9.15.7, “Proxy Discovery & Assignment Flow”.

 

9.15.15.1.  Revision History

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

 

Rev i­ sio n Description
1 Initial Release

 

9.15.15.2.  Classification

 

Hierarchy Role Context PICS Code
Base Utility Node PXVALID

 

  • Cluster Identifiers

 

Iden­ tifier Name

0x004

4

ValidProxies

 

  • Data Types

 

9.15.15.4.1. ValidProxyStruct

 

Encapsulates the Node ID of a Valid Proxy.

 

Quality: Fabric-Scoped
Id Name Type Constraint Quality Access Default Confor­ mance
1 NodeID node-idx all   RW   M

 

9.15.15.5.  Attributes

Table 76. Cluster Server Attributes

 

Id Name Type Range Quality Access Default Confor­ mance
0 ValidProx­ yList list[Valid­ ProxyS­ truct] N/A N F RW empty M

 

9.15.15.5.1. ValidProxyList

 

List of valid proxies that can proxy this Node. Each entry in this list is fabric-scoped.

 

9.15.15.6.  Commands

 

Id Name Direction Response Access Conformance
0x00 Get Valid Proxies Request Client ⇒ Server Get Valid Prox­ ies Response O M
0x01 Get Valid Proxies Response Server ⇒ Client N   M

 

  • Get Valid Proxies Request

 

This command is used during proxy discovery, as specified in Section 9.15.7, “Proxy Discovery & Assignment Flow”.

This command has an empty payload.

 

  • Get Valid Proxies Response

 

This command is used during proxy discovery, as specified in Section 9.15.7, “Proxy Discovery & Assignment Flow”.

 

Id Field Type Constraint Quality Default Confor­ mance
0 ProxyN­ odeIdList list[node-id]       M

 

ProxyNodeList

This contains the list of node ids stored in the ValidProxyList whose associated fabric matches the accessing fabric.

 

 

 

 

Adsense

 

 WiFi IoT Module

 

www.mxchip.com

 

 

 Bluetooth Module

www.feasycom.com

 

 

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

 

www.simcom.com

 

Viewed Page List