Struct InteractionModel 

pub struct InteractionModel<'a, C, B, T, K, N, NC = NoopWirelessNetCtl, R = (), const NS: usize = rs_matter::::im::InteractionModel::{constant#0}, const NE: usize = rs_matter::::im::InteractionModel::{constant#1}>
where
    B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>,
{ /* private fields */ }

The implementation needs a DataModel instance to interact with the underlying clusters of the data model.

NC is the network controller type driving the (optional) wireless connection manager from InteractionModel::run. It defaults to NoopWirelessNetCtl, which is the right choice for Ethernet (and what the convenience InteractionModel::new constructor wires up); wireless devices pass a real controller via InteractionModel::new_with_net_ctl.

Implementations

impl<'a, C, B, T, K, N, const NS: usize, const NE: usize> InteractionModel<'a, C, B, T, K, N, NoopWirelessNetCtl, (), NS, NE>

where C: Crypto, B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>, T: DataModel, K: KvBlobStoreAccess, N: Networks,

pub fn new( matter: &'a Matter<'a>, crypto: C, buffers: &'a B, handler: T, kv: K, state: &'a InteractionModelState<N, NS, NE>, ) -> InteractionModel<'a, C, B, T, K, N, NoopWirelessNetCtl, (), NS, NE>

Create the data model for a device that does not need an operational wireless connection manager (typically an Ethernet device).

This is a convenience wrapper around InteractionModel::new_with_net_ctl that fixes the network controller to an inert NoopWirelessNetCtl, so InteractionModel::run’s connection-management branch stays dormant.

Arguments

• matter - a reference to the Matter instance
• buffers - a reference to an implementation of Buffers<IMBuffer> which is used for allocating RX and TX buffers on the fly, when necessary
• handler - an instance of type T which implements the DataModel trait. This instance is used for interacting with the underlying clusters of the data model. Note that the expectations is for the user to provide a handler that handles the Matter system clusters as well (Endpoint 0), possibly by decorating her own clusters with the rs_matter::dm::root_endpoint::with_ methods
• kv - an instance of type K which implements the KvBlobStoreAccess trait (obtain one via Matter::kv). This instance is used for interacting with the key-value blob store.
• state - a reference to the InteractionModelState holding the subscriptions table, the events queue and the network store (the latter parameterized by the Networks implementation N).

impl<'a, C, B, T, K, N, NC, const NS: usize, const NE: usize> InteractionModel<'a, C, B, T, K, N, NC, (), NS, NE>

where C: Crypto, B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>, T: DataModel, K: KvBlobStoreAccess, N: Networks,

pub fn new_with_net_ctl( matter: &'a Matter<'a>, crypto: C, buffers: &'a B, handler: T, kv: K, net_ctl: NC, state: &'a InteractionModelState<N, NS, NE>, ) -> InteractionModel<'a, C, B, T, K, N, NC, (), NS, NE>

Create the data model with an explicit network controller net_ctl.

Use this for wireless devices: net_ctl drives the operational connection manager run from InteractionModel::run (and is typically the same controller instance also wired into the NetworkCommissioning cluster handler). For Ethernet devices prefer the InteractionModel::new convenience constructor.

Arguments

• matter - a reference to the Matter instance
• buffers - a reference to an implementation of Buffers<IMBuffer> which is used for allocating RX and TX buffers on the fly, when necessary
• handler - an instance of type T which implements the DataModel trait. This instance is used for interacting with the underlying clusters of the data model. Note that the expectations is for the user to provide a handler that handles the Matter system clusters as well (Endpoint 0), possibly by decorating her own clusters with the rs_matter::dm::root_endpoint::with_ methods
• kv - an instance of type K which implements the KvBlobStoreAccess trait (obtain one via Matter::kv). This instance is used for interacting with the key-value blob store.
• net_ctl - the network controller (NetCtl + WirelessDiag + NetChangeNotif) used by the operational wireless connection manager driven from InteractionModel::run.
• state - a reference to the InteractionModelState holding the subscriptions table, the events queue and the network store (the latter parameterized by the Networks implementation N).

impl<'a, C, B, T, K, N, NC, R, const NS: usize, const NE: usize> InteractionModel<'a, C, B, T, K, N, NC, R, NS, NE>

where C: Crypto, B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>, T: DataModel, K: KvBlobStoreAccess, N: Networks, R: ReportDataHandler,

pub fn new_with_reports( matter: &'a Matter<'a>, crypto: C, buffers: &'a B, handler: T, kv: K, net_ctl: NC, report_handler: R, state: &'a InteractionModelState<N, NS, NE>, ) -> InteractionModel<'a, C, B, T, K, N, NC, R, NS, NE>

Create the data model with an explicit network controller net_ctl and a ReportDataHandler report_handler — the controller / subscriber role.

This is InteractionModel::new_with_net_ctl plus a report consumer: after this node establishes subscriptions (via the IM client), the publishers push ReportData on fresh inbound exchanges, which the InteractionModel routes to report_handler. The default (new/new_with_net_ctl) constructors leave the report handler as (), which disowns every report — correct for a pure accessory.

Arguments

Same as InteractionModel::new_with_net_ctl, plus:

• report_handler - an instance of type R implementing ReportDataHandler, invoked once per received ReportData chunk.

pub const fn matter(&self) -> &'a Matter<'a>

Get a reference to the Matter instance this data model is associated with.

pub const fn crypto(&self) -> &C

pub fn open_basic_comm_window(&self, timeout_secs: u16) -> Result<(), Error>

Open the basic commissioning window.

Equivalent to Matter::open_basic_comm_window but additionally bumps the data version of the AdministratorCommissioning cluster on the root endpoint and routes the change to subscribers — both happen automatically because this InteractionModel is itself the AttrChangeNotifier passed down.

Prefer this entry point over the Matter one for any code path that has a InteractionModel available; Matter::open_basic_comm_window is the building block we delegate to and does not bump dataver (see its docs).

pub fn close_comm_window(&self) -> Result<bool, Error>

Close the active commissioning window.

Equivalent to Matter::close_comm_window but additionally bumps the AdministratorCommissioning dataver and routes subscribers via this InteractionModel’s AttrChangeNotifier. See open_basic_comm_window for the rationale.

pub fn bump_configuration_version(&self) -> Result<u32, Error>

Bump BasicInformation::ConfigurationVersion by one, persist the new value, and notify subscribers (which also bumps the BasicInformation cluster’s dataver via this InteractionModel’s AttrChangeNotifier).

Per Matter Core Spec, callers MUST invoke this whenever the node’s exposed fixed-quality surface changes — typically after a firmware update that adds or removes functionality, after an internal reconfiguration that changes any F-quality attribute (Descriptor::ServerList, PartsList, …), or (for bridges) after a bridged node is added or removed. It is not invoked automatically by rs-matter because the library has no way to know about an application’s reconfiguration events.

Returns the new ConfigurationVersion value.

pub async fn startup(&self) -> Result<(), Error>

Bring the Data Model to its operational state after a reboot.

Call once, after constructing the InteractionModel and before running it or serving exchanges. In order:

• Re-hydrates the InteractionModelState - the events-queue epoch (so event numbers are not reused across reboots) and the network store;
• Replays any persisted subscriptions into the reporter’s table (if the persistent-subscriptions feature is enabled), so a subscriber that had a subscription before this reboot keeps receiving reports instead of having to notice the loss and re-subscribe;
• Broadcasts LifecycleOp::Startup to every cluster handler in the data model, so handlers with a persistence story of their own (which the Interaction Model otherwise treats as opaque) can re-hydrate their state from HandlerContext::kv.

The Matter-level counterpart is Matter::startup - call that one first.

pub async fn factory_reset(&self) -> Result<(), Error>

Factory-reset the Data Model persistable state.

The counterpart of InteractionModel::startup. In order:

• Resets the InteractionModelState persisted contents to factory defaults - the events-queue epoch, the network store and (if compiled in) the persisted subscriptions - removing them from the KV store;
• Broadcasts LifecycleOp::FactoryReset to every cluster handler in the data model, so handlers can reset their own state and remove their persisted data from HandlerContext::kv.

Call when the node is factory-reset, alongside the Matter-level counterpart, Matter::factory_reset.

pub async fn run(&self) -> Result<(), Error>

where NC: NetCtl + NetCtlStatus + WirelessDiag + NetChangeNotif,

pub async fn connect_once(&self, network_id: &[u8]) -> Result<(), Error>

where NC: NetCtl + NetCtlStatus + WirelessDiag + NetChangeNotif,

Perform a single, one-shot connect to the wireless network with the given ID, immediately and regardless of the commissioning status.

This drives the same WirelessMgr used by InteractionModel::run (over this model’s network controller and the network store owned by its InteractionModelState), but calls WirelessMgr::connect_once rather than the operational loop. It exists so a stack performing non-concurrent (BLE-only) commissioning can replay the deferred ConnectNetwork once the operational radio is up but before commissioning completes - without having to own a WirelessMgr (or the networks) itself.

pub async fn handle(&self, exchange: &mut Exchange<'_>) -> Result<(), Error>

Answer a responding exchange using the DataModel instance wrapped by this exchange handler.

impl<C, B, T, K, N, NC, R, const NS: usize, const NE: usize> InteractionModel<'_, C, B, T, K, N, NC, R, NS, NE>

where C: Crypto, B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>, T: DataModel, K: KvBlobStoreAccess, N: Networks,

pub fn load_stats(&self, fab_idx: Option<NonZero<u8>>) -> DeviceLoad

The node’s resource-utilisation metrics, for the GeneralDiagnostics cluster’s DeviceLoadStatus attribute.

fab_idx is the fabric of the reading subject, for CurrentSubscriptionsForFabric; pass None when no fabric is in scope.

Handlers reach this through ImStats::device_load rather than calling it directly, but it is public so a controller can query its own load.

Deliberately free of the R: ReportDataHandler bound the other InteractionModel methods carry: the figures come from the transport and the subscriptions table, so both the accessory and controller roles can report them.

Trait Implementations

impl<C, B, T, K, N, NC, R, const NS: usize, const NE: usize> AttrChangeNotifier for InteractionModel<'_, C, B, T, K, N, NC, R, NS, NE>

where C: Crypto, B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>, T: DataModel, K: KvBlobStoreAccess, N: Networks,

fn notify_attr_changed(&self, endpoint_id: u16, cluster_id: u32, attr_id: u32)

Notify that the state of an attribute has changed.

fn notify_cluster_changed(&self, endpoint_id: u16, cluster_id: u32)

Notify that every attribute of the given cluster may have changed.

fn notify_endpoint_changed(&self, endpoint_id: u16)

Notify that every attribute on every cluster of the given endpoint may have changed.

fn notify_all_changed(&self)

Notify that every attribute on every cluster on every endpoint may have changed.

impl<C, B, T, K, N, NC, R, const NS: usize, const NE: usize> EventEmitter for InteractionModel<'_, C, B, T, K, N, NC, R, NS, NE>

where C: Crypto, B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>, T: DataModel, K: KvBlobStoreAccess, N: Networks,

fn emit_event<F>( &self, endpoint_id: u16, cluster_id: u32, event_id: u32, priority: EventPriority, f: F, ) -> Result<u64, Error>

where F: FnOnce(EventTLVWrite<'_>) -> Result<(), Error>,

Emit an event.

impl<C, B, T, K, N, NC, R, const NS: usize, const NE: usize> ExchangeHandler for InteractionModel<'_, C, B, T, K, N, NC, R, NS, NE>

where C: Crypto, B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>, T: DataModel, K: KvBlobStoreAccess, N: Networks, R: ReportDataHandler,

async fn handle(&self, exchange: Exchange<'_>) -> Result<(), Error>

impl<C, B, T, K, N, NC, R, const NS: usize, const NE: usize> HandlerContext for InteractionModel<'_, C, B, T, K, N, NC, R, NS, NE>

where C: Crypto, B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>, T: DataModel, K: KvBlobStoreAccess, N: Networks,

fn matter(&self) -> &Matter<'_>

Return the Matter object that is associated with this handler

fn crypto(&self) -> impl Crypto

Return the crypto object that is associated with this operation.

fn kv(&self) -> impl KvBlobStoreAccess

Return a blob store that can be used to persist data across reboots.

fn networks(&self) -> impl NetworksAccess

Return the networks access object.

fn metadata(&self) -> impl Metadata

Return the metadata of the node that is associated with this handler.

fn handler(&self) -> impl AsyncHandler

Return the global handler that this handler is part of.

fn buffers( &self, ) -> impl Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>

Return the buffer pool of the Data Model.

fn im_stats(&self) -> impl ImStats

Return the Interaction Model statistics of the node.

fn notify_fabric_removed(&self, fab_idx: NonZero<u8>)

Notify that the fabric with the given local index has been removed from the fabric table, by synchronously broadcasting LifecycleOp::FabricRemoval to every handler in the data model.

impl<C, B, T, K, N, NC, R, const NS: usize, const NE: usize> ImStats for InteractionModel<'_, C, B, T, K, N, NC, R, NS, NE>

where C: Crypto, B: Buffers<Vec<u8, rs_matter::::transport::exchange::Buffer::{constant#0}>>, T: DataModel, K: KvBlobStoreAccess, N: Networks,

fn device_load(&self, fab_idx: Option<NonZero<u8>>) -> DeviceLoad

The node’s resource-utilisation metrics, for GeneralDiagnostics::DeviceLoadStatus.