Skip to main content

zigbee_host/
device.rs

1//! What the host knows about each device.
2
3use serde::{Deserialize, Serialize};
4use zigbee_primitives::{Ieee, NodeId};
5use zigbee_zdo::{NodeDescriptor, SimpleDescriptor};
6
7/// The interview's steps, in order.
8#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
9#[serde(rename_all = "snake_case")]
10pub enum InterviewStage {
11    /// Read the node descriptor.
12    NodeDescriptor,
13    /// List the active endpoints.
14    ActiveEndpoints,
15    /// Read each endpoint's simple descriptor.
16    SimpleDescriptors,
17    /// Read the Basic cluster (manufacturer, model, power source).
18    Basic,
19    /// Bind clusters, configure reporting, enroll IAS zones.
20    Configure,
21    /// Finished.
22    Done,
23}
24
25impl InterviewStage {
26    /// The next step.
27    pub fn next(self) -> InterviewStage {
28        match self {
29            InterviewStage::NodeDescriptor => InterviewStage::ActiveEndpoints,
30            InterviewStage::ActiveEndpoints => InterviewStage::SimpleDescriptors,
31            InterviewStage::SimpleDescriptors => InterviewStage::Basic,
32            InterviewStage::Basic => InterviewStage::Configure,
33            InterviewStage::Configure | InterviewStage::Done => InterviewStage::Done,
34        }
35    }
36}
37
38/// Where a device's interview stands. Persisted, so an interview a sleepy
39/// device did not finish resumes where it stopped.
40#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
41pub struct Interview {
42    /// The next step to run ([`InterviewStage::Done`] when complete).
43    pub stage: InterviewStage,
44    /// The last failure, if the interview stopped on one.
45    #[serde(default, skip_serializing_if = "Option::is_none")]
46    pub error: Option<String>,
47    /// Attempts so far.
48    #[serde(default)]
49    pub attempts: u32,
50}
51
52impl Default for Interview {
53    fn default() -> Self {
54        Interview {
55            stage: InterviewStage::NodeDescriptor,
56            error: None,
57            attempts: 0,
58        }
59    }
60}
61
62impl Interview {
63    /// True once every step has run.
64    pub fn is_done(&self) -> bool {
65        self.stage == InterviewStage::Done
66    }
67}
68
69/// A reporting configuration the host wrote to a device.
70#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
71pub struct ConfiguredReport {
72    /// Endpoint.
73    pub endpoint: u8,
74    /// Cluster.
75    pub cluster: u16,
76    /// Attribute.
77    pub attribute: u16,
78    /// The device's ZCL status for it (0 is success).
79    pub status: u8,
80}
81
82/// A device on the network.
83#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
84pub struct Device {
85    /// IEEE address.
86    pub ieee: Ieee,
87    /// Current network address.
88    pub nwk: NodeId,
89    /// A name a person gave it.
90    #[serde(default, skip_serializing_if = "Option::is_none")]
91    pub name: Option<String>,
92    /// The node descriptor.
93    #[serde(default, skip_serializing_if = "Option::is_none")]
94    pub node_descriptor: Option<NodeDescriptor>,
95    /// Endpoints, from the simple descriptors.
96    #[serde(default)]
97    pub endpoints: Vec<SimpleDescriptor>,
98    /// Basic cluster: manufacturer name.
99    #[serde(default, skip_serializing_if = "Option::is_none")]
100    pub manufacturer: Option<String>,
101    /// Basic cluster: model identifier.
102    #[serde(default, skip_serializing_if = "Option::is_none")]
103    pub model: Option<String>,
104    /// Basic cluster: power source.
105    #[serde(default, skip_serializing_if = "Option::is_none")]
106    pub power_source: Option<u8>,
107    /// Basic cluster: software build id.
108    #[serde(default, skip_serializing_if = "Option::is_none")]
109    pub sw_build_id: Option<String>,
110    /// Basic cluster: date code.
111    #[serde(default, skip_serializing_if = "Option::is_none")]
112    pub date_code: Option<String>,
113    /// Basic cluster: ZCL version.
114    #[serde(default, skip_serializing_if = "Option::is_none")]
115    pub zcl_version: Option<u8>,
116    /// Basic cluster: stack version.
117    #[serde(default, skip_serializing_if = "Option::is_none")]
118    pub stack_version: Option<u8>,
119    /// Basic cluster: hardware version.
120    #[serde(default, skip_serializing_if = "Option::is_none")]
121    pub hw_version: Option<u8>,
122    /// Basic cluster: application version.
123    #[serde(default, skip_serializing_if = "Option::is_none")]
124    pub app_version: Option<u8>,
125    /// The interview's progress.
126    #[serde(default)]
127    pub interview: Interview,
128    /// Reporting the host configured.
129    #[serde(default, skip_serializing_if = "Vec::is_empty")]
130    pub reporting: Vec<ConfiguredReport>,
131    /// The IAS zone type (contact, motion, water leak...), read at enrollment.
132    #[serde(default, skip_serializing_if = "Option::is_none")]
133    pub ias_zone_type: Option<u16>,
134    /// The IAS zone id the host enrolled it with.
135    #[serde(default, skip_serializing_if = "Option::is_none")]
136    pub ias_zone_id: Option<u8>,
137    /// It completed Zigbee 3.0 trust center link key exchange.
138    #[serde(default)]
139    pub unique_link_key: bool,
140    /// Its parent when it joined.
141    #[serde(default, skip_serializing_if = "Option::is_none")]
142    pub parent: Option<NodeId>,
143    /// When it joined, seconds since the Unix epoch.
144    #[serde(default)]
145    pub joined_unix: u64,
146    /// Last time anything arrived from it (not persisted, so receiving a
147    /// message never writes to flash).
148    #[serde(skip)]
149    pub last_seen_unix: Option<u64>,
150    /// Link quality of the last message's last hop (not persisted).
151    #[serde(skip)]
152    pub last_lqi: Option<u8>,
153    /// Signal strength of the last message's last hop (not persisted).
154    #[serde(skip)]
155    pub last_rssi: Option<i8>,
156}
157
158impl Device {
159    /// A device that just joined.
160    pub fn new(ieee: Ieee, nwk: NodeId, now_unix: u64) -> Device {
161        Device {
162            ieee,
163            nwk,
164            name: None,
165            node_descriptor: None,
166            endpoints: Vec::new(),
167            manufacturer: None,
168            model: None,
169            power_source: None,
170            sw_build_id: None,
171            date_code: None,
172            zcl_version: None,
173            stack_version: None,
174            hw_version: None,
175            app_version: None,
176            interview: Interview::default(),
177            reporting: Vec::new(),
178            ias_zone_type: None,
179            ias_zone_id: None,
180            unique_link_key: false,
181            parent: None,
182            joined_unix: now_unix,
183            last_seen_unix: None,
184            last_lqi: None,
185            last_rssi: None,
186        }
187    }
188
189    /// The device's receiver is off when idle (a sleepy end device), so
190    /// requests wait at its parent until it polls.
191    pub fn is_sleepy(&self) -> bool {
192        self.node_descriptor
193            .as_ref()
194            .is_some_and(|d| !d.rx_on_when_idle())
195    }
196
197    /// The endpoint that has a cluster as a server, if any.
198    pub fn endpoint_with(&self, cluster: u16) -> Option<&SimpleDescriptor> {
199        self.endpoints
200            .iter()
201            .find(|e| e.input_clusters.contains(&cluster))
202    }
203
204    /// The application profile of an endpoint (Home Automation if unknown).
205    pub fn profile_of(&self, endpoint: u8) -> u16 {
206        self.endpoints
207            .iter()
208            .find(|e| e.endpoint == endpoint)
209            .map(|e| e.profile_id)
210            .unwrap_or(zigbee_zcl::PROFILE_HOME_AUTOMATION)
211    }
212}