Skip to main content

Crate matter_controller

Crate matter_controller 

Source
Expand description

The high-level Matter controller API — the single crate a consumer depends on to commission and control Matter devices from pure Rust.

MatterController is the entry point. It persists a fabric and a stable commissioner identity through a pluggable ControllerStore (a default FileStore ships), commissions devices over IP, and exposes each device through a cheap Node handle that transparently establishes, caches, and reuses the operational CASE session.

§Capabilities

§Quickstart

use std::sync::Arc;
use matter_controller::{
    AttestationTrust, FabricConfig, FileStore, MatterController, MatterTime, ReadPath,
    SubscriptionEvent,
};

// Persisted store + attestation trust (test roots shown; use
// `AttestationTrust::from_dirs(..)` with production PAA/CD roots for
// certified devices).
let store = Arc::new(FileStore::new("controller-state.bin"));
let controller = MatterController::builder(store)
    .attestation_trust(AttestationTrust::example_device_roots())
    .build()
    .await?;

// One-time: create the fabric (idempotent across restarts — load the
// snapshot instead of re-creating in real apps).
let fabric_id = controller.create_fabric(FabricConfig::new(
    1,
    1,
    1,
    (MatterTime::from_unix_secs(0), MatterTime::NO_EXPIRY),
)).await?;
let _ = fabric_id;

// Commission a device, then control it. `label` is an opaque
// caller-supplied string persisted on the device entry; pass `None` if
// you have nothing to attach.
let info = controller
    .commission("MT:Y.K90AFN00KA0648G00", Some("kitchen plug".into()))
    .await?;
let node = controller.node(info.node_id);

// Read all attributes of the OnOff cluster (0x0006) on endpoint 1.
let report = node.read(&[ReadPath::cluster(1, 0x0006)]).await?;
for (path, value) in report {
    println!("{path:?} = {value:?}");
}

// Subscribe to live changes.
let mut sub = node.subscribe(&[ReadPath::cluster(1, 0x0006)], &[], 1, 30).await?;
while let Some(event) = sub.next().await {
    if let SubscriptionEvent::Report(change) = event {
        println!("changed: {:?} = {:?}", change.path, change.value);
    }
}

Migrating from matter.js? See docs/matter-js-migration-guide.md.

Re-exports§

pub use builder::MatterControllerBuilder;
pub use controller::MatterController;
pub use error::Error;
pub use fabric::FabricConfig;
pub use node::DstOffsetEntry;
pub use node::InvokeResult;
pub use node::Node;
pub use node::TimeGranularity;
pub use node::TimeZoneEntry;
pub use state::CommissionerIdentity;
pub use state::ControllerState;
pub use state::DeviceEntry;
pub use state::FabricEntry;
pub use state::GroupKeySetConfig;
pub use store::ControllerStore;
pub use store::FileStore;
pub use store::StoreError;
pub use subscription::AttributeReport;
pub use subscription::Subscription;
pub use subscription::SubscriptionEvent;
pub use trust::AttestationTrust;

Modules§

builder
Builder for MatterController. Configures attestation trust and the admin vendor id before spawning the owning actor.
controller
MatterController — the public entry point. A cheap, cloneable handle over the owning actor task (a crate-internal tokio task).
error
Error type for matter-controller.
fabric
Fabric creation. Mints the fabric trust root (RCAC + IPK) and the controller’s stable commissioner operational identity in one shot. The commissioner NOC is minted here exactly once and persisted; every later CASE handshake reuses it (retiring the earlier per-call minting).
node
A cheap handle addressing one device node. Holds no session state.
state
In-memory controller state. These types are the persistable record; live signers are reconstructed from the stored PKCS#8 keys on demand.
store
Persistence abstraction. The controller writes an opaque, versioned snapshot blob through this trait; it never assumes a filesystem.
subscription
A live attribute subscription: reports arrive via Subscription::next.
trust
Device-attestation trust material: the PAA roots that anchor DAC/PAI chain validation and the CD signing roots that anchor Certification-Declaration signatures. Configured once on the controller (attestation is a fabric-wide security policy — chip holds it on the commissioner the same way).

Structs§

AclEntry
One ACL entry (AccessControlEntryStruct, Matter spec §9.10.5.2).
AclTarget
One ACL target (AccessControlTargetStruct, Matter spec §9.10.5.4).
AttributePath
A concrete attribute path: (endpoint, cluster, attribute).
BindingTarget
One Binding.TargetStruct — a unicast (node + endpoint [+ cluster]) or group (group [+ cluster]) binding. The device stamps the fabric index; callers never set it.
CheckIn
A verified inbound Check-In from a registered ICD.
CommandPath
A concrete command path: (endpoint, cluster, command).
CommissioningWindow
The result of opening an enhanced commissioning window — everything a second commissioner needs to onboard the device onto its own fabric.
EventFilter
An EventFilterIB: only events with event_number >= event_min are reported (used to resume after the last seen event). node is omitted when None.
EventPath
A read/subscribe event path with optional (wildcard) components. A None field is omitted from the encoded EventPathIB, which the IM interprets as a wildcard. node is normally None for a controller addressing the connected node; is_urgent requests urgent reporting on a subscription (B2).
EventReportItem
One EventDataIB (a real event with data).
FabricDescriptor
One fabric a device belongs to (a decoded FabricDescriptorStruct).
GroupKeyMapEntry
One GroupKeyMap entry binding a group id to a key set (Matter §11.2.6.x).
GroupKeySet
A group key set to provision via KeySetWrite (Matter §11.2.6.1).
IcdRegistration
A persisted ICD client registration — the controller registered itself as a check-in client with the device node_id, and holds the shared key needed to verify that device’s Check-In messages.
MatterTime
A Matter time value: seconds since 2000-01-01T00:00:00Z, wrapping as a u32 (the spec’s wire-native representation).
NodeInfo
Metadata about a node commissioned onto one of the controller’s fabrics.
OpenWindowOpts
Options for Node::open_commissioning_window.
ReadPath
A read-request attribute path with optional (wildcard) components. A None field is omitted from the encoded AttributePathIB, which the Matter IM interprets as a wildcard (Appendix A.6): omit attribute → all attributes of the cluster; omit endpoint → all endpoints; etc. Responses are always keyed by a concrete AttributePath.
ThreadDataset
Network (Wi-Fi/Thread) credentials for MatterController::commission_ble (feature ble) and the network-type witness for Error::network_feature_unsupported, re-exported from matter-commissioning. A Thread operational dataset (Thread TLV bytes) used to provision a device onto a Thread network. The caller obtains it from a border router (e.g. ot-ctl dataset active -x, hex-decoded).
WiFiCredentials
Network (Wi-Fi/Thread) credentials for MatterController::commission_ble (feature ble) and the network-type witness for Error::network_feature_unsupported, re-exported from matter-commissioning. Wi-Fi station credentials supplied to AddOrUpdateWiFiNetwork.
WindowStatus
Snapshot of the AdministratorCommissioning status attributes.

Enums§

AclAuthMode
ACL authentication mode (AccessControlEntryAuthModeEnum, Matter spec §9.10.5.3).
AclPrivilege
ACL privilege level (AccessControlEntryPrivilegeEnum, Matter spec §9.10.5.3).
CommissioningWindowStatus
Decoded WindowStatus enum8.
EventPriority
Event priority (Matter §14.3). Unknown values are preserved verbatim so a newer-revision device does not break decoding.
EventReport
One EventReportIB: a real event (Data) or a per-path error (Status).
EventTimestamp
The timestamp carried by an EventDataIB. A report carries exactly one of these (absolute epoch/system, or a delta against the prior event in a subscription stream); None if the device omitted all four (tolerated rather than rejected).
IcdClientType
IcdManagement.ClientTypeEnum — whether the registration is permanent or ephemeral (Matter Core §9.17).
ImStatus
An Interaction Model status, as carried by a StatusIB.
NetworkCredentials
Network (Wi-Fi/Thread) credentials for MatterController::commission_ble (feature ble) and the network-type witness for Error::network_feature_unsupported, re-exported from matter-commissioning. Operational-network credentials for the commissionee, selecting which network-provisioning sub-cursor the state machine runs after AddNOC.
NetworkKind
Network (Wi-Fi/Thread) credentials for MatterController::commission_ble (feature ble) and the network-type witness for Error::network_feature_unsupported, re-exported from matter-commissioning. Which Matter network-commissioning type a device declared in its NetworkCommissioning::FeatureMap.
Value
A decoded Matter TLV value, collapsed across wire widths.

Constants§

DEFAULT_WINDOW_ITERATIONS
Spec default/floor PBKDF iterations for an opened window.
DEFAULT_WINDOW_TIMEOUT_S
Spec-recommended commissioning-window timeout (seconds).