Scott-Files/matterdecode
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated to be pure bash and remove references to the web pages.

Browse Source
This commit is contained in:
Scott Garrett committed 2026-09-01 17:40:24 -04:00
1 parent 589ebaff46
commit f56678833e
7 files changed
+133 -1719
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CLAUDE.md
+109 -146
View File
@@ -7,136 +7,121 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
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:
`homekit-decode.sh`). For Matter, a user runs `matter-decode.sh` with an `MT:`
URI (as a positional argument or on stdin); it decodes the 84-bit payload and
prints the fields — version, vendor/product IDs, commissioning flow, discovery
capabilities, discriminator, passcode, and the derived manual pairing code. 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).
- `matter-decode.sh` — the pure-bash CLI Matter decoder. Takes an `MT:` URI as an
argument or on stdin and prints the decoded fields. It has no camera/QR-scanning
(that was the only feature the former browser app added, and it is gone).
- `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).
*different* format from Matter's `MT:`). 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), consumed by
`matter-decode.sh`; 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.
another URL or a local XML file. 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
`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.
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
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
`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`.
(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:
There is **no build, test, lint, or package step** — this is not a build project.
The two decoders are standalone bash scripts and the two `gen-*.py` are Python 3
stdlib regenerators; nothing is compiled or bundled.
- 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.
- Run the Matter decoder: `./matter-decode.sh "MT:..."`, or pipe it:
`echo "MT:..." | ./matter-decode.sh`.
- Run the HomeKit decoder: `./homekit-decode.sh [code]` (with no argument it
decodes the demo payload `005KEOUCE`).
- Regenerate `manufacturers.tsv`: `python3 gen-manufacturers.py` pulls the
pinned upstream `manufacturers.xml` over the network; pass a URL or a local
`.xml` file to use a different source.
- Regenerate LIFX's `products.tsv` rows: `python3 gen-lifx-products.py` (network
by default; a positional URL or local `.json` overrides).
- The decoders read their companion TSVs (`manufacturers.tsv`, `products.tsv`,
`vendor-equivalents.tsv`) from their own directory; a missing TSV drops that
extra lookup — it is never an error.
- Pure bash (3.x+); the `gen-*.py` scripts need only the Python 3 standard
library.
## Architecture
Everything lives in `matter-qr-decoder.html` (~1500 lines). Two regions matter:
The decode logic lives directly in the bash scripts — there is no shared library,
no embedded data map, and no build output. There are two decoders, and they
decode **two different on-wire formats**, so they are independent and should not
be unified.
1. **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.
2. **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.
### matter-decode.sh — the Matter `MT:` pipeline
### Decode pipeline (the core)
`decodeUri()` (triggered live on input) runs, in order:
`main()` decodes a URI given as an argument or read from stdin, in order:
1. Validate the `MT:` prefix, then take the base38 payload after it.
2. `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`).
3. `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):
2. Base38-decode it to bytes. The 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 errors. Bytes are extracted **little-endian**
(`value & 0xFF`, then `>>= 8`).
3. Read the 84-bit field layout **LSB-first**. Fixed field order/widths (see the
"Data Encoding Format" table in `README.md` for the source of truth):
version(3), vendor ID(16), product ID(16), custom flow(2), discovery caps(8),
discriminator(12), passcode(27).
4. Display helpers translate raw numbers: `getCustomFlowName`, `getDiscoveryCapabilities`
(bit flags: SoftAP / BLE / On IP Network), `formatVendorId`/`formatProductId`
(decimal + `0x`-hex padded to 4).
4. Display helpers translate the raw numbers: a custom-flow name, discovery
capabilities (bit flags: SoftAP / BLE / On IP Network), and decimal + `0x`-hex
(padded to 4) for the vendor/product IDs.
### Vendor name lookup
### Vendor / product / equivalence lookups (matter-decode.sh only)
`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.
Three optional companion TSVs add names on top of the raw decode; each degrades
silently (a missing file drops its extra, never an error):
### Product name lookup + vendor equivalences (bash only)
- **`manufacturers.tsv`** (`vendor ID \t name`) — resolves the decoded vendor ID
to a name, printed on the Vendor ID line.
- **`products.tsv`** (`vendor ID \t product ID \t name`) — resolved via
`get_product_name VENDOR PRODUCT`, which checks the exact vendor first, then
every equivalent; first match wins.
- **`vendor-equivalents.tsv`** (`alias \t canonical`, `#` lines ignored,
canonical-form: the canonical id never appears in col 1) — resolved via
`equivalent_vendor_ids VENDOR`, which returns the whole equivalence class
(the vendor plus every alias sharing its canonical id, sorted). The *other*
class members' names are joined and appended to the Vendor ID line 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.
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.
`get_product_name` must `return 0` on a miss: under `set -e`, a non-zero status
in the `pname=$(...)` substitution would abort the script before anything prints.
`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)
### Manual pairing code (matter-decode.sh 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
@@ -144,27 +129,26 @@ 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.
(`chill-uk/matter-qr-app`, `web/app.js`).
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).
(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.
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 setup-code decode (homekit-decode.sh)
`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
setup. That is a different on-wire format from Matter's `MT:`, so this is
**not** a port of `matter-decode.sh`'s pipeline; it is standalone, with 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
@@ -182,11 +166,11 @@ stderr, exit 1). `val` is then sliced **LSB-first** into the HomeKit layout:
- `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.
`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
@@ -199,41 +183,20 @@ The header comments in `homekit-decode.sh` record each fix (the categoryId / fla
## 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.
- `matter-decode.sh` (Matter `MT:`, **base38**) and `homekit-decode.sh`
(HomeKit `X-HM://`, **base36**) decode *different* on-wire formats. Don't try
to unify the two decoders; when editing `homekit-decode.sh`, keep the
corrected bit layout (`pin / flag / categoryId / reserved / version`) as the
source of truth.
- `manufacturers.tsv` is the *only* copy of the vendor map now. Regenerate it with
`gen-manufacturers.py`: the 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), pinned to the same commit the
committed TSV was generated from, so it reproduces the TSV byte-for-byte. A
positional arg overrides with another URL or a local XML file.
- The product-name lookup and vendor equivalences live **only in
`matter-decode.sh`** — `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.