66 Matter Commissioning

In 60 Seconds

Matter commissioning uses PASE (Password Authenticated Session Establishment) from the QR code passcode for initial pairing over BLE, then installs a Node Operational Certificate for CASE-based secure sessions. Multi-Admin allows a single device to join up to 5 fabrics (Apple, Google, Amazon, etc.) simultaneously, with production devices requiring per-device cryptographic identity.

66.1 Matter Device Implementation and Commissioning

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

Minimum Viable Understanding

Matter commissioning uses PASE (Password Authenticated Session Establishment) from the QR code passcode for initial pairing over BLE, then installs a Node Operational Certificate for subsequent CASE-based secure sessions. Multi-Admin allows a single device to join up to 5 fabrics (Apple, Google, Amazon, etc.) simultaneously, and production devices require unique per-device cryptographic identity provisioned via secure elements.

Learning Objectives

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

Implement a basic Matter device with standard clusters and attribute callbacks
Design custom clusters for manufacturer-specific features beyond standard device types
Analyze QR code and setup code structure including discriminator and passcode fields
Configure the complete commissioning flow from PASE establishment through NOC installation
Diagnose factory reset and multi-admin commissioning issues in production deployments

66.2 Prerequisites

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

Matter SDKs and Development Environment: SDK selection and environment setup
Matter Architecture and Fabric: Data model, security, and fabric concepts
Matter Device Types and Clusters: Device types and cluster library

For Beginners: What Happens When You Commission a Device?

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

Scan QR Code: Your phone scans the code on the device packaging
Bluetooth Connection: Phone connects to device via Bluetooth Low Energy
Security Handshake: They verify each other using a secret code (PASE)
Network Setup: Phone tells the device how to connect to your Wi-Fi or Thread network
Certificate Install: Device receives a “digital ID card” (certificate) for your home
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.

66.3 Implementing a Matter Device

66.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);
}

Show code

viewof inlineKC1 = InlineKnowledgeCheck({
  question: "In the ESP-Matter light example above, what is the purpose of the `PRE_UPDATE` callback type in the attribute update handler?",
  options: [
    "It validates the new attribute value before it is applied to hardware, allowing the firmware to reject invalid values",
    "It triggers a factory reset before any attribute change takes effect",
    "It sends the old attribute value to the commissioner for logging purposes",
    "It updates the LED GPIO pin before the Matter stack processes the change"
  ],
  correctIndex: 0,
  explanation: "The PRE_UPDATE callback fires before the attribute value is committed, giving the application code an opportunity to validate the incoming value (e.g., reject out-of-range brightness levels). POST_UPDATE fires after the value is stored and is where you control the actual hardware (GPIO)."
})

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

66.4 Commissioning Implementation

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

Putting Numbers to It: Setup Passcode Security Strength

The 27-bit passcode in Matter QR codes provides the security foundation for initial device commissioning. Understanding its cryptographic strength helps evaluate PASE security.

Formula: Possible combinations = 2^n where n = number of bits

Worked Example - Matter Setup Passcode:

Given: - Passcode length: 27 bits - PASE uses SPAKE2+ (prevents offline brute force) - Network attack rate: ~1,000 attempts/second (rate-limited by protocol)

Calculate total combinations: \[\text{Combinations} = 2^{27} = 134{,}217{,}728 \approx 134\,\text{million}\]

Calculate brute force time at network speed (with SPAKE2+ rate limiting): \[\text{Time} = \frac{134{,}217{,}728}{1{,}000\,\text{attempts/s}} = 134{,}218\,\text{s} \approx 37\,\text{hours}\]

However, Matter implements additional protections: - Rate limiting: 10 failed attempts triggers 30-minute lockout - Adjusted brute force time: \(\frac{134\,\text{M attempts}}{10\,\text{attempts}} \times 30\,\text{min} = 251{,}000\,\text{years}\)

Interpretation: The raw 27-bit space would take only 37 hours to exhaust at network speeds, which seems weak. BUT the 10-attempt lockout mechanism extends this to effectively impossible timescales. This is why Matter commissioning is only vulnerable during the brief window when the device advertises commissioning mode (typically 3-10 minutes after factory reset). Once commissioned, PASE is no longer accessible, and all communication uses 128-bit CASE session keys.

66.4.2 Commissioning Flow Implementation

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

66.5 Production Considerations

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

66.5.2 Secure Element Integration

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. — Figure 66.2: Matter Device Security Architecture with MCU and Secure Element Integration

66.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;
}

Sensor Squad: How Matter Devices Join Your Smart Home

Lila the LED is a brand-new smart light that just arrived at your house. Here is her story of “commissioning” – the process of joining your smart home:

Step 1: Show your ID. Lila has a QR code on her box – it is like her passport. When you scan it with your phone, the phone learns her secret handshake code.

Step 2: Bluetooth introduction. Your phone connects to Lila over Bluetooth Low Energy. They do a secret handshake called PASE (like whispering a password). Now they trust each other temporarily.

Step 3: Join the network. Your phone tells Lila the Wi-Fi password (or Thread network info). Lila connects to your home network.

Step 4: Get a permanent ID card. Lila receives a digital certificate – like a student ID card for your home. From now on, she uses this ID card (called CASE) instead of the temporary password.

Max the Microcontroller explains the coolest part: “Multi-Admin means Lila can have up to 5 ID cards – one for Apple Home, one for Google Home, one for Amazon Alexa! It is like having a student ID, a library card, AND a gym membership all at once. She belongs to multiple ‘clubs’ (fabrics) simultaneously.”

Sammy the Sensor adds: “And if you need to start over, a factory reset erases all the ID cards – like shredding all your membership cards and starting fresh.”

66.6 Common Mistake: Commissioning Timeout During Multi-Admin Setup

Common Mistake: Multi-Admin Commission Window Expiration

The Mistake: A Matter smart lock is successfully commissioned into Apple Home (Fabric A). The user immediately tries to commission the same device into Google Home (Fabric B) and gets a “Device not found” or “Commission failed” error, even though the device is powered on and responding to Apple Home commands.

Why This Happens:

After initial commissioning, the device closes its commissioning window for security. Multi-admin requires explicitly opening a new commission window from the first fabric before the second controller can join. Many users expect the device to remain joinable indefinitely after the first setup.

What’s Actually Happening:

Initial commissioning to Fabric A (Apple):
- Device advertises over BLE with discriminator and setup code
- PASE session established using QR code passcode
- Apple installs NOC (Node Operational Certificate) for Fabric A
- Commission window closes automatically after NOC installation
Attempted second commissioning to Fabric B (Google):
- Device is no longer advertising (window closed)
- Google Home scans for devices → finds nothing
- User sees “No devices found” error

The Fix:

Must explicitly open commission window from Fabric A controller:

// On the device (triggered by first fabric administrator)
// Option 1: Open window with new passcode
esp_matter::commission_window_open(
    600,        // 600 seconds (10 minutes)
    0x1234,     // New discriminator
    20202021    // New setup passcode
);

// Option 2: Enhanced commissioning window (Matter 1.2+)
esp_matter::enhanced_commission_window_open(
    900,        // 900 seconds (15 minutes)
    PAKEPasscodeVerifier  // Pre-computed verifier
);

In Apple Home app (user-facing steps): 1. Open device settings in Home app 2. Tap “Turn On Pairing Mode” or “Allow Additional Setup” 3. Device advertises for 10 minutes 4. Now switch to Google Home app and add device

In Google Home app:

Add new device
Scan QR code or enter setup code
Device joins as second fabric
Commission window automatically closes after success

Real-World Impact:

72% of multi-admin setup failures are from users not opening commission window
Support tickets show confusion: “Why can’t I add it to Google if it works in Apple?”
Best practice: App UX should prompt “Enable pairing mode” before switching ecosystems

Prevention in Production:

Implement physical button: Hold for 10 seconds to open commission window
Display LED pattern: Blink blue when commission window is open
Mobile app: “Share with another app” button opens window automatically
Timeout notification: Warn user when window is about to close (e.g., “2 minutes remaining”)

Security Note: Auto-opening commission windows on every boot would be a security risk. The explicit open-close pattern ensures only authorized users (with access to first fabric) can add additional controllers.

Common Pitfalls

1. QR Code Scanning Failures in Low Light

Matter QR codes on device labels are often small and positioned in hard-to-reach locations. Ensure adequate lighting and phone camera focus; the Matter setup code can also be entered manually as a fallback.

2. IP Network Provisioning on Wrong Frequency Band

Matter over Wi-Fi currently requires 2.4 GHz bands for many devices. Attempting to provision a 2.4 GHz-only device on a 5 GHz network will fail silently or with a cryptic error. Always check device specifications for supported bands.

3. Not Cleaning Up Failed Commissioning Attempts

Partial commissioning leaves devices in an intermediate state. Always factory reset a device before retrying commissioning after a failure, as partial commissioning can block subsequent attempts.

🏷️ Label the Diagram

Code Challenge

Order the Steps

Match the Concepts

66.7 Summary

Key Takeaways

Matter device implementation uses callbacks - The SDK handles protocol complexity; you implement attribute change handlers to control hardware
Custom clusters extend standard functionality - Use manufacturer-specific cluster IDs (0xFFF1xxxx) for proprietary features while maintaining interoperability
Commissioning uses PASE for initial pairing - QR code contains passcode for Password Authenticated Session Establishment, then CASE for subsequent connections
Multi-Admin enables ecosystem coexistence - Devices can be controlled by up to 5 fabrics (Apple, Google, Amazon, etc.) simultaneously
Production requires unique cryptographic identity - Each device needs unique DAC and private key, ideally generated/stored in secure elements
Factory reset must clear all fabric data - Proper reset enables device recommissioning without security vulnerabilities

66.8 Knowledge Check

Quiz: Matter Commissioning

Key Concepts

Commissioning: The process of adding a new Matter device to a fabric: scanning QR/NFC, establishing PASE session, provisioning network credentials, issuing NOC, and completing ACL setup.
QR Code / Setup Code: A QR code or 11-digit numeric code on a Matter device encoding the setup discriminator, passcode, and supported discovery transports used to initiate commissioning.
Discriminator: A 12-bit value in the Matter setup payload that distinguishes between multiple devices of the same manufacturer during Bluetooth LE discovery.
Commissioner: A controller that performs the commissioning workflow — typically a phone app (Apple Home, Google Home, Amazon Alexa) or a hub.
IP Network Credentials: The Wi-Fi SSID/password or Thread operational dataset provisioned to a device during commissioning to connect it to the IP network.
NOC Chain: The certificate chain (Root CA → ICAC → NOC) installed on a device during commissioning, establishing its cryptographic identity within the fabric.

66.9 What’s Next

Topic	Description
Matter Testing and Certification	CHIP Tool usage, debugging techniques, and CSA certification process
Thread Network Architecture	Thread mesh networking fundamentals, roles, and border routers
Matter Architecture and Fabric	Deeper exploration of Matter’s data model, interaction model, and fabric security
Matter Device Types and Clusters	Complete device type taxonomy, cluster library, and data model design
Zigbee Network Formation	Zigbee coordinator, router, and end device roles in mesh network formation