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
//! A controller watching an energy device (Core §8.5, §10.7.5).
//!
//! M5's exit criterion in executable form: a client subscribes to a Device Energy Management
//! device, receives reports as its state changes, and notices when it stops hearing from it.
//! Both halves are this crate's — `im::subscription` and `im::server` publish,
//! `im::client` subscribes — and they were written from §8.5 separately.
//!
//! The rule worth the most here is §8.5.3.2's: the *publisher* chooses the `MaxInterval`, and
//! the subscriber has to use the one it was told rather than the ceiling it asked for. A
//! subscriber that assumed otherwise would declare a live subscription dead, tear it down and
//! build another, for ever — on a battery device, until the battery ran out.

#![cfg(all(feature = "std", feature = "rustcrypto"))]
#![allow(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::indexing_slicing,
    clippy::panic,
    clippy::arithmetic_side_effects
)]

use core::cell::Cell;

use matter_kit::DefaultConfig;
use matter_kit::clusters::device_energy_management::{
    self as dem, DemHooks, DeviceEnergyManagement, ESAStateEnum, ESATypeEnum, OptOutStateEnum,
};
use matter_kit::dm::spec::Optional;
use matter_kit::dm::{ClusterDescriptor, Endpoint, Node, Privilege};
use matter_kit::im::client::{LIVENESS_MARGIN, ReportAssembler, Subscription};
use matter_kit::im::ib::AttributeReport;
use matter_kit::im::message::SubscribeRequest;
use matter_kit::im::subscription::{NewSubscription, ReportReason, SubscriptionTable};
use matter_kit::im::{
    AccessControl, AttributePath, InteractionContext, Outcome, ReportData, Server,
    SubscribeResponse, encode_subscribe_request,
};
use matter_kit::msg::{FabricIndex, SessionId};
use matter_kit::platform::{Duration, Instant};
use matter_kit::tlv::Value;

struct AllowAll;

impl AccessControl for AllowAll {
    fn allows(&self, _path: &AttributePath, _required: Privilege) -> Outcome {
        Outcome::Granted
    }
}

/// A battery inverter that an energy manager watches.
#[derive(Debug)]
struct Battery {
    state: Cell<ESAStateEnum>,
    opt_out: Cell<OptOutStateEnum>,
}

impl Default for Battery {
    fn default() -> Self {
        Self {
            state: Cell::new(ESAStateEnum::Online),
            opt_out: Cell::new(OptOutStateEnum::NoOptOut),
        }
    }
}

impl DemHooks for Battery {
    fn esa_type(&self) -> ESATypeEnum {
        ESATypeEnum::BatteryStorage
    }

    fn can_generate(&self) -> bool {
        true
    }

    fn base_state(&self) -> ESAStateEnum {
        self.state.get()
    }

    fn abs_min_power(&self) -> i64 {
        -5_000_000
    }

    fn abs_max_power(&self) -> i64 {
        5_000_000
    }

    fn opt_out_state(&self) -> OptOutStateEnum {
        self.opt_out.get()
    }
}

fn at(seconds: u64) -> Instant {
    Instant::ZERO.saturating_add(Duration::from_secs(seconds))
}

/// The subscription table a controller-facing device keeps.
type Table = SubscriptionTable<DefaultConfig, 15, 3>;

const FABRIC: FabricIndex = FabricIndex(1);

struct Device<'a> {
    node: Node<'a>,
    cluster: DeviceEnergyManagement<'a, Battery>,
}

fn device(battery: &Battery) -> Device<'_> {
    let conforming = Box::leak(Box::new(
        DeviceEnergyManagement::<Battery>::conforming(
            dem::feature::POWER_FORECAST_REPORTING,
            &Optional::NONE,
        )
        .expect("sized"),
    ));
    let clusters: &'static [ClusterDescriptor<'static>] =
        Box::leak(Box::new([conforming.descriptor()]));
    let endpoints: &'static [Endpoint<'static>] = Box::leak(Box::new([Endpoint::new(1, clusters)]));
    Device {
        node: Node::new(endpoints),
        cluster: DeviceEnergyManagement::new(battery, dem::feature::POWER_FORECAST_REPORTING),
    }
}

fn ctx(now: Instant) -> InteractionContext<'static> {
    InteractionContext {
        fabric_index: Some(FABRIC),
        session: Some(SessionId(1)),
        now,
        ..InteractionContext::default()
    }
}

/// Publishes one report, as the device's loop would when a subscription comes due.
fn publish<'b>(
    device: &Device<'_>,
    subscriptions: &mut Table,
    id: u32,
    reason: ReportReason,
    now: Instant,
    buf: &'b mut [u8],
) -> &'b [u8] {
    let subscription = subscriptions.find_mut(id).expect("a subscription");
    let access = AllowAll;
    let server = Server::new(device.node, &access, &device.cluster, 8);
    let mut scratch = [0u8; 2048];
    let (bytes, _) = server
        .report(subscription, reason, &ctx(now), &mut scratch, buf)
        .expect("a report");
    bytes
}

// --- Subscribing -----------------------------------------------------------------------------

#[test]
fn a_controller_subscribes_to_an_energy_device_and_is_told_the_real_interval() {
    // §8.5.3.2: the publisher computes the `MaxInterval` and "SHALL report it in the
    // SubscribeResponse". A subscriber that used its own ceiling instead would time out early
    // on any publisher that chose a longer one — and §8.5.3.2 explicitly lets it.
    let battery = Battery::default();
    let device = device(&battery);

    // The controller's request, on the wire.
    let mut buf = [0u8; 512];
    let encoded = encode_subscribe_request(
        &mut buf,
        [
            AttributePath::attribute(1, dem::ID, dem::ESA_STATE),
            AttributePath::attribute(1, dem::ID, dem::OPT_OUT_STATE),
        ],
        [],
        5,
        60,
        true,
        true,
    )
    .expect("encodes")
    .to_vec();

    // The device decodes it and opens a subscription.
    let request = SubscribeRequest::decode(&encoded).expect("decodes");
    assert_eq!(request.min_interval_floor_s, 5);
    assert_eq!(request.max_interval_ceiling_s, 60);
    assert!(request.keep_subscriptions);
    assert!(request.fabric_filtered);
    let paths: Vec<AttributePath> = request
        .attribute_paths()
        .expect("paths")
        .expect("some")
        .map(|p| p.expect("decodes"))
        .collect();
    assert_eq!(paths.len(), 2);

    let mut subscriptions = Table::new();
    let id = subscriptions
        .subscribe(
            &NewSubscription {
                session: Some(SessionId(1)),
                fabric_index: Some(FABRIC),
                peer_node_id: None,
                fabric_filtered: request.fabric_filtered,
                keep_subscriptions: request.keep_subscriptions,
                min_interval_s: request.min_interval_floor_s,
                max_interval_s: request.max_interval_ceiling_s,
                paths: &paths,
                event_paths: &[],
                min_event_number: 0,
            },
            at(0),
        )
        .expect("a subscription");

    let subscription = subscriptions.find(id).expect("it exists");
    let response = SubscribeResponse {
        subscription_id: id,
        max_interval_s: subscription.max_interval_s,
        revision: None,
    };

    // The controller records what it was *told*, not what it asked for.
    let mut held = Subscription::new(&response, at(0));
    assert_eq!(held.id(), id);
    assert_eq!(held.max_interval_s(), response.max_interval_s);

    // §8.5.1's second action: the *priming* report, which carries the whole of what was asked
    // for and goes out before the `SubscribeResponse` above. A subscriber whose first report
    // arrived only when something changed would not know the current state at all — and for an
    // attribute that rarely changes it might never find out.
    let access = AllowAll;
    let server = Server::new(device.node, &access, &device.cluster, 8);
    let mut scratch = [0u8; 2048];
    let mut buf = [0u8; 2048];
    let (bytes, _) = server
        .prime(
            id,
            paths.iter().copied().map(Ok),
            &ctx(at(0)),
            &mut scratch,
            &mut buf,
        )
        .expect("a priming report");
    let report = ReportData::decode(bytes).expect("decodes");
    assert_eq!(
        report.subscription_id,
        Some(id),
        "§8.5.3.2 requires the priming report to carry the subscription's own id"
    );
    assert!(held.heard(&report, at(0)), "the report was not ours");

    let mut assembler: ReportAssembler<2048> = ReportAssembler::new();
    assert!(assembler.push(&report).expect("push"), "one chunk is whole");
    let reports: Vec<_> = assembler.reports().map(|r| r.expect("decodes")).collect();
    assert_eq!(reports.len(), 2, "both attributes were reported");
}

#[test]
fn a_change_the_controller_asked_about_produces_a_report() {
    // The point of a subscription: the energy manager learns the battery went into a fault
    // without asking, which is what lets it stop planning around a machine that has stopped.
    let battery = Battery::default();
    let device = device(&battery);
    let paths = [AttributePath::attribute(1, dem::ID, dem::ESA_STATE)];
    let mut subscriptions = Table::new();
    let id = subscriptions
        .subscribe(
            &NewSubscription {
                session: Some(SessionId(1)),
                fabric_index: Some(FABRIC),
                peer_node_id: None,
                fabric_filtered: true,
                keep_subscriptions: true,
                min_interval_s: 1,
                max_interval_s: 60,
                paths: &paths,
                event_paths: &[],
                min_event_number: 0,
            },
            at(0),
        )
        .expect("a subscription");

    // Nothing has changed, and the minimum interval has not elapsed.
    assert!(subscriptions.due(at(0)).next().is_none());

    battery.state.set(ESAStateEnum::Fault);
    assert_eq!(
        subscriptions.note_change(&AttributePath::attribute(1, dem::ID, dem::ESA_STATE)),
        1,
        "the change did not reach the subscription"
    );
    let (_, reason) = subscriptions.due(at(2)).next().expect("a report is due");
    assert_eq!(reason, ReportReason::Data);

    let mut buf = [0u8; 2048];
    let bytes = publish(&device, &mut subscriptions, id, reason, at(2), &mut buf);
    let report = ReportData::decode(bytes).expect("decodes");
    let mut assembler: ReportAssembler<2048> = ReportAssembler::new();
    assembler.push(&report).expect("push");

    let value = assembler
        .reports()
        .next()
        .expect("one report")
        .expect("decodes");
    let AttributeReport::Data(value) = value else {
        panic!("expected a value, not a status");
    };
    let mut reader =
        matter_kit::tlv::TlvReader::new_in(value.data, matter_kit::tlv::ContainerKind::Structure);
    let element = reader.next_element().unwrap().unwrap();
    assert_eq!(
        element.value,
        Value::Unsigned(u64::from(ESAStateEnum::Fault.value())),
        "the controller did not learn the new state"
    );
}

// --- Liveness ---------------------------------------------------------------------------------

#[test]
fn a_keep_alive_counts_as_proof_of_life() {
    // §8.5.3: when nothing has changed by the maximum interval "the publisher SHALL send an
    // empty ReportData message". Its whole purpose is to say the subscription is still there,
    // so a subscriber that only counted *data* reports would tear down every subscription to
    // a device that simply is not changing — which is most devices, most of the time.
    let battery = Battery::default();
    let device = device(&battery);
    let paths = [AttributePath::attribute(1, dem::ID, dem::ESA_STATE)];
    let mut subscriptions = Table::new();
    let id = subscriptions
        .subscribe(
            &NewSubscription {
                session: Some(SessionId(1)),
                fabric_index: Some(FABRIC),
                peer_node_id: None,
                fabric_filtered: true,
                keep_subscriptions: true,
                min_interval_s: 1,
                max_interval_s: 30,
                paths: &paths,
                event_paths: &[],
                min_event_number: 0,
            },
            at(0),
        )
        .expect("a subscription");
    let subscription = subscriptions.find(id).expect("it exists");
    let mut held = Subscription::new(
        &SubscribeResponse {
            subscription_id: id,
            max_interval_s: subscription.max_interval_s,
            revision: None,
        },
        at(0),
    );

    // Nothing changed, so the report that goes out at the maximum interval is the empty one.
    let (_, reason) = subscriptions.due(at(30)).next().expect("due");
    assert_eq!(reason, ReportReason::KeepAlive);
    let mut buf = [0u8; 2048];
    let bytes = publish(&device, &mut subscriptions, id, reason, at(30), &mut buf);
    let report = ReportData::decode(bytes).expect("decodes");
    assert!(held.heard(&report, at(30)));

    // The subscriber's deadline moved with it.
    let margin = LIVENESS_MARGIN.as_secs();
    assert!(!held.is_expired(at(30 + 30 + margin - 1)));
    assert!(held.is_expired(at(30 + 30 + margin)));
}

#[test]
fn a_subscription_that_goes_quiet_expires_but_not_at_the_exact_interval() {
    // §8.5.4: "If the subscriber does not receive a report within the maximum interval ... the
    // subscriber SHALL consider the subscription to have expired." Timing out at *exactly*
    // MaxInterval would tear down a working subscription on the first MRP retransmission, and
    // over a sleepy Thread network the first retransmission is not unusual.
    let held = Subscription::new(
        &SubscribeResponse {
            subscription_id: 7,
            max_interval_s: 60,
            revision: None,
        },
        at(0),
    );
    let margin = LIVENESS_MARGIN.as_secs();
    assert!(!held.is_expired(at(60)), "expired at exactly MaxInterval");
    assert!(!held.is_expired(at(60 + margin - 1)));
    assert!(held.is_expired(at(60 + margin)));
    assert_eq!(held.expires_at(), at(60 + margin));
}

#[test]
fn one_subscriptions_reports_do_not_keep_another_alive() {
    // §8.5.3.2 puts the id in every report precisely so a subscriber holding several can tell
    // them apart. Crediting one subscription's liveness to another would keep a dead one alive
    // indefinitely — and a controller watching twenty devices holds twenty of these.
    let mut first = Subscription::new(
        &SubscribeResponse {
            subscription_id: 1,
            max_interval_s: 60,
            revision: None,
        },
        at(0),
    );
    // An empty keep-alive, as §8.5.3's would arrive — for subscription 2.
    let mut buf = [0u8; 64];
    let foreign = matter_kit::im::encode_report_data(
        &mut buf,
        Some(2),
        core::iter::empty::<matter_kit::im::ib::AttributeReport<'_>>(),
        false,
        true,
    )
    .expect("encodes")
    .to_vec();
    let foreign = ReportData::decode(&foreign).expect("decodes");
    assert!(
        !first.heard(&foreign, at(30)),
        "a foreign report was credited"
    );
    assert!(first.is_expired(at(60 + LIVENESS_MARGIN.as_secs())));

    let mut buf = [0u8; 64];
    let ours = matter_kit::im::encode_report_data(
        &mut buf,
        Some(1),
        core::iter::empty::<matter_kit::im::ib::AttributeReport<'_>>(),
        false,
        true,
    )
    .expect("encodes")
    .to_vec();
    let ours = ReportData::decode(&ours).expect("decodes");
    assert!(first.heard(&ours, at(30)));
    assert!(!first.is_expired(at(60 + LIVENESS_MARGIN.as_secs())));
}