This section introduces the core concepts of Matter that every developer should understand before building, testing, or deploying devices. Here you’ll find the fundamentals: What Matter is, how its data model works, what transactions mean, and how networks like Thread and OTBR fit into the ecosystem.

Matter Basics

What is Matter?

Matter is an open standard for the smart home, developed by the Connectivity Standards Alliance (CSA) with the participation of Apple, Google, Amazon, Samsung, and many other manufacturers. Its goal is to solve the issue of poor compatibility between devices by acting as a “common language” that allows devices to connect and work locally and securely, regardless of brand or platform.

Learn more on Wikipedia

Highlight of Matter

• Multi-ecosystem support: A Matter device can work with Apple Home, Google Home, Amazon Alexa, or Samsung SmartThings.
• Local control: Runs on Thread and Wi-Fi, ensuring devices continue to function even without internet access.
• Simple setup: Users just scan a QR code or enter a setup code instead of installing multiple apps.
• Built-in security: All Matter devices are certified with high security standards, using end-to-end encryption.
• Royalty-free: As an open standard, Matter makes it easier for manufacturers to adopt without expensive licensing fees.

How does Matter work?

Matter relies on a few core technologies:

• Commissioning (Initial setup):

  New devices are added to a Matter network using Bluetooth Low Energy (BLE) for quick discovery and pairing.

• Networking:

  • Wi-Fi: Provides high bandwidth, suitable for devices like cameras or speakers.
  • Thread: A low-power mesh network, ideal for sensors, switches, and light bulbs.

• Data Model:

  Every Matter device follows the same data model:

  Node → Endpoint → Cluster → Attribute / Command / Event

  Ensuring that different controllers can understand and interact with devices consistently.

  *diagram: Node → Endpoint → Cluster hierarchy*

Endpoints & Clusters

Endpoints

In Matter, an Endpoint is an independent functional unit within a Node. Each endpoint contains a set of clusters that define its attributes, commands, and events. This makes the endpoint the place where the device’s application functionality is represented. When all endpoints are combined, they provide a “complete picture” of the node’s capabilities.

For example, a smart sensor may have three endpoints:

• Endpoint 1: Temperature Measurement
• Endpoint 2: Humidity Measurement
• Endpoint 3: Occupancy Detection

Each endpoint can be accessed and managed separately, allowing functions to operate in parallel and independently.

Matter classifies endpoints into two types:

• Leaf endpoints: operate independently and do not rely on other endpoints.
• Composed endpoints require access to or integration with other endpoints to function.

A smart thermostat is a typical example: one endpoint performs temperature measurement, while another endpoint is responsible for heating/cooling control. The control endpoint relies on the data from the temperature measurement endpoint to operate accurately.

A node has endpoints numbered starting from 0, with each endpoint containing its own set of features. Endpoint 0 has a special role and is assigned the “Root Node” device type. It always includes utility clusters that apply to the entire node, such as Basic Information, ACL, Network Commissioning, Discovery, Addressing, Diagnostics, and Software Update. etc.

Each endpoint within a node is assigned a Device Type, which defines the functional category that the endpoint provides. A Device Type describes a standardized set of capabilities for a device, such as On/Off Light, Dimmable Light, or Temperature Sensor.

Each Device Type includes a set of mandatory and optional clusters as defined in the Matter specification. This standardization ensures that devices from different manufacturers can communicate and operate seamlessly within the same Matter network.

The other endpoints are numbered sequentially and may differ in configuration depending on the node. Endpoints with the same number on different nodes can represent different sets of features.

Clusters

A Cluster is a collection of related data that groups attributes (state or configuration), commands (actions), and events (state changes) for a specific feature within an endpoint.

In simple terms, a cluster acts as an interface or service that represents a distinct device function. In the Matter data model, clusters are the smallest independent functional units.

An endpoint can contain multiple clusters, each defining a separate feature. This modular design allows multiple instances of the same function and enables flexible, fine-grained control.

Example: On an LED strip, each bulb can be represented by its own cluster. This allows individual bulbs to be turned on or off using the On/Off cluster, adjusted in brightness through the Level Control cluster, or have their color changed independently — instead of controlling the entire strip as a single unit.

Attributes, Commands & Events

Attributes describe the current state, configuration, or capabilities of a device.

For example, a light bulb has an OnOff attribute to indicate whether it is on or off, and a Brightness attribute to represent its brightness level. A switch might have a SwitchPosition attribute to show whether it is in the up or down position.

Each attribute can carry different data types, such as an integer (uint8), a string, or an array.

Some attributes are special and referred to as fabric-scoped attributes, meaning they can only be accessed within the same fabric - that is, within the same trusted network of devices and controllers.

Commands are instructions defined within a cluster, used for communication between a client and a server to request a specific action. You can think of a command as the “verb” in the language. A command always has a clear direction:

• From client → server (e.g, a switch sends a command to turn on a light).
• Or from server → client (e.g., a device sends a notification back to the app).

A command may receive a response in two forms:

• Request – for example, a switch sends an On() command to the light bulb’s server cluster to turn it on.
• Response – for example, the light bulb replies that the command was successful, or returns an error/unsupported message.

Events in Matter are records of state changes that have occurred within a device.

Each event includes a timestamp marking when the change happened, a priority level indicating its importance, and a counter that increments with every new event to track the sequence of changes.

This makes events especially valuable for logging, troubleshooting, and analyzing device behavior over time.

Example Data Model of Smart Light

There are two main types of Clusters:

• Server Cluster: Stateful. It holds the actual data and acts as the main “storage and processing unit.”
• Client Cluster: Stateless. It does not store data itself, but is used to interact with a Server Cluster by reading/writing attributes, receiving events, or sending commands.

Example:

• A light bulb may have an On-Off Server Cluster, which stores the “on/off” state and processes incoming requests.
• A switch may have an On-Off Client Cluster, which sends on/off commands to the light bulb.

When the user presses the switch, the Switch Node sends an On/Off command through its Client Cluster.

The command is transmitted over the Matter network to the Light Node, which receives it via the On/Off Server Cluster and updates its state (turning the light on or off).

Optionally, the Light Node may emit a StateChanged event to report the new status.

A cluster can take on either the server or client role, depending on its position and purpose. This allows a node (device) to both store data (via a server cluster) and interact with or control other nodes (via a client cluster).

Transaction

What is a transaction?

A transaction is a sequence of one or more actions. Actions in a transaction are defined as first or following to better describe dependencies in this specification. Each transaction is identified by a Transaction ID, which logically groups related actions together.

In Matter Utilities, it is an application-level sequence of actions executed in order, forming a workflow on a device’s cluster (e.g., Set Level → Wait → Toggle).

Guarantees

Unlike a database commit, a transaction in Matter Utilities is not “atomic”, meaning it does not guarantee that all steps will either succeed or fail as a single unit. Instead, it operates at the application level, where each action is attempted in turn. If one step fails, the system applies retries or fallbacks so that the overall flow can still continue.

This design makes transactions more flexible and practical for testing, debugging, and demonstration purposes, even in less reliable network or device conditions.

Use cases

Transactions are especially helpful in situations where you need consistent, repeatable actions. Some common examples include:

• Demo scenes: Quickly showcase how a device or feature behaves under specific conditions using pre-built automation steps.
• Regression tests: Re-run the same set of actions to verify that recent updates or fixes haven’t introduced new issues.
• Reproducible bug reports: Capture and share the exact sequence of actions that trigger a bug, making it easier for others to debug and validate.

Group & Scene

The Groups and Scenes in Matter allow multiple devices to be organized, controlled, and synchronized more efficiently. Groups are used to manage devices collectively through Groupcast communication, while Scenes allow predefined device states to be stored and recalled for simplified smart home control and automation.

Group

In the CSA Matter specification, the Group Cluster is an optional cluster responsible for managing group membership information on end devices. It enables devices to participate in logical groups that support group-based control using groupcast addressing.

The following are the key functions of a Group Cluster:

Add/Remove Group

Allows a controller or application to dynamically add or remove a device from a specific group.

View Group Membership

Allows devices to check which groups they currently belong to. Allows controllers or applications to check which groups a device currently belongs to, helping maintain accurate group-based control.

Capacity Management

Each device supports a limited number of groups. The Group Cluster provides this information so applications can avoid exceeding the device’s supported capacity.

Scene

The Scenes Management Cluster, defined in the Matter Application Cluster Specification by the CSA, is used to save and restore predefined device states on a Matter endpoint.

A scene consists of multiple attribute values collected from one or more clusters located on the same endpoint as the Scenes Management Cluster. When a Matter controller recalls a saved scene, the stored values are applied back to their corresponding attributes, allowing the device to return to the previously configured state.

Scene Table

Scene-related data is stored in the Scene Table as Fabric-scoped entries. Each entry contains the information required to identify and restore a specific scene, including:

• Group ID Indicates the group associated with the scene. A value of 0 means the scene is not linked to any group.
• Scene ID A unique identifier used to distinguish a scene within a group.
• Scene Name The name assigned to the scene.
• Scene Transition Time Defines the transition duration, in milliseconds, for changing from the current state to the stored scene state.
• Extension Fields Contains the Cluster IDs and corresponding Attribute Values for the clusters included in the scene configuration.

Fabric Usage in the Scene Table

Each endpoint maintains its own Scene Table for storing scene data.

To ensure fair resource usage across Fabrics, a single Fabric can only use a portion of the total scene entries available on an endpoint. For example, if an endpoint supports up to 16 scenes, one Fabric may use a maximum of 8 scene entries.

This limitation helps prevent a single Fabric from occupying all available scene slots and reduces excessive flash memory usage across multiple Fabrics and endpoints.

Networks & OTBR

What is OTBR?

An OpenThread Border Router (OTBR) acts as a vital bridge, seamlessly connecting a low-power Thread mesh network to a standard IPv6 local area network (LAN) (typically Wi-Fi or Ethernet). This connection is essential for Matter devices operating on Thread.

It enables seamless communication between Thread devices and external IP-based systems.

OTBR can run on:

• Raspberry Pi (commonly used for quick prototyping)
• Linux server / PC
• Docker container (fast and flexible deployment)

In addition, OTBR supports Radio Co-Processor (RCP):

• The Thread radio (802.15.4 network) resides on a separate chip (SoC).
• The host CPU runs OTBR, managing communication with the Thread and IP networks.

OTBR includes several features, such as:

• NAT64 for IPv4 connectivity
• DHCPv6 Prefix Delegation to obtain IPv6 prefixes for the Thread network
• Thread Border Agent to support external commissioning

OTBR provides the following services:

• mDNS Publisher — Enables an External Commissioner to discover the OTBR and its associated Thread network.
• PSKc Generator — Used to generate a PSKc key.

Reference: For more details, visit the OpenThread Border Router Guide

Why is an OTBR important for Matter Utilities?

For Matter Utilities to discover and communicate with Matter devices operating on a Thread network, an OTBR must be present and correctly configured on your local network. It translates requests between the Wi-Fi/Ethernet network where Matter Utilities runs and the Thread network where your devices are located.

Installation

You can set up OTBR in several environments, depending on your hardware and workflow:

• Docker: Recommended for quick setup and easy maintenance.
• Native Linux: Suitable for direct integration into Linux-based systems.
• Raspberry Pi Quickstart: Ideal for testing and small-scale deployments.

Step-by-step guides for each installation path are available in the OpenThread setup instructions