matter_kit/dm/device.rs
1//! Device types: what an endpoint must be furnished with (the Device Library).
2//!
3//! An endpoint advertises its device types in the Descriptor cluster's `DeviceTypeList`
4//! (§9.5.5), and that list is a *claim*. A commissioner reading "On/Off Light" then expects
5//! Identify, Groups, On/Off with its Lighting feature, and Scenes Management to be there — so
6//! a device that advertises the type without furnishing it is one that appears in an app and
7//! then does not work.
8//!
9//! These tables are generated from the same CSA XML the clusters are, and
10//! [`DeviceType::validate`] is the check: given an endpoint's cluster list, what is missing
11//! and what does not belong.
12
13use crate::dm::conformance::{Conform, Conformance, Supports};
14use crate::dm::node::Endpoint;
15use crate::im::{AttributeId, ClusterId, CommandId, EventId};
16
17/// A cluster a device type requires or allows on the endpoint.
18#[derive(Debug, Clone, Copy)]
19pub struct RequiredCluster {
20 /// The cluster's id.
21 pub id: ClusterId,
22 /// The readable name — "On/Off".
23 pub name: &'static str,
24 /// Whether it is the server side. A *client* cluster is a binding target the endpoint
25 /// talks to, not something it serves, so a validator must not demand it in the endpoint's
26 /// own cluster list.
27 pub server: bool,
28 /// Whether the endpoint must have it.
29 pub conform: Conform,
30 /// Feature bits the device type demands beyond the cluster's own conformance, by the
31 /// cluster's own short codes.
32 ///
33 /// This is the part a cluster list alone cannot express: On/Off Light does not merely
34 /// require On/Off, it requires On/Off **with Lighting**, and a light that serves the
35 /// cluster without the feature has no `StartUpOnOff` — so it comes back on at whatever
36 /// state it was in, which is the behaviour the device type exists to rule out.
37 pub features: &'static [(&'static str, Conform)],
38 /// Attributes the device type demands beyond the cluster's own conformance, by name.
39 pub attributes: &'static [(&'static str, Conform)],
40 /// Commands it demands, by name.
41 pub commands: &'static [(&'static str, Conform)],
42 /// Events it demands, by name.
43 pub events: &'static [(&'static str, Conform)],
44}
45
46/// One device type.
47#[derive(Debug, Clone, Copy)]
48pub struct DeviceType {
49 /// The `DeviceTypeID` that appears in `DeviceTypeList`.
50 pub id: u32,
51 /// Its name — "On/Off Light".
52 pub name: &'static str,
53 /// The revision that goes alongside the id in `DeviceTypeList`.
54 pub revision: u16,
55 /// `simple`, `utility`, `node` or `dynamic utility`. A utility device type may share an
56 /// endpoint with another; a *simple* one may not (§9.2), which is the rule a bridge gets
57 /// wrong when it puts two lights on one endpoint.
58 pub class: &'static str,
59 /// `endpoint` or `node`.
60 pub scope: &'static str,
61 /// What the endpoint must and may serve.
62 pub clusters: &'static [RequiredCluster],
63}
64
65/// What an endpoint's furnishing got wrong.
66#[derive(Debug, Clone, Copy, PartialEq, Eq)]
67pub enum Defect {
68 /// A cluster the device type requires and the endpoint does not serve.
69 MissingCluster(ClusterId),
70 /// A cluster the device type explicitly disallows.
71 DisallowedCluster(ClusterId),
72 /// A cluster is present but without a feature the device type demands of it.
73 MissingFeature {
74 /// Which cluster.
75 cluster: ClusterId,
76 /// The feature's short code, as the specification names it.
77 code: &'static str,
78 },
79 /// A cluster the device type requires the endpoint to speak *as a client*, and the
80 /// endpoint's `ClientList` does not name (§9.5.6.3).
81 MissingClient(ClusterId),
82 /// A cluster is present but without an element the device type demands of it.
83 ///
84 /// A device type may tighten its clusters' own conformance: §1.2.6 calls Identify's
85 /// `TriggerEffect` optional, and §4.1's On/Off Light makes it mandatory. A check that
86 /// only compared cluster ids would pass an endpoint whose app screen has a dead button.
87 MissingElement {
88 /// Which cluster.
89 cluster: ClusterId,
90 /// The element's name, as the specification writes it.
91 name: &'static str,
92 },
93}
94
95/// An endpoint, seen as a set of clusters, so device-type conformance can be evaluated.
96struct Furnished<'a> {
97 endpoint: &'a Endpoint<'a>,
98}
99
100impl Supports for Furnished<'_> {
101 fn feature_map(&self) -> u32 {
102 // A device type's conformance is about clusters, never about one cluster's features.
103 0
104 }
105
106 fn has_attribute(&self, _id: AttributeId) -> bool {
107 false
108 }
109
110 fn has_command(&self, _id: CommandId) -> bool {
111 false
112 }
113
114 fn has_event(&self, _id: EventId) -> bool {
115 false
116 }
117
118 fn has_cluster(&self, id: ClusterId) -> bool {
119 self.endpoint
120 .clusters
121 .iter()
122 .any(|cluster| cluster.id == id)
123 }
124}
125
126impl DeviceType {
127 /// Checks an endpoint against this device type, reporting each defect to `found`.
128 ///
129 /// Only **server** clusters are checked. A device type's client-side entries name what the
130 /// endpoint may *bind to* — an On/Off Light's client Occupancy Sensing is a sensor
131 /// somewhere else on the fabric — and demanding one in the endpoint's own list would
132 /// reject every conformant light.
133 ///
134 /// Elements whose conformance is prose are skipped, for the same reason
135 /// [`spec::Cluster::validate`](crate::dm::spec::Cluster::validate) skips them.
136 pub fn validate(
137 &self,
138 endpoint: &Endpoint<'_>,
139 spec_of: impl Fn(ClusterId) -> Option<&'static crate::dm::spec::Cluster>,
140 mut found: impl FnMut(Defect),
141 ) {
142 let furnished = Furnished { endpoint };
143 for required in self.clusters {
144 let verdict = required.conform.verdict(&furnished);
145 if !required.server {
146 // §9.5.6.3's ClientList is the only evidence an endpoint *consumes* a
147 // cluster — a client binding has no descriptor. §6.1's On/Off Light Switch
148 // requires On/Off as a client and as nothing else, so skipping this would
149 // make a light indistinguishable from the switch that controls it.
150 if verdict == Conformance::Mandatory && !endpoint.clients.contains(&required.id) {
151 found(Defect::MissingClient(required.id));
152 }
153 continue;
154 }
155 let present = furnished.has_cluster(required.id);
156 match verdict {
157 Conformance::Mandatory if !present => {
158 found(Defect::MissingCluster(required.id));
159 continue;
160 }
161 Conformance::Disallowed if present => {
162 found(Defect::DisallowedCluster(required.id));
163 continue;
164 }
165 _ => {}
166 }
167 if !present {
168 continue;
169 }
170 Self::check_features(endpoint, required, &spec_of, &mut found);
171 Self::check_elements(endpoint, required, &spec_of, &mut found);
172 }
173 }
174
175 /// The attributes, commands and events a device type demands of a cluster it requires.
176 ///
177 /// A device type names them by the specification's own names — "TriggerEffect",
178 /// "CopyScene" — so resolving one to an id needs the cluster's table, which is what
179 /// `spec_of` supplies. An element the caller's library does not define is skipped rather
180 /// than guessed at, the same way an unknown cluster is.
181 fn check_elements(
182 endpoint: &Endpoint<'_>,
183 required: &RequiredCluster,
184 spec_of: &impl Fn(ClusterId) -> Option<&'static crate::dm::spec::Cluster>,
185 found: &mut impl FnMut(Defect),
186 ) {
187 if required.attributes.is_empty()
188 && required.commands.is_empty()
189 && required.events.is_empty()
190 {
191 return;
192 }
193 let Some(served) = endpoint
194 .clusters
195 .iter()
196 .find(|cluster| cluster.id == required.id)
197 else {
198 return;
199 };
200 let Some(defined) = spec_of(required.id) else {
201 return;
202 };
203 let furnished = Furnished { endpoint };
204 let mut demand = |name: &'static str, conform: &Conform, present: Option<bool>| {
205 if conform.verdict(&furnished) != Conformance::Mandatory {
206 return;
207 }
208 // `None` is an element the library does not define — nothing to check against.
209 if present == Some(false) {
210 found(Defect::MissingElement {
211 cluster: required.id,
212 name,
213 });
214 }
215 };
216 for (name, conform) in required.attributes {
217 let present = defined
218 .attributes
219 .iter()
220 .find(|a| a.name == *name)
221 .map(|a| served.attribute(a.id).is_some());
222 demand(name, conform, present);
223 }
224 for (name, conform) in required.commands {
225 let present = defined.commands.iter().find(|c| c.name == *name).map(|c| {
226 if c.to_server {
227 served.accepted_command(c.id).is_some()
228 } else {
229 // A response command is generated, never accepted: §7.13.4's
230 // GeneratedCommandList is derived from the accepted commands' responses,
231 // plus whatever the instance generates unprompted.
232 served.generated_commands.contains(&c.id)
233 || served
234 .accepted_commands
235 .iter()
236 .any(|a| a.response == Some(c.id))
237 }
238 });
239 demand(name, conform, present);
240 }
241 for (name, conform) in required.events {
242 let present = defined
243 .events
244 .iter()
245 .find(|e| e.name == *name)
246 .map(|e| served.events.iter().any(|served| served.id == e.id));
247 demand(name, conform, present);
248 }
249 }
250
251 /// The features a device type demands of a cluster it requires.
252 ///
253 /// Resolving a short code to a bit needs the cluster's own feature table, and `spec_of`
254 /// is how the caller supplies it —
255 /// [`clusters::validate_endpoint`](crate::clusters::validate_endpoint) passes the
256 /// generated library. A parameter rather than a reach into `clusters::generated` because
257 /// the data model is the layer *below* the cluster library, and a cluster the caller does
258 /// not know is skipped rather than guessed at: a manufacturer-specific cluster on an
259 /// endpoint is perfectly legal and has no table anywhere.
260 fn check_features(
261 endpoint: &Endpoint<'_>,
262 required: &RequiredCluster,
263 spec_of: &impl Fn(ClusterId) -> Option<&'static crate::dm::spec::Cluster>,
264 found: &mut impl FnMut(Defect),
265 ) {
266 if required.features.is_empty() {
267 return;
268 }
269 let Some(served) = endpoint
270 .clusters
271 .iter()
272 .find(|cluster| cluster.id == required.id)
273 else {
274 return;
275 };
276 let Some(defined) = spec_of(required.id) else {
277 return;
278 };
279 for (code, conform) in required.features {
280 if conform.verdict(&Furnished { endpoint }) != Conformance::Mandatory {
281 continue;
282 }
283 let Some(feature) = defined.feature(code) else {
284 continue;
285 };
286 if feature.bit < 32 && served.feature_map & (1u32 << feature.bit) == 0 {
287 found(Defect::MissingFeature {
288 cluster: required.id,
289 code,
290 });
291 }
292 }
293 }
294
295 /// Whether an endpoint is furnished for this device type.
296 #[must_use]
297 pub fn is_satisfied_by(
298 &self,
299 endpoint: &Endpoint<'_>,
300 spec_of: impl Fn(ClusterId) -> Option<&'static crate::dm::spec::Cluster>,
301 ) -> bool {
302 let mut ok = true;
303 self.validate(endpoint, spec_of, |_| ok = false);
304 ok
305 }
306}