Skip to main content

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}