How does Matter commissioning work?

The commissioner, a phone app or hub, runs a fixed sequence of stages that Google’s Matter primer lists in order, and the device is only usable once the last one succeeds. Matter calls the device being added the commissionee.

1. Discovery. The device advertises that it can be commissioned, over Bluetooth LE, a Wi-Fi Soft AP, or DNS-SD on a network it is already on. Its advertisement includes the discriminator from its setup code.
2. PASE. The commissioner matches the discriminator, then uses the passcode from the setup code to run Passcode Authenticated Session Establishment. The chip-tool guide says this uses the SPAKE2+ protocol. The commissioner also arms a fail-safe, which rolls the device back to its original state if commissioning does not finish.
3. Device information. The commissioner reads the descriptors on endpoint 0 and the Basic Information cluster: vendor ID, product ID, product name, serial number and device type.
4. Regulatory configuration. The SetRegulatoryConfig command sets whether the device is indoors or outdoors and its country code.
5. Attestation. The device proves it is a genuine, certified Matter product (see below).
6. Certificate signing request. The device generates a new operational key pair and returns a CSR. The private key stays on the device.
7. Operational certificate. The ecosystem’s certificate authority signs a Node Operational Certificate (NOC). The commissioner installs the fabric’s root certificate with AddTrustedRootCert and the NOC with AddNOC.
8. Network provisioning. For Wi-Fi and Thread devices, the commissioner sends the network credentials. Ethernet devices skip this step.
9. Operational discovery. The device joins the network, and the commissioner finds it there with DNS-SD.
10. CASE and CommissioningComplete. The commissioner opens a Certificate Authenticated Session Establishment session using the new certificates and sends CommissioningComplete, which also disarms the fail-safe.

The table below maps each step to its transport and spec terms, as of the Matter 1.6.1 data model (October 2026).

Matter uses Bluetooth LE during setup because a new Wi-Fi or Thread device is not on any network yet, so Bluetooth LE is the only channel a phone can reach it on. Home Assistant’s documentation puts it plainly: the controller sends your network credentials to the device over Bluetooth, and from then on the device communicates over its native interface, Wi-Fi or Thread. Bluetooth is not used to control the device.

The rules for this advertising are specific. Google’s discovery primer says the device advertises as a Bluetooth LE peripheral at 20 to 60 millisecond intervals for the first 30 seconds after power-up, then at 150 to 1500 millisecond intervals, and stops advertising once it is commissioned to its first fabric. The commissioner only needs to scan passively on the three advertising channels. Bluetooth LE is never used for operational discovery, so once setup is done it plays no further part. What is BLE advertising? covers how these packets work.

Not every device advertises on its own. The primer notes that many devices advertise for about 3 to 15 minutes after power-up, while locks and other access devices must not advertise automatically, because unprovisioned advertising is not safe for them, and appliances such as dishwashers whose main control is not from the fabric also wait for a user action. The setup payload records this as the commissioning flow: standard (pairing mode on power-up), user action required, or custom, where the steps come from the CSA’s Distributed Compliance Ledger.

The setup code is the shared secret that lets the commissioner prove it is allowed to set the device up. It holds two values, which the chip-tool guide defines:

• Discriminator, a 12-bit value used to tell apart several devices advertising at once. It is not secret in any useful sense: devices broadcast it.
• Setup passcode, a 27-bit value used to authenticate the device in PASE. The SDK restricts it to 00000001 to 99999998 and rejects trivial values such as 11111111, 12345678 and 87654321.

The QR code payload starts with MT: and also carries the vendor and product IDs, the commissioning flow and the discovery methods the device supports. The numeric manual pairing code, 11 or 21 digits, carries the passcode and part of the discriminator for people who cannot scan.

PASE turns the passcode into session keys without sending the passcode itself. A commissioning window opened later works from a verifier rather than the passcode: the Administrator Commissioning cluster sends the device a passcode verifier, with a salt of 16 to 32 bytes and an iteration count between 1,000 and 100,000. In practice, treat the label as a key. Anyone in range who has the code while the device is in commissioning mode can complete PASE, so keep the label away from people who should not set the device up, and remember that the device stops advertising over Bluetooth LE once it joins its first fabric.

A Matter device proves it is genuine by signing a fresh challenge with a private key whose certificate chains back to a CSA-approved authority. Every certified device carries a Device Attestation Certificate (DAC), unique per device, issued by an intermediate certificate (PAI) that a Product Attestation Authority (PAA) signs. The CSA’s FAQ says these authorities are operated by Alliance members, not by the CSA itself, and Google’s primer says the set of trusted PAA certificates is maintained in the Distributed Compliance Ledger, a public ledger the CSA describes as holding device provenance, certification status and setup parameters.

Google’s attestation primer gives the procedure:

1. The commissioner generates a random 32-byte nonce and asks the device for its attestation information.
2. The device returns its Certification Declaration, a timestamp and the nonce, signed with its attestation private key, plus its DAC and PAI.
3. The commissioner looks up the PAA in its trust store and checks the chain, including revocation of the PAI and PAA, that the vendor ID on the DAC matches the PAI, that the signature and nonce are valid, and that the Certification Declaration is signed by one of the CSA’s well-known keys.
4. It cross-checks the vendor and product IDs across the Basic Information cluster, the Certification Declaration and the DAC.

Matter 1.4.2 (August 2025) added standard certificate revocation lists for DACs, so a commissioner can also refuse a certificate that was revoked after it was issued.

The commissioner sends a new device its Wi-Fi or Thread credentials over the PASE session and tells it to connect. The Network Commissioning cluster defines the commands: ScanNetworks to list what the device can see, AddOrUpdateWiFiNetwork with the SSID and password, or AddOrUpdateThreadNetwork with the Thread network’s Active Operational Dataset, and then ConnectNetwork. The chip-tool guide notes that the Matter specification does not say how a controller obtains those credentials. Phones and hubs usually already know them: Apple says that once the user scans the setup code, the iPhone provisions the accessory onto Wi-Fi or Thread automatically, and the app never prompts for network credentials.

Thread devices also need a Thread border router to be reachable from the rest of the home network. After they join, they register their DNS-SD records with the border router, which answers multicast DNS on their behalf, so the commissioner on Wi-Fi can find them. What is a Thread border router? covers that box in detail, and How does Wi-Fi provisioning over Bluetooth LE work? compares this step with non-Matter setup schemes.

A Matter device can be commissioned without Bluetooth in four cases, and the device has to support the method. The SDK’s setup payload has five flags for how a device can be discovered: Soft AP, Bluetooth LE, on-network, Wi-Fi Public Action Frame and NFC.

• Already on the network. An Ethernet device, or one that joined Wi-Fi or Thread some other way, is discovered with DNS-SD and commissioned over IP. The chip-tool guide’s pairing code and onnetwork commands do this.
• Adding a second ecosystem. A device that is already commissioned no longer advertises over Bluetooth LE, so every additional fabric joins over the network through a commissioning window an existing administrator opens. What is a Matter fabric? covers multi-admin.
• Wi-Fi only. Matter 1.4.2 (August 2025) added commissioning over Wi-Fi Unsynchronized Service Discovery (USD), which the CSA says lets devices onboard without a Bluetooth LE radio and lets existing Wi-Fi products adopt Matter through a firmware update.
• NFC. Matter 1.4.1 let an NFC tag carry the setup payload in place of a QR code, but Bluetooth LE still completed setup. Matter 1.6 (June 2026) moved the whole commissioning exchange onto NFC, so a phone held near a bulb or in-wall switch can commission it before it has mains power.

Wi-Fi Soft AP is defined too, with an SSID of the form MATTER-ddd-vvvv-pppp, but Google’s primer notes that it was not implemented in version 1.0 of the Matter SDK. Whether a given phone or hub supports USD or NFC commissioning depends on its own software, so check before you rely on either.

Most Matter commissioning failures are about the network around the device, not the device. Work through these in order:

1. The device is not in commissioning mode. Its advertising window may have closed, or it may need a button press. Power-cycle it or use its pairing trigger. If it was set up before, it stopped advertising after its first fabric: either get a share code from the app that controls it, or factory reset it.
2. The phone cannot run the setup flow. Home Assistant’s documentation asks for Android 8.1 or later (12 or later recommended) with up-to-date Google Play services, or iOS or iPadOS 16.4 or later, and says Android can show “Matter is unavailable” until Play services has downloaded its Matter modules.
3. The phone is on the wrong network. For Wi-Fi devices, Home Assistant says Matter devices often use 2.4 GHz, so the phone should be on the same 2.4 GHz network the device will use. The Network Commissioning cluster has status codes that point at this: NetworkNotFound, AuthFailure for a wrong password, and RegulatoryError for a band or channel mismatch such as 2.4 GHz against 5 GHz.
4. There is no Thread border router, or the phone does not have its credentials. A Thread device needs a border router near it. Home Assistant’s error “this device requires a border router” is fixed by setting one up and syncing its Thread credentials to the phone.
5. The network blocks discovery. Home Assistant says Matter relies on local IPv6 and mDNS multicast moving freely, and may not work with VLANs, multicast filtering or misbehaving IGMP snooping. Keep the commissioner, the device and any border router on one flat network, and turn off router settings that “optimize” multicast.
6. Attestation fails. Test boards and developer firmware use test certificates, so production ecosystems refuse them or ask for confirmation. On an iPhone, Home Assistant’s documentation says you may see an “Uncertified Accessory” prompt with an Add Anyway option. For development, chip-tool has flags to supply your own PAA trust store.

Offline Protocol does not commission Matter devices and is not a Matter controller. The idea at the heart of commissioning, a short-range setup step that bootstraps long-lived keys, does appear in how the SDK pairs a phone with a constrained “leaf” device: the phone creates an MLS group and the device joins it with a key package sent over the shared radio. The leaf crate’s documentation is explicit that this pairing proves who a peer is, not that the owner meant it, since “any address in radio range can complete a pairing, so firmware decides when the radio accepts one”. The crate compiles for chips such as the ESP32-C6 and Cortex-M33, but has not yet been run on a board. Offline Protocol for embedded devices describes it.