Skip to main content

matter_kit/dm/
meta.rs

1//! What a cluster *is*: the descriptors a node is built from (Core §7.10–7.13).
2//!
3//! These are static data, meant to be `const` and to live in flash. A cluster's shape does
4//! not change at runtime — its *values* do — so nothing here is owned or mutable, and an
5//! endpoint is a slice of descriptors the application points at rather than a structure it
6//! builds.
7//!
8//! # The global attributes are not in the list
9//!
10//! §7.13 gives every cluster instance five attributes it must support:
11//! `ClusterRevision`, `FeatureMap`, `AttributeList`, `AcceptedCommandList` and
12//! `GeneratedCommandList`. They are **synthesised** from the descriptor rather than written
13//! into it — [`global`](crate::dm::global) — because three of the five are lists *of* the
14//! descriptor's contents, and a hand-maintained copy is a copy that drifts.
15//!
16//! That is not a stylistic preference. `AttributeList` is read by every commissioner during
17//! discovery, and a cluster whose declared list disagrees with what it actually serves fails
18//! certification in a way that is tedious to find.
19
20use crate::dm::access::Access;
21use crate::im::{AttributeId, ClusterId, CommandId, EventId};
22
23/// How often an attribute's value may be reported (§7.7.8, §7.12).
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
25#[non_exhaustive]
26pub enum Reporting {
27    /// Reported on every change — the ordinary case.
28    #[default]
29    OnChange,
30    /// `Q` — Quieter Reporting: "Changes to the value under conditions other than those
31    /// specified in the attribute description SHOULD NOT be reported." The conditions are
32    /// prose per attribute, so the policy lives with the cluster, not here.
33    Quieter,
34    /// `C` — changes are omitted entirely; a client must poll.
35    ChangesOmitted,
36}
37
38bitflags::bitflags! {
39    /// The qualities §7.12 gives an attribute, beyond its access.
40    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
41    pub struct AttributeQualities: u8 {
42        /// `X` — nullable: the attribute may hold TLV null.
43        const NULLABLE = 1 << 0;
44        /// `N` — non-volatile: the value survives a reboot (§7.12.1).
45        const NON_VOLATILE = 1 << 1;
46        /// `F` — fixed: the value never changes after the node is built, so it need not be
47        /// watched for reporting.
48        const FIXED = 1 << 2;
49        /// `P` — the attribute supports atomic writes (§7.15).
50        const ATOMIC = 1 << 3;
51        /// `L` — large message: the value requires TCP (§7.7.5).
52        const LARGE = 1 << 4;
53        /// `S` — the attribute takes part in scenes: Scenes Management captures and recalls
54        /// it (§1.4.5's extension field sets). A cluster that forgets which of its attributes
55        /// are `S` produces scenes that restore some of a light's state and not the rest.
56        const SCENE = 1 << 5;
57    }
58}
59
60/// One attribute of a cluster (§7.12).
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62pub struct AttributeDescriptor {
63    /// The attribute id.
64    pub id: AttributeId,
65    /// Its access qualities.
66    pub access: Access,
67    /// Its reporting policy.
68    pub reporting: Reporting,
69    /// Its other qualities.
70    pub qualities: AttributeQualities,
71}
72
73impl AttributeDescriptor {
74    /// A readable attribute at View privilege — §7.6's default.
75    #[must_use]
76    pub const fn read_only(id: AttributeId) -> Self {
77        Self {
78            id,
79            access: Access::read_only(crate::dm::access::Privilege::View),
80            reporting: Reporting::OnChange,
81            qualities: AttributeQualities::empty(),
82        }
83    }
84
85    /// A readable and writable attribute — `RW VO`.
86    #[must_use]
87    pub const fn read_write(id: AttributeId) -> Self {
88        Self {
89            id,
90            access: Access::read_write(),
91            reporting: Reporting::OnChange,
92            qualities: AttributeQualities::empty(),
93        }
94    }
95
96    /// The same attribute with a different access.
97    #[must_use]
98    pub const fn with_access(mut self, access: Access) -> Self {
99        self.access = access;
100        self
101    }
102
103    /// The same attribute with extra qualities.
104    #[must_use]
105    pub const fn with_qualities(mut self, qualities: AttributeQualities) -> Self {
106        self.qualities = qualities;
107        self
108    }
109
110    /// The same attribute with a reporting policy.
111    #[must_use]
112    pub const fn with_reporting(mut self, reporting: Reporting) -> Self {
113        self.reporting = reporting;
114        self
115    }
116}
117
118/// One command of a cluster (§7.11).
119#[derive(Debug, Clone, Copy, PartialEq, Eq)]
120pub struct CommandDescriptor {
121    /// The command id.
122    pub id: CommandId,
123    /// Its access — which for a command means its invoke privilege.
124    pub access: Access,
125    /// The id of the command this one is answered with, if it has a response.
126    ///
127    /// §7.13.4: "For each client request command in this list that mandates a response from
128    /// the server, the response command SHALL be indicated in the GeneratedCommandList" — so
129    /// this is what lets that list be synthesised rather than written twice.
130    pub response: Option<CommandId>,
131}
132
133impl CommandDescriptor {
134    /// A request command invocable at Operate — §7.6's default for a request command.
135    #[must_use]
136    pub const fn new(id: CommandId) -> Self {
137        Self {
138            id,
139            access: Access::invoke(crate::dm::access::Privilege::Operate),
140            response: None,
141        }
142    }
143
144    /// The same command, answered by `response`.
145    #[must_use]
146    pub const fn with_response(mut self, response: CommandId) -> Self {
147        self.response = Some(response);
148        self
149    }
150
151    /// The same command with a different access.
152    #[must_use]
153    pub const fn with_access(mut self, access: Access) -> Self {
154        self.access = access;
155        self
156    }
157}
158
159/// An event's priority (§7.14).
160#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
161#[non_exhaustive]
162pub enum EventPriority {
163    /// Lowest: development and diagnostics.
164    Debug,
165    /// The ordinary case.
166    #[default]
167    Info,
168    /// Highest: an event whose loss matters.
169    Critical,
170}
171
172/// One event of a cluster (§7.14).
173#[derive(Debug, Clone, Copy, PartialEq, Eq)]
174pub struct EventDescriptor {
175    /// The event id.
176    pub id: EventId,
177    /// Its access — read only, at some privilege.
178    pub access: Access,
179    /// Its priority.
180    pub priority: EventPriority,
181}
182
183impl EventDescriptor {
184    /// An event readable at View — §7.6's default.
185    #[must_use]
186    pub const fn new(id: EventId) -> Self {
187        Self {
188            id,
189            access: Access::read_only(crate::dm::access::Privilege::View),
190            priority: EventPriority::Info,
191        }
192    }
193
194    /// The same event at a different priority.
195    #[must_use]
196    pub const fn with_priority(mut self, priority: EventPriority) -> Self {
197        self.priority = priority;
198        self
199    }
200}
201
202/// What a cluster instance looks like (§7.10).
203///
204/// Static: this is the cluster's *shape*, which does not change at runtime. The attribute,
205/// command and event slices are expected to be `const` arrays in flash, and to be **sorted
206/// by id** — [`ClusterDescriptor::attribute`] and its siblings binary-search them, and
207/// §7.13's synthesised lists are emitted in that order.
208#[derive(Debug, Clone, Copy, PartialEq, Eq)]
209pub struct ClusterDescriptor<'a> {
210    /// The cluster id.
211    pub id: ClusterId,
212    /// `ClusterRevision` (§7.13.1) — "the (highest) revision number of the cluster
213    /// specification that has been implemented", and never zero for a cluster defined after
214    /// the attribute existed.
215    pub revision: u16,
216    /// `FeatureMap` (§7.13.2). Zero "for a cluster whose definition does not define a
217    /// FeatureMap".
218    pub feature_map: u32,
219    /// The attributes this instance serves, **excluding** the global ones of §7.13, sorted
220    /// by id.
221    pub attributes: &'a [AttributeDescriptor],
222    /// The client-to-server commands it accepts, sorted by id.
223    pub accepted_commands: &'a [CommandDescriptor],
224    /// The server-to-client commands it generates that are *not* responses to an accepted
225    /// command — most clusters have none, because responses are derived from
226    /// [`CommandDescriptor::response`].
227    pub generated_commands: &'a [CommandId],
228    /// The events it may emit, sorted by id.
229    pub events: &'a [EventDescriptor],
230}
231
232impl<'a> ClusterDescriptor<'a> {
233    /// The descriptor for an attribute id, including the global ones of §7.13.
234    #[must_use]
235    pub fn attribute(&self, id: AttributeId) -> Option<AttributeDescriptor> {
236        if let Some(global) = crate::dm::global::descriptor(id) {
237            return Some(global);
238        }
239        self.attributes
240            .binary_search_by_key(&id, |a| a.id)
241            .ok()
242            .and_then(|index| self.attributes.get(index).copied())
243    }
244
245    /// The descriptor for an accepted command id.
246    #[must_use]
247    pub fn accepted_command(&self, id: CommandId) -> Option<CommandDescriptor> {
248        self.accepted_commands
249            .binary_search_by_key(&id, |c| c.id)
250            .ok()
251            .and_then(|index| self.accepted_commands.get(index).copied())
252    }
253
254    /// The descriptor for an event id.
255    #[must_use]
256    pub fn event(&self, id: EventId) -> Option<EventDescriptor> {
257        self.events
258            .binary_search_by_key(&id, |e| e.id)
259            .ok()
260            .and_then(|index| self.events.get(index).copied())
261    }
262
263    /// Every attribute id this instance serves, in ascending order: the cluster's own,
264    /// then §7.13's globals.
265    ///
266    /// This is `AttributeList`'s content. The globals sort last because their ids are
267    /// `0xFFF8`–`0xFFFD`, above any cluster-specific id.
268    pub fn attribute_ids(&self) -> impl Iterator<Item = AttributeId> + 'a {
269        let own = self.attributes.iter().map(|a| a.id);
270        own.chain(crate::dm::global::ATTRIBUTE_IDS.iter().copied())
271    }
272
273    /// Every command id the server may generate: each accepted command's response, plus any
274    /// declared outright.
275    ///
276    /// §7.13.5: "For each command in this list that is a response to a client request
277    /// command, the request command SHALL be indicated in the AcceptedCommandList" — which
278    /// is exactly the relation this derives from, so the two lists cannot disagree.
279    pub fn generated_command_ids(&self) -> impl Iterator<Item = CommandId> + 'a {
280        let responses = self.accepted_commands.iter().filter_map(|c| c.response);
281        responses.chain(self.generated_commands.iter().copied())
282    }
283
284    /// Whether the descriptor is well formed: every slice sorted and free of duplicates, and
285    /// no attribute claiming an id §7.13 reserves for a global.
286    ///
287    /// A `const` node cannot be validated at compile time today, so this is what
288    /// [`Node::validate`](crate::dm::Node::validate) calls — once, at start-up, rather than
289    /// per request. An unsorted slice would make the binary searches silently miss.
290    #[must_use]
291    pub fn is_well_formed(&self) -> bool {
292        fn ascending<T: Copy, K: Ord>(items: &[T], key: impl Fn(&T) -> K) -> bool {
293            items.windows(2).all(|w| match w {
294                [a, b] => key(a) < key(b),
295                _ => true,
296            })
297        }
298        ascending(self.attributes, |a| a.id)
299            && ascending(self.accepted_commands, |c| c.id)
300            && ascending(self.events, |e| e.id)
301            && !self
302                .attributes
303                .iter()
304                .any(|a| crate::dm::global::is_global(a.id))
305    }
306}
307
308/// A device type an endpoint conforms to (§9.5.5.1).
309///
310/// Part of the node's *shape*, not of any one cluster: §9.5 requires every endpoint to
311/// declare at least one, the Descriptor cluster merely publishes it, and §6.6.6.2's access
312/// control matches ACL targets against it. Holding it on the endpoint is what keeps those
313/// three readings of the same fact from disagreeing.
314#[derive(Debug, Clone, Copy, PartialEq, Eq)]
315pub struct DeviceType {
316    /// `DeviceType [0]` — a `devtype-id`, the identifier from the Device Library.
317    pub device_type: u32,
318    /// `Revision [1]` — "the implemented revision of the device type definition", min 1.
319    pub revision: u16,
320}
321
322impl DeviceType {
323    /// A device type at a revision.
324    #[must_use]
325    pub const fn new(device_type: u32, revision: u16) -> Self {
326        Self {
327            device_type,
328            revision,
329        }
330    }
331}