matter-kit 0.3.0

Matter (CSA smart-home standard) protocol implementation in Rust: no_std, no-alloc, executor-agnostic
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
//! Fixed Label `0x0040` and User Label `0x0041` (Core §9.7–9.9).
//!
//! Both are instances of §9.7's Label cluster, which "provides a feature to tag an endpoint
//! with zero or more labels" and is a *base* cluster — it has no cluster id of its own and
//! exists only through the two derived ones. They differ in exactly one thing, and it is the
//! access quality:
//!
//! | | id | `LabelList` access |
//! |---|---|---|
//! | [`FixedLabel`] | `0x0040` | `RV` — read-only, the manufacturer's |
//! | [`UserLabel`]  | `0x0041` | `RW VM` — writable at Manage, the owner's |
//!
//! That is the whole distinction and it is worth stating plainly: a fixed label is what the
//! factory burned in ("serial", "model"), and a user label is what somebody with a phone
//! typed ("room": "kitchen"). Making the fixed one writable would let a commissioner rewrite
//! a device's identity; making the user one read-only would leave every ecosystem unable to
//! name the thing it just commissioned.
//!
//! # Why they share a file
//!
//! §9.7.4.1's `LabelStruct` is the same in both, and so is the encoding. Two files would
//! mean two copies of the same TLV, which is two places for the max-16 constraint to be got
//! wrong.

use core::cell::RefCell;

use crate::dm::{
    Access, AttributeDescriptor, AttributeQualities, ClusterDescriptor, CommandDescriptor,
    Privilege, Resolved,
};
use crate::im::{AttributeId, ClusterHandler, ClusterId, InteractionContext, Status, WriteOp};
use crate::tlv::{ContainerKind, Tag, TlvReader, TlvWriter, Value};

use super::Cluster;

/// `0x0040` (§9.8.3).
pub const FIXED_LABEL_ID: ClusterId = 0x0040;
/// `0x0041` (§9.9.3).
pub const USER_LABEL_ID: ClusterId = 0x0041;

/// The revision both derived clusters are at (§9.8.1, §9.9.1).
pub const REVISION: u16 = 1;

/// `LabelList` (§9.7.5.1) — the only attribute either cluster has.
pub const LABEL_LIST: AttributeId = 0x0000;

/// The longest a `Label` or a `Value` may be (§9.7.4.1: "max 16").
pub const LABEL_MAX: usize = 16;

/// One `LabelStruct` (§9.7.4.1): "a string tuple with strings that are user defined".
///
/// The specification declines to give either half a meaning — "The Label or Value semantic is
/// not defined here" — and offers `"room":"bedroom 2"` and `"orientation":"North"` as
/// examples. So this is deliberately two strings and no interpretation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Label<'a> {
    /// `Label [0]` — the key. "room", "zone", "direction".
    pub label: &'a str,
    /// `Value [1]` — "a discriminator for a Label that may have multiple instances".
    pub value: &'a str,
}

impl<'a> Label<'a> {
    /// A label, or `None` if either half exceeds §9.7.4.1's 16 characters.
    ///
    /// Checked here rather than at write time so a `const` device model cannot declare a
    /// label it would be unable to report.
    #[must_use]
    pub const fn new(label: &'a str, value: &'a str) -> Option<Self> {
        if label.len() > LABEL_MAX || value.len() > LABEL_MAX {
            return None;
        }
        Some(Self { label, value })
    }

    fn encode(&self, w: &mut TlvWriter<'_>) -> crate::error::Result<()> {
        w.start_structure(Tag::Anonymous)?;
        w.utf8(Tag::Context(0), self.label)?;
        w.utf8(Tag::Context(1), self.value)?;
        w.end_container()
    }
}

/// An owned label, for the list a [`UserLabel`] holds.
///
/// Owned rather than borrowed because a user label arrives over the wire and has to outlive
/// the message it came in — which a `&str` into the receive buffer would not.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct OwnedLabel {
    label: heapless::String<LABEL_MAX>,
    value: heapless::String<LABEL_MAX>,
}

impl OwnedLabel {
    /// The key half.
    #[must_use]
    pub fn label(&self) -> &str {
        &self.label
    }

    /// The value half.
    #[must_use]
    pub fn value(&self) -> &str {
        &self.value
    }

    /// Borrows it as a [`Label`].
    #[must_use]
    pub fn as_label(&self) -> Label<'_> {
        Label {
            label: &self.label,
            value: &self.value,
        }
    }

    /// Builds one, refusing anything past §9.7.4.1's 16 characters.
    pub fn new(label: &str, value: &str) -> Result<Self, Status> {
        let mut out = Self::default();
        out.label
            .push_str(label)
            .map_err(|_| Status::ConstraintError)?;
        out.value
            .push_str(value)
            .map_err(|_| Status::ConstraintError)?;
        Ok(out)
    }
}

/// Writes a `LabelList` as the array §9.7.5.1 describes.
fn write_list<'a>(
    labels: impl Iterator<Item = Label<'a>>,
    w: &mut TlvWriter<'_>,
    tag: Tag,
) -> Result<(), Status> {
    let full = |r: crate::error::Result<()>| r.map_err(|_| Status::ResourceExhausted);
    full(w.start_array(tag))?;
    for label in labels {
        full(label.encode(w))?;
    }
    full(w.end_container())
}

/// Reads one `LabelStruct` whose opening structure the caller has taken.
fn decode_label(reader: &mut TlvReader<'_>) -> Result<OwnedLabel, Status> {
    let mut label = None;
    let mut value = None;
    loop {
        let Some(element) = reader.next_element().map_err(|_| Status::InvalidAction)? else {
            return Err(Status::InvalidAction);
        };
        if element.value == Value::EndOfContainer {
            break;
        }
        match element.tag.context() {
            Some(0) => label = Some(element.utf8().map_err(|_| Status::InvalidAction)?),
            Some(1) => value = Some(element.utf8().map_err(|_| Status::InvalidAction)?),
            _ => reader
                .skip_value(&element)
                .map_err(|_| Status::InvalidAction)?,
        }
    }
    // §9.7.4.1 gives both fields a fallback of "empty", so an absent one is the empty string
    // rather than a malformed struct.
    OwnedLabel::new(label.unwrap_or_default(), value.unwrap_or_default())
}

// --- Fixed Label -------------------------------------------------------------------------------

/// §9.8.5's one attribute: `RV`, and `N` because a fixed label survives a reboot by definition.
const FIXED_ATTRIBUTES: &[AttributeDescriptor] =
    &[AttributeDescriptor::read_only(LABEL_LIST).with_qualities(AttributeQualities::NON_VOLATILE)];

const NO_COMMANDS: &[CommandDescriptor] = &[];

/// The descriptor for Fixed Label.
#[must_use]
pub const fn fixed_cluster() -> ClusterDescriptor<'static> {
    ClusterDescriptor {
        id: FIXED_LABEL_ID,
        revision: REVISION,
        feature_map: 0,
        attributes: FIXED_ATTRIBUTES,
        accepted_commands: NO_COMMANDS,
        generated_commands: &[],
        events: &[],
    }
}

/// Fixed Label `0x0040` (§9.8): the labels the manufacturer burned in.
///
/// Read-only over the wire — §9.8.5 gives `LabelList` access `RV` — so the list is `&'static`
/// data alongside the rest of the device's `const` model, and there is no path by which a
/// commissioner could rewrite it.
#[derive(Debug, Clone, Copy)]
pub struct FixedLabel<'a> {
    labels: &'a [Label<'a>],
}

impl<'a> FixedLabel<'a> {
    /// A cluster over the manufacturer's labels.
    #[must_use]
    pub const fn new(labels: &'a [Label<'a>]) -> Self {
        Self { labels }
    }

    /// The labels it reports.
    #[must_use]
    pub const fn labels(&self) -> &'a [Label<'a>] {
        self.labels
    }
}

impl ClusterHandler for FixedLabel<'_> {
    fn read(
        &self,
        resolved: &Resolved<'_>,
        _ctx: &InteractionContext<'_>,
        w: &mut TlvWriter<'_>,
        tag: Tag,
    ) -> Result<(), Status> {
        if resolved.attribute != LABEL_LIST {
            return Err(Status::UnsupportedAttribute);
        }
        write_list(self.labels.iter().copied(), w, tag)
    }
}

impl Cluster for FixedLabel<'_> {
    const ID: ClusterId = FIXED_LABEL_ID;
}

// --- User Label --------------------------------------------------------------------------------

/// §9.9.5's one attribute: `RW VM`, writable at Manage, and `N`.
///
/// Manage rather than Operate is the point: renaming a device is configuration, not use, so
/// §9.9.5 puts it above the privilege an ordinary occupant holds.
const USER_ATTRIBUTES: &[AttributeDescriptor] = &[AttributeDescriptor::read_write(LABEL_LIST)
    .with_access(Access::read_write_with(Privilege::View, Privilege::Manage))
    .with_qualities(AttributeQualities::NON_VOLATILE)];

/// The descriptor for User Label.
#[must_use]
pub const fn user_cluster() -> ClusterDescriptor<'static> {
    ClusterDescriptor {
        id: USER_LABEL_ID,
        revision: REVISION,
        feature_map: 0,
        attributes: USER_ATTRIBUTES,
        accepted_commands: NO_COMMANDS,
        generated_commands: &[],
        events: &[],
    }
}

/// User Label `0x0041` (§9.9): the labels the owner set.
///
/// `N` is a claim this type cannot make good on its own — §9.9.5 says the list survives a
/// reboot, and nothing here writes to storage. [`UserLabel::labels`] is what a device
/// persists, and [`UserLabel::restore`] is how it comes back.
#[derive(Debug)]
pub struct UserLabel<const N: usize> {
    labels: RefCell<heapless::Vec<OwnedLabel, N>>,
}

impl<const N: usize> Default for UserLabel<N> {
    fn default() -> Self {
        Self::new()
    }
}

impl<const N: usize> UserLabel<N> {
    /// A cluster with no labels — a factory-fresh device's empty list (§9.9.5's fallback).
    #[must_use]
    pub const fn new() -> Self {
        Self {
            labels: RefCell::new(heapless::Vec::new()),
        }
    }

    /// The labels, for a device about to persist them.
    #[must_use]
    pub fn labels(&self) -> core::cell::Ref<'_, heapless::Vec<OwnedLabel, N>> {
        self.labels.borrow()
    }

    /// Restores the list a device persisted.
    pub fn restore(&self, labels: impl IntoIterator<Item = OwnedLabel>) -> Result<(), Status> {
        let mut held = self.labels.borrow_mut();
        held.clear();
        for label in labels {
            held.push(label).map_err(|_| Status::ResourceExhausted)?;
        }
        Ok(())
    }
}

impl<const N: usize> ClusterHandler for UserLabel<N> {
    fn read(
        &self,
        resolved: &Resolved<'_>,
        _ctx: &InteractionContext<'_>,
        w: &mut TlvWriter<'_>,
        tag: Tag,
    ) -> Result<(), Status> {
        if resolved.attribute != LABEL_LIST {
            return Err(Status::UnsupportedAttribute);
        }
        let labels = self.labels.borrow();
        write_list(labels.iter().map(OwnedLabel::as_label), w, tag)
    }

    fn write(
        &self,
        resolved: &Resolved<'_>,
        data: &[u8],
        op: WriteOp,
        _ctx: &InteractionContext<'_>,
    ) -> Result<(), Status> {
        if resolved.attribute != LABEL_LIST {
            return Err(Status::UnsupportedWrite);
        }
        let mut reader = TlvReader::new_in(data, ContainerKind::Structure);
        let element = reader
            .next_element()
            .map_err(|_| Status::InvalidAction)?
            .ok_or(Status::InvalidAction)?;

        match op {
            // §10.6.4.3.1's REPLACE: the array is the new contents of the list.
            WriteOp::Replace => {
                if element.value.container() != Some(ContainerKind::Array) {
                    return Err(Status::InvalidAction);
                }
                let mut replacement: heapless::Vec<OwnedLabel, N> = heapless::Vec::new();
                loop {
                    let Some(item) = reader.next_element().map_err(|_| Status::InvalidAction)?
                    else {
                        return Err(Status::InvalidAction);
                    };
                    if item.value == Value::EndOfContainer {
                        break;
                    }
                    if item.value.container() != Some(ContainerKind::Structure) {
                        return Err(Status::InvalidAction);
                    }
                    replacement
                        .push(decode_label(&mut reader)?)
                        .map_err(|_| Status::ResourceExhausted)?;
                }
                *self.labels.borrow_mut() = replacement;
            }
            // §10.6.4.3.1's ADD: one more label.
            WriteOp::Append => {
                if element.value.container() != Some(ContainerKind::Structure) {
                    return Err(Status::InvalidAction);
                }
                let label = decode_label(&mut reader)?;
                self.labels
                    .borrow_mut()
                    .push(label)
                    .map_err(|_| Status::ResourceExhausted)?;
            }
        }
        Ok(())
    }
}

impl<const N: usize> Cluster for UserLabel<N> {
    const ID: ClusterId = USER_LABEL_ID;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_label_longer_than_sixteen_is_refused_when_the_model_is_built() {
        assert!(Label::new("room", "kitchen").is_some());
        assert!(Label::new("room", "seventeen chars!!").is_none());
        assert!(Label::new("a-seventeen-char!", "x").is_none());
        // Exactly sixteen is the limit, not one short of it.
        assert!(Label::new("sixteen-chars-ok", "sixteen-chars-ok").is_some());
    }

    #[test]
    fn the_two_clusters_differ_only_in_whether_the_list_can_be_written() {
        // The whole point of there being two derived clusters. A writable fixed label would
        // let a commissioner rewrite a device's identity; a read-only user label would leave
        // every ecosystem unable to name what it just commissioned.
        let fixed = fixed_cluster();
        let user = user_cluster();
        assert_eq!(fixed.id, 0x0040);
        assert_eq!(user.id, 0x0041);

        let fixed_list = fixed.attribute(LABEL_LIST).expect("LabelList");
        assert_eq!(fixed_list.access.read, Some(Privilege::View));
        assert_eq!(fixed_list.access.write, None, "§9.8.5 gives it `RV`");

        let user_list = user.attribute(LABEL_LIST).expect("LabelList");
        assert_eq!(user_list.access.read, Some(Privilege::View));
        assert_eq!(
            user_list.access.write,
            Some(Privilege::Manage),
            "§9.9.5 gives it `RW VM` — renaming is configuration, not use"
        );
        // Both survive a reboot.
        assert!(
            fixed_list
                .qualities
                .contains(AttributeQualities::NON_VOLATILE)
        );
        assert!(
            user_list
                .qualities
                .contains(AttributeQualities::NON_VOLATILE)
        );
    }

    #[test]
    fn a_user_label_list_is_bounded_by_its_capacity() {
        let cluster = UserLabel::<2>::new();
        cluster
            .restore([
                OwnedLabel::new("room", "kitchen").expect("fits"),
                OwnedLabel::new("floor", "1").expect("fits"),
            ])
            .expect("two fit");
        assert_eq!(
            cluster
                .restore([
                    OwnedLabel::new("a", "1").expect("fits"),
                    OwnedLabel::new("b", "2").expect("fits"),
                    OwnedLabel::new("c", "3").expect("fits"),
                ])
                .unwrap_err(),
            Status::ResourceExhausted,
            "§9.6.1's rule for a full list, and the only honest answer without an allocator"
        );
    }

    #[test]
    fn an_over_long_label_is_a_constraint_error_not_a_truncation() {
        // Truncating would store something the client never asked for and report success.
        assert_eq!(
            OwnedLabel::new("this-label-is-far-too-long", "x").unwrap_err(),
            Status::ConstraintError
        );
    }
}