Skip to main content

Module clusters

Module clusters 

Source
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(&ethernet, &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;rustcrypto
pub 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_commissioningrustcrypto
Administrator Commissioning needs crypto’s SPAKE2+ verifier and sc’s PBKDF parameters. Administrator Commissioning cluster 0x003C (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_managementrustcrypto
Group Key Management, cluster 0x003F (Core §11.2).
groupcastprovisional and rustcrypto
§11.27 is provisional (Core §2.13), and its key material is group’s. Groupcast, cluster 0x0065 (Core §11.27). Provisional.
groups
Groups, cluster 0x0004 (Application Cluster §1.3).
icd_managementrustcrypto
ICD Management needs icd’s Check-In Protocol, which is cryptography. ICD Management, cluster 0x0046 (Core §9.16).
identify
Identify, cluster 0x0003 (Application Cluster §1.2).
joint_fabric_administratorrustcrypto
Joint Fabric Administrator, cluster 0x0753 (Core §11.25).
joint_fabric_datastorerustcrypto
Joint Fabric Datastore, cluster 0x0752 (Core §11.24).
label
Fixed Label 0x0040 and User Label 0x0041 (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_credentialsrustcrypto
Operational Credentials needs cert, attestation and fabric, which are all cryptography. Operational Credentials cluster 0x003E (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 TSUG feature of the Thermostat cluster (App §4.3).
thread_network_diagnostics
Thread Network Diagnostics, cluster 0x0035 (Core §11.14).
tlsrustcrypto
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 null means 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).