CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A collection of Matter commissioning QR decoders (the MT: URI format used by Matter/CHIP devices), plus a standalone bash decoder for Apple HomeKit setup codes (the X-HM:// payload — a different on-wire format, in homekit-decode.sh). For Matter, users either paste an MT: URI or scan a QR code; the result shows the decoded payload (version, vendor/product IDs, commissioning flow, discovery capabilities, discriminator, passcode). Key files:

matter-qr-decoder.html — the single-file browser app (Vue 3 + Bootstrap).
matter-decode.sh — a pure-bash CLI port of the same decode logic (no camera scanning; takes a URI as an argument or on stdin).
homekit-decode.sh — a standalone pure-bash decoder for Apple HomeKit setup codes (the X-HM:// payload an accessory shows on first setup — a different format from Matter's MT:). No browser counterpart and no companion TSV (the accessory-category table is inlined). See the HomeKit setup-code decode section below.
manufacturers.tsv — vendor ID → name table (~900 rows), shared by both tools and optional (a missing file only drops the vendor-name lookup).
gen-manufacturers.py — Python 3 stdlib script that regenerates manufacturers.tsv. Default source is the upstream manufacturers.xml fetched over the network (via curl; a GitHub blob/ URL is auto-rewritten to its raw.githubusercontent.com form). A positional arg overrides with another URL or a local XML file; passing matter-qr-decoder.html uses the embedded <map> block as an offline fallback. Reproduces the committed TSV byte-for-byte.
products.tsv — 3-column vendor ID → product ID → name table, consumed by matter-decode.sh's get_product_name(): when the decoded vendor ID (or an equivalent, see vendor-equivalents.tsv) is present, the product ID is resolved to a name and printed on the Product ID line. LIFX's rows are keyed under 4870. Optional — a missing file only drops the product-name lookup.
vendor-equivalents.tsv — 2-column alias vendor ID → canonical vendor ID table, hand-edited, recording companies that are the same after a merger/acquisition (e.g. Feit 5155 → LIFX 4870). Used by matter-decode.sh so a product resolves under either ID and the vendor name is annotated (a.k.a. ...). #-comment lines are ignored. Optional.
gen-lifx-products.py — Python 3 stdlib script that regenerates LIFX's rows (vendor 4870) in products.tsv. Default source is LIFX's upstream products.json fetched over the network (via curl, falling back to urllib); a positional arg overrides with another URL or a local .json file. It merges LIFX's rows into products.tsv (dropping LIFX's old rows, preserving every other vendor's), so re-running it is safe alongside other vendors' generators. Caveat: products.json carries only a pid per product (no separate Matter/CHIP product-id field), so the lookup assumes LIFX's Matter product ID equals their pid.
README.md — user-facing docs; this file documents the internals.

Commands

There is no build, test, lint, or package step — this is not a git repo and has no package.json. The entire app is one HTML file that runs in the browser:

Run/develop: open matter-qr-decoder.html in a modern browser and edit it directly.
Camera scanning (getUserMedia) requires a secure context — serve over HTTPS or localhost (e.g. python3 -m http.server then open http://localhost:8000).
The "Scan QR" feature uses the BarcodeDetector API, which is Chromium-only (Chrome/Edge). Firefox/Safari fall back to a "not supported" message; paste-input works everywhere.
The page loads Vue 3, Bootstrap 5.3, and Bootstrap Icons from CDNs, so it needs network access.

Architecture

Everything lives in matter-qr-decoder.html (~1500 lines). Two regions matter:

App logic (the <script> before #app is mounted, ~lines 255-559): a single Vue.createApp({...}) mounted to #app, with all state in setup() via ref/computed. The UI template (lines ~26-253) is plain HTML using v-model/v-if/v-on bindings, no SFC or build step.
Vendor map (<script type="text/xml">, ~lines 560-1495): a <map> of <mapping code="0xXXXX" translation="Name"/> entries. This block is the bulk of the file. It is derived from upstream project-chip/connectedhomeip .../zcl/data-model/manufacturers.xml (Apache-2.0, generated 2022-08-02) and carries an "do not edit manually" note — refresh it from upstream rather than hand-editing individual rows.

Decode pipeline (the core)

decodeUri() (triggered live on input) runs, in order:

Validate the MT: prefix, then take the base38 payload after it.
base38Decode(str) → Uint8Array. Charset is 0-9A-Z-. (38 chars). Chunking is greedy: 5 chars→3 bytes, 4→2, 2→1; a length that doesn't fit those groupings throws Invalid base38 string length. Bytes are extracted little-endian (value & 0xFF, then >>= 8).
extractBits(bytes, startBit, bitCount) reads the 84-bit field layout LSB-first. Fixed field order/widths (see the in-page "Data Encoding Format" table for the source of truth): version(3), vendor ID(16), product ID(16), custom flow(2), discovery caps(8), discriminator(12), passcode(27).
Display helpers translate raw numbers: getCustomFlowName, getDiscoveryCapabilities (bit flags: SoftAP / BLE / On IP Network), formatVendorId/formatProductId (decimal + 0x-hex padded to 4).

Vendor name lookup

getVendorName(id) → parseVendorMappings() lazily parses the embedded XML once (cached on vendorMap, a let inside setup()) via DOMParser, keyed by parseInt(code, 16). It is exposed reactively through the vendorName computed, so the lookup re-runs when the decoded vendor ID changes.

Product name lookup + vendor equivalences (bash only)

Unlike the vendor-name lookup, the product-name lookup and the vendor-equivalence table live only in matter-decode.sh — the browser app has neither. This is a deliberate, documented divergence from the usual "keep the two in lockstep" rule, chosen because the product catalog and the equivalence list change more often than the vendor map and are not yet worth embedding in the static HTML.

matter-decode.sh defines two helpers:

equivalent_vendor_ids VENDOR — resolves VENDOR to its whole equivalence class via vendor-equivalents.tsv (2 cols alias \t canonical, # lines ignored, canonical-form: the canonical id never appears in col 1). It prints the vendor itself plus every alias sharing its canonical id, sorted. A missing vendor-equivalents.tsv yields just the vendor.
get_product_name VENDOR PRODUCT — checks products.tsv (3 cols vendor \t product \t name) for the exact vendor first, then every equivalent; first match wins. A missing products.tsv yields no name. It must return 0 on a miss: under set -e, a non-zero status in the pname=$(...) substitution would abort the script before anything prints.

In main(), the product name (pname) is printed on the Product ID line via the same [[ -n $pname ]] && printf pattern the vendor name uses. The vendor name is annotated with its equivalents: the other class members' names (from manufacturers.tsv) are joined and appended as (a.k.a. X, ...), so a Feit (5155) device reads Feit Electric Company, Inc. (a.k.a. Lifi Labs INC. dba LIFX) and a LIFX (4870) device reads the mirror image. Both products.tsv and vendor-equivalents.tsv are optional; a missing file only drops its extra.

gen-lifx-products.py regenerates LIFX's rows into products.tsv by merging (dropping only vendor 4870's rows, preserving others). To add another vendor, write a sibling gen-<vendor>-products.py that parses that vendor's catalog and merges its rows — keyed under its own vendor ID — into the same products.tsv; then add that vendor's equivalences (if any) to vendor-equivalents.tsv. Mirroring this into the HTML app is the natural next step if it is wanted.

Manual pairing code (bash only)

matter-decode.sh also prints a Pairing Code: line: the Matter manual pairing code — the PIN a commissioning app (Apple Home, Google Home, the Matter app) asks you to type. It is not a raw payload field; it is derived from the passcode and discriminator and, for non-standard commissioning flows, the vendor/product IDs, then guarded by a Verhoeff check digit. This is a port of generateManualPairingCode() from the standalone "Matter QR Code Tool" (chill-uk/matter-qr-app, web/app.js); the browser app in this repo has neither this nor the product/equivalence lookups, so like them it is bash-only.

Two helpers, defined just above main():

verhoeff_check_digit DIGITS — the Verhoeff check digit over a decimal string (the three standard Verhoeff tables are inlined; digits are processed right-to-left, as the reference does).
compute_pairing_code VENDOR PRODUCT FLOW DISCRIMINATOR PASSCODE — assembles the code. The 12-bit discriminator contributes its top 4 bits; the 27-bit passcode is split into its low 14 and high 13 bits; non-standard flows (user-intent 1, custom 2) append 5-digit vendor and product groups. Result: 11 digits for the standard flow, 21 otherwise, plus the check digit.

HomeKit setup-code decode (bash only)

homekit-decode.sh is a second, independent decoder — for Apple HomeKit setup codes, the X-HM:// payload an accessory (or its packaging) shows on first setup. That is a different on-wire format from Matter's MT:, so this is not a port of the HTML app's pipeline; it is standalone, with no browser counterpart and no companion TSV (the accessory-category table is inlined). It sits alongside matter-decode.sh as the repo's other CLI decoder.

Input is an optional positional argument, defaulting to the demo payload 005KEOUCE. A leading X-HM:// is stripped if present. The first 9 characters are the fixed parameter block; anything after them is a variable-length setup id, carried through verbatim (it is not part of the numeric block).

Unlike Matter's base38 payload (charset 0-9 A-Z - ., 38 symbols), the HomeKit block is base36 (0-9 A-Z, 36 symbols): each char does val = val*36 + digit, and an out-of-range character is a hard error (to stderr, exit 1). val is then sliced LSB-first into the HomeKit layout:

pin(27) | flag(4) | categoryId(8) | reserved(4) | version(3)

flag is a 4-bit sub-flag set — 1=NFC, 2=IP, 4=BLE, 8=WAC/MFi — printed as True/False lines.
categoryId is resolved to its HAP homekit_accessory_category_* name (e.g. 5 → "Lightbulb", 8 → "Switch") via an inlined case; an id not in the table prints "unknown" (id 25 is reserved by HomeKit, so it is unknown by design, and "Heater" corrects a "Header" typo in the source table). A case rather than an associative array is used on purpose so the script runs on the stock macOS bash 3.2 that #!/usr/bin/env bash resolves to.
The decoded fields are packed back into a 9-char block (mirroring composeSetupUri's stepwise packing) and printed as a reconstructed X-HM://… payload, so the output is a complete record the barcode can be rebuilt from.

This is the corrected bit layout — the one composeSetupUri in the homekit-code package actually encodes — rather than a misaligned earlier one. The header comments in homekit-decode.sh record each fix (the categoryId / flag / version positions, and the dropped "Thread" misread of categoryId bits).

Gotchas

The BarcodeDetector scanner polls the camera via setInterval every 200ms and auto-stops the first time it sees a QR starting with MT:; stopScanning() clears the interval and stops the media tracks — keep those paired when changing scanning.
parseVendorMappings short-circuits on a non-empty vendorMap; if you add a mechanism to update the map, clear/reset that cache or new codes won't be seen.
The relative links /tools/ and / (header/footer) imply this page is deployed as part of a larger static site (Tommie Gannert's blog/tools), but that site isn't in this repo.
matter-decode.sh is a bash port of the HTML app's decode pipeline, kept in lockstep with it — the base38 charset/chunking, little-endian byte extraction, and the 84-bit LSB-first field layout are identical. When you change the decode logic in the HTML app, mirror it in the script (and vice versa). The script's extras are the optional manufacturers.tsv (vendor name), products.tsv (product name), and vendor-equivalents.tsv (vendor equivalences); without any of them it still decodes everything else.
homekit-decode.sh is not part of that lockstep: it decodes a different on-wire format (Apple HomeKit X-HM://, base36 — not Matter's base38) and has no HTML-app counterpart. Don't try to unify the two decoders or mirror HomeKit changes into the HTML app; when editing it, keep the corrected bit layout (pin / flag / categoryId / reserved / version) as the source of truth.
manufacturers.tsv is regenerated with gen-manufacturers.py (Python 3 stdlib). Default source is the upstream manufacturers.xml fetched over the network (via curl; a GitHub blob/ URL is auto-rewritten to its raw.githubusercontent.com form). A positional arg overrides with another URL or a local XML file, and passing matter-qr-decoder.html uses the embedded <map> block as an offline fallback. The default fetch is pinned to the same commit the HTML block came from, so it reproduces the committed TSV byte-for-byte. Caveat: the script writes only the TSV — the embedded <script type="text/xml"> block in the HTML app has the same upstream provenance and a "do not edit manually" note, so refreshing the TSV from new upstream XML leaves the HTML copy stale. Refresh both from the same source.
The product-name lookup and vendor equivalences are bash-only — matter-decode.sh has them, the browser app does not, so this is one place the two are not in lockstep (deliberate, for now). products.tsv and vendor-equivalents.tsv are optional and degrade silently (a missing file means no name / no equivalent, never an error). vendor-equivalents.tsv is canonical-form, one hop: the canonical id must not itself appear in col 1. get_product_name must return 0 on a miss or set -e aborts the decode. Mirror these into the HTML app (a second embedded map plus a productName / equivalentVendorName computed) only if that is wanted.

15 KiB Raw Blame History