matc/lib.rs
1//! Matter controller library
2//!
3//! This library allows to controll Matter compatible devices. Library uses asynchronous Rust and depends on Tokio.
4//! Following are main parts of api:
5//! - [Transport](transport::Transport) - Representation of IP/UDP transport. Binds to specified IP/port,
6//! allows to define virtual connections for remote destinations
7//! and demultiplexes incoming messages based on these connections.
8//! - [CertManager](certmanager::CertManager) - Trait allowing to supply external certificate storage.
9//! Default implementation [certmanager::FileCertManager] stores certificates to specified directory in PEM format.
10//! - [Controller](controller::Controller) - Matter controller - uses [Transport](transport::Transport) to send/receive messages,
11//! [CertManager](certmanager::CertManager) to get certificates.
12//! Allows to [commission](controller::Controller::commission) device, [authenticate](controller::Controller::auth_sigma)
13//! commissioned device. Authenticated device is represented by [Connection](controller::Connection) which allows to
14//! [read attributes](controller::Connection::read_request) and [invoke commands](controller::Connection::invoke_request).
15//! - [tlv](tlv) - Module with simple matter tlv encoders and decoders which can be used to encode command parameters
16//! and decode complex responses.
17//! - [discover](discover) - simple mdns based discovery of matter devices on local network
18//!
19//!
20//! Examples directory contains simple demo application and simple standalone examples on how to use APIs.
21//!
22//! Example how to initialize certificate authority and create controller user - stores certificates in pem directory:
23//! ```no_run
24//! # use matc::certmanager::FileCertManager;
25//! # use anyhow::Result;
26//! # fn main() -> Result<()> {
27//! let fabric_id = 1000;
28//! let controller_id = 100;
29//! let cm = FileCertManager::new(fabric_id, "./pem");
30//! cm.bootstrap()?;
31//! cm.create_user(controller_id)?;
32//! # Ok(())
33//! # }
34//! ```
35//!
36//! Example how to commission device using certificates pre-created in pem directory:
37//! ```no_run
38//! # use matc::certmanager;
39//! # use anyhow::Result;
40//! # use std::sync::Arc;
41//! # use matc::transport;
42//! # use matc::controller;
43//! # use matc::clusters;
44//! # #[tokio::main]
45//! # async fn main() -> Result<()> {
46//! let fabric_id = 1000;
47//! let device_id = 300;
48//! let controller_id = 100;
49//! let pin = 123456;
50//! let cm: Arc<dyn certmanager::CertManager> = certmanager::FileCertManager::load("./pem")?;
51//! let transport = transport::Transport::new("0.0.0.0:5555").await?;
52//! let controller = controller::Controller::new(&cm, &transport, fabric_id)?;
53//! let connection = transport.create_connection("1.2.3.4:5540").await;
54//! let mut connection = controller.commission(&connection, pin, device_id, controller_id).await?;
55//! // commission method returns authenticated connection which can be used to send commands
56//! // now we can send ON command:
57//! connection.invoke_request(1, // endpoint
58//! clusters::defs::CLUSTER_ID_ON_OFF,
59//! clusters::defs::CLUSTER_ON_OFF_CMD_ID_ON,
60//! &[]).await?;
61//! # Ok(())
62//! # }
63//! ```
64//!
65//! Example sending ON command to device which is already commissioned using certificates pre-created in pem directory:
66//! ```no_run
67//! # use matc::certmanager;
68//! # use anyhow::Result;
69//! # use std::sync::Arc;
70//! # use matc::transport;
71//! # use matc::controller;
72//! # use matc::tlv;
73//! # use matc::clusters;
74//! # #[tokio::main]
75//! # async fn main() -> Result<()> {
76//! let fabric_id = 1000;
77//! let device_id = 300;
78//! let controller_id = 100;
79//! let cm: Arc<dyn certmanager::CertManager> = certmanager::FileCertManager::load("./pem")?;
80//! let transport = transport::Transport::new("0.0.0.0:5555").await?;
81//! let controller = controller::Controller::new(&cm, &transport, fabric_id)?;
82//! let connection = transport.create_connection("1.2.3.4:5540").await;
83//! let mut c = controller.auth_sigma(&connection, device_id, controller_id).await?;
84//! // send ON command
85//! c.invoke_request(1, // endpoint
86//! clusters::defs::CLUSTER_ID_ON_OFF,
87//! clusters::defs::CLUSTER_ON_OFF_CMD_ID_ON,
88//! &[]).await?;
89//! //
90//! // invoke SetLevel command to show how to supply command parameters
91//! let tlv = tlv::TlvItemEnc {
92//! tag: 0,
93//! value: tlv::TlvItemValueEnc::StructInvisible(vec![
94//! tlv::TlvItemEnc { tag: 0, value: tlv::TlvItemValueEnc::UInt8(50) }, // level
95//! tlv::TlvItemEnc { tag: 1, value: tlv::TlvItemValueEnc::UInt16(1000)}, // transition time
96//! tlv::TlvItemEnc { tag: 2, value: tlv::TlvItemValueEnc::UInt8(0) }, // options mask
97//! tlv::TlvItemEnc { tag: 3, value: tlv::TlvItemValueEnc::UInt8(0) }, // options override
98//! ])
99//! }.encode()?;
100//! c.invoke_request(1, // endpoint
101//! clusters::defs::CLUSTER_ID_LEVEL_CONTROL,
102//! clusters::defs::CLUSTER_LEVEL_CONTROL_CMD_ID_MOVETOLEVEL,
103//! &tlv).await?;
104//! //
105//! // read level
106//! let result = c.read_request2(1,
107//! clusters::defs::CLUSTER_ID_LEVEL_CONTROL,
108//! clusters::defs::CLUSTER_LEVEL_CONTROL_ATTR_ID_CURRENTLEVEL,
109//! ).await?;
110//! println!("{:?}", result);
111//! # Ok(())
112//! # }
113//! ```
114//!
115//!
116#![doc = include_str!("../readme.md")]
117
118pub mod cert_matter;
119pub mod cert_x509;
120pub mod certmanager;
121pub mod clusters;
122mod commission;
123pub mod controller;
124pub mod discover;
125mod fabric;
126pub mod mdns;
127pub mod messages;
128pub mod onboarding;
129mod retransmit;
130mod session;
131mod sigma;
132pub mod spake2p;
133pub mod tlv;
134pub mod transport;
135mod util;