跳到主要内容

Matter Subscription

Use a Matter subscription adaptor to receive live updates from Matter devices on the local network. Your native Matter stack subscribes to cluster attributes (for example On/Off, brightness, color). The SDK registers a Matter channel with the base SDK subscription manager so your UI can listen for node updates the same way as cloud or push channels.

信息

Optional. Requires @espressif/rainmaker-base-sdk with subscription manager support.

Reference implementation: ESPMatterSubscriptionAdapter.ts in esp-rainmaker-home native-adaptors.

What the adaptor does​

The Home app ESPMatterSubscriptionAdapter (passed as matterSubscriptionAdapter) talks to your platform Matter stack. When the SDK needs updates for a node, it asks the adaptor to subscribe on the fabric. Attribute reports from clusters (endpoint, cluster, attribute, value) are delivered through your adaptor’s callback.

initialize()
subscribeToDevice(nodeId, fabricId, callback)
unsubscribeFromDevice(nodeId, fabricId)
isDeviceReachable(nodeId, fabricId)   // optional reachability check on the LAN
dispose()

Use the linked Home app adapter unless you need a custom native bridge.

Configure and enable​

import { ESPRMMatterBase, ESPRMBase } from "@espressif/rainmaker-matter-sdk";
import { matterSubscriptionAdapter } from "./native-adaptors/implementations/ESPMatterSubscriptionAdapter";

ESPRMMatterBase.configure({
  // ... other config
  matterSubscriptionAdapter,
});

await ESPRMMatterBase.initializeMatterSubscription();

initializeMatterSubscription() registers the Matter channel with ESPRMBase.subscriptionManager. Call it after configure() and user login, when you are ready to receive local Matter updates.

Fabric ID​

The adaptor needs the Matter fabric ID for each RainMaker node ID. If your app stores fabric mapping elsewhere, set a resolver on the channel:

ESPRMMatterBase.getMatterSubscriptionChannel()?.setFabricIdResolver(
  async (nodeId) => "<MATTER_FABRIC_ID_FOR_NODE>"
);

Subscribe from your app​

Use the base SDK subscription manager. You do not call the Matter adaptor directly for each screen—register once, then subscribe per node:

await ESPRMBase.subscriptionManager.subscribeToNode("<NODE_ID>", (update) => {
  console.log("Update from", update.source, update.payload);
});

When a Matter node is on the LAN and the adaptor is subscribed, cluster attribute changes surface as node updates. Combine with cloud or notification channels by setting channel order on the subscription manager (see the Base SDK subscription docs).

When to use it​

  • You want low-latency device state on the home Wi-Fi, without waiting for cloud round-trips
  • Your native stack already supports attribute subscriptions on commissioned Matter nodes
  • You already use the RainMaker subscription manager for other channels

If you only need one-off reads or writes, use Controlling (Local or Remote) instead.

On this page