ESP RainMaker Next Generation Matter TypeScript SDK

The @espressif/rmng-matter-sdk package extends the ESP RainMaker Next Generation Base SDK with Matter protocol support — fabric management, Matter commissioning, certificate handling, and local device control over the Matter transport. Built specifically for React Native applications, it enables seamless integration of Matter-compatible devices into the ESP RainMaker Next Generation ecosystem.

Table of Contents

• Overview
• Key Features
• Requirements
• Dependencies
• Installation
  • Package Manager
  • Local Installation
• Quick Start
• Usage Examples
  • Fabric Management
  • Matter Commissioning
  • Matter Node Control
  • Real-time Subscriptions
• Architecture
• API Documentation
• Troubleshooting
• Contributing
• Resources
• License

Overview

The @espressif/rmng-matter-sdk is a TypeScript SDK that adds a comprehensive Matter protocol layer on top of the ESP RainMaker Next Generation base SDK. It provides APIs for managing Matter fabrics, commissioning Matter-compatible devices, issuing Node Operational Certificates (NoCs), and controlling devices over the Matter local transport with automatic fallback to cloud communication.

What's New in the NG Matter SDK

• Fabric Management: Create, retrieve, and manage Matter fabrics with multi-fabric support
• End-to-End Commissioning: Complete commissioning flow with CSR nonce generation and NoC issuance
• Matter Local Transport: Control devices over the Matter protocol using a pluggable native adapter
• Matter Subscription Channel: Real-time device updates with Matter-to-RMNG data transformation
• Base SDK Re-export: All base SDK functionality available through a single import

Key Features

• [x] Fabric Management: Create, retrieve, and manage Matter fabrics with support for multi-fabric architectures.
• [x] Matter Commissioning: End-to-end commissioning flow including CSR nonce generation, NoC issuance, and user-node mapping confirmation.
• [x] Local Matter Transport: Control devices over the Matter local transport using a pluggable native control-adapter interface for iOS and Android.
• [x] Subscription Channel: Receive real-time device updates through a Matter-aware subscription channel that transforms native Matter attribute updates into SDK-compatible formats.
• [x] Base SDK Re-export: All base SDK functionality (auth, user, device, group management, MQTT) is available through a single import.
• [x] Type Safety: Full TypeScript support with comprehensive type definitions for Matter-specific data models.
• [x] Modular Design: Clean separation of concerns — fabric, node, transport, and subscription are independent modules.

Requirements

Before installing the @espressif/rmng-matter-sdk package, ensure you meet the following prerequisites:

• React Native: Version 0.72.0 or higher
• Node.js: Version 20 or higher (see .nvmrc)
• TypeScript: Version 5.0 or higher (recommended)
• iOS: iOS 16.4 or higher (Matter framework requirement)
• Android: API level 27 (Android 8.1) or higher with Google Play Services for Matter
• Base SDK: The @espressif/rmng-base-sdk package (automatically resolved as a dependency)

Dependencies

Runtime Dependencies

The SDK has a single runtime dependency:

• @espressif/rmng-base-sdk — ESP RainMaker Next Generation Base SDK (authentication, MQTT, device management)

Matter local control is provided by your application via the ESPRMNGMatterControlAdapterInterface — the SDK does not bundle any native Matter libraries directly.

Development Dependencies

For building and testing:

• Build: rollup, @rollup/plugin-typescript, @rollup/plugin-*, typescript
• Tests: jest, ts-jest, jest-junit, dotenv
• Lint/Format: eslint, prettier
• Docs: typedoc

Installation

Package Manager

To install the latest version of the @espressif/rmng-matter-sdk package:

Using npm:

npm install @espressif/rmng-matter-sdk

Using Yarn:

yarn add @espressif/rmng-matter-sdk

Using pnpm:

pnpm add @espressif/rmng-matter-sdk

Local Installation

For development and testing with the local SDK:

1. Clone the repository and navigate to the SDK directory

2. Install dependencies:

   npm install

3. Build the package:

   npm run build

4. Create a tarball for testing locally:

   npm pack

5. In your React Native project, install the local SDK:

   npm install <PATH_TO_PACK_TARBALL_FILE>

Quick Start

1. Configure the SDK

import { ESPRMNGMatterBase } from "@espressif/rmng-matter-sdk";
import type { ESPRMNGMatterBaseConfig } from "@espressif/rmng-matter-sdk";

const config: ESPRMNGMatterBaseConfig = {
  baseUrl: "https://your-api-gateway.amazonaws.com",
  apiPath: "/prod",
  userApiBaseUrl: "https://your-user-api-gateway.amazonaws.com",
  userApiPath: "/prod",
  identityId: "your-identity-pool-id",
  awsRegion: "your-aws-region",
  userPoolId: "your-user-pool-id",
  clientId: "your-cognito-client-id",
  iotEndpoint: "your-iot-endpoint.amazonaws.com",
  customStorageAdapter: yourStorageAdapter,
  provisionAdapter: yourProvisionAdapter,
  mqttAdapter: yourMQTTAdapter,
  matterVendorId: "0x131B",
  matterAdapter: yourMatterAdapter,
  matterControlAdapter: yourMatterControlAdapter,
  matterSubscriptionAdapter: yourMatterSubscriptionAdapter,
};

// configure() initializes both the Matter SDK and the base SDK internally
ESPRMNGMatterBase.configure(config);

// Initialize the Matter subscription channel (registers with the base subscription manager)
await ESPRMNGMatterBase.initializeMatterSubscription();

2. Authenticate and Work with Fabrics

import { ESPRMNGBase, ESPRMNGFabric } from "@espressif/rmng-matter-sdk";

const auth = ESPRMNGBase.getAuthInstance();
const user = await auth.login("[email protected]", "password");

// Get all groups and fabrics
const { groups, fabrics } = await user.getGroupsAndFabrics();

// Or construct a fabric directly from a known groupId
const fabric = new ESPRMNGFabric({ groupId: "your-group-id", groupName: "My Fabric" });

Usage Examples

Fabric Management

import { ESPRMNGBase, ESPRMNGFabric } from "@espressif/rmng-matter-sdk";

const manageFabrics = async () => {
  const auth = ESPRMNGBase.getAuthInstance();
  const user = await auth.login("[email protected]", "password");

  // Create a new fabric
  const fabric = await user.createNewFabric("Living Room Fabric");

  // Retrieve fabrics by group ID or name (getFabricById uses groupId)
  const fabricById = await user.getFabricById("your-group-id");
  const fabricByName = await user.getFabricByName("Living Room Fabric"); // returns undefined if not found

  // Get all groups and fabrics together
  const { groups, fabrics } = await user.getGroupsAndFabrics();
  console.log("Groups:", groups.length, "Fabrics:", fabrics.length);

  // Construct a fabric directly when you already know the groupId
  // (useful in headless tasks where getGroups may not be available)
  const directFabric = new ESPRMNGFabric({ groupId: "group-id", groupName: "" });
};

Matter Commissioning

The SDK exposes three distinct cloud flows aligned with VerifyRequest in the RMNG swagger.

Flow A — Pure Matter device (device NOC + confirm)

const commissionPureMatterDevice = async (fabric: ESPRMNGFabric) => {
  const { request_id } = await fabric.initiateNodeAssociation();

  const verifyResponse = await fabric.addNodeToMatterFabric({
    requestId: request_id,
    nocsrElements: nocsrElementsHex,
    attestationChallenge: attestationChallengeHex,
    attestationSignature: attestationSignatureHex,
  });
  console.log("Device NOC:", verifyResponse.noc);
  console.log("Matter node ID:", verifyResponse.matter_node_id);
  console.log("RMNG node ID:", verifyResponse.node_id);

  await fabric.confirmUserNodeMapping({ requestId: request_id });
};

Flow B — RainMaker device on a Matter group (no NOC)

const addRainMakerNodeToMatterGroup = async (fabric: ESPRMNGFabric) => {
  const { request_id } = await fabric.initiateNodeAssociation();

  await fabric.verifyNodeAssociation({
    requestId: request_id,
    challengeResponse: signedChallengeHex,
    nodeId: "MySmartLight01",
  });
};

Flow C — User joins fabric (controller NOC)

const joinFabricAsUser = async (fabric: ESPRMNGFabric, csrPem: string) => {
  const userNoc = await fabric.issueUserNoC({ csr: csrPem });
  console.log("User NOC:", userNoc.noc, "Matter user ID:", userNoc.matter_user_id);
};

getCSRNonce() is a deprecated alias for initiateNodeAssociation() — prefer initiateNodeAssociation().

Matter Node Control

import { ESPRMNGMatterBase } from "@espressif/rmng-matter-sdk";

const controlMatterDevice = async (matterNodeId: string, endpoint = 1) => {
  const controlAdapter = ESPRMNGMatterBase.ESPRMNGMatterControlAdapter;
  if (!controlAdapter) {
    console.error("Matter control adapter not configured");
    return;
  }

  // Local control goes through the native adapter (read / write / invoke).
  await controlAdapter.invoke(matterNodeId, endpoint, 0x6, 0x1);

  const matterNodePayload = ESPRMNGMatterBase.buildESPRMNGMatterNode(rmngNode, {
    identifier: "your-adapter-identifier",
    groupId: "your-group-id",
  });
};

Real-time Subscriptions

import { ESPRMNGMatterBase, ESPRMNGBase } from "@espressif/rmng-matter-sdk";

const setupSubscriptions = async () => {
  // After configure(), initialize the Matter subscription channel
  await ESPRMNGMatterBase.initializeMatterSubscription();

  // Verify registration with the base subscription manager
  const subManager = ESPRMNGBase.subscriptionManager;
  console.log("Registered channels:", subManager.getRegisteredChannels());
  console.log("Channel order:", subManager.getGlobalChannelOrder());

  // The MatterSubscriptionChannel automatically:
  // - Receives native Matter attribute updates via the subscription adapter
  // - Transforms them into base SDK-compatible format
  // - Dispatches updates through the subscription manager
};

Architecture

The ESP RainMaker Next Generation Matter SDK follows a layered architecture that extends the base SDK:

Source Structure

src
├── ESPRMNGMatterBase.ts                 — static config/lifecycle (extends ESPRMNGBase)
├── ESPRMNGFabric.ts                     — Matter fabric (extends ESPRMNGGroup)
├── ESPRMNGMatterNode.ts                 — Matter-aware node
├── ESPRMNGMatterDevice.ts               — Matter device
├── ESPRMNGMatterDeviceParam.ts          — Matter device param (read/write)
├── ESPRMNGMatterCommissioningRequest.ts — commissioning result model
├── index.ts                             — public barrel (also re-exports rmng-base-sdk)
├── config/                              — cluster registry + cluster types
├── methods/                             — prototype augmentations per class
│   ├── ESPRMNGFabric/                   — commissioning + certificate flow
│   ├── ESPRMNGGroup/                    — ConvertToFabric
│   ├── ESPRMNGMatterCommissioningRequest/
│   ├── ESPRMNGMatterDevice/ · ESPRMNGMatterDeviceParam/
│   ├── ESPRMNGMatterNode/               — cluster/endpoint/metadata accessors
│   ├── ESPRMNGService/
│   └── ESPRMNGUser/                     — fabric/group queries + EventSubscriptionModel
├── services
│   ├── ESPRMNGMatterHelpers/            — node/group transforms + registry
│   ├── ESPRMNGMatterSubscriptionChannel/ — live attribute subscription channel
│   └── ESPRMNGMatterTransport/          — control-adapter interface
├── storage/                             — node + local-metadata persistence
├── types/                               — io, node, fabric, param, subscription
└── utils/                               — constants, error, helpers, node utilities

Component Hierarchy

@espressif/rmng-matter-sdk
├── ESPRMNGMatterBase (static)
│   ├── configure(config)              — Initializes Matter + base SDK
│   ├── initializeMatterSubscription() — Registers Matter channel with subscription manager
│   ├── buildESPRMNGMatterNode()        — Builds node payload from shadow data
│   ├── setMatterCommissioningAdaptor() / requireMatterCommissioningAdaptor() / getMatterSubscriptionChannel()
│   ├── ESPRMNGMatterCommissioningAdaptor — Native Matter adapter (commissioning)
│   ├── ESPRMNGMatterControlAdapter       — Native Matter control adapter (read/write)
│   └── getFabricIdForNode()            — Resolves fabric for a node
│
├── ESPRMNGFabric (extends ESPRMNGGroup)
│   ├── initiateNodeAssociation()      — POST node-assoc-requests (InitiateResponse)
│   ├── getCSRNonce()                  — Deprecated alias for initiateNodeAssociation()
│   ├── verifyNodeAssociation()        — challenge_response verify (RainMaker on Matter group)
│   ├── addNodeToMatterFabric()        — nocsr_elements verify (device NOC)
│   ├── issueUserNoC()                 — User/controller NOC (POST matter-nocs)
│   └── confirmUserNodeMapping()       — Finalize nocsr_elements commissioning
│
├── ESPRMNGMatterNode
│   ├── hasCluster() / getEndpointWithCluster()
│   ├── getServerClusters() / getClientClusters()
│   └── setMatterNodeId()
│
├── ESPRMNGMatterDeviceParam
│   └── setValue() / getValue() — Uses ESPRMNGMatterControlAdapter (native bridge)
│
├── MatterSubscriptionChannel
│   └── transformMatterToRMNG()       — Converts Matter updates to base SDK format
│
└── @espressif/rmng-base-sdk (re-exported)
    ├── ESPRMNGBase, ESPRMNGAuth, ESPRMNGUser
    ├── ESPDevice, ESPRMNGGroup
    ├── MQTT, ESPRMNGSubscriptionManager
    └── ESPRMNGStorage, Logger, Utils

Core Components

• ESPRMNGMatterBase: Static class — configure() initializes both the Matter layer and the base SDK (ESPRMNGBase.init()). Holds references to native adapters and the Matter subscription channel. Also provides setMatterCommissioningAdaptor(), requireMatterCommissioningAdaptor(), and getMatterSubscriptionChannel().
• ESPRMNGFabric: Extends ESPRMNGGroup with optional fabricDetails for Matter-specific metadata. Can be constructed directly from a groupId or retrieved via user methods.
• ESPRMNGMatterNode: Matter-aware node with endpoint/cluster accessors. Built from shadow data via buildESPRMNGMatterNode().
• ESPRMNGMatterDeviceParam: Cluster-aware param with setValue() / getValue() — delegates to ESPRMNGMatterControlAdapter configured on ESPRMNGMatterBase.
• MatterSubscriptionChannel: Receives native Matter attribute updates, transforms them via transformMatterToRMNG(), and dispatches through the base SDK's subscription manager.

Key Interfaces & Types

• ESPRMNGMatterBaseConfig: SDK configuration — extends base config with matterVendorId, matterAdapter, matterControlAdapter, matterSubscriptionAdapter
• ESPRMNGMatterControlAdapterInterface: Native adapter for Matter local control (iOS/Android)
• ESPRMNGMatterCommissioningAdaptorInterface: Native adapter for Matter commissioning (CSR generation, etc.)
• ESPRMNGMatterControlResult: Result type for Matter control operations
• ESPRMNGMatterAttributeReadResult: Result type for Matter attribute reads
• ESPRMNGMatterSubscriptionAdapter: Subscription adapter for native Matter attribute updates
• MatterDeviceUpdate: Real-time device update payload (endpointId, clusterId, attributeId, value)
• ESPRMNGMatterCapabilityResponse: Fabric capability details (fabric_id, root_ca, ipk, group_cat_id_admin, group_cat_id_operate)

API Documentation

Matter cloud REST APIs

| SDK method | HTTP | Path | Swagger schema | |------------|------|------|----------------| | createNewFabric(name) | POST | /v1/groups | CreateGroupRequest → CreateGroupResponse | | getGroups() | GET | /v1/groups | ListGroupsResponse | | initiateNodeAssociation() | POST | /v1/groups/{groupId}/node-assoc-requests | InitiateResponse | | verifyNodeAssociation(params) | POST | .../node-assoc-requests/{requestId}/verify | VerifyRequest (method 1) | | addNodeToMatterFabric(params) | POST | .../node-assoc-requests/{requestId}/verify | VerifyRequest (method 2) | | confirmUserNodeMapping(params) | POST | .../node-assoc-requests/{requestId}/confirm | optional capabilities | | issueUserNoC(request) | POST | /v1/groups/{groupId}/matter-nocs | MatterNOCRequest → MatterNOCResponse |

Comprehensive API documentation is available for all public classes, interfaces, and methods in the SDK.

Generate Documentation Locally

To generate the API documentation locally:

npm run genDocs

This will create a docs/ directory containing the generated HTML documentation. Open docs/index.html in your browser to view the documentation.

Documentation Features

• Complete API Reference: All public classes, methods, and interfaces are documented
• Type Information: Full TypeScript type definitions with examples
• Method Signatures: Parameter types, return types, and thrown errors
• Search Functionality: Search across all documented APIs
• Class Hierarchy: Visual representation of class relationships

The documentation is generated using TypeDoc from the JSDoc comments in the source code.

Troubleshooting

Common Issues

1. Matter Commissioning Failures

   • Ensure the device is in commissioning mode and discoverable
   • Verify the fabric is properly initialized with prepareFabricForMatterCommissioning
   • Check that the native Matter controller (iOS/Android) is properly configured

2. Local Transport Not Working

   • Verify the ESPRMNGMatterControlAdapterInterface is properly implemented in your native module
   • Ensure the Matter node ID and endpoint ID are correct
   • Check that the device is reachable on the local network

3. Subscription Updates Not Arriving

   • Ensure MQTT connection is established via the base SDK (for MQTT channel)
   • Verify the Matter subscription channel is properly initialized with matterSubscriptionAdapter
   • For Matter updates: ensure the native ESPRMNGMatterSubscriptionAdapter is implemented and pushes attribute updates via subscribeToDevice callback (not MQTT shadow topics)

Testing

Run unit tests:

npm test

Run tests with coverage:

npm run test:coverage

Linting & Formatting

Lint with ESLint:

npm run lint

Format code with Prettier:

npm run format

Contributing

We welcome contributions! Please see our contributing guidelines for more information.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Resources

• Changelog

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.