Getting Started

The @espressif/rainmaker-matter-sdk package extends @espressif/rainmaker-base-sdk with Matter fabrics, commissioning, and control. This guide gets you to a logged-in app with Matter configured — the minimum before creating a fabric or adding a device.

NPM Package: @espressif/rainmaker-matter-sdk

Reference config: Home app getMatterSDKConfig() in config/sdk.config.ts

---

Prerequisites

• Node.js 22.0.0 or higher (recommended)
• @espressif/rainmaker-base-sdk — installed with the Matter SDK
• RainMaker API access — base URL and version (base URL guide)
• Home app Matter adapters — native-adaptors (see Matter Adapters)

---

Installation

npm install @espressif/rainmaker-matter-sdk

yarn add @espressif/rainmaker-matter-sdk

pnpm add @espressif/rainmaker-matter-sdk

The package re-exports the base SDK. Matter-specific APIs come from @espressif/rainmaker-matter-sdk.

---

Configuration

Reuse your Base SDK config (URL, storage, provisioning, …), then add Matter fields. That is what the Home app does in getMatterSDKConfig():

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

// Base adapters (same as rainmaker-base-sdk)
import asyncStorageAdapter from "./native-adaptors/implementations/ESPAsyncStorage";
// … provisionAdapter, localDiscoveryAdapter, localControlAdapter, etc.

// Matter adapters (Home app)
import { matterCommissioningAdaptor } from "./native-adaptors/implementations/ESPMatterAdapter";
import { ESPMatterControlAdapter } from "./native-adaptors/implementations/ESPMatterControlAdapter";
import { ESPMatterSubscriptionAdapter } from "./native-adaptors/implementations/ESPMatterSubscriptionAdapter";
import { matterLocalDiscoveryAdapter } from "./native-adaptors/implementations/MatterDiscoverAdapter";
import { matterClusterConfig } from "./sdk-adaptors/ESPRMMatterBase/cluster.config";

// Home app getMatterSDKConfig():
ESPRMMatterBase.configure({
  // Base SDK fields
  baseUrl: "https://api.rainmaker.espressif.com",
  version: "v1",
  customStorageAdapter: asyncStorageAdapter,
  // … other base adapters as needed

  // Matter fields
  matterCommissioningAdaptor,
  matterControlAdapter: ESPMatterControlAdapter,
  matterSubscriptionAdapter: ESPMatterSubscriptionAdapter,
  matterLocalDiscoveryAdapter,
  matterVendorId: "0x131B",
  clusterConfig: matterClusterConfig,
});

Full source: getMatterSDKConfig()

Cluster UI mapping: cluster.config.ts — see Cluster Config.

After configure (and login), if you use subscriptions:

await ESPRMMatterBase.initializeMatterSubscription();

---

Matter config fields

Field	Required?	Role
matterVendorId	Yes	Matter vendor ID for native commissioning (e.g. 0x131B)
matterCommissioningAdaptor	Yes for commission / user NoC	CSR, ecosystem commissioning, postMessage — ESPMatterAdapter
matterControlAdapter	For LAN control	matter_local read / write / invoke — ESPMatterControlAdapter
matterSubscriptionAdapter	For live LAN updates	Attribute reports — ESPMatterSubscriptionAdapter
matterLocalDiscoveryAdapter	Recommended for LAN reachability	Operational discovery — MatterDiscoverAdapter
clusterConfig	For control-screen params	Maps Matter clusters → UI params — Cluster Config

All Base SDK fields (baseUrl, version, storage, provisioning, …) still apply. See Base SDK Getting Started and Adapters.

Remote control via a RainMaker Controller does not need the control adapter — see Remote Control.

---

Quick start: login and create a fabric

const authInstance = ESPRMMatterBase.getAuthInstance();
const user = await authInstance.login("<USERNAME>", "<PASSWORD>");

const fabric = await user.createFabric({
  name: "Home Fabric",
  description: "Primary Matter fabric",
  type: "home",
});

console.log("Fabric created:", fabric.id);

Expected outcome: User is authenticated and a Matter fabric exists. Next you load fabric details and commission a device.

Throughout this docs set, userInstance means the logged-in ESPRMUser. Auth flows are the same as Base SDK User Management.

---

Next steps

1. Create or select a fabric
2. Load fabric details with getFabricDetails()
3. Commission a device
4. Controlling — local and remote