matter-kit
A Matter implementation in Rust: one crate,
no_std, no allocation, and no runtime of its own.
🚧 Status: under construction. A device can be commissioned into a fabric end to end — over IPv6, Bluetooth LE, Wi-Fi PAF or NFC — answer Reads, Writes and Invokes, hold subscriptions, enforce access control, take part in groupcast, and move a firmware image over TCP. The CHIP SDK's own
chip-toolcommissions thelightexample through the whole of §5.5 with attestation verified, and eleven of the CSA Test Harness's certification cases pass against it. The 1.6 cluster library is generated from the CSA data model with its conformance rules. What is missing is most of the application clusters' behaviour. See Status.
🏠 What Matter is, and why this exists
Matter is the CSA's smart-home standard — the protocol behind Apple Home, Google Home, Alexa and SmartThings, running over Wi-Fi, Ethernet and Thread. This crate targets specification 1.6 (approved 2026-06-16).
The reference implementation is C++. There is a good Rust one,
rs-matter. This is a second Rust one, built
around four decisions that are hard to retrofit:
📦 One crate. Not a family to keep in version step. Everything optional is a Cargo
feature. The code generator is repository tooling (cargo xtask), not a dependency.
📖 The cluster library is generated, and it knows its own rules. All 135 clusters and 91
device types come from the CSA's machine-readable data model — the same files the Test Harness
reads — with the conformance expression for every element. So the crate can tell you that
StartUpOnOff is mandatory with the Lighting feature and forbidden without it, check your
device's descriptors against that, or simply build them for you:
use on_off;
use ;
let light = new?;
// Five attributes and six commands, none of them written down anywhere.
📏 A capacity is checked against the specification. Every table — fabrics, sessions, exchanges,
subscriptions, access-control entries — is a fixed-capacity array, and each one carries a
const assertion that its capacity can keep the promises the node makes to every fabric. A
node that could not pass certification does not compile, and the failing rule is named in the
build error:
use ;
// Every capacity defaults to the specification's own minimum, so this is a conformant node.
let acl: = new;
// error: Acl: Core §2.11.1.1 promises ACL_ENTRIES_PER_FABRIC to every fabric,
// so the list must hold FABRICS × that many
// let too_small: Acl<DefaultConfig, 4, 4, 3> = Acl::new();
Config carries what a capacity cannot tell you — how much of it each fabric is owed, which
is also what the node advertises in CapabilityMinima, SupportedFabrics and
AccessControlEntriesPerFabric. Those attributes are read from the tables, never from a number
typed beside them, because the specification says each is "the actual" figure.
Cargo features cannot do this: they are global and additive, so two crates in one binary that want different sizes silently get the union, and nothing checks the result against the specification.
And the sizes are in the image rather than in a design note. ./footprint/run.sh links a whole
light for an nRF52840 and reads the sections out: 88 KiB of flash and 39 KiB of RAM, of
which 14 KiB is fifteen subscriptions and 9 KiB is five fabrics. There is no radio in that
image, so it measures this crate and not a finished product.
⚙️ No runtime is chosen for you. The crate is async over core::future and reaches the
outside world through small traits — sockets, timers, randomness, storage. No executor crate
is in the dependency tree at all; the examples run on a block_on of their own.
🧹 A fabric leaves, and nothing of it stays. RemoveFabric is one sentence in the
specification — "SHALL remove all associated data" — that reaches fourteen tables owned by ten
clusters. Here it is one call, handler.on_lifecycle(Lifecycle::FabricRemoved(index)),
delivered to every cluster a device serves; adding a cluster adds it to that fan-out. Fabric
indices are reused, so an entry that outlives its fabric is inherited by whoever gets that index
next — which for an access-control entry is an administrator nobody granted.
🛡️ Nothing panics on network input, and nothing truncates it either. unwrap, expect,
panic!, slice indexing, unchecked arithmetic and the three casting lints are denied
crate-wide — an as that drops the high bits is the same mistake as an overflow, arriving by a
quieter door. Every deliberate cast carries the invariant that makes it safe. Every parser
returns an error, and resource exhaustion is a value, so a device that runs out of exchanges
answers BUSY rather than aborting.
🔐 And it answers to somebody who did not write it. SECURITY.md has the
disclosure address, what is in scope, the properties the crate guarantees and how each is
checked, the support policy, and the limitations worth knowing before you ship. Releases publish
through crates.io Trusted Publishing and carry a CycloneDX SBOM.
📊 Status
Every layer below is built and tested against the sections that define it. The full breakdown — eighty-odd rows, each citing its specification section — is on the status page.
| Area | What is built | 1.6 |
|---|---|---|
| Wire and message layer | TLV, the message frame, counters and the replay window, security and privacy, exchanges and MRP | Appendix A, §4.4–§4.12 |
| Transports | UDP, TCP with §4.5 stream framing, BLE/BTP, PAFTP over Wi-Fi Public Action Frames, NFC/NTL | §4.5, §4.15, §4.19–§4.21 |
| Secure channel | the ch. 3 cryptosuite, SPAKE2+, PASE, CASE, secure sessions, StatusReport — and sc::Channel, which owns §5.5's rules around them: one handshake at a time, sixty seconds, twenty failures, and the session each produces |
ch. 3, §4.11–§4.14, §5.5 |
| Groupcast | operational group keys and epoch rotation, group sessions, the peer table, MCSP — and the receive path a device needs: join the group's multicast address, try every candidate key, act on the command and answer nothing | §4.16–§4.18, §8.8.2.3 |
| Credentials | Matter TLV certificates and exact X.509 regeneration, the DAC/PAI/PAA chain, the Certification Declaration, NOCSR, a certificate authority | ch. 6 |
| Commissioning | onboarding payloads, the fail-safe, both sides of §5.5's flow and its rules on admitting a PASE request, Network Recovery, Joint Fabric and Fabric Synchronization | ch. 5, ch. 12 |
| Interaction model | all ten messages and sixteen information blocks, Read/Write/Invoke, subscriptions and the reporting engine, events, atomic writes, cluster data versions, chunking both ways | ch. 7, ch. 8, ch. 10 |
| Access control | §6.6.6's algorithm clause by clause — CATs, fabric isolation, the two-stage check | §6.6 |
| Node lifetime | session eviction with the CloseSession report it owes, a session's exchanges dying with it, and fabric removal reaching every cluster |
§4.11.1.1, §4.13.3.1, §11.18.6.12 |
| Exchanges | the table, MRP's backoff curve, §4.10.3.1's protocol registration and §4.10.5.2's three rules for an unsolicited message — so a stranger cannot fill a fixed-capacity table and end session establishment | §4.10, §4.12 |
| Discovery | DNS-SD records and TXT keys, a responder, RFC 6762's probe/announce/conflict schedule | §4.3 |
| Large data | BDX and both OTA cluster halves, TLS Certificate and Client Management | §11.20, §11.22, ch. 14 |
| Clusters | the generated library with its conformance and TLV types, and 36 hand-written cluster modules — On/Off, Level Control, Groups, Scenes, Mode Base, the energy clusters, all three network diagnostics clusters over driver traits, the commissioning clusters | Application Cluster, Device Library |
Not yet written: most of the application clusters' behaviour behind the generated descriptors, device attestation revocation and the DCL, the per-chip radio drivers, and the typed client layer over the generated types.
1823 tests across 75 files; 27 fuzz targets clean; builds for thumbv7em-none-eabihf and
riscv32imac-unknown-none-elf, and links for the first of them into 88 KiB of flash
and 39 KiB of RAM; the feature powerset checked in full.
And one check worth more than the rest, because it is the only one without this crate on both
ends: ./interop/chip/run.sh has the CHIP SDK's own chip-tool — the controller every
certified Matter product is paired by — commission examples/light through the whole of Core
§5.5, with device attestation verified rather than bypassed. The same container carries the
CSA Test Harness's own 618 certification cases, and ./interop/chip/python.sh runs them
against the example; eleven pass, TC_OPCREDS_3_1 across all eighty-five of its steps.
Both ends in containers on an IPv6 network — no hardware, no radio, no C++ toolchain. The
status page names every case.
🔌 The wire format
Every byte Matter puts on the wire above the message header is TLV (Core Appendix A).
use ;
// Core Table 128's example: { 0 = 42, 1 = -17 }
let bytes = ;
validate?;
assert_eq!;
# Ok::
TlvWriter is the other half, and it refuses to produce invalid TLV: an anonymous member of a
structure, a tagged member of an array or an unbalanced container are errors at the call.
🧩 Serving a node
A device's shape is const data — endpoints holding cluster descriptors, in flash, costing
no RAM. A Server walks it and one ClusterHandler supplies the behaviour, with write
and invoke defaulting to refusal. A Dispatcher turns an arriving message into the reply,
applying the rules §8.7.2.3 and §8.8.2.3 put between an opcode and any work — the Timed
window, and the MaxPathsPerInvoke bound on how many commands one message may ask for.
use ;
use ;
const EP1: & = &;
const ENDPOINTS: & = &;
// §7.10.3's cluster data versions. A report without one is an attribute the CHIP SDK's
// cache discards, so a node that omits them is conformant and uncommissionable.
let versions = new;
let server = new
.with_data_versions;
let mut dispatcher: = new;
let mut cursor = START;
let request = new;
match dispatcher.dispatch?
⏱️ Testing a protocol that is mostly timers
Half of Matter is deadlines: MRP backs off over four seconds, a fail-safe expires, an
intermittently connected device sleeps for an hour. So time is a parameter, and
platform::sim is a supported platform — an in-process IPv6 network with a virtual clock
that jumps to the next deadline, and loss, duplication and jitter you set per test.
use ;
use ;
let net = new; // seeded: same run, same result, every time
net.impair; // drop three datagrams in ten
let start = now;
block_on;
// An hour of virtual time has passed, and no wall-clock time has.
assert_eq!;
🔨 Building
Run a device
A commissionable node on real sockets: UDP 5540 for Matter, mDNS 5353 so a commissioner can find it, PASE from a printed passcode, and the commissioning clusters over the session it produces. It prints what to point at it:
chip-tool pairing onnetwork 1 20202021
MATTER_IFINDEX picks the interface to advertise on — it defaults to loopback, which is
enough to see the node locally and not enough to be found from another machine.
Other examples: --example commission runs a full PASE exchange and then a wrong passcode;
--example bridge presents devices the node does not contain; --example reliable_exchange
drives MRP over a lossy simulated link.
📚 Documentation
- Guides and reference — what Matter is, how to serve a node, commissioning, discovery, and how a protocol made of timers gets tested.
- Stability — what a
0.xdependency promises, which three surfaces cost you work when they move, and the deprecation rule.cargo-semver-checksenforces it in CI. - CHANGELOG.md — what moved between releases, and what to change if you are on the previous one.
- API reference — every module documents the rules it implements against the section that states them.
📖 Specification references
Claims in the source cite their section: Core §4.12 is the Matter 1.6 Core
Specification, App §1.5 the Application Cluster Specification, DL §4.2 the Device
Library. The documents are free from
csa-iot.org but
are not redistributable, so they are not in this repository.
⚖️ License
Dual-licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option. Apache-2.0 compatibility is deliberate: it lets code and test vectors flow
to and from rs-matter and the CHIP SDK.
Matter® is a registered trademark of the Connectivity Standards Alliance. This project is not affiliated with or endorsed by the Alliance, and nothing here is a certified implementation.