Controlling
Controlling covers how your app reacts to and commands Matter devices after commissioning — reading and writing cluster attributes through ESPRMMatterDeviceParam.
There is one app API and two independent transports. The SDK picks a transport at runtime; each path has its own interfaces and adapters.
Shared app API
Both paths use the same calls. You do not choose local vs remote in UI code:
await powerParam.getValue();
await powerParam.setValue(true);
The SDK maps the param to endpoint / cluster / attribute (or command) via cluster config, then runs executeMatterControl.
Default order (DEFAULT_MATTER_TRANSPORT_ORDER):
matter_local— Local Controlmatter_controller— Remote Control
Only modes present in node.availableTransports are tried. On failure, the next mode is used. If none succeed → NODE_UNREACHABLE.
Transport manager + remote path require @espressif/rainmaker-matter-sdk 3.1.0+.
Two paths — clear separation
| Local Control | Remote Control | |
|---|---|---|
| Transport key | matter_local | matter_controller |
| How it reaches the device | Phone → native Matter stack → device on LAN | Phone → RainMaker cloud cmd-resp → RainMaker Controller → device on fabric |
| When to use | Phone on home Wi‑Fi / same LAN as device | Phone off LAN; hub online in the cloud |
| Required adapter | matterControlAdapter | None (built-in SDK handler) |
| SDK interface | ESPMatterControlAdapterInterface | MatterControllerTransportMetadata on the peer + cmd-resp |
| Home app reference | ESPMatterControlAdapter.ts | Wiring in app layer; see RainMaker Controller |
| Depends on | Native Matter stack; usually local discovery for reachability | Controller node on fabric; peer availableTransports.matter_controller |
Local and remote are independent. You can ship:
- Local only — configure
matterControlAdapter, never registermatter_controller - Remote only — skip the control adapter; register controller transport on peers (LAN ops will not work)
- Both — default Home app setup; local first, remote as fallback
Dependencies and adapters by path
Local Control depends on
| Dependency | Role |
|---|---|
| matterControlAdapter | Native read / write / invoke |
| ESPMatterControlAdapterInterface | Contract the adapter implements |
| Optional: matterLocalDiscoveryAdapter | Marks peers reachable → fills matter_local transport |
| Optional: clusterConfig | Builds params the UI binds to |
| Native Matter module (Android/iOS) | Actual CASE session on LAN |
Details: Local Control · adapters: Matter Adapters
Remote Control depends on
| Dependency | Role |
|---|---|
| RainMaker Controller node on the fabric | Relays Matter ops |
| availableTransports.matter_controller + controllerNodeId on the peer | Enables the remote transport |
| Built-in matterControllerControlHandler | createCmdResp → poll → parse (no app adapter) |
| Logged-in user / cloud API | Cmd-resp to the controller node |
| Does not use matterControlAdapter | Local adapter is unused for this hop |
Details: Remote Control · hub: RainMaker Controller
Documentation map
| Guide | Content |
|---|---|
| This page | How control works overall; local vs remote; interfaces |
| Local Control | Adapter methods, configure, read/write/invoke |
| Remote Control | Controller transport, fallback, wiring |
| RainMaker Controller | Hub node, discovery, services |
| Enable Controller Transport | Register matter_controller, cmd IDs |
| App-Side Controller Wiring | Home-app found/lost + MTDevices |
Related
- Matter Adapters — full adapter list (Home app implementations)
- Matter Subscription — live attribute reports (separate from get/set)
- Matter Nodes —
ESPRMMatterNodeand params