Skip to main content

Remote Control

Remote Control commands Matter devices when the phone is not on the LAN. The SDK uses the matter_controller transport: RainMaker command-response to a RainMaker Controller node, which relays the Matter operation to the peer on the fabric.

info

Requires @espressif/rainmaker-matter-sdk 3.1.0+.

This path does not use matterControlAdapter. Local LAN control is a separate path — see Local Control.

Dependencies (remote path)​

What you need for matter_controller only. This hop does not call matterControlAdapter.

Required​

DependencyWhat it doesReference
RainMaker Controller on the fabricHub that relays Matter ops to peersRainMaker Controller
availableTransports.matter_controller on the peerEnables remote transport; metadata needs controllerNodeIdEnable Controller Transport
Built-in matterControllerControlHandlercreateCmdResp → poll → parse (in the SDK)SDK 3.1.0+
Logged-in user + cloud APIsCmd-resp targets the controller RainMaker node idBase SDK auth / cmd-resp
DependencyWhat it doesReference
App wiring for found/lost + MTDevicesAttach / remove peer transports when the hub is onlineApp-Side Controller Wiring

Not used on this path​

DependencyWhy
matterControlAdapterLocal LAN hop only — see Local Control

How it differs from local​

LocalRemote
Transportmatter_localmatter_controller
AdapterESPMatterControlAdapterInterfaceNone — SDK handler
NetworkLAN / CASECloud cmd-resp → hub → fabric
App must supplyNative control adaptercontrollerNodeId on peer transport

Same UI API:

await powerParam.getValue();
await powerParam.setValue(true);

When to use it​

  • Phone is off the home LAN, but a Matter controller hub is online in the cloud
  • Local Matter fails and you want automatic fallback (default order: local → remote)
  • A RainMaker Controller is commissioned into the same fabric as peer devices

For LAN-only apps, skip this section and use Local Control alone.

Enable the transport​

Register on each peer you want to reach remotely:

peerNode.availableTransports.matter_controller = {
  type: "matter_controller",
  metadata: {
    controllerNodeId: "<CONTROLLER_RAINMAKER_NODE_ID>",
    // timeoutSeconds: 60,
  },
};

Full cmd IDs (4352 / 4353 / 4354) and handler flow: Enable Controller Transport.

note

The SDK emits matterControllerFound / matterControllerLost but does not auto-attach peer transports. Your app must register metadata — see App-Side Controller Wiring.

Custom transport managers​

Override the built-in remote handler per node if needed:

node.customTransportManagers = {
  matter_controller: {
    getParams: async (payload, node) => { /* ... */ },
    setParam: async (payload, node) => { /* ... */ },
  },
};

Documentation​

GuideCovers
RainMaker ControllerHub node, discovery events, services
Enable Controller TransportavailableTransports, cmd IDs, SDK handler
App-Side Controller WiringHome-app found/lost, MTDevices, fan-out

What could go wrong​

SymptomLikely cause
NODE_UNREACHABLENo transports registered, or every transport failed
Remote never attemptedPeer missing matter_controller / wrong controllerNodeId
Cmd-resp timeoutController offline, peer not in hub device list, or timeout too low
Local always usedLocal succeeds first — expected with default order

On this page