How Does the Matter QR Code Work?

Love ‘em or hate ‘em, QR codes are apparently here to stay. From guerilla street marketing sprayed on the side of buildings, to making payments, QR codes have become ubiquitous. They’re also a key component of the Matter smart home standard, encoding everything you need to pair a Matter device with your home—using just your smartphone camera. 

But before we discuss exactly how Matter uses QR codes, we should probably explain what a QR code is. 

What is a QR Code?

Invented in 1994 by a Japanese company, QR (Quick Response) codes are an evolution of the machine-readable barcode. But while a barcode is one-dimensional (read along a single line), QR codes are two-dimensional: they can be read both vertically and horizontally. 

QR codes are more complex and, therefore, more data-dense, meaning they can store a lot more information than a barcode. This means you can encode things like a web URL, contact details, or Wi-Fi password, rather than just a short string of numbers. Here’s an example of data encoded as Wi-Fi access details:

WIFI:S:MySSID;T:WPA;P:MyPassW0rd;;

The data density of QR codes also allows you to store error-correction data. With a 1D barcode, if you lost the last few lines off, it’s unreadable. With a QR code, anywhere from 7 to 30% of the data can be scratched off or lost without issue: spare data is used to correct the missing parts. You can choose how much when creating the code. Here's one I defaced earlier—try scanning it, and you should see that it still works:

What Does a Matter QR Code Contain?

If you use a QR code reader that can tell you the raw data stored on a Matter pairing QR code, you’ll find something like this: 

MT:Y.K9042C00KA0648G00

The “MT:” at the start tells us (and your smartphone) that this is a Matter code, so it knows to open the appropriate app and start pairing. The rest of the (19) alphanumeric numbers are Base38 encoded, but can be broken down into the following parts:

• Version: a basic number telling us which version or the QR code for Matter it’s using, in case future Matter versions change the QR code format in some way.
• Vendor and Product ID: This tells us who made the product, and a unique identifier for the product. You can view the full list of vendors on the Distributed Compliance Ledger, as well as registered products (Models)
• Commission Flow: This is a multiple-choice option that tells the commissioning software how the product should be set up—either basic, user intent (you need to press a button on the device to confirm), or some other custom option.
• Discovery capabilities: this tells your smart home app how the device can be found. Is it broadcasting over Bluetooth Low Energy (BLE), Wi-Fi, both, or something else.
• Discriminator: just a unique number to discriminate between similar devices.
• PIN code: This is a numeric password 8 digits long. 

Note that the number shown beside the QR code on a Matter device is not the same as the PIN code. Instead, it’s a manual pairing code, generated in much the same way as the QR code data, but not identical as it stores less data. 

You can decode the contents of the QR code yourself by downloading and running the Project CHIP toolchain (“Connected Home IP”, which was the previous name of Matter). After downloading the project, navigate to the /src/setup_payload/python directory and run the SetupPayload.py tool with the argument “parse” (be sure to adjust the directory if you placed it somewhere else):

python SetupPayload.py parse MT:Y.K9042C00KA0648G00

• Flow: 0
• Pincode: 20202021
• Short Discriminator: 15
• Long Discriminator: 3840
• Discovery Capabilities: 2
• Vendor Id: 65521  (0xfff1)
• Product Id: 32768  (0x8000)

This is a test Vendor and Product ID, which can be used to test uncertified devices (which we’ll have a tutorial on at some point). 

We can try again with the manual pairing to see what that stores:  

SetupPayload.py parse 34970112332

• Flow: 0
• Pincode: 20202021
• Short Discriminator: 15

The Vendor ID and Product ID are not included in the manual pairing code, nor is the Long Discriminator.

Still, it contains enough to set up the device, whether you use the manual pairing code or the QR code. The full QR code just makes it a bit easier. 

Matter QR Codes: Fantastic (When It Works)

When it works right, adding a Matter device to your smart home system is brilliantly simple: scan the QR code, name the device, and add it to a room. But underneath the surface, there's a lot going on—and a few things that might go wrong. But at least now you know just what that QR code contains. 

I'm still in shock that there are legitimate uses for QR codes other than Rickrolling people.