matter-clusters 0.4.1

Matter protocol cluster definitions (generated from the spec).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# matter-clusters

Typed Matter cluster definitions: per-cluster attribute/command/struct codecs,
feature flags, enums (with `Unknown(n)` forward-compat) and bitmaps. The modules
under `gen/` are generated from a pinned `@matter/model` dump by the `xtask`
codegen tool.

Part of [`matter-rust`](https://github.com/phunapps/matter-rust).

```toml
[dependencies]
matter-clusters = "0.4"
```

## What this crate does

- Provides encode/decode functions for the attributes, commands, and structs of
  47 Matter clusters (mandatory **and** optional attributes), as Matter TLV.
- Models cluster enums with an `Unknown(n)` variant (forward-compatible decode),
  feature maps as `bitflags`, and nullable fields as `Nullable<T>` (distinct
  from `Option<T>`).
- Generates all of the above from the spec model, gated against drift in CI.

## What this crate does not do

- It is **not** the full Matter cluster set — only the 47 listed below. More
  are generated as they are needed.
- It does **not** provide generic or wildcard attribute access, or
  manufacturer-specific typed codecs. Reading arbitrary attributes a device
  publishes is the Interaction Model layer / high-level controller (see *Reading
  attributes beyond these clusters*).
- It is **codecs only**. Encoding a command is not the same as running the
  protocol around it: ACL evaluation, group multicast, commissioning-window
  orchestration, and OTA live in `matter-controller` and its siblings.
- It performs no IO and no session/transport work — it only encodes/decodes
  bytes.

## Status

**0.4.1**, published on crates.io. Stability: a `0.x` crate, so a **minor** bump
may break API — and adding clusters is a routine minor bump.

## Clusters

47 clusters are generated today, covering their **mandatory and optional**
attributes, by area:

- **Core / identity** — BasicInformation, Descriptor, Identify, Groups, Binding,
  FixedLabel, UserLabel, PowerSource, GeneralDiagnostics.
- **Lighting and actuators** — OnOff, LevelControl, ColorControl, DoorLock
  (Aliro features excluded), WindowCovering, Thermostat,
  ThermostatUserInterfaceConfiguration, FanControl,
  PumpConfigurationAndControl.
- **Sensing** — OccupancySensing, TemperatureMeasurement,
  RelativeHumidityMeasurement, IlluminanceMeasurement, PressureMeasurement,
  FlowMeasurement, BooleanState, Switch, AirQuality, and the ten
  ConcentrationMeasurement clusters (CarbonMonoxide 0x040C, CarbonDioxide
  0x040D, NitrogenDioxide 0x0413, Ozone 0x0415, Pm25 0x042A, Formaldehyde
  0x042B, Pm1 0x042C, Pm10 0x042D, TotalVolatileOrganicCompounds 0x042E, Radon
  0x042F).
- **Energy** — ElectricalPowerMeasurement, ElectricalEnergyMeasurement.
- **Administration** — AccessControl, GroupKeyManagement,
  AdministratorCommissioning, OperationalCredentials, IcdManagement,
  TimeSynchronization, OtaSoftwareUpdateRequestor, OtaSoftwareUpdateProvider.

Verification varies by cluster, and the level is deliberate rather than
accidental. Every cluster has decode-smoke coverage. matter.js 0.16.11
byte-parity vectors (`test-vectors/clusters/`) cover the core, lighting, and
sensing sets, plus one vector for each novel wire shape a later cluster
introduced: the nested `MeasurementAccuracyStruct`, the list-typed
`AtomicRequest` command, GeneralDiagnostics' struct-with-byte-fields
`NetworkInterface`, the recursive list-of-struct in
`AccessControl.ReviewFabricRestrictions`, and FLOAT32 attributes. The read/write
actuator clusters additionally carry `decode(encode(x)) == x` roundtrips, and
floats get both a binary32-edge roundtrip (signed zero, subnormals, infinities,
NaN — compared by bits) and a `proptest` roundtrip drawn uniformly from the
whole binary32 bit space. A `single` attribute accepts a FLOAT32 element only,
matching chip's strict `TLVReader::Get(float&)`.

For any attribute not covered by these typed codecs — manufacturer-specific, or
a cluster not in this list — the generic `Value` path in `matter-controller`
remains the universal answer. Hand-written support lives in `types`
(`Nullable<T>`), `error` (`ClusterError`), and `datatypes`
(`SemanticTagStruct`).

## Usage

```rust
use matter_clusters::gen::{basic_information, on_off};

// Command payload — embed in an InvokeRequest.
let _toggle = on_off::encode_toggle();

// Attribute roundtrips: encode a value, decode it back.
let tlv = on_off::encode_on_time(30);
assert_eq!(on_off::decode_on_time(&tlv)?, 30);

let tlv = basic_information::encode_node_label(&"living room".to_string());
assert_eq!(basic_information::decode_node_label(&tlv)?, "living room");
# Ok::<(), matter_clusters::error::ClusterError>(())
```

See `crates/matter-commissioning/examples/control_onoff.rs` for an end-to-end
read / toggle / write against a real device (runbook:
`docs/runbooks/m7.5-control-onoff.md`).

## Generated code

`cargo xtask codegen` writes `src/gen/<cluster>.rs` (+ `globals.rs`, `mod.rs`)
from `xtask/model/clusters.json`. Do not edit the generated files by hand —
change the emitter (`xtask/src/codegen/`) and regenerate. `cargo xtask codegen
--check` gates drift in CI.

## Reading attributes beyond these clusters

Typed codecs cover these clusters' mandatory and optional attributes (a device
may not implement a given optional attribute — it then returns
`UNSUPPORTED_ATTRIBUTE`). To read attributes of other clusters, or
manufacturer-specific attributes, use the generic Interaction Model path:
`matter_interaction::parse_report_data` yields
`(AttributePath, matter_codec::Value)` for any attribute without a typed codec,
and `matter-controller` wraps that in a generic read/write/subscribe API with
wildcard paths.

## Correctness posture

- **Decode-smoke coverage** for every generated cluster.
- **Byte-parity** against matter.js 0.16.11 TLV combinators
  (`test-vectors/clusters/`) for the core, lighting, and sensing sets, plus one
  vector per novel wire shape — see [Clusters](#clusters) for exactly which.
- **`proptest` roundtrips** over attribute values.
- **A `cargo-fuzz` target** over the generated decoders (weekly CI).
- **`cargo xtask codegen --check`** fails CI if the committed `src/gen/` drifts
  from what the emitter + `clusters.json` produce.

## Cryptographic posture

`matter-clusters` performs no cryptography. It is pure data encoding.

## MSRV

Rust 1.88 (workspace MSRV). See the workspace `CHANGELOG.md`.

## License

Apache 2.0. See `LICENSE` at the workspace root.