Skip to content

Emit BasicInformation::StartUp event after data model startup#41

Open
snabb wants to merge 2 commits into
sysgrok:nextfrom
snabb:startup-event
Open

Emit BasicInformation::StartUp event after data model startup#41
snabb wants to merge 2 commits into
sysgrok:nextfrom
snabb:startup-event

Conversation

@snabb
Copy link
Copy Markdown
Contributor

@snabb snabb commented May 23, 2026

Summary

Emit BasicInformation::StartUp on the root endpoint from run_dm /
run_dm_with_bump, as required by Matter 1.5.1 Core §11.1.6.1 (SHALL).
Every Node has to emit it "as soon as reasonable after completing a
boot or reboot process," with SoftwareVersion matching the
BasicInformation attribute of the same name.

Today, applications built on rs-matter-stack get no help with this —
each one has to wire its own Handler impl into the chain just to emit
one mandatory event. Stack-level emission means every downstream
project is spec-compliant without per-app boilerplate.

Implementation

A small emit_startup_event_once(dm) helper is called at the top of
run_dm and run_dm_with_bump, before the responder and DM run()
future start. By that point the DataModel (and its event ringbuf +
EventNumber persistence from #39) is fully initialised, and every
Ethernet / wireless run-loop in the crate funnels through one of those
two paths.

run_dm is called more than once per boot in the wireless flow — once
from the commissioning task (wireless/thread.rs:507,
wireless/wifi.rs:504) and once from the operational task
(wireless/thread.rs:579, wireless/wifi.rs:576). §11.1.6.1's "boot
or reboot process" wording is per process boot, not per network attach,
so the helper is gated by a startup_event_emitted: IfMutex<bool>
field on MatterStack that flips to true on the first successful
emission and short-circuits subsequent calls. On Err the flag stays
false so a transient KV failure on the EventNumber epoch-boundary
write gets retried on the next run_dm.

SoftwareVersion is pulled from self.matter().dev_det().sw_ver.
Failures are logged at warn!, not propagated — a zero-sized events
ringbuf already silently drops events on emission, and there's no
reason to fail the run loop over a missing observability event.

If the device boots uncommissioned, StartUp fires during the
commissioning run_dm, before any controller is bound. It lands in
the ringbuf and the commissioner picks it up on its first subscribe
after CASE — which is correct per the buffered event-subscription
model and consistent with §11.1.6.1's silence on who must receive
the event.

Test plan

  • cargo build / cargo clippy --no-deps clean on next HEAD.
  • End-to-end on ESP32-C6 + Home Assistant matter-server (matter.js):
    device-side log shows BasicInformation::StartUp emitted (sw_ver=1, event_number=50000) ~2.3 s after boot; controller-side log shows
    ClientEventEmitter Received event basicInformation.startUp on server-2-134b.@1:37 softwareVersion: 1 after the next subscribe.
    EventNumber increments by EVENT_NUMBER_EPOCH_SIZE (10000) per
    reboot, confirming persist EventNumber across restarts (Matter Core §7.14.1.1) #39's persistence still works through this path.

snabb added 2 commits May 23, 2026 00:51
Matter 1.5.1 Core §11.1.6.1 requires (SHALL) every Node to emit
BasicInformation::StartUp after boot, with SoftwareVersion matching the
BasicInformation attribute. Stack-level emission means every downstream
project gets spec compliance without per-app wiring.

Emitted at the top of run_dm / run_dm_with_bump because by that point
the DataModel (and its event ringbuf + EventNumber persistence) is
ready, and every wireless / Ethernet run-loop funnels through one of
those two paths. SoftwareVersion is pulled from matter.dev_det().sw_ver.
Failures are logged, not propagated.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant