RainMaker Controller

A RainMaker Matter Controller is a RainMaker node on the fabric that can relay Matter read, write, and invoke operations to peer Matter devices. The phone talks to the controller over the RainMaker cloud (command-response); the controller talks to peers on the Matter fabric.

信息

This is the hub used by the built-in matter_controller transport in @espressif/rainmaker-matter-sdk 3.1.0+. It is not the same as the platform Matter stack (ChipDeviceController / MTRDeviceController) used during commissioning, and it does not use matterControlAdapter (Local Control).

---

Dependencies

Item	Role
Controller node on fabric	Relays Matter ops to peers
Peer availableTransports.matter_controller	Points at this controller’s RainMaker node id
SDK cmd-resp handler	No separate app control adapter
Optional: setup service / MTDevices	Peer reachability for app wiring

Parent guide: Remote Control.

What a controller node is

Aspect	Detail
Role	Hub / relay for Matter ops when LAN control from the phone is unavailable
Identity	RainMaker node id (controllerNodeId in transport metadata)
Detection	Device type in node config is one of esp.device.matter-controller or matter-controller
Services	Typically esp.service.matter-controller and/or esp.service.matter-controller-setup

Controller nodes appear in fabric group node lists like any other RainMaker node. Peer end devices remain normal Matter / RainMaker Matter nodes; remote control attaches a transport on the peer, pointing at the controller’s RainMaker node id.

---

Discovery

When fabric nodes are loaded (for example via fabric.getNodesWithDetails()), the SDK runs syncMatterControllers:

1. Finds nodes whose device type is in MATTER_CONTROLLER_DEVICE_TYPE
2. Persists known controller ids per group
3. Emits lifecycle events as controllers appear or disappear across syncs / restarts

Event	Constant	Meaning
Found	ESPRMMatterEventType.matterControllerFound (com.espressif.event.matterControllerFound)	Controller present for the group
Lost	ESPRMMatterEventType.matterControllerLost (com.espressif.event.matterControllerLost)	Controller no longer present for the group

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

user.subscribe(ESPRMMatterEventType.matterControllerFound, (event) => {
  console.log("Controller found:", event.nodeId);
});

user.subscribe(ESPRMMatterEventType.matterControllerLost, (event) => {
  console.log("Controller lost:", event.nodeId);
});

备注

Discovery alone does not enable remote control. You must still register availableTransports.matter_controller on each peer — see Enable Controller Transport and App-Side Controller Wiring.

---

Setup service and peer reachability

Controllers often expose a setup service that reports which Matter peers the hub can reach:

Item	Value
Setup service type	esp.service.matter-controller-setup
Matter devices param	esp.param.matter-devices
Notification / shadow keys (app)	MatterCTLSetup, nested MTDevices

Apps use that map (online / offline + RainMaker node id) to add or remove matter_controller on peers. See App-Side Controller Wiring.

---

Controller UX notes (Home app reference)

In the Espressif RainMaker Home app reference:

• Controller devices are often treated as settings-oriented (no primary Control screen)
• Users can request a device-list refresh by writing MTCtlCMD = 2 on the controller (or setup) service
• Reachability badges may show a controller source when matter_controller transport is registered

Adapt naming and UI to your product; the SDK only requires a valid controllerNodeId on peer transports.

---

Related services

Service type	Role
esp.service.matter-controller	Primary controller service (e.g. MTCtlCMD)
esp.service.matter-controller-setup	Setup / peer list (esp.param.matter-devices)

---

What could go wrong

Symptom	Likely cause
No found/lost events	Group sync not loading nodes; device type not in controller types; storage adapter missing
Events fire but peers stay unreachable	App never registers peer transports
Stale peer list	Need MTCtlCMD = 2 refresh or wait for setup-param updates

---

Related

• Remote Control — remote path overview and dependencies
• Enable Controller Transport
• App-Side Controller Wiring
• Local Control — separate LAN path
• Controlling — local vs remote comparison