Skip to main content

Local Control

Local Control commands Matter devices on the same LAN as the phone. The SDK uses the matter_local transport and calls your matterControlAdapter, which bridges to the native Matter stack (CHIP / MatterSupport).

info

This page is local only. Remote / off-LAN control is a separate path — see Remote Control. Both share getValue() / setValue(), but different interfaces and adapters.

Reference implementation: ESPMatterControlAdapter.ts in esp-rainmaker-home native-adaptors.

Dependencies (local path)​

What you need for matter_local only. Remote Control pieces are listed so you do not mix them in.

Required​

DependencyWhat it doesReference
matterControlAdapterTS bridge: SDK → native read / write / invokeESPMatterControlAdapter.ts
ESPMatterControlAdapterInterfaceContract that adapter implementsInterface below
Native Matter modulePlatform CASE session (Android / iOS)Home app ESPMatterModule / Matter control native code
DependencyWhat it doesReference
clusterConfigBuilds UI params with cluster / attribute IDsCluster config
matterLocalDiscoveryAdapterMarks peers reachable; enables matter_local on nodesMatterDiscoverAdapter.ts

Not used on this path​

DependencyWhy
matter_controller / RainMaker ControllerRemote hop only — see Remote Control

Pass adapters through ESPRMMatterBase.configure(). Without matterControlAdapter, LAN getValue / setValue cannot run.

Interface: ESPMatterControlAdapterInterface​

init?(config)                                              // optional: fabric setup (fabric ID, group ID, CA/IPK)
read(matterNodeId, endpoint, clusterId, attributeId)
write(matterNodeId, endpoint, clusterId, attributeId, value)
invoke(matterNodeId, endpoint, clusterId, commandId, payload?)
shutdown?()                                                // optional: tear down native controller

Implement read and write at minimum. Add invoke for command-based params (writeAsCommand / matterCommandId in cluster config). The Home app adapter already implements these.

Configure​

import { ESPRMMatterBase } from "@espressif/rainmaker-matter-sdk";
import { matterControlAdapter } from "./native-adaptors/implementations/ESPMatterControlAdapter";
import { matterLocalDiscoveryAdapter } from "./native-adaptors/implementations/MatterDiscoverAdapter";

ESPRMMatterBase.configure({
  // ... base + commissioning config
  matterControlAdapter,
  matterLocalDiscoveryAdapter, // recommended so matter_local is available on peers
  clusterConfig: matterClusterConfig,
});

Call init from your app when the user opens a fabric or home screen, if the native layer needs fabric credentials before the first read or write.

Full adapter catalog: Matter Adapters.

Control from your app​

Load a Matter node and use device parameters — the SDK maps each param to endpoint, cluster, and attribute IDs using your cluster config.

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

const nodes = await fabric.getNodesWithDetails();
const matterNode = nodes.find((n) => n instanceof ESPRMMatterNode) as ESPRMMatterNode;

const device = matterNode.devices?.[0];
const powerParam = device?.params?.find((p) => p.name === "Power");

if (powerParam) {
  await powerParam.getValue();
  console.log("Power:", powerParam.value);

  await powerParam.setValue(true);
}

Cloud node details do not include live Matter attribute values. Call getValue() when you need the current state from the device on the LAN.

If matter_controller is also registered, the transport manager may fall back to remote after a local failure — that is Remote Control, not this adapter.

Read vs write vs invoke​

  • Attributes — getValue() → adapter read; setValue() → adapter write when the param has a Matter attribute ID.
  • Commands — setValue() → adapter invoke when the param uses writeAsCommand or matterCommandId.

You normally call only getValue() / setValue(); the SDK chooses read, write, or invoke from param metadata.

When to use local control​

  • User toggles a light, dimmer, or plug while the phone is on the same network as the device
  • You want control without a cloud round-trip
  • Native Matter can reach commissioned nodes on the fabric

For off-LAN control, use Remote Control. For continuous UI sync, add Matter Subscription (separate adapter: matterSubscriptionAdapter).

On this page