go-matter

Matter is an open-source connectivity standard for smart home and IoT (Internet of Things) devices. go-matter is a Go library for building a Matter controller, and matterctl is the command which drives it.

Note: 🌱 This is a spare-time hobby project, so progress may be slow and changes may appear irregular. Thank you for your patience 🙂

Bundled third-party test credentials. matter/credentials/testcreds contains the public test attestation credentials of the Matter SDK, project-chip/connectedhomeip (Apache License 2.0): the development DAC and PAI for vendor ID 0xFFF1 and product ID 0x8000, the test PAA, and the example Certification Declaration. They are copied unmodified from commit d305b0761957c960c26c0841e1b50add2365871d, with the SDK's LICENSE and NOTICE. See matter/credentials/testcreds/certs/README.md for the source of each file. They are for development and testing only: their private key is public, and commissioners accept them only in development mode.

Full-screen controller

Run make tui for the fictional offline matterctl tui dashboard. Live mode requires an explicit --live option and a valid commissioner fabric, restored from the selected store or explicitly created in the UI. Network operations require UI confirmation. This initial draft supports saved-device menus, manual/QR pairing forms, Descriptor inspection and selected read/On-Off controls. See scope, keys, screenshots and verification. No physical device was commissioned or operated for this implementation.

Status

go-matter is a commissioner (controller). It discovers a commissionable device over BLE and mDNS, commissions it onto a fabric, and reads, writes and invokes the clusters of the node afterwards.

Running as a Matter device is under development. The matter/device package advertises itself as a commissionable node over mDNS and answers PASE, but go-matter cannot yet be commissioned all the way by another controller, and it serves no cluster of its own. The device role is planned for v1.0.0.

	Status
Commissioning and operating a device (commissioner)	Supported
Being commissioned, and serving clusters (device)	In development: PASE only
matterctl command	Supported

What the commissioner supports

• Discovering a commissionable device over BLE and over mDNS, from a QR code payload or a manual pairing code
• Commissioning over BLE (BTP) and over IP: PASE (SPAKE2+), the fail-safe and general commissioning flow, CSR and NOC issuance, and CASE
• A persistent store of the fabric and of the commissioned nodes, so that a node is reachable again after a restart
• Reconnecting to a commissioned node with a fresh CASE handshake
• The Interaction Model: Read, Write and Invoke, including the reassembly of a chunked list
• The Message Reliability Protocol: acknowledgements and counters
• The Basic Information, Descriptor, General Commissioning, General Diagnostics, Network Commissioning, Operational Credentials, Access Control and On/Off clusters, as a client

What is not supported yet

• The device attestation chain of trust is not validated. The attestation exchange runs and its response is parsed, but the certificate chain is accepted without being verified against the Distributed Compliance Ledger. Do not rely on go-matter to reject an untrusted device.
• Interaction Model subscriptions: an attribute is read on demand, and a change cannot be reported to the controller
• Thread commissioning: only the Wi-Fi credentials of a device can be set, with pairing code-wifi
• Groups, bindings, scenes and OTA software update
• Session resumption: every reconnect is a full CASE handshake
• The clusters which are not listed above

Releases

Version	Scope
v0.8.0	The commissioner, with the gaps which are listed above
v0.9.0	The commissioner completed: attestation validation, subscriptions, and the clusters verified against real devices
v1.0.0	The device role, and a stable API

Progress Overview

Packages

Category	Package	Status	Description
Discovery	ble.btp	✅ Implemented	BLE transport protocol (BTP) implementation
	mdns	✅ Implemented	mDNS (Multicast DNS) service discovery
Commissioning	protocol.pase	✅ Implemented	Passcode-Authenticated Session Establishment (PASE / SPAKE2+)
	protocol.case	✅ Implemented	Certificate-Authenticated Session Establishment (CASE)
	protocol.session	✅ Implemented	Secure session management
	credentials	✅ Under verification	Attestation, CSR, and CA/NOC chain handling (attestation chain-of-trust validation is intentionally skipped for now)
	store	✅ Implemented	Persistent fabric and commissionee record store
Interaction Model	protocol.im	✅ Implemented	Read/Write/Invoke Interaction Model transactions, incl. chunked list reassembly
	protocol.mrp	✅ Implemented	Message Reliability Protocol (acknowledgement, counters)
Clusters	cluster	✅ Implemented	Basic Information, Descriptor, General Commissioning/Diagnostics, Network Commissioning, Operational Credentials, Access Control
	cluster.onoff	✅ Under verification	On/Off cluster client (not yet exercised against a real device)
Operation	cmd.matterctl	🚧 In progress	matterctl CLI (pairing, scan, per-cluster read/write/invoke)
Encoding	encoding.base38	✅ Implemented	Base38 encoding/decoding
	encoding.qr	✅ Implemented	QR code generation
	encoding.pairing	✅ Implemented	Manual pairing code handling
	encoding.message	✅ Implemented	Message Frame Format encoding
	encoding.tlv	✅ Implemented	TLV (Tag-Length-Value) encoding

Related Projects

Project	Status	Description
go-ble	v0.9.0 (central only)	Go package for Bluetooth Low Energy (BLE) communication
go-mdns	v0.9.0 (client only)	Go package for mDNS (Multicast DNS) service discovery

Install

go get -u github.com/cybergarage/go-matter

The matterctl command is installed with:

go install github.com/cybergarage/go-matter/cmd/matterctl@latest

Usage

A commissioner is started once, and it then discovers, commissions and reaches the devices of its fabric.

commissioner := matter.NewCommissioner()
if err := commissioner.Start(); err != nil {
	return err
}
defer commissioner.Stop()

// The payload comes from the manual pairing code, or from the QR code, of
// the device.
payload, err := encoding.NewPairingCodeFromString(code)
if err != nil {
	return err
}

commissionee, err := commissioner.Commission(context.Background(), payload)
if err != nil {
	return err
}

nodeID, _ := commissionee.NodeID()

A commissioned node is reached again through the store, without commissioning it a second time:

node, err := commissioner.Connect(context.Background(), nodeID)
if err != nil {
	return err
}

res, err := node.ReadAttribute(endpointID, clusterID, attributeID)

Commissioning bounds the whole PASE-through-CASE exchange with a single deadline, which defaults to DefaultCommissioningTimeout (120 seconds): a device commits its new fabric to persistent storage and then re-advertises itself over mDNS before CASE can start, and a shorter deadline expires in the middle of that.

Command

matterctl commissions and operates a device from a terminal. See the command reference.

$ matterctl scan
$ matterctl pairing code 1 MT:-24J0AFN00KA0648G00
$ matterctl pairing code-wifi 1 MT:-24J0AFN00KA0648G00 <ssid> <password>
$ matterctl basicinformation read 1 0
$ matterctl onoff on 1 1
$ matterctl any read 0x0006 0x0000 1 1
$ matterctl reset

User Guides

• Operation
  • matterctl
• Commissioner
  • Commissioner Persistent Store
• Device
  • Device (in development)
  • Device Persistent Store

References

• Matter
  • Matter 1.5 Standard Namespace Specification
  • Matter 1.5 Device Library Specification
  • Matter 1.5 Core Specification
  • Matter 1.5 Application Cluster Specification

Versioned metadata catalog

The initial offline matter/datamodel catalog provides version-pinned SDK device/cluster/attribute/command metadata. See source licensing, coverage, regeneration and API. It does not enable new device operations or change the library's protocol target.