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:
- Finds nodes whose device type is in
MATTER_CONTROLLER_DEVICE_TYPE - Persists known controller ids per group
- 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 = 2on the controller (or setup) service - Reachability badges may show a controller source when
matter_controllertransport 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