Commissioning / pairing code
Commissioning is Matter’s standardized setup process: scan the QR code (or type the 11-digit numeric code) printed on the device, and the controller securely verifies the device, joins it to your Wi-Fi or Thread network, and installs its fabric credentials. Every Matter device ships with such a code, and it is worth keeping.
Under the hood, the code carries a discriminator and a passcode used to establish an encrypted session, usually over Bluetooth LE for first contact. The controller checks the device’s attestation certificate against CSA certification records, provisions network credentials, and adds the device to its fabric. The whole flow is defined by the spec, which is why setup looks the same whether the app is Apple Home or Google Home.
Practical notes: the printed code can normally be reused after a factory reset, so do not throw away the sticker or manual — though some devices generate a code dynamically in an app or on a display instead. Adding a device to a second ecosystem does not use the printed code; the first ecosystem generates a temporary one (see multi-admin). Zigbee and Z-Wave have their own, different pairing procedures — this entry is Matter-specific.
| Manual code length | 11 digits for the standard flow; 21 digits for custom commissioning flows |
|---|---|
| QR payload | A base-38 string prefixed “MT:”, carrying vendor ID, product ID, discriminator, and passcode |
| Passcode / discriminator | 27-bit setup passcode, 12-bit discriminator used to pick the right device out of several |
| First contact | Bluetooth LE for Wi-Fi and Thread devices; straight over IP for Ethernet devices |
| Key exchange | PASE using SPAKE2+, then a permanent CASE session on certificates |
| Attestation check | Device Attestation Certificate verified against roots published in the CSA ledger |
What is actually printed on that sticker
The QR code is a base-38 encoded payload beginning “MT:”. It carries the specification version, the manufacturer’s vendor ID and product ID, a 12-bit discriminator, a 27-bit setup passcode, and flags describing how the device can be discovered — BLE, on-network, or soft-AP. The 11-digit numeric code is the same information minus the vendor and product identifiers, which is why typing it works but is slightly slower to resolve.
The discriminator exists to solve a mundane problem: if you unbox four identical sensors at once, four identical BLE advertisements appear. The discriminator lets the commissioner pick the one whose code you scanned. The passcode is the shared secret that proves you physically hold the device.
Some devices never print a code. Products with a display or a companion app can generate one dynamically, and a few use NFC instead of a QR code. Everything else should have the sticker in at least two places — on the device and in the manual — and it is worth photographing both before the device goes on a ceiling.
The handshake, in order
A factory-fresh device advertises over Bluetooth LE. The commissioner finds it by discriminator and runs PASE, a SPAKE2+ exchange that turns the printed passcode into an encrypted session without ever transmitting the passcode itself. Ethernet devices skip BLE entirely and are found on the network directly.
Inside that session the controller asks the device for its Device Attestation Certificate and verifies the chain against the Product Attestation Authority roots published in the Distributed Compliance Ledger. This is the step that distinguishes a certified device from something merely claiming to be one, and it is why uncertified firmware ports often fail here with a vague “cannot verify this accessory” message.
The controller then hands over network credentials — a Wi-Fi SSID and password, or a Thread operational dataset — installs its fabric’s operational certificate, and closes the BLE session. The device joins the real network, re-announces itself over mDNS, and the controller opens a CASE session against the new certificate. Only then does it read the device’s endpoints and clusters and build the UI you see. The whole sequence normally takes 30 to 90 seconds.
Why commissioning fails, in order of likelihood
The most common cause is a network that will not carry the traffic. Matter needs IPv6 enabled on the LAN and multicast/mDNS allowed between the phone, the controller, and the device. Guest networks, client isolation, and VLAN separation between your phone and your hub all produce the same symptom: the device joins the network and then “cannot be found”.
Second is the 2.4 GHz problem. Most Matter Wi-Fi devices are 2.4 GHz-only, and if your router splits bands into separate SSIDs, the phone sitting on 5 GHz hands over credentials the device cannot use. Either merge the bands temporarily or connect the phone to the 2.4 GHz SSID for the duration of setup.
Then the mundane ones: Bluetooth switched off or permission denied on the phone; a Thread device with no border router online; a device that is not actually factory-fresh, because it still holds a fabric from a previous owner or a previous attempt; and a commissioning window that expired while you were reading the manual. Factory-reset the device and start again — Matter commissioning is idempotent and there is no penalty for retrying.
Frequently asked questions
What is the 11-digit code on a Matter device?
It is the manual pairing code — the same setup information the QR code carries, encoded for typing. Use it when the QR code is damaged, unreachable on an installed device, or your phone camera will not focus on it. It contains the discriminator and setup passcode, so treat it as a secret: anyone who has it and physical proximity can commission the device.
Can I reuse a Matter QR code after a factory reset?
Almost always, yes. The setup passcode is burned into the device at manufacture, so a factory reset returns the device to a commissionable state that the original code still opens. The exceptions are devices that generate codes dynamically in an app or on a display. Keep the sticker and the manual regardless.
Why does Matter setup need Bluetooth?
Because a factory-fresh Wi-Fi or Thread device is not on any network yet, so there is no IP path to it. Bluetooth LE is the out-of-band channel used to prove you hold the device and to hand over network credentials. Once the device is on the network, Bluetooth is no longer used — control runs entirely over Wi-Fi, Ethernet, or Thread.
I lost the Matter setup code. Can I still add the device?
If the device is already commissioned in one ecosystem, yes — use that app to open a pairing window and generate a fresh code for any further ecosystems. If it is not commissioned anywhere and the code is gone from the device, the manual, and the app, some manufacturers will supply it against a serial number, but many will not, and the device may be unusable.
My Matter device joins Wi-Fi and then fails. What is wrong?
That failure point almost always means the device reached the network but the controller could not discover it afterwards. Check that IPv6 is enabled on your router, that mDNS/multicast is not being filtered, and that the phone, controller, and device are on the same subnet with no client isolation. Mesh Wi-Fi systems with aggressive band steering and IoT VLANs are the usual offenders.