Chapter 9. System Model Specification ‌

Practical Information
1. Revision History
  
  Revision
  Description
  1
  Initial Release of this specification
2. Scope and Purpose
  This is part of a package of Data Model specifications that are agnostic to underlying layers (encoding, 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.
3. Origin Story
  The origin of this section is the Dotdot Architecture Model and parts of Chapter 2 of the Zigbee Cluster 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.
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.
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).
    
    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.
  - The endpoint MAY support additional device types (application, utility or node device types) as defined by each additional device type.
    
    For example: The Temperature Sensor device type mandates the Temperature Measurement server cluster, and does not require additional device types or endpoints.
    A leaf device type is not composed of other device types.
    
    For example: A Dimmer Switch device type mandates these clusters: On/Off, Level Control, Identify, and does not require additional device types or endpoints.
    Most device types define leaf endpoints without the need for composition.
    
    A composed device type is composed of two 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 temperature sensor leaf endpoints (one for each of the sensors). Those leaf endpoints would indicate and conform to the temperature sensor device type.
- A composed device type MAY indicate a PartsList of local endpoints that are part of the composed device type.
- A root node device type SHALL be a singleton on the root node endpoint.
- The PartsList of the Descriptor cluster on the root node endpoint SHALL list all endpoints on the node, except the root node endpoint.
- The root node endpoint SHALL NOT exist in any other endpoint’s PartsList on the node.
- The root node endpoint requirements are defined by a node scoped device type.
- There SHALL be only one root node endpoint for the node.
- 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 PartsList.
- Each endpoint that supports a device type that is a conformant part of a composed device type on another endpoint SHALL be indicated, along with endpoints in its own PartsList, in the PartsList of the composed device type endpoint.
  
  For example: A Fridge/Freezer endpoint has a PartsList with the Fridge and Freezer endpoint, but also all other dependent endpoints below, including temperature sensor endpoints for the Fridge, Freezer, and Ice Tray (which is part of the Freezer), etc.
  This means that each PartsList indicates all endpoints below it, in the tree hierarchy of composed device types.
- Extra endpoints MAY be in the PartsList that extend the device type implementation.
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 deleted.
  - 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 address.
    - 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 address.
  - For existing exposed entities, the endpoint addresses SHALL NOT be changed.
    - This persistency requirement also holds for the case of restart/reboot of the device.
      As a result of these mechanisms, endpoint addresses that were used for exposed entities that were once exposed but now have been removed will not be reused in the future (apart from the exceptional 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.
Interaction Model Relationships
This section define some of the system behaviors and their constraints as they apply to interactions specified in the Interaction Model.
1. Subscription
  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.
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 (bindings) 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.

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.

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

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

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

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

Revision History
The global ClusterRevision attribute value SHALL be the highest revision number in the table below.
Revision
Description
1
Initial Release
Classification

Hierarchy
Role
Context
PICS Code
Base
Utility
Endpoint
DESC
Cluster Identifiers

Identifier
Name
0x001D
Descriptor

Attributes

Id	Name	Type	Quality	Constraint	Default	Access	Conforma nce
0x0000	DeviceTyp eList	list[Device TypeStruct ]	F	min 1	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[endpoi nt-no]			empty	R V	M

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.
See the System Model specification for endpoint composition.
ServerList Attribute

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

This attribute SHALL list each cluster ID for the client clusters present on the endpoint instance.
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.

Data Types

9.5.5.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.
Table 74. DeviceTypeStruct

ID
Name
Type
Quality
Constraint
Access
Conformanc e
0
DeviceType
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 definition 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.

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 application 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 endpoints 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_EXHAUSTED, 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 number prescribed by the device type SHALL be supported for each fabric the node supports, unless the device type specifies otherwise. The total number of bindings supported SHALL be the sum of the requirements for each endpoint, unless the device types involved specify otherwise.
- For example, if a node supports 6 fabrics and a device type specifies at least 3 bindings must be supported, the node would need to support at least 18 bindings and ensure that at least 3 were available to every fabric.
  A binding SHALL only be created with the Cluster field if the indicated client cluster exists on the endpoint.
  When a binding is removed, the client endpoint SHALL end the binding relationship with the removed binding target.
Revision History
The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision
Description
1
Initial Release
Classification

Hierarchy
Role
Scope
PICS Code
Base
Utility
Endpoint
BIND
Cluster Identifiers

Identifier
Name
0x001E
Binding

Attributes

Id	Name	Type	Quality	Constraint	Access	Default	Conforma nce
0x0000	Binding	list[TargetS truct]	N	desc	RW F VM	[]	M

9.6.5.1. Binding Attribute

Endpoint Device Type

Node

Group

Cluster

Endpoint

Example Description

Light Switch Client

omit

1234

omit

switch endpoint sends On/Off, Level & Color Control cluster commands to group 1234

Temp Sensor Client

456789

omit

1026

temperature sensor client subscribes to node 456789

endpoint 3 temperature measurement

cluster

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

Data Types

9.6.6.1. TargetStruct

Access Quality: Fabric Scoped
ID
Name
Type
Quality
Constraint
Access
Default
Conforman ce
1
Node
node-id

all

Endpoint
2
Group
group-id

all

!Endpoint
Access Quality: Fabric Scoped
3
Endpoint
endpoint- no

all

!Group
4
Cluster
cluster-id

all

O

Node Field

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

Group Field

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

Endpoint Field

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

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.
1. Revision History
  The global ClusterRevision attribute value SHALL be the highest revision number in the table below.
  
  Revision
  Description
  1
  Initial Release
2. Classification
  
  Hierarchy
  Role
  Context
  PICS Code
  Base
  Utility
  Endpoint
  LABEL
3. Cluster Identifiers
  This is a base cluster with no cluster ID. Please see derived clusters for more information.
  Identifier
  Name
  n/a
  Label
4. Attributes
  
  Id
  Name
  Type
  Constraint
  Quality
  Default
  Access
  Conforma nce
  0x0000
  LabelList
  list[LabelSt ruct]
  derived
  derived
  empty
  derived
  M
  
  9.7.4.1. LabelList Attribute
  
  This is a list of string tuples. Each entry is a LabelStruct.
5. Data Types
  
  9.7.5.1. LabelStruct
  
  This is a string tuple with strings that are user defined.
  
  Id
  Name
  Type
  Constraint
  Quality
  Default
  Access
  Conforma nce
  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", "direction".
  
  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"
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 "orientation":"down". Using such indication, the user interface of a Node controlling this luminaire knows which of the endpoints is which of the lights.
1. Revision History
  The global ClusterRevision attribute value SHALL be the highest revision number in the table below.
  
  Revision
  Description
  1
  Initial Release
2. Classification
  
  Hierarchy
  Role
  Context
  PICS Code
  Derived from Label
  Utility
  Endpoint
  FLABEL
3. Cluster Identifiers
  
  Identifier
  Name
  0x0040
  Fixed Label
4. Attributes
  
  Name
  Constraint
  Quality
  Default
  Access
  Conformance
  LabelList
  
  N
  empty
  R V
  M
User Label Cluster
This cluster provides a feature to tag an endpoint with zero or more labels.
1. Revision History
  The global ClusterRevision attribute value SHALL be the highest revision number in the table below.
  
  Revision
  Description
  1
  Initial Release
2. Classification
  
  Hierarchy
  Role
  Context
  PICS Code
  Derived from Label
  Utility
  Endpoint
  ULABEL
3. Cluster Identifiers
  
  Identifier
  Name
  0x0041
  User Label
4. Attributes
  
  Name
  Constraint
  Quality
  Default
  Access
  Conformance
  LabelList
  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.

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

Revision History
- The global ClusterRevision attribute value SHALL be the highest revision number in the table below.
  
  Rev isio n
  Description
  1
  Initial Release
Classification

Hierarchy
Role
Context
PICS Code
Base
Utility
Node
ACL
Cluster Identifiers
Ident ifier
Name
0x001 F
AccessControl
Features
This Cluster has no Features.

Attributes

Table 75. Access Control Cluster Server Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Conforma nce
0x0000	ACL	list[Access ControlEnt ryStruct]	desc		desc	RW F A	M
0x0001	Extension	list[Access ControlExt ensionStru ct]	desc		desc	RW F A	O
0x0002	SubjectsPe rAccessCon trolEntry	uint16	min 4	F	4	R V	M
0x0003	TargetsPer AccessCont rolEntry	uint16	min 3	F	3	R V	M
0x0004	AccessCont rolEntriesP erFabric	uint16	min 3	F	3	R V	M

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

// entire node
// implicit entry only; does not explicitly exist!
// not fabric-specific
Access Control Cluster: { ACL: [
0: {
FabricIndex: 0, Privilege: Administer, AuthMode: PASE, Subjects: [],
Targets: []
}
],
Extension: []
}
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 Control 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 appropriate. 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 Administrator 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, particularly 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 Endpoints, 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.

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.

Table 76. AccessControlEntryStruct

Access Quality: Fabric Scoped
ID	Name	Type	Constraint	Quality	Access	Default	Conforman ce
1	Privilege	AccessCont rolEntryPri vilegeEnu m	all		S		M
2	AuthMode	AccessCont rolEntryAu thModeEn um	all		S		M
3	Subjects	list[Subject ID]	max SubjectsPe rAccessCon trolEntry	X	S		M
4	Targets	list[TargetS truct]	max TargetsPer AccessCont rolEntry	X	S		M

Privilege

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

Table 77. PrivilegeEnum

Value	Name	Description	Implicitly Granted Privileges
1	View	Can read and observe all (except Access Control Cluster and as seen by a non-Proxy)	-
2	Proxy View	Can read and observe all (as seen by a Proxy)	View
3	Operate	View privileges, and can perform the primary function of this Node (except Access Control Cluster)	View

Value	Name	Description	Implicitly Granted Privileges
4	Manage	Operate privileges, and can modify persistent configuration of this Node (except Access Control Cluster)	Operate, View
5	Administer	Manage privileges, and can observe and modify the Access Control Cluster	Manage, Operate, Proxy View, View

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 privilege 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 Control 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 configuration, 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

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

Table 78. AuthModeEnum

Value	Name	Description
1	PASE	Passcode authenticated session
2	CASE	Certificate authenticated session
3	Group	Group authenticated session

Subjects

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:

Table 79. Subject Semantics

AuthMode	Subject
PASE	Lower 16-bits → Passcode ID Upper 48-bits → all bits clear

AuthMode	Subject
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 AuthMode is PASE.

The PASE AuthMode is reserved for future use (see Section 6.6.2.8, “Bootstrapping of the Access Control 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)

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: 0xFFFF_FFFD_ABCD_0001) will not be granted access.

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

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.

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

Targets

The targets field SHALL specify a list of TargetStruct, 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.

Table 80. TargetStruct

ID	Name	Type	Constraint	Quality	Access	Default	Conforma nce
0	Cluster	cluster-id	all	X			M
1	Endpoint	endpoint- no	all	X			M
2	DeviceTyp e	devtype-id	all	X			M

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:

Table 81. Target Semantics

Cluster	Endpoint	DeviceType	Target
			Invalid
		D	All clusters on any endpoint with Descriptor containing device type D
	E		All clusters on only endpoint E
	E	D	Invalid
C			Only cluster C on all endpoints
C		D	Only cluster C on any endpoint with Descriptor 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 cluster 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 Endpoint 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 privileges 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 endpoints 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 privileges to any other cluster on Endpoint 1, or to any other cluster (including the On/Off cluster) on any other endpoint.

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.

Table 82. AccessControlExtensionStruct

Access Quality: Fabric Scoped
ID
Name
Type
Constraint
Quality
Access
Default
Conforman ce
1
Data
octstr
max 128

S

M

Data

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 profile-specific tag encoded in fully-qualified form.
Administrators MAY iterate over this list of elements, and interpret selected elements at their discretion. The content of each element is not specified, but MAY be coordinated among manufacturers 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 encoding specific entry fields and sub-fields (such as lists) in specific order and specific format (e.g. TLV).
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 concern for a given implementation, it is recommended to only use the minimum value required and avoid reporting a higher value than the required minimum.
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 concern for a given implementation, it is recommended to only use the minimum value required and avoid reporting a higher value than the required minimum.
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 concern for a given implementation, it is recommended to only use the minimum value required and avoid reporting a higher value than the required minimum.

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
CONSTRAINT_ERROR:
- Privilege enum value invalid
- AuthMode enum value invalid
- AuthMode is PASE (reserved for future use)
- Subjects element invalid
  - e.g. illegal CAT with CASE AuthMode
- Targets element invalid
  - e.g. no field present
  - e.g. both Endpoint and DeviceType fields present
- Field combinations invalid
  - e.g. Administer Privilege with Group AuthMode
    
    For example, the following Access Control Extension conditions will result in an error of CONSTRAINT_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.

Events

This cluster SHALL support these events:

Id	Name	Priority	Access	Conformance
0	AccessControlEntr yChanged	INFO	S A	M
1	AccessControlExte nsionChanged	INFO	S A	M

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 Added.
Each changed entry SHALL generate an event with ChangeType Changed.

Each removed entry SHALL generate an event with ChangeType Removed.

Access Quality: Fabric-Sensitive
Id	Field	Type	Constraint	Quality	Default	Conformanc e
1	AdminNode ID	node-id	desc	X		M
2	AdminPassc odeID	uint16	desc	X		M
3	ChangeType	ChangeType Enum	all			M
4	LatestValue	AccessContr olEntryStruc t	all	X		M

AdminNodeID

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

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

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

The type of change as appropriate.

LatestValue

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.

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 Added.
- Each changed extension SHALL generate an event with ChangeType Changed.
- Each removed extension SHALL generate an event with ChangeType Removed.

Access Quality: Fabric-Sensitive
Id	Field	Type	Constraint	Quality	Default	Conformanc e
1	AdminNode ID	node-id	desc	X		M
2	AdminPassc odeID	uint16	desc	X		M
3	ChangeType	ChangeType Enum	all			M
4	LatestValue	AccessContr olExtensionS truct	all	X		M

AdminNodeID

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

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

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

The type of change as appropriate.

LatestValue

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.

Data Types

9.10.8.1. ChangeTypeEnum

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

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 members 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 endpoints.
Note that there is a risk that multiple clients allocate the same group identifier for their own purpose. This likely leads to undesired behavior. For this reason, a client SHOULD discover the uniqueness 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.

Bridge for non-Matter devices

Introduction

A Bridge serves to allow the use of non-Matter IoT devices (e.g. devices on a Zigbee or Z-Wave network, 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 Fabric

Matter App 3

Matter App 2

Matter App 1

Bridged

Device 3

Bridged

Device 2

Bridged

Device 1

Bridge

Manufacturer App

Non-Matter Transport Layer ( e.g. Zigbee; Z-Wave; proprietary; etc.)

See and control all of the Bridged Devices and Matter Devices using Matter protocol

Manufacturer -

defined interface


	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.

Exposing functionality and metadata of Bridged Devices
After Commissioning, the Bridge SHALL expose (at least) one Node to the Fabric. The device implementing the Bridge MAY have more than one Node. This, however, is orthogonal to the bridging concept and will not be discussed further here.
- On this Node, the Bridge SHALL expose a set of endpoints representing the various Bridged Devices on the non-Matter side of the Bridge.
- Additionally, it SHALL expose an endpoint with the device type Aggregator which has a Descriptor cluster with a PartsList attribute containing all the endpoints representing those Bridged Devices. See Endpoint Composition for the concept of hierarchical composition.
- 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 particular Bridged Device, such as its device type(s).
  
  Descriptor cluster: DeviceTypeList: Root Node PartsList: EP 1, 11,12,13,14,15,16
  Basic Information cluster:
  ..
  EP 0
  Descriptor cluster: DeviceTypeList: Aggregator PartsList: EP 11,12,13,14,15,16
  EP 1
  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:
  Descriptor cluster:
  DeviceTypeList: Dimmable Light, Bridged Node
  Bridge Device Basic Information cluster:
  NodeLabel: "hallway"
  EP 13
  Descriptor cluster:
  DeviceTypeList: Generic Switch, Bridged Node
  Bridge Device Basic Information cluster:
  NodeLabel: "kitchen entrance"
  EP 16
  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
  
  Descriptor cluster: DeviceTypeList: Aggregator PartsList: EP 14,15,16
  Fixed Label cluster:
  LabelList: [[" bridge","Z-Wave"]]
  EP 2
  Descriptor cluster:
  DeviceTypeList: Generic Switch, Bridged Node
  Bridge Device Basic Information cluster:
  NodeLabel: "living room entrance"
  EP 14
  Descriptor cluster: EP 15
  DeviceTypeList: Temperature Sensor, Bridged Node
  Bridge Device Basic Information cluster:
  NodeLabel: "outdoor temperature"
  Descriptor cluster:
  DeviceTypeList: Generic Switch, Bridged Node
  Bridge Device Basic Information cluster:
  NodeLabel: "kitchen entrance"
  Z-Wave devices
  EP 16
  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
  For each Bridged Device, the Bridge SHALL expose the clusters required for a device of the indicated 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.
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 discovering 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 Matter 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 example, 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.
Configuration of Bridged Devices
For configuration of the discovered Bridged Devices, two basic archetypes are described in the following 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.
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
Kitchen
Ceiling
Cooking island
Living room
Uplighter
Downlighter
Reading light
Switch 1 ON
Switch 2 OFF
Temp: 20 °C

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
New features for Bridged Devices
Bridged Devices can have their software updated independently of the Bridge, through Bridge Manufacturer-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 endpoint on the Bridge’s Node contains a Descriptor cluster that contains attributes for the device types, endpoints (PartsList) and supported clusters. Nodes that wish to be notified of such changes SHOULD monitor changes of these attributes.
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
  Aggregator 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 Endpoint allocation.
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- concept) 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.
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.
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.
Software update (OTA)
The Bridge is a Matter device and its Matter-related functionality MAY be updated using the mechanism described in Section 11.20, “Over-the-Air (OTA) Software Update”.
The Bridged Devices, on the other hand, are not native Matter devices, do not have a Product ID, and are not listed in the Distributed Compliance Ledger. They are typically updated using a mechanism 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.
Best practices for Bridge Manufacturers
This section summarizes (in order of priority) the process to determine which non-Matter devices the Bridge exposes to the Fabric.
1. Choice of supported device types
  - A Manufacturer MAY choose which of the Matter device types they can or want to support in the Bridge. After implementation of support for bridging of those device types, they SHALL certify the Bridge for those device types.
  - By default, a Bridge SHOULD expose to the Fabric all its connected non-Matter devices which can be mapped to a Matter device type for which that Bridge is certified.
    E.g., if a Bridge is certified for Matter light bulbs, it SHOULD NOT hide any light bulb on the non-Matter side from the Fabric by default (some situations where the Bridge MAY deviate from this recommendation are in the following text).
  - Given the wide variety of device types on a wide variety of standards, there may be device types on the non-Matter side that do not have a corresponding Matter device type. Such devices cannot be bridged to a Matter device type. The Manufacturer MAY choose to not expose such devices with the Bridge or MAY expose them with a manufacturer-specific device type and/or manufacturer-specific clusters.
2. Compatibility issues
  - For the device types for which a Bridge is certified, a Bridge Manufacturer MAY decide to not expose certain devices based on any reason, including compatibility and interoperability reasons, or to expose them in a 'best-effort' manner as needed.
    - The Bridge Manufacturer may choose to not expose a device that does not support certain 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 Fabric only Bridged Devices of device types which support those particular control functions or features which are required.
    - The Bridge Manufacturer may also choose to map or emulate such features which are not available in the Bridged Device; example: for a bridged colored light connected via a protocol which does not support scenes, the Bridge could emulate the scene function by storing the scenes in the Bridge and sending corresponding brightness and color commands to the light when a Scene Recall command is received from a Matter Node.
3. User choice
  - A Bridge MAY make it possible (e.g., through a Bridge Manufacturer’s app) for its users to further restrict which devices are exposed to the Fabric.
For example, a user may decide to prevent exposure to the Fabric of certain Devices Types, such as all occupancy sensors, or of only certain devices of a certain device type, such as only their bedroom occupancy sensor.
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.

Bridged Device Basic Information Cluster

Scope & Purpose
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 name.
  This cluster SHALL be exposed by a Bridge on the Endpoint representing each Bridged Device. When the functionality of a Bridged Device is represented using a set of Endpoints, this cluster SHALL only be exposed on the Endpoint which is at the top of the hierarchy for the functionality of that Bridged Device.
  This cluster SHALL NOT be used on an endpoint that is not in the Descriptor cluster PartsList of an endpoint with an Aggregator device type.
  This cluster has been derived from the Basic Information Cluster, and provides generic information about the Bridged Device. Not all of the attributes in the Basic Information Cluster are relevant for a Bridged Device (e.g. ProductID since it is not a Matter Device). For other attributes, the information 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.
Revision History
- The global ClusterRevision attribute value SHALL be the highest revision number in the table below.
  
  Revision
  Description
  1
  Initial Release
Classification

Hierarchy
Role
Context
PICS Code
Derived from Basic Information
Utility
Endpoint
BRBINFO
Cluster Identifiers

Identifier
Name
0x0039
Bridged Device Basic Information
Features
This Cluster has no Features.

Attributes

Name	Conformance
DataModelRevision	X
VendorName	O
VendorID	O
ProductName	O
ProductID	X
NodeLabel	O
Location	X
HardwareVersion	O
HardwareVersionString	O
SoftwareVersion	O
SoftwareVersionString	O
ManufacturingDate	O
PartNumber	O
ProductURL	O
ProductLabel	O
SerialNumber	O
LocalConfigDisabled	X
Reachable	M
UniqueID	O
CapabilityMinima	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 VendorID) 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.

Events
This cluster SHALL support these events:

Name
Conformance
StartUp
O
ShutDown
O
Leave
O
ReachableChanged
M

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

Actions Cluster

Scope & Purpose
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 (example: recall a scene for a group of lights by its name)
- commands to trigger such actions
- events to receive feedback on the state of such actions.
  
  The information on grouping and available actions is typically provided by the user or Bridge manufacturer 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.
Revision History
The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision
Description
1
Initial Release
Classification

Hierarchy
Role
Context
PICS Code
Base
Application
Node
ACT
Cluster Identifiers

Identifier
Name
0x0025
Actions
Features
This cluster has no features defined.

Attributes

ID	Name	Type	Constraint	Quality	Default	Access	Conforma nce
0x0000	ActionList	list[ActionS truct]	max 256		empty	R V	M
0x0001	EndpointLi sts	list[Endpoi ntListStruc t]	max 256		empty	R V	M
0x0002	SetupURL	string	max 512		empty	R V	O

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

The EndpointLists attribute holds the list of endpoint lists. Each entry SHALL have an unique EndpointListID.
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 provides.
  - Example: SetupURL could take the value of example://Actions or https://www.example.com/ Matter/bridgev1/Actions for this generic case (access generic info how to use actions provided by this cluster).
- When used with a suffix of "/?a=" and the decimal value of ActionID for one of the actions, it SHALL provide information about that particular action. This could be a deeplink to manufacturer-app/website (associated somehow to the server node) with the information/edit- screen for this action so that the user can view and update details of the action, e.g. edit the scene, or change the wake-up experience time period.
  - Example of SetupURL with suffix added: example://Actions/?a=12345 or https://www.example.com/Matter/bridgev1/Actions/?a=12345 for linking to specific info/editing of the action with ActionID 0x3039.

Commands

ID	Name	Direction	Response	Access	Conformance
0x00	InstantAction	client ⇒ server	Y	O	desc
0x01	InstantAction WithTransition	client ⇒ server	Y	O	desc
0x02	StartAction	client ⇒ server	Y	O	desc
0x03	StartActionWit hDuration	client ⇒ server	Y	O	desc
0x04	StopAction	client ⇒ server	Y	O	desc
0x05	PauseAction	client ⇒ server	Y	O	desc
0x06	PauseActionWi thDuration	client ⇒ server	Y	O	desc
0x07	ResumeAction	client ⇒ server	Y	O	desc
0x08	EnableAction	client ⇒ server	Y	O	desc
0x09	EnableActionW ithDuration	client ⇒ server	Y	O	desc
0x0a	DisableAction	client ⇒ server	Y	O	desc
0x0b	DisableAction WithDuration	client ⇒ server	Y	O	desc

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

Some general requirements and data fields for all the commands:

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

ID
Name
Type
Constraint
Quality
Default
Conformanc e
0
ActionID
uint16
all

M
1
InvokeID
uint32
all

O
2
Duration
uint32
all

MS
M

The Duration data field SHALL indicate the requested duration in seconds.

This command disables a certain action or automation, and SHALL change the action’s state to Disabled. 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.

Events
This cluster SHALL support these events:

Id
Name
Priority
Access
Conformance
0
StateChanged
INFO
V
M
1
ActionFailed
INFO
V
M

Data Types

ActionStruct

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

ID	Name	Type	Constraint	Quality	Access	Default	Conforma nce
0	ActionID	uint16	all		R		M
1	Name	string	max 32 [128]		R		M
2	Type	ActionType Enum	all		R		M
3	EndpointLi stID	uint16	all		R		M
4	Supported Commands	map16	0 to 0x0fff		R		M
5	State	ActionState Enum	all		R		M

The ActionID data field SHALL provide an unique identifier used to identify an action.

The Name data field SHALL indicate the name (as assigned by the user or automatically by the server) associated with this action. This can be used for identifying the action to the user by the client. Example: "my colorful scene".

The Type data field SHALL indicate the type of action. The value of Type of an action, along with its SupportedCommands 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.

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

The SupportedCommands data field is a bitmap which SHALL be used to indicate which of the cluster’s commands are supported for this particular action, with a bit set to 1 for each supported command according to the table below. Other bits SHALL be set to 0.

Note - the bit allocation of this table SHALL follow the ID’s of the Commands of this cluster.

bit	Command supported
0	InstantAction
1	InstantActionWithTransition
2	StartAction
3	StartActionWithDuration
4	StopAction
5	PauseAction
6	PauseActionWithDuration
7	ResumeAction
8	EnableAction
9	EnableActionWithDuration
10	DisableAction
11	DisableActionWithDuration

The State data field SHALL indicate the current state of this action.

ActionTypeEnum

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

Value	Name	Description	Conformance
0	other	use this only when none of the other values applies	M
1	scene	bring the endpoints into a certain state	M
2	sequence	a sequence of states with a certain time pattern	M

Value	Name	Description	Conformance
3	automation	control an automation (e.g. motion sensor controlling 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 notification	M

Type=scene can be used to set a static state of the associated endpoints (typically using InstantAction or InstantActionWithTransition), or to bring these endpoints into a more dynamic state (typically using StartAction), 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 trigger such actions.

Example: see examples 1 and 2.

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

Example: see example 4.

Type=automation 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.

Type=exception 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.

Type=notification 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.

Type=alarm is similar 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.

ActionStateEnum

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

Value
Name
Description
Conformance
0
Inactive
The action is not active
M
Value
Name
Description
Conformance
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 SupportedCommands.
ActionErrorEnum

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

Value
Name
Description
Conformance
0
unknown
other reason not listed in the row(s) below
M
1
interrupted
The action was interrupted by another command or interaction
M
EndpointListStruct

The EndpointListStruct 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
Access
Default
Conforma nce
0
EndpointLi stID
uint16
all

R

M
1
Name
string
max 32
[128]

R

M
2
Type
EndpointLi stTypeEnu m
all

R

M
3
Endpoints
list[endpoi nt-no]
max 256

R

M

The EndPointListID data field SHALL provide an unique identifier used to identify the endpoint list.

The Name data field SHALL indicate the name (as assigned by the user or automatically by the server) associated 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".
The Type data field SHALL indicate the type of endpoint list, see EndpointListTypeEnum. The EndPoints data field SHALL provide a list of endpoint numbers.

EndpointListTypeEnum

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

Value	Name	Description	Conformance
0	other	another group of endpoints	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.

"Room" is used for the situation where an endpoint can only be part of one such rooms (e.g. physical mapping). 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" 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.

The "other" 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.

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

Proxy Architecture

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

Proxy Subscriptions

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.
Upstream/Downstream Subscription Mechanics

Upstream and downstream subscriptions have the following properties:
- Both subscriptions are independent, but weakly linked.
  - Data is received on the client side, stored on the server side, and used to generate a different set of reports to downstream client(s).
- It is data that is being proxied, not the actual subscription messages themselves.
- The termination of a downstream subscription will automatically result in an amendment of the upstream subscription to remove the relevant paths that were in the downstream, with a
  complete termination of the upstream subscription if there was only 1 downstream subscriber present.
- The disappearance of an upstream subscription will not automatically cancel the downstream subscription.
  - Upstream subscriptions MAY disappear due to network connectivity issues. If an upstream sync report is not received, the proxy SHALL attempt once to re-subscribe to the upstream source; if that re-subscription attempt fails, the proxy SHALL terminate any associated downstream subscriptions.
  - If an upstream subscription is positively terminated by the source as a whole, that will result in a similar termination of the downstream subscription.
- In addition to forwarding status codes embedded in the ReportData from the source, the proxy will convey a special 'NO_UPSTREAM_SUBSCRIPTION' IM status code to the downstream client if it has not established a subscription to the source.
  The diagram below gives a sample sequence show-casing the two subscriptions:
  
  Figure 57. Upstream/Downstream subscription sequences
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_SUBSCRIPTION' status code. This conveys effectively the same information as the sync message would had the client directly subscribed to the source.
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.

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.
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.
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
Constraints
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 multiple fabrics. To make this possible, a proxy SHOULD when possible, be commissioned into all fabrics 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 subscribe 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.
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.
Security & Privacy
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.

Parameters and Constants

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

Table 83. Glossary of constants

Constant Name

Description

Default Value

PROXY_SCAN_RESPONSE_JITTER

The maximum amount of time to randomly wait before sending a Proxy Discover Response Command message.

1000

milliseconds

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

milliseconds

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”.
Id
Name
Direction
Response
Access
Conformance
0x00
Proxy Discover Request
Client ⇒ Server
N
O
M
0x01
Proxy Discover Response
Server ⇒ Client
N

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

Id
Field
Type
Constraint
Quality
Default
Conforman ce
0
SourceNode Id
node-id
all

M
1
NumHopsT oSource
uint16
desc

M
2
AvailableCa pacity
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 corresponding Proxy Discover Request Command message.

NumHopsToSource

If the proxy currently subscribes to the source (either directly or indirectly), this indicates the number 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.
Proxy Configuration Cluster
This cluster provides a means for a proxy-capable device to be told the set of Nodes it SHALL proxy.
Table 84. Cluster Server Attributes

Id
Name
Type
Range
Quality
Access
Default
Conforma nce
0
Configura tionList
list[Config urationStr uct]
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.
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”.

Revision History
- The global ClusterRevision attribute value SHALL be the highest revision number in the table below.
  
  Rev isio n
  Description
  1
  Initial Release
Classification

Hierarchy
Role
Context
PICS Code
Base
Utility
Node
PXVALID
Cluster Identifiers

Ident ifier
Name
0x004
4
ValidProxies
Definitions

9.15.15.4.1. ValidProxyStruct

Encapsulates the Node ID of a Valid Proxy.
Quality: Fabric-Scoped
Id
Name
Type
Constraint
Quality
Access
Default
Conforma nce
1
NodeID
node-idx
all

RW

M
Server Attributes
Table 85. Cluster Server Attributes

Id
Name
Type
Range
Quality
Access
Default
Conforma nce
0
ValidProx yList
list[ValidPr oxyStruct]
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.
Commands

Id	Name	Direction	Response	Access	Conformance
0x00	Get Valid Proxies Request	Client ⇒ Server	Get Valid Proxies 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
Conforman ce
0
ProxyNodeI dList
list[node-id]

M
ProxyNodeList

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

Hierarchy	Role	Context	PICS Code
Derived from Label	Utility	Endpoint	FLABEL

Quality: Fabric-Scoped
Id	Name	Type	Constraint	Quality	Access	Default	Conforma nce
1	ProxyAllN odes	bool	desc		RW	false	M
2	SourceList	list[node- id]	desc		RW	empty	M

Id	Name	Type	Range	Quality	Access	Default	Conforma nce
0	Configura tionList	list[Config urationStr uct]	all	N	RW	empty	M

Revision	Description
1	Initial Release of this specification

Revision	Description
1	Initial Release

Identifier	Name
0x001D	Descriptor

Revision	Description
1	Initial Release

Cluster Library Reference library of cluster specifications.

Device Library Reference library of devices type definitions.

Persistency

DeviceTypeList Attribute

ServerList Attribute

ClientList Attribute

PartsList Attribute

9.5.5.1. DeviceTypeStruct

NOTE

9.6.5.1. Binding Attribute

9.6.6.1. TargetStruct

9.7.4.1. LabelList Attribute

9.7.5.1. LabelStruct

9.9.4.1. LabelList

Default Value

Administration Guidelines

ACL Attribute

Extension Attribute

SubjectsPerAccessControlEntry Attribute

TargetsPerAccessControlEntry Attribute

AccessControlEntriesPerFabric Attribute

AccessControlEntryChanged Event

AccessControlExtensionChanged Event

9.10.8.1. ChangeTypeEnum

NOTE

Topology or logical grouping

Native Matter functionality in Bridge

Information about Bridged Devices

Clusters for Bridged Device functionality (device types)

Sending commands from a Matter controller to a Bridged Device

Receiving status/events/commands from a Bridged Device

9.13.7.1. ReachableChanged Event

ActionList attribute

EndpointLists attribute

SetupURL attribute

InstantAction Command

InstantActionWithTransition Command

StartAction Command

StartActionWithDuration Command

StopAction Command

PauseAction Command

PauseActionWithDuration Command

ResumeAction Command

EnableAction Command

EnableActionWithDuration Command

DisableAction Command

DisableActionWithDuration Command

StateChanged Event

ActionFailed Event

ActionStruct

ActionTypeEnum

ActionStateEnum

ActionErrorEnum

EndpointListStruct

EndpointListTypeEnum

Example 1: Scene recall

Example 2: Set dynamic light effect

Example 3: Pause sensor automation

Example 4: Wake-up routine

Example 5: Scheduled scene recall

Example 6: Alarm system

Overview

Upstream/Downstream Subscription Mechanics