Skip to main content

App-Side Controller Wiring

The Enable Controller Transport guide covers the SDK contract (availableTransports.matter_controller + controllerNodeId). This page documents a reference architecture used in the Espressif RainMaker Home app: how the app reacts to controller discovery, reads peer reachability from the controller setup service, and adds or removes remote transport on peers.

info

Cmd-resp create, poll, and parse stay in the Matter SDK. The app supplies controllerNodeId only. Adapt file names and store APIs to your project.

What “app side” means​

LayerResponsibility
Matter SDKsyncMatterControllers, found/lost events, executeMatterControl, cmd-resp handler
Group syncLoad fabric nodes; subscribe to controller found/lost once per session
Transport handlerOn found: cloud-subscribe controller, sync peer transports from MTDevices
CDF / storehandleNodeTransportUpdate add/remove; fan-out peer param updates to UI
Controller settings UIOptional: MTCtlCMD = 2 to refresh the hub’s Matter device list

Found: discover hub → subscribe → read reachability → attach matter_controller on online peers (and refresh when setup params change).

Lost: detach matter_controller from peers that used that hub.

Subscribe after group sync​

After the user is logged in and group/fabric nodes are loaded, subscribe once:

import { ESPRMMatterEventType } from "@espressif/rainmaker-matter-sdk";

user.subscribe(ESPRMMatterEventType.matterControllerFound, (event) => {
  handleMatterControllerFound(event); // event.nodeId = controller RainMaker id
});

user.subscribe(ESPRMMatterEventType.matterControllerLost, (event) => {
  handleMatterControllerLost(event);
});

Home app entry point (reference): subscribeMatterControllerTransport(esprmUser) from the Matter base adaptor / group sync path.

On controller found​

  1. Resolve the controller node in your store
  2. If the controller is not cloud-connected, treat as lost (remove peer transports)
  3. Cloud-subscribe the controller node so you receive connect / disconnect / param updates
  4. Read setup-service reachability and add matter_controller on online peers
peer.availableTransports.matter_controller = {
  type: "matter_controller",
  metadata: { controllerNodeId },
};

In CDF apps, prefer the store helper (e.g. handleNodeTransportUpdate(store, peerId, { type, metadata }, "add")) so UI reachability stays consistent.

Peer reachability from setup service​

Constant (concept)Value
Setup serviceesp.service.matter-controller-setup
Devices param typeesp.param.matter-devices
Notification keyMatterCTLSetup → nested MTDevices

Each MTDevices entry typically includes a RainMaker node id and an online flag. Suggested rules:

  • Online + rainmaker_node_id → add matter_controller with that controller’s id
  • Offline → remove matter_controller from that peer
  • Controller lost / disconnected → remove matter_controller from all peers that pointed at that controller

Fan-out live updates​

When the controller setup param changes, the hub may push peer attribute snapshots. The Home app:

  1. Parses MatterCTLSetup / MTDevices from the controller’s param update
  2. Builds a synthetic peer ESPNodeUpdateData
  3. Forwards it through the same Matter node-update handler used for local Matter subscriptions

That keeps UI state fresh for peers reached only via the controller, without requiring LAN Matter subscriptions.

Refresh controller device list​

If peers are missing from the hub’s list, request a refresh by writing MTCtlCMD = 2 on the controller (or setup) service’s writable command param.

Home app helpers (reference): getMatterControllerConfig / updateMatterControllerDeviceList under shared Matter controller utilities.

On controller lost​

  1. Unsubscribe from the controller’s cloud subscription
  2. Find peers whose matter_controller metadata controllerNodeId matches
  3. Remove that transport from those peers

Do not rely on the controller still being in the node store — resolve peer ids from your registered-transports map if needed.

Explicit contract​

Owned by SDKOwned by app
Detect controllers in group listsSubscribe to found/lost
Emit found/lost eventsDecide which peers get transport
Cmd-resp create / poll / parseSupply controllerNodeId
Default transport orderAdd/remove availableTransports
Local control via adapterOptional MTDevices fan-out + settings UX

What could go wrong​

SymptomLikely cause
Found event but no remote controlForgot to register peer transports
Transports stuck after hub offlineMissing lost/disconnect handler
UI not updating remotelyNo fan-out from setup param pushes
Empty MTDevicesHub list stale — try MTCtlCMD = 2

On this page