Expand description
Matter controller library
This library allows to controll Matter compatible devices. Library uses asynchronous Rust and depends on Tokio. Following are main parts of api:
- Transport - Representation of IP/UDP transport. Binds to specified IP/port, allows to define virtual connections for remote destinations and demultiplexes incoming messages based on these connections.
- CertManager - Trait allowing to supply external certificate storage. Default implementation certmanager::FileCertManager stores certificates to specified directory in PEM format.
- Controller - Matter controller - uses Transport to send/receive messages, CertManager to get certificates. Allows to commission device, authenticate commissioned device. Authenticated device is represented by Connection which allows to read attributes and invoke commands.
- tlv - Module with simple matter tlv encoders and decoders which can be used to encode command parameters and decode complex responses.
- discover - simple mdns based discovery of matter devices on local network
Examples directory contains simple demo application and simple standalone examples on how to use APIs.
Example how to initialize certificate authority and create controller user - stores certificates in pem directory:
let fabric_id = 1000;
let controller_id = 100;
let cm = FileCertManager::new(fabric_id, "./pem");
cm.bootstrap()?;
cm.create_user(controller_id)?;
Example how to commission device using certificates pre-created in pem directory:
let fabric_id = 1000;
let device_id = 300;
let controller_id = 100;
let pin = 123456;
let cm: Arc<dyn certmanager::CertManager> = certmanager::FileCertManager::load("./pem")?;
let transport = transport::Transport::new("0.0.0.0:5555").await?;
let controller = controller::Controller::new(&cm, &transport, fabric_id)?;
let connection = transport.create_connection("1.2.3.4:5540").await;
let mut connection = controller.commission(&connection, pin, device_id, controller_id).await?;
// commission method returns authenticated connection which can be used to send commands
// now we can send ON command:
connection.invoke_request(1, // endpoint
clusters::defs::CLUSTER_ID_ON_OFF,
clusters::defs::CLUSTER_ON_OFF_CMD_ID_ON,
&[]).await?;
Example sending ON command to device which is already commissioned using certificates pre-created in pem directory:
let fabric_id = 1000;
let device_id = 300;
let controller_id = 100;
let cm: Arc<dyn certmanager::CertManager> = certmanager::FileCertManager::load("./pem")?;
let transport = transport::Transport::new("0.0.0.0:5555").await?;
let controller = controller::Controller::new(&cm, &transport, fabric_id)?;
let connection = transport.create_connection("1.2.3.4:5540").await;
let mut c = controller.auth_sigma(&connection, device_id, controller_id).await?;
// send ON command
c.invoke_request(1, // endpoint
clusters::defs::CLUSTER_ID_ON_OFF,
clusters::defs::CLUSTER_ON_OFF_CMD_ID_ON,
&[]).await?;
//
// invoke SetLevel command to show how to supply command parameters
let tlv = tlv::TlvItemEnc {
tag: 0,
value: tlv::TlvItemValueEnc::StructInvisible(vec![
tlv::TlvItemEnc { tag: 0, value: tlv::TlvItemValueEnc::UInt8(50) }, // level
tlv::TlvItemEnc { tag: 1, value: tlv::TlvItemValueEnc::UInt16(1000)}, // transition time
tlv::TlvItemEnc { tag: 2, value: tlv::TlvItemValueEnc::UInt8(0) }, // options mask
tlv::TlvItemEnc { tag: 3, value: tlv::TlvItemValueEnc::UInt8(0) }, // options override
])
}.encode()?;
c.invoke_request(1, // endpoint
clusters::defs::CLUSTER_ID_LEVEL_CONTROL,
clusters::defs::CLUSTER_LEVEL_CONTROL_CMD_ID_MOVETOLEVEL,
&tlv).await?;
//
// read level
let result = c.read_request2(1,
clusters::defs::CLUSTER_ID_LEVEL_CONTROL,
clusters::defs::CLUSTER_LEVEL_CONTROL_ATTR_ID_CURRENTLEVEL,
).await?;
println!("{:?}", result);
§simple rust matter protocol library
This is prototype of matter protocol library in rust (controller side).
It supports controller side of:
- PASE - passcode authenticated session establishment
- variant of spake 2+
- CASE - certificate authenticated session establishment
- variant of SIGMA
- Commisioning procedure
- sign and push certificates to device
- Basic interactions
- Read attribute
- Invoke command
Use of demo application:
-
Compile demo application using cargo. Binary will be found usually in target/debug/examples/demo.
cargo build --example demo
-
demo application uses clap. use –help to learn all supported parameters
-
create CA certificates in directory pem:
./demo ca-bootstrap
-
create key/certificate for controller with id 100:
./demo ca-create-controller 100
-
discover all commissionable devices using mdns:
./demo discover commissionable --timeout 3
-
discover all commissioned devices using mdns:
./demo discover commissioned --timeout 3
-
if you have manual pairing code you need to extract passcode from it using following command:
demo decode-manual-pairing-code 1577-384-0075
-
commission device (device ip address is 192.168.5.70, commissioning passcode is 123456, device id will be 300, device admin has id 100):
./demo commission 192.168.5.70:5540 100 300 123456
-
update fabric label in device:
./demo command invoke-command-update-fabric-label --device-address 192.168.5.70:5540 --controller-id 100 --device-id 300 "testfabric"
-
example how to use read command to read any attribute. This example lists all provisioned fabrics by reading attribute 1(fabrics) from cluster 62 (operational credentials) from endpoint 0:
./demo command read --device-address 192.168.5.70:5540 --controller-id 100 --device-id 300 0 62 1
-
turn device on/off:
demo command invoke-command-on --device-address 192.168.5.70:5540 --controller-id 100 --device-id 300
demo command invoke-command-off --device-address 192.168.5.70:5540 --controller-id 100 --device-id 300
-
if you want to start from scratch remove directory pem
Modules§
- cert_
matter - Handling of certificates in Matter format
- cert_
x509 - Handling of x509 certificate compatible with matter
- certmanager
- Certificate manager trait and default file based implementation
- clusters
- controller
- discover
- Module with very simple mdns based discovery of matter devices. Usually application shall discover devices using these methods and filter according discriminator. This module tries to send mdns using ipv4 and ipv6 multicast at same time. If more control over discovery mechanism is required, it may be better to use some external mdns library.
- mdns
- Very simple mdns client library
- messages
- onboarding
- tlv
- Utilities to decode/encode matter tlv
- transport