# Matter QR Code Decoder Decode the commissioning QR code that Matter / CHIP devices ship with. A Matter device's setup QR encodes a short `MT:` URI that carries the information a commissioning app (e.g. Apple Home, Google Home, the Matter app) needs to pair with the device for the first time. This tool takes that URI and shows you what is inside. No build, no install, no package step. Two ways to use it: a browser app and a command-line script that share the same decode logic. ## What it decodes Given an `MT:` URI, the payload (84 bits, see [Data format](#data-format)) is split into these fields: | Field | Meaning | |---|---| | **Version** | Encoding version (3 bits) | | **Vendor ID** | 16-bit manufacturer identifier, shown as decimal + `0x`-hex, with a name looked up from `manufacturers.tsv` when available | | **Product ID** | 16-bit vendor-assigned product identifier, decimal + `0x`-hex | | **Custom Flow** | Commissioning flow type: 0 = Standard, 1 = User Intent, 2 = Custom, 3 = Reserved | | **Discovery** | How the device can be found: **SoftAP** / **BLE** / **On IP Network** (a bitset — a device may show more than one) | | **Discriminator** | 12-bit discriminator | | **Passcode** | 27-bit commissioning passcode | ## Components | File | What it is | |---|---| | [`matter-qr-decoder.html`](matter-qr-decoder.html) | The browser app. Single self-contained HTML file (Vue 3 + Bootstrap 5.3, loaded from CDNs). | | [`matter-decode.sh`](matter-decode.sh) | A pure-bash CLI port of the same decode logic. No camera scanning. | | [`manufacturers.tsv`](manufacturers.tsv) | Tab-separated `vendor ID → name` table (~900 rows) used to turn a numeric vendor ID into a name. Shared by both tools; optional. | | [`gen-manufacturers.py`](gen-manufacturers.py) | Python 3 script that regenerates `manufacturers.tsv`; pulls the upstream `manufacturers.xml` over the network by default (or a URL/local file/HTML block you pass in). | `CLAUDE.md` documents the internals for anyone (or Claude Code) working on the code. --- ## Browser app ### Requirements - A modern browser with network access (the page loads Vue 3, Bootstrap 5.3, and Bootstrap Icons from CDNs). - Camera scanning needs a **secure context** — serve it over `HTTPS` or `localhost`, not `file://`: ```sh python3 -m http.server 8000 # then open http://localhost:8000/matter-qr-decoder.html ``` ### Use it 1. Paste an `MT:` URI into the **Input** box — decoding happens live as you type. 2. Or click **Scan QR** and point your camera at the code. Scanning stops itself the moment it reads an `MT:` QR. Two caveats: - **Scan QR is Chromium-only** (Chrome / Edge). It uses the `BarcodeDetector` API. Firefox and Safari show a "not supported" message — **pasting a URI works everywhere**, so use that on those browsers. - The **Data Encoding Format** and **Discovery Capabilities Bits** sections at the bottom of the page explain the layout shown in the output. --- ## Command line `matter-decode.sh` decodes a URI from an argument or from stdin and prints the same fields as the web UI: ```sh ./matter-decode.sh "MT:..." echo "MT:..." | ./matter-decode.sh ``` Example output (run the URI through the script to reproduce): ``` $ echo "MT:O083635783973181337368400343813154179" | ./matter-decode.sh Version: 0 Vendor ID: 13012 (0x32D4) Product ID: 50616 (0xC5B8) Custom Flow: User Intent Commissioning Flow Discovery: BLE Discriminator:1723 Passcode: 8126392 ``` (The vendor ID `0x32D4` isn't in `manufacturers.tsv`, so no name is printed — that's expected, not an error.) The script is pure bash (3.x+). It reads `manufacturers.tsv` from its own directory to resolve the vendor name; without that file every field still decodes and only the vendor name is omitted. --- ## Data format The URI is `MT:` followed by a **base38** payload (charset `0-9 A-Z - .`, 38 symbols). The payload decodes to bytes, read **little-endian**, then sliced into the 84-bit field layout **LSB-first**: ``` version(3) | vendor ID(16) | product ID(16) | custom flow(2) | discovery caps(8) | discriminator(12) | passcode(27) ``` Base38 decoding is greedy: 5 chars → 3 bytes, 4 → 2, 2 → 1; a length that fits none of those groupings is an error. Both the HTML app and the shell script use this same scheme, which is why the two stay in lockstep. ## Vendor name lookup Both tools map a numeric **Vendor ID** to a name using `manufacturers.tsv` (`vendor ID` in the first column, name in the second). The table is derived from upstream `project-chip/connectedhomeip .../zcl/data-model/manufacturers.xml` (Apache-2.0, generated 2022-08-02). **Refresh it from upstream rather than hand-editing individual rows.** To refresh the table, run **`gen-manufacturers.py`** (Python 3 standard library only). By default it **pulls the upstream `manufacturers.xml` over the network** (via `curl`) and writes the sorted two-column TSV (`decimal id \t name`) to `manufacturers.tsv`: ```sh python3 gen-manufacturers.py ``` The source is pinned to the same commit the HTML block was generated from, so a fresh pull reproduces the current `manufacturers.tsv` exactly. To refresh from a different upstream revision, pass a source — a URL (a GitHub `blob/` URL is auto-rewritten to its `raw.githubusercontent.com` form) or a local XML file: ```sh python3 gen-manufacturers.py https://.../manufacturers.xml python3 gen-manufacturers.py ./manufacturers.xml ``` No network? Use the embedded block as the source instead: ```sh python3 gen-manufacturers.py matter-qr-decoder.html ``` The same table is also embedded as a `` XML block near the end of `matter-qr-decoder.html` (marked "do not edit manually"). This script regenerates only the TSV, so if you refresh the TSV from new upstream XML, also paste that XML into the HTML's `