Expand description
Cluster behaviour, over the shapes in generated (Core ch. 9 and ch. 11).
A node is not just a data model — it has to answer. generated has every cluster’s
shape; this module has the behaviour for the ones that have any, from the utility clusters
that make a device commissionable and describable to the application clusters a product is
built from. All of them are implemented against the same
cluster descriptor and ClusterHandler machinery, so
there is one mechanism and not a privileged one for the built-ins.
Each module below documents the section it implements, and takes its ID, REVISION and
conformance from generated rather than restating them — a second copy of a number the
specification moves is a number that is wrong after the next revision.
§Composition
ClusterHandler is one trait for a whole device — a device
has one cluster implementation table and not one per cluster. So each cluster here
implements the narrower Cluster trait, which adds the one thing dispatch needs: the
cluster’s id. A tuple of Clusters is itself a ClusterHandler, dispatching on that id:
use matter_kit::clusters::basic_information::{Attributes, BasicInformation, Location, Product};
use matter_kit::clusters::descriptor::{self, DeviceType};
use matter_kit::clusters::general_commissioning::{self, GeneralCommissioning, RegulatoryLocation};
use matter_kit::clusters::network_commissioning::{
self as netcomm, Capabilities, EthernetDriver, NetworkCommissioning,
};
use matter_kit::clusters::Descriptor;
use matter_kit::commissioning::window::CommissioningWindow;
use matter_kit::commissioning::failsafe::{BasicCommissioningInfo, FailSafe};
use matter_kit::dm::{Endpoint, Node};
use matter_kit::msg::VendorId;
const PRODUCT: Product<'static> = Product::new(
"Example Vendor", VendorId(0xFFF1), "Example Light", 0x8000, "unique-id",
);
// The attribute list is derived from the product, not written twice.
let attributes = Attributes::new(&PRODUCT, false, false);
// Sorted by cluster id — 0x001D, 0x0028, 0x0030, 0x0031 — because the lookups binary-
// search and `Node::validate` is what catches getting it wrong.
let clusters = [
descriptor::cluster(), // 0x001D
attributes.cluster(), // 0x0028
general_commissioning::cluster(), // 0x0030
netcomm::ethernet(), // 0x0031
];
// §9.5 requires every endpoint to declare at least one device type. It lives on the
// endpoint rather than on the Descriptor cluster, because access control matches ACL
// targets against it too and the two must not be able to disagree.
const ROOT_NODE: &[DeviceType] = &[DeviceType::new(0x0016, 3)];
let endpoints = [Endpoint::new(0, &clusters).with_device_types(ROOT_NODE)];
let node = Node::new(&endpoints);
node.validate().expect("sorted, so the binary searches cannot silently miss");
// One `Location` cell, shared: §11.10.7.4's SetRegulatoryConfig writes Basic
// Information's Location attribute.
let location = Location::region_agnostic();
// The fail-safe is node state, not cluster state: §11.18's credential commands record
// against the same context General Commissioning arms.
let fail_safe = core::cell::RefCell::new(FailSafe::new(BasicCommissioningInfo::default()));
// And so is the commissioning window: §11.19 opens it, §11.10.7.2 gives a PASE
// commissioner priority while it is open, and §11.10.7.6 closes it.
let window = core::cell::RefCell::new(CommissioningWindow::new());
// An Ethernet interface needs no driver and accepts no commands (§11.9.7's table is
// `WI | TH`); its one `Networks` entry is seeded by the server.
let ethernet = EthernetDriver;
let network = NetworkCommissioning::<_, 1>::new(ðernet, &fail_safe, Capabilities::default());
network.store_mut().seed(b"eth0", true).expect("one entry fits");
let handler = (
Descriptor::new(node, 0),
BasicInformation::new(&PRODUCT, &location),
GeneralCommissioning::new(
&location,
RegulatoryLocation::IndoorOutdoor,
&fail_safe,
&window,
),
network,
);
// `handler` is a `ClusterHandler`; hand it to `Server::new` with an access control.The match is over const ids, so it compiles to a jump table and costs nothing at
runtime — the same dispatch a hand-written match would produce, without the chance of
forgetting an arm.
§Why these types carry state and the descriptors do not
A cluster descriptor is the cluster’s shape and lives
in flash. What each type here adds is its values — a device’s vendor name, its
breadcrumb, its fail-safe. ClusterHandler takes &self
because reads must be possible from a shared reference, so anything mutable is behind a
Cell: no allocation, no locking, and no &mut threaded through the
interaction model for the sake of two attributes.
Re-exports§
pub use administrator_commissioning::AdministratorCommissioning;rustcryptopub use basic_information::BasicInformation;pub use descriptor::Descriptor;pub use general_commissioning::GeneralCommissioning;pub use network_commissioning::NetworkCommissioning;pub use operational_credentials::OperationalCredentials;rustcrypto
Modules§
- access_
control - Access Control, cluster
0x001F(Core §9.10). - administrator_
commissioning rustcrypto - Administrator Commissioning needs
crypto’s SPAKE2+ verifier andsc’s PBKDF parameters. Administrator Commissioning cluster0x003C(Core §11.19) — letting a second administrator in. - basic_
information - Basic Information cluster
0x0028(Core §11.1) — who this node is. - binding
- Binding, cluster
0x001E(Core §9.6). - bridged_
device_ basic_ information - Bridged Device Basic Information, cluster
0x0039(Core §9.13). - commissioner_
control - Commissioner Control, cluster
0x0751(Core §11.26) — Fabric Synchronization’s front door. - descriptor
- Descriptor cluster
0x001D(Core §9.5) — what an endpoint is. - device_
energy_ management - Device Energy Management, cluster
0x0098(Application Cluster §9.2). - electrical_
measurement - Electrical Power Measurement (
0x0090, §2.13) and Electrical Energy Measurement (0x0091, §2.12) — what an appliance is drawing, and what it has drawn. - energy_
evse - Energy EVSE, cluster
0x0099(Application Cluster §9.3). - ethernet_
network_ diagnostics - Ethernet Network Diagnostics, cluster
0x0037(Core §11.16). - general_
commissioning - General Commissioning cluster
0x0030(Core §11.10) — the commissioning lifecycle. - general_
diagnostics - General Diagnostics, cluster
0x0033(Core §11.12). - generated
- The Matter cluster library, generated from the CSA data model.
- group_
key_ management rustcrypto - Group Key Management, cluster
0x003F(Core §11.2). - groupcast
provisionalandrustcrypto - §11.27 is provisional (Core §2.13), and its key material is
group’s. Groupcast, cluster0x0065(Core §11.27). Provisional. - groups
- Groups, cluster
0x0004(Application Cluster §1.3). - icd_
management rustcrypto - ICD Management needs
icd’s Check-In Protocol, which is cryptography. ICD Management, cluster0x0046(Core §9.16). - identify
- Identify, cluster
0x0003(Application Cluster §1.2). - joint_
fabric_ administrator rustcrypto - Joint Fabric Administrator, cluster
0x0753(Core §11.25). - joint_
fabric_ datastore rustcrypto - Joint Fabric Datastore, cluster
0x0752(Core §11.24). - label
- Fixed Label
0x0040and User Label0x0041(Core §9.7–9.9). - level_
control - Level Control, cluster
0x0008(Application Cluster §1.6). - mode
- Mode Base (Application Cluster §1.10) — one implementation for every cluster derived from it.
- network_
commissioning - Network Commissioning cluster
0x0031(Core §11.9) — putting a device on a network. - on_off
- On/Off, cluster
0x0006(Application Cluster §1.5). - operational_
credentials rustcrypto - Operational Credentials needs
cert,attestationandfabric, which are all cryptography. Operational Credentials cluster0x003E(Core §11.18) — joining and leaving fabrics. - ota_
provider - OTA Software Update Provider, cluster
0x0029(Core §11.20.6). - ota_
requestor - OTA Software Update Requestor, cluster
0x002A(Core §11.20.7). - scenes
- Scenes Management, cluster
0x0062(Application Cluster §1.4). - software_
diagnostics - Software Diagnostics, cluster
0x0034(Core §11.13). - thermostat_
suggestions - Thermostat suggestions: §4.3.7’s
TSUGfeature of the Thermostat cluster (App §4.3). - thread_
network_ diagnostics - Thread Network Diagnostics, cluster
0x0035(Core §11.14). - tls
rustcrypto - TLS on a Matter node (Core ch. 14): the certificates and the endpoints.
- water_
heater_ management - Water Heater Management, cluster
0x0094(Application Cluster §9.5). - wi_
fi_ network_ diagnostics - Wi-Fi Network Diagnostics, cluster
0x0036(Core §11.15).
Structs§
- At
- One endpoint’s clusters, for a node that has more than one.
- Endpoints
- A node’s endpoints, each an
At.
Enums§
- Reading
- What a driver can say about a diagnostics attribute whose
nullmeans something.
Traits§
- Cluster
- One cluster implementation, tagged with the id it answers for.
Functions§
- endpoint_
satisfies - Whether an endpoint is furnished for a device type it claims.
- validate_
endpoint - Checks an endpoint against a device type, using the generated cluster library to resolve the feature codes a device type names (§9.2).