# Matter

> Reference for the Matter driver: Bluetooth commissioning into the local Fabric, the Pair device flow, node identity and cluster tags.

The Matter driver reads **Matter-over-Thread** equipment: smart sensors, plugs,
lights and similar devices certified for the Matter standard. Ganter Lab acts as a
**Matter controller with its own local Fabric**: it commissions each device once
over **Bluetooth Low Energy** on this computer, hands it the credentials of your
existing Thread network, and from then on talks to it over that network through your
Thread Border Router.

That reverses the usual setup order. A Matter Device does not start from a host and
port: it starts from a **pairing ceremony**, and only the commissioned node's stable
identity is stored afterwards.

What you need before pairing:

- A **Bluetooth Low Energy adapter** on this computer, turned on, with Windows
  allowing Ganter Lab to use it.
- An existing **Thread network** with a Border Router, and its complete **Active
  Operational Dataset**. Ganter Lab joins devices to your network; it cannot invent
  credentials for it.
- The device's **setup code**, printed on the device or its packaging, and the
  device in pairing mode.

## The Pair device flow {#the-pair-device-flow}

On the Matter driver, the toolbar offers **Pair device** where other drivers offer
Add device. It opens a form with three fields:

| Field | What it is | Format | Default |
|---|---|---|---|
| Device name | The editable name the Device will carry in Connector. | Free text | `Matter device` |
| Matter setup code | The official manual pairing code, or the complete QR payload. Entered masked, with a reveal control. | An 11- or 21-digit manual code (dashes and spaces are ignored; the check digit is verified), or the full QR payload beginning with `MT:`. A QR payload that does not advertise Bluetooth commissioning is refused, as are reserved or out-of-range passcodes. | empty |
| Thread Operational Dataset | The complete **active** dataset of your Thread network, from the network administrator or the Border Router. Entered masked, with a reveal control. | Hexadecimal text (whitespace and a `hex:` prefix are tolerated), at most 254 bytes once decoded. It must be the complete dataset: Active Timestamp, Channel, Channel Mask, Extended PAN ID, Mesh-Local Prefix, Network Key, Network Name, PAN ID, PSKc and Security Policy must all be present, and a partial or malformed dataset is refused with the missing element named. | empty |

**Pair device** stays disabled until all three fields are filled. While pairing runs
the form reports its stage: **Validate** (checking the code and dataset), **Find**
(searching for the device over Bluetooth), **Pair** (authenticating with the setup
code), **Join Thread** (sending the network configuration and waiting for the device
to appear on the Thread network), **Save** (recording the commissioned node in the
local Fabric).

**Cancel** is available while the physical device has not been changed yet; once
commissioning has altered the device, the button reads that Ganter Lab is finishing
safely and the flow completes the record instead of abandoning a half-commissioned
node. One pairing runs at a time; a second attempt while one is under way is
refused.

**Secrets are never persisted.** The setup code and the Thread dataset exist only in
the form while it is open; they are cleared when pairing finishes, fails or is
canceled, and nothing of them is written to the configuration. What is saved is the
node's identity alone.

If pairing fails, the message states the cause: an invalid code or dataset, missing
or disabled Bluetooth, Windows denying Bluetooth access, no matching device found,
the device rejecting the setup code, or the device commissioning but never appearing
on the Thread network. A wrong setup code is named as such, so the answer is to
reread the printed code and put the device back into pairing mode.

Whenever a failure arrives after the equipment was already commissioned, the message
says so and shows the Node ID: the node **remains in the Fabric** and can be added
later with Discover once it reaches the network. Do not reset the device in that
case; only a message that says nothing was saved means the equipment was left
untouched.

## Node identity {#node-identity}

A paired Device is bound to the equipment's stable 64-bit **Node ID**, shown
read-only in its Connection card as 16 hexadecimal digits, beside the device state.
The editable display name is yours to change; the Node ID is not. A Device whose
stored identity can no longer be read shows **Needs re-pairing** in its place.

Because identity is the Node ID, Matter Devices keep independent connection state:
disabling, deleting or losing one node does not make another unavailable, and
deleting a Device releases only its use of the secure session — it does not remove
the equipment from the local Fabric.

## Discovery {#discovery}

**Discover** on the Matter driver lists the nodes already commissioned into this
application's local Fabric, so a node whose Device was deleted (or whose pairing
finished without a Device) can be added back without a new ceremony. A Node ID that
is already configured is marked as such and **Open** navigates to the existing
Device. Discovery candidates carry the node identity and no setup secret. The
general discovery flow is described on the [Connector](connector) page.

## Tags {#tags}

A Matter tag has no free-text address field. The **tag name is the cluster name**
to read. The name must match the cluster's name as the Matter specification spells
it — spaces and punctuation included, capitalization ignored: `On/Off`,
`Level Control`, `Temperature Measurement`. Because the name is the address, it
cannot contain a colon; the panel refuses one and says so. A name no cluster
carries reads as an error naming the unknown cluster. The value is converted to the
tag's declared data type; a value the declared type cannot represent also reads as
an error rather than a stand-in number.

Two number fields say **where** on the device to read that cluster. A device
exposes one **endpoint** per controllable output, numbered from 1, so a two-channel
lamp or a power strip is read one endpoint per tag; endpoint 0 is the node itself.
The **attribute** is which value of the cluster to read, and 0 is the cluster's own
value, which is what almost every tag wants.

| Field | What it does | Values | Default |
|---|---|---|---|
| Tag name | Names the tag and selects the Matter cluster read from the node. No colon. | The spelled cluster name, e.g. `On/Off` | `Tag 1` |
| Output (endpoint) | Which output of the device this tag reads. | 0 and up; 1 is the first controllable output | 1 |
| Attribute | Which attribute of the cluster this tag reads. | 0 and up; 0 is the cluster's own value | 0 |
| Data type | The OPC UA type the value is exposed as. | Boolean, Int32, UInt32, Float, Double, String | Float |
| Poll interval | How often the attribute is read, per tag, with the device default (1000 ms) applying where the tag states none. | milliseconds | device default |

Matter tags are **read only**: the access field offers no writable choice and
attribute writes are refused by the runtime. Mutating a Matter device (switching it
on, for instance) is a Matter command, which tag writes do not model.