What's in the Matter Box: Setup Code, QR Code and the First-Pair Experience

What a Matter setup code is

A Matter setup code is the unique numeric or scannable credential associated with a device — printed on or inside its packaging — that lets a Matter controller commission the device into a fabric during onboarding. It is not a password in the account sense; it is a commissioning credential. Structurally it pairs two pieces: a short discriminator, which the controller uses to discover the right device among others nearby, and a longer passcode, which proves the controller is pairing the intended unit and not a different device in the next apartment. Together they let two strangers — a phone and a sensor — establish a trusted first meeting without any prior shared account.

QR code vs manual pairing code

The QR code and the manual pairing code carry the same payload: the QR encodes the setup payload — discriminator and passcode, and optionally the vendor and product IDs — so a phone camera reads it in one step, while the manual code is the same information typed as a string, typically an 11-digit code or a longer 21-digit code when vendor and product IDs are included. The QR is simply the faster, lower-error path; the manual code is the fallback for a smudged label or a camera that will not focus. A well-built product ships both, because the moment a customer cannot read either, the device is a paperweight on the shelf.

Where the setup code lives, and the factory's provisioning role

The setup code is bound to the device's factory data — the per-unit credentials written at manufacture that also include the Device Attestation Certificate chain — so the printed code, the on-device attestation and the Distributed Compliance Ledger entry all refer to the same device identity. This binding is the part most people never see and most factories under-estimate. The code is not a label we print from a spreadsheet; it is the human-readable face of credentials that the connectivity module carries in secure storage. A standard CSA-certified Matter connectivity module handles the attestation chain, but the pairing between that chain and the printed code is a line discipline the factory owns.

In practice the code is placed where it stays with the unit through its life: on the product label, on a card inside the box, or surfaced in the companion app after sign-in. For a battery sensor the body or inner packaging is the common choice. The factory's job is to generate the per-unit credentials, print the matching code, and verify the pair on the production line — and the exact provisioning flow depends on the module and the certification body, so we confirm the match on the line rather than assuming it held.

The first-pair journey, step by step

Seen from the customer's side, onboarding is short but unforgiving:

First the user opens their controller app and scans the QR code; the app reads the setup payload and discovers the device by its discriminator. The controller and device then run the commissioning handshake (PASE) to establish a first trusted session, the device is added to the fabric, and a second session (CASE) secures all later communication. The device then appears as its Matter device type or types, and local control works without any cloud. Each step depends on the previous one, which is why a single broken link — a mismatched code, an unsupported controller version, a missing Thread border router for a Thread device — turns the whole flow into a support ticket. The customer does not care which link broke; they only know the sensor will not join.

Onboarding friction and what the factory controls

Most "won't pair" tickets trace to a short list of causes, and the factory controls more of them than brands assume. A mismatch between the printed code and the device's factory data is a manufacturing defect, not a user error, and is caught by an end-of-line commissioning check in which every unit is actually paired into a test fabric before it ships. A damaged or unreadable QR, a module that was never commissioned in the test fabric, or an attestation chain that does not resolve all produce the same symptom — a device that looks fine and will not join — so the line discipline around setup codes is part of quality, not decoration. What the factory cannot control is the customer's controller version or their home network; those are documented in the onboarding guide we ship with the product.

Factory stance: we print and verify, we do not relabel

Shenan Yangguang designs, prototypes, validates and mass-produces Matter security hardware. We hold and support the certification programmes for the products we build, and we do not relabel a third party's product. For onboarding we generate and verify the setup code against each unit's factory data on the line, run every device through a commissioning check, and ship an onboarding guide that names the controller and border-router requirements up front. We build the product and its identity; we do not stamp someone else's unit with our label and call it done. For the failure modes behind a "won't join" ticket, our commissioning troubleshooting note goes deeper, and our fabric-security piece explains the PASE and CASE handshakes the setup code sets in motion.