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

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

No files matched your search

+16 -59
View File
@@ -6,13 +6,13 @@ 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.
No build, no install, no package step. A command-line script decodes the Matter
`MT:` payload for you.
There is also a separate, standalone command-line decoder for Apple **HomeKit**
setup codes — the `X-HM://` payload an accessory shows on first setup. That is a
different format from Matter's `MT:` (see [HomeKit setup-code decoder](#homekit-setup-code-decoder));
it has no browser counterpart and no companion tables.
it is a separate, standalone decoder with no companion tables.
## What it decodes
@@ -34,11 +34,10 @@ split into these fields:
| 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. |
| [`homekit-decode.sh`](homekit-decode.sh) | A standalone pure-bash decoder for Apple **HomeKit** setup codes (the `X-HM://` payload) — a different format from Matter's `MT:`, with no browser counterpart and no companion tables. |
| [`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). |
| [`matter-decode.sh`](matter-decode.sh) | A pure-bash CLI decoder for the Matter `MT:` payload. No camera scanning. |
| [`homekit-decode.sh`](homekit-decode.sh) | A standalone pure-bash decoder for Apple **HomeKit** setup codes (the `X-HM://` payload) — a different format from Matter's `MT:`, with no companion tables. |
| [`manufacturers.tsv`](manufacturers.tsv) | Tab-separated `vendor ID → name` table (~900 rows) used to turn a numeric vendor ID into a name. Used by `matter-decode.sh`; 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 you pass in). |
| [`products.tsv`](products.tsv) | Tab-separated `vendor ID → product ID → name` table (3 columns) used by `matter-decode.sh` to turn a product ID into a name, for any vendor that has a catalog (e.g. **LIFX**, vendor `0x1306` / `4870`). Optional. |
| [`vendor-equivalents.tsv`](vendor-equivalents.tsv) | Tab-separated `alias vendor ID → canonical vendor ID` table recording companies that are the same after a merger/acquisition (e.g. Feit `5155` = LIFX `4870`), so a product resolves under either ID. Hand-edited; optional. |
| [`gen-lifx-products.py`](gen-lifx-products.py) | Python 3 script that (re)generates LIFX's rows in `products.tsv`, merging them in from LIFX's upstream `products.json` over the network by default (or a URL/local file); preserves other vendors' rows. |
@@ -48,40 +47,10 @@ 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:
`matter-decode.sh` decodes a URI from an argument or from stdin and prints these
fields:
```sh
./matter-decode.sh "MT:..."
@@ -142,12 +111,11 @@ version(3) | vendor ID(16) | product ID(16) | custom flow(2)
```
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.
none of those groupings is an error. The shell script uses this scheme.
## Vendor name lookup
Both tools map a numeric **Vendor ID** to a name using
`matter-decode.sh` maps 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`
@@ -163,8 +131,8 @@ only). By default it **pulls the upstream `manufacturers.xml` over the network**
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
The source is pinned to the same commit the committed `manufacturers.tsv` was
generated from, so a fresh pull reproduces it 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:
@@ -173,17 +141,6 @@ 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 `<map>` 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 `<script type="text/xml">` block to keep the two copies in sync.
## Product name lookup
`matter-decode.sh` also maps a **Product ID** to a name, for any vendor that has
@@ -237,7 +194,7 @@ is considered. The canonical (col-2) id should not itself appear in col-1.
`homekit-decode.sh` decodes a **HomeKit** setup code — the `X-HM://` payload an
Apple accessory (or its packaging) shows on first setup. It is a *different*
on-wire format from Matter's `MT:`, a standalone tool with no browser app and no
on-wire format from Matter's `MT:`, a standalone tool with no
companion tables — the accessory-category names are inlined in the script.
```sh
@@ -300,5 +257,5 @@ The vendor mapping is derived from Matter/CHIP's `manufacturers.xml`, which is
Apache-2.0. The LIFX product mapping is derived from LIFX's `products.json`.
Vendor equivalences (`vendor-equivalents.tsv`) are maintained locally. The
HomeKit decoder's accessory-category names follow Apple's HomeKit
`homekit_accessory_category` definitions. The app
itself is a small single-file utility.
`homekit_accessory_category` definitions. The decoders are small standalone bash
utilities.