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}