1033  Matter Device Implementation and Commissioning

1033.1 Matter Device Implementation and Commissioning

Time: ~12 min | Difficulty: Advanced | Unit: P08.C48.U03

NoteLearning Objectives

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

  • Implement a basic Matter device with standard clusters
  • Add custom clusters for manufacturer-specific features
  • Understand QR code and setup code structure
  • Implement the complete commissioning flow
  • Handle factory reset and device re-commissioning

1033.2 Prerequisites

Before diving into this chapter, you should be familiar with:

Commissioning is the process of adding a new device to your smart home. Here’s what happens step by step:

  1. Scan QR Code: Your phone scans the code on the device packaging
  2. Bluetooth Connection: Phone connects to device via Bluetooth Low Energy
  3. Security Handshake: They verify each other using a secret code (PASE)
  4. Network Setup: Phone tells the device how to connect to your Wi-Fi or Thread network
  5. Certificate Install: Device receives a β€œdigital ID card” (certificate) for your home
  6. Ready to Use: Device can now be controlled through the smart home app

It’s like checking into a hotel - you show your ID (QR code), get verified, receive your room key (certificate), and connect to the hotel Wi-Fi.

1033.3 Implementing a Matter Device

1033.3.1 Basic Light Example Structure

// main.cpp - ESP-Matter Light Example
#include <esp_matter.h>
#include <esp_matter_core.h>

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

// Callback when On/Off attribute changes
static esp_err_t app_attribute_update_cb(
    attribute::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)
{
    if (type == PRE_UPDATE) {
        // Validate before applying
    } else if (type == POST_UPDATE) {
        if (cluster_id == OnOff::Id) {
            if (attribute_id == OnOff::Attributes::OnOff::Id) {
                // Control the actual LED
                gpio_set_level(LED_GPIO, val->val.b ? 1 : 0);
            }
        }
    }
    return ESP_OK;
}

extern "C" void app_main()
{
    // Initialize Matter
    esp_matter::node::config_t node_config;
    node_t *node = node::create(&node_config, app_attribute_update_cb, NULL);

    // Create Light endpoint
    light::config_t light_config;
    light_config.on_off.on_off = false;
    light_config.level_control.current_level = 128;
    endpoint_t *endpoint = light::create(node, &light_config, ENDPOINT_FLAG_NONE);

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

    // Enable commissioning
    esp_matter::factory_reset::register_button(BUTTON_GPIO);
}

1033.3.2 Implementing Custom Clusters

For devices not covered by standard clusters, you can add manufacturer-specific clusters:

// Custom cluster definition
static const uint32_t CUSTOM_CLUSTER_ID = 0xFFF10001;

// Add custom cluster to endpoint
cluster::create(endpoint, CUSTOM_CLUSTER_ID, CLUSTER_FLAG_SERVER);

// Add custom attribute
attribute::create(cluster, 0x0000, ATTRIBUTE_FLAG_NONE,
                  esp_matter_uint16(0));  // Custom attribute

// Add custom command
command::create(cluster, 0x00, COMMAND_FLAG_ACCEPTED,
                custom_command_callback);

1033.4 Commissioning Implementation

1033.4.1 QR Code and Setup Code

Every Matter device needs a setup code for commissioning:

Setup Code Format:

MT:Y.K9042C00KA0648G00  (QR Code)
34970112332              (Manual Pairing Code)

Components:

Field Bits Description
Version 3 Payload version (0)
Vendor ID 16 CSA-assigned vendor ID
Product ID 16 Manufacturer-assigned
Custom Flow 2 Commissioning flow type
Discovery 8 Discovery capabilities
Discriminator 12 Device identifier
Passcode 27 Setup PIN code

1033.4.2 Commissioning Flow Implementation

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2C3E50', 'primaryTextColor': '#fff', 'primaryBorderColor': '#16A085', 'lineColor': '#E67E22', 'secondaryColor': '#16A085', 'tertiaryColor': '#7F8C8D'}}}%%
sequenceDiagram
    participant App as Controller App
    participant Dev as Matter Device
    participant BR as Border Router

    Note over Dev: Power on, enter commissioning mode

    App->>Dev: Scan QR Code
    App->>Dev: BLE Discovery (discriminator)
    App->>Dev: PASE Handshake (passcode)

    Note over App,Dev: Secure PASE session established

    App->>Dev: Read Basic Information
    App->>Dev: Configure Thread/Wi-Fi Network

    Note over Dev: Connect to Thread/Wi-Fi

    Dev->>BR: Join Thread Network
    BR->>Dev: IPv6 Address Assigned

    App->>Dev: Install NOC Certificate
    App->>Dev: Configure ACL

    Note over App,Dev: CASE session established

    App->>Dev: Read all clusters
    App->>Dev: Subscribe to attributes

    Note over App,Dev: Device ready for use

Figure 1033.1: Complete Matter Device Commissioning Sequence with Network and Security Setup

{fig-alt=β€œComplete Matter commissioning sequence: App scans QR code, discovers device via BLE, establishes PASE session using passcode, reads device info, configures Thread/Wi-Fi network, device joins network through Border Router, app installs NOC certificate and ACL, CASE session established, app reads clusters and subscribes to attributes. Device is now commissioned and ready.”}

1033.4.3 Implementing Factory Reset

// Factory reset handler
static void factory_reset_handler(void *arg)
{
    // Clear all Matter fabric data
    chip::Server::GetInstance().GetFabricTable().DeleteAllFabrics();

    // Clear network credentials
    esp_matter::network::reset();

    // Clear application data
    nvs_flash_erase();

    // Restart device
    esp_restart();
}

// Register factory reset button (hold 10 seconds)
esp_matter::factory_reset::register_button(BUTTON_GPIO, 10000);

1033.5 Production Considerations

1033.5.1 Manufacturing Data

Each device needs unique manufacturing data:

Data Source Storage
Device Certificate PKI/Factory Secure element
Device Private Key Factory generated Secure element
Setup Code Per-device unique QR code label
Discriminator Per-device unique Flash
Vendor ID CSA-assigned Firmware
Product ID Manufacturer-assigned Firmware

1033.5.2 Secure Element Integration

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2C3E50', 'primaryTextColor': '#fff', 'primaryBorderColor': '#16A085', 'lineColor': '#E67E22', 'secondaryColor': '#16A085', 'tertiaryColor': '#7F8C8D'}}}%%
graph TB
    subgraph MCU["Main MCU"]
        App[Application Code]
        Matter[Matter Stack]
        Crypto[Crypto Interface]
    end

    subgraph SE["Secure Element"]
        Keys[Private Keys]
        Certs[Certificates]
        HSM[Crypto Engine]
    end

    Matter --> Crypto
    Crypto <--> SE

    style App fill:#2C3E50,stroke:#16A085,color:#fff
    style Keys fill:#E67E22,stroke:#2C3E50,color:#fff

Figure 1033.2: Matter Device Security Architecture with MCU and Secure Element Integration

{fig-alt=β€œSecure element integration showing Main MCU with Application Code, Matter Stack, and Crypto Interface connecting to separate Secure Element containing Private Keys, Certificates, and Crypto Engine. Bidirectional connection between Crypto Interface and Secure Element ensures keys never leave secure hardware.”}

1033.5.3 OTA Update Implementation

// OTA Update handler
static esp_err_t ota_event_handler(esp_ota_event_t event)
{
    switch (event) {
        case OTA_START:
            // Notify Matter stack of pending update
            chip::DeviceLayer::PlatformMgr().ScheduleWork(
                notify_ota_start, NULL);
            break;

        case OTA_PROGRESS:
            // Update progress attribute
            update_ota_progress(event.progress);
            break;

        case OTA_COMPLETE:
            // Verify image and apply
            esp_ota_mark_app_valid();
            esp_restart();
            break;

        case OTA_FAILED:
            // Rollback and notify
            esp_ota_mark_app_invalid();
            break;
    }
    return ESP_OK;
}

1033.6 Summary

TipKey Takeaways

  1. Matter device implementation uses callbacks - The SDK handles protocol complexity; you implement attribute change handlers to control hardware

  2. Custom clusters extend standard functionality - Use manufacturer-specific cluster IDs (0xFFF1xxxx) for proprietary features while maintaining interoperability

  3. Commissioning uses PASE for initial pairing - QR code contains passcode for Password Authenticated Session Establishment, then CASE for subsequent connections

  4. Multi-Admin enables ecosystem coexistence - Devices can be controlled by up to 5 fabrics (Apple, Google, Amazon, etc.) simultaneously

  5. Production requires unique cryptographic identity - Each device needs unique DAC and private key, ideally generated/stored in secure elements

  6. Factory reset must clear all fabric data - Proper reset enables device recommissioning without security vulnerabilities

1033.7 What’s Next

Continue to the next chapter to learn about testing and certification: