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

Added homekit-decode.sh to the mix, and updated the readmes.

Browse Source
This commit is contained in:
Scott Garrett committed 2026-09-01 10:56:23 -04:00
1 parent 27ebf13f6f
commit 589ebaff46
3 files changed
+131 -12
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CLAUDE.md
+54 -3
View File
@@ -5,13 +5,20 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## What this is
A collection of Matter commissioning QR decoders (the `MT:` URI format used by
Matter/CHIP devices). 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). Three artifacts:
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
@@ -151,6 +158,45 @@ Two helpers, defined just above `main()`:
(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
@@ -166,6 +212,11 @@ Two helpers, defined just above `main()`:
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
README.md
+70 -1
View File
@@ -9,6 +9,11 @@ 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.
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.
## What it decodes
Given an `MT:` URI, the payload (84 bits, see [Data format](#data-format)) is
@@ -31,6 +36,7 @@ split into these fields:
|---|---|
| [`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). |
| [`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. |
@@ -227,9 +233,72 @@ product name and vice-versa.
The table is hand-edited and optional: a missing file simply means no equivalent
is considered. The canonical (col-2) id should not itself appear in col-1.
## HomeKit setup-code decoder
`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
companion tables — the accessory-category names are inlined in the script.
```sh
./homekit-decode.sh # defaults to the demo payload 005KEOUCE
./homekit-decode.sh "X-HM://005KEOUCE"
```
A leading `X-HM://` is stripped if present; the first 9 characters are the fixed
parameter block and anything after them is a variable-length **setup id**, kept
verbatim (it is not part of the numeric block).
Example output:
```
$ ./homekit-decode.sh
Setup PIN: 38313374
Flag: 10
Supports NFC: False
Supports IP: True
Supports BLE: False
Supports WAC/MFi: True
Category ID: 5 (Lightbulb)
Reserved: 0
Version: 0
Setup ID: <none>
Setup Payload: X-HM://005KEOUCE
```
### How it decodes
Unlike Matter's **base38** payload (`0-9 A-Z - .`), the 9-character HomeKit block
is **base36** (`0-9 A-Z`, 36 symbols) — an out-of-range character is a hard
error. The resulting integer is sliced **least-significant-bit first** into the
HomeKit field 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
(each printed True/False).
- **Category ID** is resolved to its HomeKit
[`homekit_accessory_category`](https://developer.apple.com/documentation/homekit/hmaccessorycategory)
name (e.g. `5` → Lightbulb, `8` → Switch); an id not in the table prints
"unknown".
- The fields are packed back into a 9-character block and printed as a
reconstructed `X-HM://…` payload, so the output is a complete record the barcode
can be rebuilt from.
The script uses the **corrected** bit layout that `composeSetupUri` in the
`homekit-code` package actually encodes; an earlier version had the
`categoryId` / `flag` / `version` positions misaligned. Each fix is noted in the
script's header comments.
---
## License
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 app
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-decode.sh
+7 -8
View File
@@ -1,10 +1,10 @@
#!/usr/bin/env bash
#
# homekit-decode.fixed.sh — corrected decoder for a HomeKit setup payload.
# homekit-decode.sh — decoder for a HomeKit setup payload.
#
# This is a fixed copy of homekit-decode.sh. It decodes using the *correct*
# HomeKit bit layout (the one composeSetupUri in the homekit-code package
# actually encodes), instead of the misaligned bit positions in the original.
# It decodes using the *correct* HomeKit bit layout (the one composeSetupUri in
# the homekit-code package actually encodes), instead of the misaligned bit
# positions an earlier version used.
#
# Correct layout, least-significant bit first:
# bits 0-26 pin (27 bits)
@@ -13,7 +13,7 @@
# bits 39-42 reserved (4 bits)
# bits 43-45 version (3 bits)
#
# Fixes vs homekit-decode.sh:
# Fixes vs the earlier version:
# - categoryId was (val >> 27) & 0xFF, which mixed in the flag field; the
# categoryId field starts at bit 31, so it is now (val >> 31) & 0xFF.
# - The original "IP/BLE/Thread" flags read bits 35/36/37, which live inside
@@ -25,9 +25,8 @@
# - the category id is resolved to its HAP name (e.g. 8 -> "Switch"); ids not
# in the known table print as "unknown".
#
# Usage: ./homekit-decode.fixed.sh [PAYLOAD]
# Defaults to the demo payload "005KEOUCE" when no argument is given, matching
# the original so the two scripts decode the same thing by default.
# Usage: ./homekit-decode.sh [PAYLOAD]
# Defaults to the demo payload "005KEOUCE" when no argument is given.
# The output also prints the setup id and a reconstructed "X-HM://" payload
# rebuilt from the decoded fields: a complete record for recreating the barcode.