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 18.0 or higher
• 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-typescript2, @rollup/plugin-*, typescript
• Tests: jest, ts-jest, jest-junit, dotenv
• Lint/Format: 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

const commissionDevice = async (fabric: ESPRMNGFabric) => {
  try {
    // Option A: Full attestation-based flow (preferred)
    const response = await fabric.addNodeToMatterFabric({
      requestId: "your-request-id",
      nocsrElements: nocsrElementsBase64,
      attestationChallenge: challengeBase64,
      attestationSignature: signatureBase64,
    });
    console.log("NOC issued:", response.noc, "Matter Node ID:", response.matter_node_id);

    // Option B: Legacy CSR-only flow
    const nocResponse = await fabric.issueUserNoC(csrBase64);
    console.log("NOC issued:", nocResponse.noc);

    // Confirm the user-node mapping after commissioning
    const confirmResponse = await fabric.confirmUserNodeMapping({
      requestId: "your-request-id",
    });
    console.log("Commissioning confirmed");
  } catch (error) {
    console.error("Commissioning failed:", error);
  }
};

Matter Node Control

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

const controlMatterDevice = async (matterNodeId: string) => {
  // Access the native control adapter (set during configure)
  const controlAdapter = ESPRMNGMatterBase.ESPRMNGMatterControlAdapter;
  if (!controlAdapter) {
    console.error("Matter control adapter not configured");
    return;
  }

  // Create a local transport for a Matter node and endpoint ID (default 1)
  const transport = new ESPRMNGMatterLocalTransport(matterNodeId, 1);
  // Use setDeviceParam/getDeviceParams for RMNG-style param operations

  // Build a node payload from RMNG node or shadow data (identifier and groupId required)
  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
├── ESPRMNGFabric.ts
├── ESPRMNGMatterBase.ts
├── ESPRMNGMatterNode.ts
├── index.ts
├── methods
│   ├── ESPRMNGFabric (AddNodeToMatterFabric, ConfirmUserNodeMapping, GetCSRNonce, IssueUserNoC)
│   ├── ESPRMNGMatterNode (buildESPRMNGMatterNode, getConnectivityFromShadow, hasCluster, etc.)
│   └── ESPRMNGUser (CreateNewFabric, GetFabricById, GetFabricByName, GetGroupsAndFabrics, PrepareFabricForMatterCommissioning)
├── services
│   ├── ESPRMNGMatterSubscriptionChannel (MatterSubscriptionChannel)
│   └── ESPRMNGMatterTransport (ESPRMNGMatterControlAdapterInterface, ESPRMNGMatterLocalTransport)
├── types (input, output, matter, subscription, ESPRMNGMatterNode)
└── utils (constants, error, helpers)

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
│   ├── setMatterAdapter() / requireMatterAdapter() / getMatterSubscriptionChannel()
│   ├── ESPRMNGMatterAdapter            — Native Matter adapter (commissioning)
│   ├── ESPRMNGMatterControlAdapter    — Native Matter control adapter (read/write)
│   └── getFabricIdForNode()            — Resolves fabric for a node
│
├── ESPRMNGFabric (extends ESPRMNGGroup)
│   ├── addNodeToMatterFabric()        — Attestation-based NOC issuance
│   ├── issueUserNoC()                 — Legacy CSR-based NOC issuance
│   ├── confirmUserNodeMapping()       — Confirms commissioning
│   └── getCSRNonce()                  — Generates CSR nonce
│
├── ESPRMNGMatterNode
│   ├── hasCluster() / getEndpointWithCluster()
│   ├── getServerClusters() / getClientClusters()
│   └── setMatterNodeId()
│
├── ESPRMNGMatterLocalTransport (matterNodeId, endpoint?)
│   └── setDeviceParam() / getDeviceParams() — Uses ESPRMNGMatterControlAdapterInterface (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 setMatterAdapter(), requireMatterAdapter(), 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().
• ESPRMNGMatterLocalTransport: Implements ESPTransportInterface — constructor (matterNodeId, endpoint?) where endpoint defaults to 1. Delegates to ESPRMNGMatterControlAdapterInterface via setDeviceParam() and getDeviceParams() for direct Matter device communication.
• 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)
• ESPRMNGMatterAdapterInterface: 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

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

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
• README Validation Report

License

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