matc 0.1.2

Matter protocol library (controller side)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222

//! Device manager for simplified Matter device interaction.
//!
//! Wraps certificate management, transport, controller, and a persistent device
//! registry so that commissioning and connecting to devices is simpler
//!
//! # First-time setup
//! ```no_run
//! # use matc::devman::{DeviceManager, ManagerConfig};
//! # #[tokio::main]
//! # async fn main() -> anyhow::Result<()> {
//! let config = ManagerConfig { fabric_id: 1000, controller_id: 100,
//!                              local_address: "0.0.0.0:5555".into() };
//! let dm = DeviceManager::create("./matter-data", config).await?;
//! let conn = dm.commission("192.168.1.100:5540", 123456, 300, "kitchen light").await?;
//! # Ok(())
//! # }
//! ```
//!
//! # Reconnecting later
//! ```no_run
//! # use matc::devman::DeviceManager;
//! # #[tokio::main]
//! # async fn main() -> anyhow::Result<()> {
//! let dm = DeviceManager::load("./matter-data").await?;
//! let conn = dm.connect_by_name("kitchen light").await?;
//! # Ok(())
//! # }
//! ```

mod config;
mod device;

pub use config::ManagerConfig;
pub use device::Device;

use std::sync::Arc;

use anyhow::{Context, Result};

use crate::{certmanager, controller, transport};

pub struct DeviceManager {
    base_path: String,
    config: ManagerConfig,
    transport: Arc<transport::Transport>,
    controller: Arc<controller::Controller>,
    certmanager: Arc<dyn certmanager::CertManager>,
    registry: std::sync::Mutex<device::DeviceRegistry>,
}

impl DeviceManager {
    /// First-time setup: creates directory structure, bootstraps CA,
    /// creates controller user, and saves config.
    pub async fn create(base_path: &str, config: ManagerConfig) -> Result<Self> {
        std::fs::create_dir_all(base_path)
            .context(format!("creating base directory {}", base_path))?;
        config::save_config(base_path, &config)?;

        let pem = config::pem_path(base_path);
        let cm = certmanager::FileCertManager::new(config.fabric_id, &pem);
        cm.bootstrap()?;
        cm.create_user(config.controller_id)?;

        let cm: Arc<dyn certmanager::CertManager> = certmanager::FileCertManager::load(&pem)?;
        let transport = transport::Transport::new(&config.local_address).await?;
        let controller = controller::Controller::new(&cm, &transport, config.fabric_id)?;
        let registry = device::DeviceRegistry::load(&config::devices_path(base_path))?;

        Ok(Self {
            base_path: base_path.to_owned(),
            config,
            transport,
            controller,
            certmanager: cm,
            registry: std::sync::Mutex::new(registry),
        })
    }

    /// Load an existing device manager from a previously created base directory.
    pub async fn load(base_path: &str) -> Result<Self> {
        let config = config::load_config(base_path)?;
        let pem = config::pem_path(base_path);
        let cm: Arc<dyn certmanager::CertManager> = certmanager::FileCertManager::load(&pem)?;
        let transport = transport::Transport::new(&config.local_address).await?;
        let controller = controller::Controller::new(&cm, &transport, config.fabric_id)?;
        let registry = device::DeviceRegistry::load(&config::devices_path(base_path))?;

        Ok(Self {
            base_path: base_path.to_owned(),
            config,
            transport,
            controller,
            certmanager: cm,
            registry: std::sync::Mutex::new(registry),
        })
    }

    /// Commission a device and save it to the registry.
    /// Returns an authenticated connection ready for commands.
    pub async fn commission(
        &self,
        address: &str,
        pin: u32,
        node_id: u64,
        name: &str,
    ) -> Result<controller::Connection> {
        let conn = self.transport.create_connection(address).await;
        let connection = self
            .controller
            .commission(&conn, pin, node_id, self.config.controller_id)
            .await?;

        let device = Device {
            node_id,
            address: address.to_owned(),
            name: name.to_owned(),
        };
        self.registry
            .lock()
            .map_err(|e| anyhow::anyhow!("registry lock: {}", e))?
            .add(device)?;

        Ok(connection)
    }

    /// Connect to a previously commissioned device by node ID.
    pub async fn connect(&self, node_id: u64) -> Result<controller::Connection> {
        let address = {
            let reg = self.registry.lock().map_err(|e| anyhow::anyhow!("registry lock: {}", e))?;
            reg.get(node_id)
                .context(format!("device {} not found in registry", node_id))?
                .address
                .clone()
        };
        let conn = self.transport.create_connection(&address).await;
        self.controller
            .auth_sigma(&conn, node_id, self.config.controller_id)
            .await
    }

    /// Connect to a previously commissioned device by friendly name.
    pub async fn connect_by_name(&self, name: &str) -> Result<controller::Connection> {
        let (node_id, address) = {
            let reg = self.registry.lock().map_err(|e| anyhow::anyhow!("registry lock: {}", e))?;
            let dev = reg
                .get_by_name(name)
                .context(format!("device '{}' not found in registry", name))?;
            (dev.node_id, dev.address.clone())
        };
        let conn = self.transport.create_connection(&address).await;
        self.controller
            .auth_sigma(&conn, node_id, self.config.controller_id)
            .await
    }

    /// List all registered devices.
    pub fn list_devices(&self) -> Result<Vec<Device>> {
        let reg = self.registry.lock().map_err(|e| anyhow::anyhow!("registry lock: {}", e))?;
        Ok(reg.list().to_vec())
    }

    /// Get a device by node ID.
    pub fn get_device(&self, node_id: u64) -> Result<Option<Device>> {
        let reg = self.registry.lock().map_err(|e| anyhow::anyhow!("registry lock: {}", e))?;
        Ok(reg.get(node_id).cloned())
    }

    /// Get a device by friendly name.
    pub fn get_device_by_name(&self, name: &str) -> Result<Option<Device>> {
        let reg = self.registry.lock().map_err(|e| anyhow::anyhow!("registry lock: {}", e))?;
        Ok(reg.get_by_name(name).cloned())
    }

    /// Remove a device from the registry.
    pub fn remove_device(&self, node_id: u64) -> Result<()> {
        self.registry
            .lock()
            .map_err(|e| anyhow::anyhow!("registry lock: {}", e))?
            .remove(node_id)
    }

    /// Rename a device in the registry.
    pub fn rename_device(&self, node_id: u64, name: &str) -> Result<()> {
        self.registry
            .lock()
            .map_err(|e| anyhow::anyhow!("registry lock: {}", e))?
            .rename(node_id, name)
    }

    /// Update the stored address for a device.
    pub fn update_device_address(&self, node_id: u64, address: &str) -> Result<()> {
        self.registry
            .lock()
            .map_err(|e| anyhow::anyhow!("registry lock: {}", e))?
            .update_address(node_id, address)
    }

    /// Get a reference to the underlying controller.
    pub fn controller(&self) -> &Arc<controller::Controller> {
        &self.controller
    }

    /// Get a reference to the underlying transport.
    pub fn transport(&self) -> &Arc<transport::Transport> {
        &self.transport
    }

    /// Get a reference to the certificate manager.
    pub fn certmanager(&self) -> &Arc<dyn certmanager::CertManager> {
        &self.certmanager
    }

    /// Get the config.
    pub fn config(&self) -> &ManagerConfig {
        &self.config
    }

    /// Get the base path.
    pub fn base_path(&self) -> &str {
        &self.base_path
    }
}