Devices in Matter have a well-defined data model(DM), which is a hierarchical modeling of a Device's features. At the toplevel of this hierarchy there is a Device.
Devices and Endpoints
All Devices, including smartphones and home assistants, are composed ofNodes1. A Node is a unique identifiable and addressable resource in anetwork that a user can perceive as functionally whole. Network communication inMatter originates and terminates at a Node.
Nodes are a collection of Endpoints. Each Endpoint encloses a feature set.For instance, an Endpoint might relate to a lighting functionality, whileanother relates to motion detection, and another deals with utilities suchas Device OTA.
Node roles
A Node role is a set of related behaviors. Each Node may have one or moreroles. Node roles include:
- Commissioner: A Node that performsCommissioning.
- Controller: A Node that can control one or more Nodes.Examples include the Google Home app (GHA),Google Assistant, and the Google Nest Hub (2nd gen). Somedevice types, such as the On/Off LightSwitch, have the Controllerrole.
- Controlee: A Node that can be controlled by one or moreNodes. Most device types can be a Controlee, except for some device typeswhich have the Controller role, such as the On/Off LightSwitch. The On/Off LightSwitch can only be a Controller. It cannot be a Controlee.
- OTA Provider: A Node that can provide OTA software updates.
- OTA Requestor: A Node that can request OTA softwareupdates.
Clusters
Within an Endpoint a Node has one or more Clusters. These are anotherstep in the Device hierarchy, as they group specific functionality such as aon/off cluster on a smart plug, or a level control cluster on a dimmablelight Endpoint.
A Node may also have several Endpoints, each creating an instance of the samefunctionality. For example, a light fixture may expose independent control ofindividual lights or a power strip may expose control of individual sockets.
Attributes
At the last level we'll find Attributes, which are states held by the node,such as the current level attribute of a level control cluster. Attributesmay be defined as different data types such as uint8, strings or arrays.
Commands
Besides Attributes, Clusters also have Commands, which are actions thatmay be performed. They are the equivalent in Matter's DM ofa remote procedure call. Commands are verb-like, such as lock door on aDoor Lock cluster. Commands may generate responses and results; inMatter, such responses are also defined as Commands, goingin the reverse direction.
Events
Lastly, Clusters may also have Events, which can be thought of as a recordof past state transitions. While Attributes represent the current states,events are a journal of the past, and include a monotonically increasingcounter, a timestamp and a priority.They enable capturing state transitions, as well as data modeling that isnot readily achieved with attributes.
The Endpoint 0 is reserved for the Utility Clusters. Utility Clustersare specific Clusters that enclose servicing functionality on an Endpoint, suchas discovery, addressing, diagnostics and software update. On the other hand,the Application Clusters support primary actions such as on/off ortemperature measurement.
Device Types
Altogether, which Cluster combinations should be included as a devicemanufacturer plans a new Device?
The Matter specification requires that the device implementor extend one or more Device Types. A Device Type is a collection ofmandatory and optional Clusters that define the top-level attributes of aphysical Device, such as Dimmable Light, Door Lock, or Video Player.
The Device Types are not specified by the Matterspecification main document, but by an accompanying document: the DeviceLibrary. Similarly, all Application Clusters are defined in the ApplicationCluster Library. These three documents can be found on theConnectivity Standards Alliance (Alliance) members website.
Each Endpoint implementing a Device Type must implement the mandatory Clustersthat define that Device Type. In addition to the mandatory Clusters, theEndpoint may implement additional Clusters, including one or more of the DeviceType's optional Clusters, or even Clusters that aren't part of the Device Type.
Clients and Servers
Clusters might be either a Client Cluster or a Server Cluster. While aServer is stateful and holds Attributes, Events and Commands, a Client isstateless and its responsibility is to initiate Interactions with aremote Server Cluster, thus performing:
- reads from and writes to its remote Attributes.
- reads of its remote Events.
- invocation of its remote Commands.
While the DM is hierarchical within a Node, the relationship between Nodes isnot. Nodes in Matter do not have verticalcontroller/peripheral or leader/follower relationships. On the contrary, therelationship is horizontal: Any Cluster may be either Server or Client.Thus a Node may be both Server and Client with regards to different Clustersand functionalities.
For instance, we may have two table lamps: Node A and Node B. Both nodesimplement an On/Off Light Device Type. This Device Type includes an On/OffServer Cluster that controls their respective physical light outputs.
But, as typical table lamps do, our physical devices will also include anOn/Off Light Switch Device Type for their local on/off switches. This DeviceType must implement an On/Off Client Cluster so it may control the ServerClusters.
In this sample, the On/Off Client Cluster on Node A is changing the attributesof the On/Off Server Cluster on Node A and Node B, while the Node B's ClientCluster is only changing the Server Cluster on Node B itself.
In the next section we'll detail how Client and Server Clusters interact: theInteraction Model.
Descriptor Cluster
As the name implies, the Descriptor Cluster Server provides introspectioninformation. It describes the Endpoint enumerating its:
- Server Clusters.
- Client Clusters.
- Device Types.
- Additional Endpoints, known as Parts.
Every Device Type requires the implementation of Descriptor Clusters. The RootDevice Type is defined on Endpoint 0. Reading its Descriptor Cluster willprovide the client the visibility to traverse the full tree of availableEndpoints and perform applicable operations.
The Commissioner or Controlling device such as a phone or hub can use theinformation found on the Descriptor Cluster to model the Device (light, switch,pump, thermostat), and specific features implemented by that particular instanceof the Device, showing the correct UI to the user.
Server Clusters
The ServerList Attribute lists the Cluster Servers in the Endpoint.
Client Clusters
The ClientList Attribute lists the Cluster Clients in the Endpoint.
Device Type List
The DeviceTypeList Attribute is a list of Device Types supported by theEndpoint, along with its respective revisions. It must contain at least oneDevice Type.
Parts List
The PartsList contains the list of Endpoints used for implementing this DeviceType.
The PartsList of Endpoint 0 (Root Node) contains all the Endpoints of thedevice apart from itself (Endpoint 0).
The PartsList of other Endpoints will usually be empty. For example, aTemperature Sensor mandates a Temperature Measurement Server Cluster and nothingelse.
Other device types might be composed in a tree structure of more than one DeviceType instance. For example, a Video Player Device type can be composed of TV,Video Player, Speaker and different Content App Device Types, each on adifferent Endpoint.
The Matter specification determines that a Device mayhave multiple Nodes.For example, smartphones may have multiple apps, each app being adifferent Node. For the purposes of this primer, all Devices will containa single Node. It's expected that most physical devices will follow thispattern.↩
