Matter

Reference for the Matter driver: the Wi-Fi and Thread networks devices join, Bluetooth commissioning into the local Fabric, the Pair device flow, node identity, the tags that come from the device and what writing each one does.

The Matter driver reads Matter equipment: smart sensors, plugs, lights and similar devices certified for the Matter standard, whether they join the network by Wi-Fi or by Thread. It is one driver for both. The network is only the way in: once a device is on it, Ganter Lab reads it the same way, over the local network.

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 a network registered on the driver's Networks card, and from then on talks to it over the local network: through your router for a Wi-Fi device, through your Thread Border Router for a Thread device.

You never tell Ganter Lab whether a device is Wi-Fi or Thread: the device says so itself. Once the Bluetooth session is open, Ganter Lab reads from the device which kind of network it joins, before it writes anything to it, and stops with a message of its own when the network chosen is of the other kind.

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.
• The network the device will join, registered on the Networks card: for a Wi-Fi device, the Wi-Fi name and its password; for a Thread device, 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.

Networks

The Matter driver's panel carries a card titled Networks: the Wi-Fi and Thread networks devices are joined to, one row each. A network is registered once, before the first device, and serves every device paired into it, so pairing a second lamp on the same Wi-Fi asks for nothing again. The card is drawn only for a role that may configure the Connector, because it holds the networks' secrets and serves nothing but pairing.

The card's head carries its commands, in this order:

The table lists each network's Name, its Network type (Wi-Fi network or Thread network) and its State: Ready for pairing, or what the network still lacks. A network whose name is not written yet reads Unnamed network.

The selected network's fields are edited inline under the table and save themselves. A value the rules below refuse is not written, and the field says why.

Two things decide whether a Wi-Fi device can be paired at all, and the card says both beside the fields:

• Most devices join only 2.4 GHz networks. A router that broadcasts one name on 2.4 GHz and 5 GHz serves them; a network that exists only on 5 GHz does not.
• This computer and the devices must be on the same local network. A guest network, or client isolation turned on in the router, keeps the computer from finding the devices once they have joined.

A network serves pairing only while its secret passes those rules: a Wi-Fi network with a valid name and a valid password (empty included), a Thread network with a valid dataset.

Editing a network changes what the next pairing hands over, never what a device already received. A device that has to move to another network, or whose router got a new password, is reset and paired again.

The Pair device flow

On the Matter driver, the toolbar offers Pair device where other drivers offer Add device, and so does the Matter entry of the column's New… menu. While no network is usable for pairing it stays drawn and greyed, with the tooltip "Add the network the device will join first." Otherwise it opens a form:

A folder of the Matter driver offers New device (on its Devices table, on its right-click menu and under New… > Matter > <Folder>). It opens this same form, greyed the same way while no network is usable, and the paired device is filed in that folder.

Pair device in the form stays disabled until the name and the setup code are filled and a network is usable. While pairing runs the form reports its stage: Validate (checking the code and the network's secret), Find (searching for the device over Bluetooth), Pair (authenticating with the setup code and reading which kind of network the device joins), Join the network (sending the network to the device, then asking the local network for it until it answers; the status line says whether that network is Wi-Fi or Thread), Save (opening the secure session with the device on the local network, completing its commissioning and recording the 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.

The new Device records the name of the network it joined, shown in its Network field. Pairing the next device on the same network asks only for its name and its setup code.

When pairing fails

If pairing fails, the message states the cause and what to do:

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.

A device that answers that it could not join the network is the exception: it holds nothing worth keeping. Ganter Lab ends the pairing on the device, which discards what it received and returns to pairing mode at once, and removes its node from the Fabric, so the message carries no Node ID and Discover never lists a node that cannot answer. Correct the network and pair again. Only a device that gave no answer at all keeps its node, because whether it joined is not known until it appears on the local network.

What is stored

The Wi-Fi password and the dataset never appear in the journal, in a device's address or in its Thing Description. Networks and pairing are not offered to agents through the MCP server: pairing needs someone at the device, and the networks hold secrets.

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.

The Device's panel also shows a read-only Network field: the name of the network the device joined when it was paired. A device paired by a version that did not record it says that nothing was recorded. The field is a record, not a setting: editing or removing that network on the Networks card changes nothing on the device.

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

Discover on the Matter driver lists the nodes already commissioned into this application's local Fabric and reads, from each one, the values it publishes. To read them it opens a secure session with every node, so a node that is off the network is still listed, with no values, once its session has failed to open. Discovery candidates carry the node identity and no setup secret. The general discovery flow is described on Discovery.

A configured device's values are compared with its tags by output, cluster and attribute, never by name: a tag you renamed still counts, and a value is never added twice.

The device's own page offers the same without leaving it: Discover tags, on the head of its Tags card, reads that node alone and lists the values it has no tag for yet, ticked, with Add tags (see Discovering a device's tags).

Tags

The tags of a Matter device come from the device itself: nobody types a cluster or an attribute number for them. A pairing that ends well goes straight on to them. The feed reads "Paired Matter device 'Kitchen light'.", the page opens on the Matter driver with the new device marked in its Devices table, and a scan of that one device runs at once. The device the pairing created appears in Discovered devices with the values it publishes, all ticked, and the scan closes with "Tick the values of 'Kitchen light' to create as tags, then Add tags." Untick what you do not want and press Add tags; the feed then reads "Added 5 tags to 'Kitchen light'." A device that has not answered yet reports nothing: "'Kitchen light' reported no values yet. Run Discover again once it is online." The same card comes back on every later Discover, with whatever values the device still has no tag for.

Add tags is drawn only for a role with Configure connector. It stays greyed, with its reason as the tooltip, while a scan or a pairing runs, while the station refuses changes, and while nothing is ticked ("Tick at least one value to add."). A value whose output, cluster and attribute the device already reads is never added again; when every ticked value is already there, nothing is saved: "'Kitchen light' already has a tag for every value you ticked, so nothing was added." A name another tag of the device already carries gets a number after it, as in Brightness (2).

The scan reads what the device publishes, as the Matter specification lays it out:

What the scan offers, and under which name:

A tag offered as writable arrives with the access Read and write; every other one arrives Read only.

The values the driver knows

The driver carries one table, taken from the Matter specification, of the values it knows by name and how each one changes. A value changes in one of three ways: a command the driver sends, which the device must list among the commands it accepts; a write of the attribute itself, where the specification makes it writable and the device lists it; or not at all, for a value the device only reports.

The specification sends temperatures, humidity and pressure in fixed units: hundredths of a degree Celsius, hundredths of a percent and tenths of a kilopascal. The scan offers those values already in °C, % and kPa: the tag arrives with the factor in its Scale stage (0.01 for a temperature and a humidity, 0.1 for a pressure) and the unit, so a device that sends 2150 reads 21.5 °C. A write reverses that stage before the value leaves, so a setpoint written as 21.5 reaches the device as 2150. Illuminance is logarithmic (10000 × log10(lux) + 1), so no factor converts it: it reads the number the device sends. Every other value reads as the device sends it too.

Door locks, color by X and Y coordinates, scenes, groups and the Toggle command are not in the table. A Matter device has no commands of its own either: every change is a write to one of its tags.

Writing a value

A Matter tag whose access is Read and write changes the device when it is written: from its Live value card, a dashboard control, the Logic or an agent. The write joins the device's queue like every driver's, in turn with the device's reads, and its answer is the device's own. The driver chooses the Matter command or the attribute write from the table; nobody picks a command. Only the device's SUCCESS counts as written. Everything else is refused, with a reason:

A refused write is never reported as written, nor as a device out of reach. On the tag's page the status line reads "Write refused by the equipment: CONSTRAINT_ERROR, 0x87." when the device refused it, with the reason in place of the status for a refusal settled before anything was sent, and "Write not confirmed: the equipment did not answer in time." when no answer came; "Write failed: the equipment could not be reached." is kept for a device that is not connected. The reason also travels with the write: the journal line of the write names it, with what the status means, and an agent's tag_write returns it.

A tag made by hand

For the rare value the device does not publish in a form the scan offers, Add tag on a Matter device creates a tag to fill in by hand. Its Source card shows three fields on one row, and the address preview under them assembles them as <endpoint>/<cluster>/<attribute>, in decimal (1/8/0 is the brightness of the first output). Until a cluster is chosen the tag is not saved, and the panel says: "Choose the cluster this tag reads. Without one, the device is never asked for anything."

The tag name is free: it names the tag and selects nothing on the device. The data type is chosen among Boolean, Int32, UInt32, Float, Double and String; a reading the declared type cannot represent reads as an error rather than a stand-in number. The value arrives as the device sends it: a temperature, a humidity or a pressure made by hand reads in hundredths or tenths until you give it the factor and the unit of the table above in its Scale stage.

The access field offers writing only where the driver's table changes the value, and otherwise offers Read only and says why under it:

When an edit of the output, the cluster or the attribute points the tag at a value the driver cannot write, its access returns to Read only. A tag the scan offered keeps the access the scan gave it, because only the scan asks the device which commands it accepts: a value the device did not list stays Read only, and the field still offers writing.

Tags saved by earlier versions

An earlier version named a Matter tag's cluster only through the tag's name, with an address of <endpoint>/<attribute>. When this version first starts, every tag of a Matter device whose name is a cluster of the Matter catalog (the part after the last colon, without the spaces around it, capitals ignored) takes that cluster, so it goes on reading exactly the value it read. Its name stays as it was, and its address preview then reads <endpoint>/<cluster>/<attribute>. A tag whose name matched no cluster never read anything: it stays without a cluster, its reads are refused with a reason that says so, and its page asks for the cluster. A converted tag keeps the access it had, Read only, the only one those versions offered; to write it, set Read and write, which works for the values of the table above.