Chapter 267: Matter Protocol Implementation

Chapter Objectives

By the end of this chapter, you will be able to:

• Understand the purpose of the Matter protocol and its role in the IoT ecosystem.
• Describe Matter’s core architecture, including its use of IP, Wi-Fi, Thread, and Bluetooth LE.
• Explain key Matter concepts: Fabrics, Nodes, Endpoints, Clusters, and Commissioning.
• Configure an ESP-IDF project with the esp-matter SDK to build a functional Matter device.
• Implement a standard Matter device, such as an on/off light bulb.
• Commission a Matter device onto a network using a QR code and a Matter controller.
• Identify which ESP32 variants are suitable for different Matter applications.
• Troubleshoot common issues encountered during Matter development.

Introduction

For years, the smart home has been fragmented. A Philips Hue bulb couldn’t talk to a Google Nest thermostat without a complex cloud-to-cloud integration. This lack of a common language has hindered consumer adoption and created complexity for developers. Matter is the industry’s answer to this problem.

Spearheaded by the Connectivity Standards Alliance (CSA) and backed by major technology companies like Apple, Google, Amazon, and Espressif, Matter is an open-source, IP-based connectivity protocol designed to make smart home devices secure, reliable, and seamlessly interoperable. It doesn’t replace Wi-Fi or Thread; instead, it runs on top of them, providing a unified application layer that all devices can understand.

For ESP32 developers, Matter opens the door to creating products that work out-of-the-box with all major smart home ecosystems. This chapter will introduce you to the architecture of Matter and guide you through building your first Matter-enabled device using Espressif’s powerful esp-matter SDK.

Theory

What is Matter?

At its core, Matter is an application layer protocol. It defines a common way for devices to communicate, regardless of the manufacturer or the underlying network transport. If Zigbee’s strength is low-power mesh and Wi-Fi’s is high-speed data, Matter’s strength is universal interoperability.

Matter achieves this by leveraging existing, proven technologies:

• Transport Protocols: It runs exclusively over IP (Internet Protocol) networks. The primary network transports are Wi-Fi for high-bandwidth applications (like cameras) and Thread (based on IEEE 802.15.4) for low-power, reliable mesh networks.
• Commissioning: Bluetooth LE (BLE) is used for the initial setup process, called commissioning, where a device is securely added to a network.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans'}}}%%
graph TD
    subgraph "Matter Device"
        A["<br><b>Matter Application Layer</b><br><i>(e.g., On/Off Light)</i>"]
    end

    subgraph "Network Layers"
        A --> B{Matter Core Protocol};
        B --> C[TCP / UDP];
        C --> D["Wi-Fi<br><i>(High Bandwidth)</i>"];
        C --> E["Thread (802.15.4)<br><i>(Low Power Mesh)</i>"];
    end

    subgraph "Commissioning"
        F["Bluetooth LE<br><i>(Device Setup)</i>"] --o B;
    end

    %% Styling
    classDef primary fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef comms fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;

    class A primary;
    class B,C,D,E process;
    class F comms;

Core Concepts of Matter

To work with Matter, you must understand its fundamental building blocks.

• Fabric: A “Fabric” is your unique, secure smart home network. Devices from different manufacturers can join the same Fabric, allowing them to communicate with each other locally without relying on the cloud. A device can be commissioned to multiple Fabrics simultaneously (e.g., Apple Home and Google Home), which is a key feature called Multi-Admin. Each Fabric has its own set of cryptographic credentials.
• Commissioning: This is the secure process of adding a new device to a Fabric. The process typically works as follows:
  • The new device advertises itself over Bluetooth LE.
  • A Matter Controller (e.g., a smartphone app, smart speaker) discovers the device via BLE.
  • The user scans a QR code or enters a numeric code provided with the device.
  • The Controller uses the information from the code to authenticate the device and securely transmit the Fabric’s credentials (e.g., Wi-Fi password or Thread network details).
  • The device uses these credentials to join the Wi-Fi or Thread network and is now a fully operational node in the Fabric.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans'}}}%%
sequenceDiagram
    participant D as New Device (ESP32)
    participant C as Matter Controller (Phone)
    participant N as Wi-Fi/Thread Network

    D->>D: Power On & Boot
    D->>C: Advertise self via Bluetooth LE
    C->>C: User initiates "Add Device"
    C->>D: Discover & Connect via BLE
    C->>C: User scans QR Code
    C->>D: Send authentication data
    D->>C: Authenticate & establish secure session
    C->>D: Securely transmit Fabric credentials<br>(Wi-Fi/Thread Network Info)
    D->>N: Use credentials to connect
    N-->>D: Connection successful, IP assigned
    D->>C: Notify Controller: Commissioning Complete!
    C->>C: Device appears in app

• Data Model (The “Language” of Matter): Matter defines a hierarchical structure for how a device exposes its capabilities.
  • Node: Represents a complete physical device (e.g., an ESP32 board).
  • Endpoint: Represents a distinct functional unit on a Node. A smart power strip might have one Node but multiple Endpoints, one for each controllable outlet. Endpoint 0 is always reserved for network utility functions.
  • Cluster: A group of related functionalities. Clusters are the heart of interoperability. For instance, the On/Off Cluster groups everything needed to control a switch. It contains attributes and commands.
  • Attribute: A piece of state or data. The On/Off Cluster has an OnOff attribute that holds the current state (true for on, false for off).
  • Command: An action that can be invoked on a device. The On/Off Cluster has On(), Off(), and Toggle() commands.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans'}}}%%
graph TD
    subgraph "Physical Device"
        Node["<b>Node</b><br><i>(e.g., ESP32 Board)</i>"]
    end

    subgraph "Functional Units"
        Endpoint1["<b>Endpoint 1</b><br><i>(e.g., Light Bulb)</i>"]
        Endpoint0["<b>Endpoint 0</b><br><i>(Utility & Network Info)</i>"]
    end
    
    subgraph "Capabilities (Clusters)"
        Cluster_OnOff["<b>On/Off Cluster</b><br><i>Defines switchable behavior</i>"]
        Cluster_Level["<b>Level Control Cluster</b><br><i>Defines dimmable behavior</i>"]
        Cluster_Identify["<b>Identify Cluster</b><br><i>Used for identification</i>"]
    end

    subgraph "State & Actions"
        Attribute["<b>Attribute</b><br><i>e.g., OnOff (true/false)</i>"]
        Command["<b>Command</b><br><i>e.g., On(), Off(), Toggle()</i>"]
    end

    Node --> Endpoint0;
    Node --> Endpoint1;
    Endpoint1 --> Cluster_OnOff;
    Endpoint1 --> Cluster_Level;
    Endpoint1 --> Cluster_Identify;
    Cluster_OnOff --> Attribute;
    Cluster_OnOff --> Command;

    %% Styling
    classDef node fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
    classDef endpoint fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef cluster fill:#D1FAE5,stroke:#059669,stroke-width:1px,color:#065F46;
    classDef detail fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;

    class Node node;
    class Endpoint0,Endpoint1 endpoint;
    class Cluster_OnOff,Cluster_Level,Cluster_Identify cluster;
    class Attribute,Command detail;

By using these standardized clusters, a controller knows it can send the On() command to any device that implements the On/Off server cluster, and it will turn on.

Practical Example: Building a Matter On/Off Light

Let’s build a simple Matter-enabled light bulb. This device will be commissionable and controllable from any standard Matter controller like the Google Home or Apple Home app.

1. Project Setup and esp-matter SDK

Espressif provides a dedicated SDK, esp-matter, which simplifies development. It must be installed alongside ESP-IDF.

1. Clone ESP-IDF: Ensure you have ESP-IDF v5.1 or newer.git clone -b v5.2.1 --recursive https://github.com/espressif/esp-idf.git cd esp-idf ./install.sh . ./export.sh cd ..
2. Clone esp-matter: Clone the SDK and its submodules.git clone --recursive https://github.com/espressif/esp-matter.git
3. Install esp-matter: Run the installation script.cd esp-matter ./install.sh cd ..

Now, let’s use the provided light example.

1. Copy the example to a new directory: cp -r esp-matter/examples/light my_matter_light
2. Navigate into your new project: cd my_matter_light

2. Hardware Setup

• ESP32 Variant: An ESP32-S3 or ESP32-C6 development board is ideal as they support Matter over both Wi-Fi and Thread and have enough resources. An ESP32-H2 works for Matter over Thread, and a standard ESP32 will work for Matter over Wi-Fi. We’ll proceed with an ESP32-C6-DevKitC-1.
• LED: An external LED with a resistor or the onboard RGB LED. We’ll use the onboard LED, often on GPIO8.

3. Code Walkthrough

Open the main/app_main.cpp file. Note that esp-matter examples are written in C++. Let’s examine the key parts.

/* main/app_main.cpp */
#include <esp_log.h>
#include <app_priv.h> // Contains our application-specific logic
#include <app_reset.h>

#include <esp_matter.h>
#include <esp_matter_console.h>
#include <device.h>
#include <devices/esp_matter_device.h>
// ... other includes

using namespace chip::app::Clusters;
using namespace esp_matter;
using namespace esp_matter::cluster;

static const char *TAG = "app_main";

// This callback is triggered by events from the Matter stack
static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg)
{
    switch (event->Type) {
    case chip::DeviceLayer::DeviceEventType::kInterfaceIpAddressChanged:
        ESP_LOGI(TAG, "Interface IP Address Changed");
        break;

    case chip::DeviceLayer::DeviceEventType::kCommissioningComplete:
        ESP_LOGI(TAG, "Commissioning Complete");
        break;

    // Other event cases...
    }
}

// This callback is triggered when an attribute is updated from a controller
static esp_err_t app_attribute_update_cb(callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id,
                                         uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data)
{
    // Ensure the update is for our light's endpoint and the On/Off cluster
    if (endpoint_id == light_endpoint_id && cluster_id == OnOff::Id && attribute_id == OnOff::Attributes::OnOff::Id) {
        ESP_LOGI(TAG, "On/Off attribute updated to %s", val->val.b ? "ON" : "OFF");
        
        // *** This is where you control the hardware! ***
        app_driver_light_set_power(val->val.b);
    }
    return ESP_OK;
}

extern "C" void app_main()
{
    // Initialize standard ESP32 services
    app_driver_init();

    // Initialize the Matter stack
    node::config_t node_config;
    // node_config can be used to set vendor/product info if needed
    node_t *node = node::create(&node_config, app_attribute_update_cb, NULL);

    // ** Create the device data model: An On/Off Light **
    on_off_light::config_t light_config;
    light_config.on_off.on_off = DEFAULT_POWER; // Set initial state
    // Create the endpoint for the light
    endpoint_t *light_endpoint = on_off_light::create(node, &light_config, ENDPOINT_FLAG_NONE, NULL);

    // Save the endpoint ID for use in the attribute callback
    light_endpoint_id = endpoint::get_id(light_endpoint);
    ESP_LOGI(TAG, "Light created with endpoint_id: %d", light_endpoint_id);

    // Start the Matter stack
    esp_matter::start(app_event_cb);

    // The console is useful for diagnostics, like factory resetting
    #if CONFIG_ENABLE_CHIP_SHELL
    esp_matter_console_cli_init();
    #endif
}

Key Takeaways from the Code:

• The logic is event-driven. We register callbacks (app_event_cb, app_attribute_update_cb) that the Matter stack calls when things happen.
• The data model is built programmatically. We create a node, then create a standard device type (on_off_light::create), which handles creating the endpoint and all the necessary clusters (Basic, Identify, OnOff, etc.) for us.
• The app_attribute_update_cb is our bridge to the hardware. When a Matter controller changes the OnOff attribute, this function is called, and we can then call our app_driver_light_set_power function to turn the physical LED on or off.

4. Configuration and Building

1. Set the Target: Set your target to esp32c6 (or your chosen board).
2. Run menuconfig: idf.py menuconfig
3. Navigate to Component config –> ESP Matter. Here you can configure:
   • Device Information: Set the Vendor ID (VID) and Product ID (PID). For testing, you can use the default test values. For a commercial product, you must use your CSA-assigned VID.
   • Commissioning: You can enable a “discriminator” which helps identify the device during commissioning.
4. Save and Exit.
5. Build: idf.py build

5. Flashing and Commissioning

1. Flash: idf.py -p /dev/ttyUSB0 flash (use your port).
2. Monitor: idf.py -p /dev/ttyUSB0 monitor.
3. Get the QR Code: On first boot, the device will print a URL and a large QR code to the terminal.
   • Copy the URL (https://project-chip.github.io/...) and paste it into a web browser. This will display the QR code for commissioning.
   • Alternatively, some terminals can render the QR code directly.
   A representation of the QR Code you will see in your terminal.
4. Commission the Device:
   • Open your Matter controller app (e.g., Google Home).
   • Select “Add a new device” -> “Matter-enabled device”.
   • Scan the QR code from your browser or terminal with your phone’s camera.
   • The app will use Bluetooth LE to connect to your ESP32-C6.
   • It will then ask for your Wi-Fi credentials. Provide them.
   • The device will connect to Wi-Fi, and the controller will finish the setup. Your light is now part of your smart home and can be controlled from the app!

Variant Notes

Matter support varies significantly across the ESP32 family, based on their radio capabilities and resources.

• ESP32-C6 & ESP32-H2: These are the Thread-native chips. They are ideal for creating Matter end devices that run on the low-power Thread mesh protocol. Both also have BLE for commissioning. The ESP32-C6 also has Wi-Fi, making it extremely versatile for creating Matter devices that can choose their transport or act as a border router.
• ESP32-S3 & ESP32: These are the primary Wi-Fi chips. They are excellent for creating Matter devices that require the higher bandwidth of Wi-Fi (like security cameras or voice assistants). They have sufficient RAM and processing power for the Matter stack. Both use their onboard BLE for commissioning.
• ESP32-C3: This chip can support Matter over Wi-Fi. However, its more limited RAM and flash make it suitable for simpler end devices (like a light or switch) rather than complex ones or border routers. It has BLE for commissioning.
• ESP32-S2: While it has Wi-Fi, the S2 lacks a BLE radio. This makes standard Matter commissioning difficult. It’s generally not recommended for Matter development unless using alternative, non-standard commissioning methods.

Common Mistakes & Troubleshooting Tips

Exercises

1. Dimmable Matter Light: Extend the light bulb project. In app_main.cpp, add the level_control cluster to your light’s configuration. In the app_attribute_update_cb, add a case to handle updates to the LevelControl::Id cluster and its CurrentLevel attribute. Use the value (0-254) to control LED brightness with the LEDC peripheral.
2. Matter Switch: Using the light_switch example from esp-matter/examples, create a physical switch device. You’ll need to configure it as a Matter client (a controller). Then, you will use the Matter “binding” process to link your switch to your light bulb, allowing it to control the light directly over the network.
3. Multi-Endpoint Device: Create a “dual smart plug” device. In app_main.cpp, after creating the first on_off_light endpoint, create a second one. This will result in a single Node that exposes two distinct endpoints. Both will be independently controllable from your Matter controller app. This demonstrates the power of the Matter data model.

Summary

• Matter is an IP-based application layer protocol designed to unify the smart home and ensure device interoperability.
• It operates over Wi-Fi and Thread and uses Bluetooth LE for secure commissioning.
• The core concepts are the Fabric (your secure network) and the Data Model (Node, Endpoint, Cluster).
• The esp-matter SDK provides high-level APIs to simplify building Matter devices on ESP32, abstracting much of the complexity.
• Commissioning is done easily and securely using QR codes.
• Chip selection is crucial: ESP32-C6/S3 are top choices for their features and resources, while ESP32-H2 is perfect for dedicated Thread devices.

Further Reading

• Espressif esp-matter Programming Guide: The official and most critical resource for developers.
  • https://docs.espressif.com/projects/esp-matter/en/latest/esp32/
• Connectivity Standards Alliance (CSA) Website: The official source for the Matter specification and whitepapers.
  • Matter Specification
• esp-matter Example Projects: The examples directory is your best friend. Study them to learn how to implement different device types.
  • github.com/espressif/esp-matter/tree/main/examples