ESP Rainmaker Matter TypeScript SDK

The @espressif/rainmaker-matter-sdk package provides a comprehensive SDK for integrating Matter protocol support with the ESP Rainmaker ecosystem. It enables seamless Matter device commissioning, fabric management, and certificate handling for mobile app developers.

Table of Contents

• Overview
• Key Features
• Integration with Base SDK
• Requirements
• Installation
  • Package Manager
  • Local Installation
• Usage
  • Basic Configuration
  • Creating Matter Fabrics
  • Starting Matter Device Commissioning
  • Adding Matter Nodes (Manual Flow)
  • Managing User Certificates
  • Advanced Fabric Management
  • Converting Groups to Fabrics
• Resources
• License
• API Documentation

Overview

The @espressif/rainmaker-matter-sdk package extends the ESP Rainmaker ecosystem with full Matter protocol support. It provides a unified API for Matter fabric management, device commissioning, and certificate handling, enabling developers to build applications that seamlessly integrate both ESP Rainmaker cloud services and local Matter mesh networks.

The SDK provides:

• Matter Fabric Management: Create and manage Matter fabrics with full certificate authority capabilities
• Device Commissioning: Support for both pure Matter devices and RainMaker-enabled Matter devices
• Certificate Management: Issue and manage Node Operational Certificates (NoCs) and user certificates
• Cross-Platform Compatibility: Works with React Native and other cross-platform frameworks

Key Features

• [x] Matter Fabric Creation: Create and configure Matter fabrics with automatic certificate generation
• [x] Certificate Management: Issue NoCs for devices and user certificates for fabric access
• [x] Challenge-Response Authentication: Secure device authentication using cryptographic challenges
• [x] Paginated Responses: Efficient handling of large datasets with built-in pagination support

Integration with Base SDK

Matter local discovery uses the unified local discovery adapter from the base SDK. The base SDK's localDiscoveryAdapter supports discovering multiple service types concurrently, including _matter._tcp for Matter devices.

Requirements

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

• Node.js: Version 22.0.0 or higher is recommended
• Package Manager: Any one from npm, yarn, or pnpm installed
• ESP Rainmaker Base SDK: This package extends the base RainMaker SDK functionality

Installation

Package Manager

To install the latest version of the @espressif/rainmaker-matter-sdk package from the npm registry, you can use your preferred package manager:

Using npm:

npm install @espressif/rainmaker-matter-sdk

Using Yarn:

yarn add @espressif/rainmaker-matter-sdk

Using pnpm:

pnpm add @espressif/rainmaker-matter-sdk

Local Installation

To build and install the package locally for development and testing:

1. Clone the repository

2. Check out the appropriate branch:

   git checkout main

3. Ensure you are using Node.js v22.0.0 or higher. If you have nvm installed, you can run:

   nvm use

   If you don't have nvm, please install Node.js v22.0.0 or a higher version manually.

4. Install the required dependencies using your preferred package manager:

   npm install
   # or
   yarn install

5. Build the package:

   npm run build
   # or
   yarn run build

6. Create a tarball for testing locally:

   npm pack
   # or
   yarn pack

7. Add the tarball to your project:

   npm install <PATH_TO_PACK_TARBALL_FILE>
   # or
   yarn add <PATH_TO_PACK_TARBALL_FILE>

After installation, you can import and configure the SDK in your project as shown in the usage examples below.

Usage

Basic Configuration

Begin by configuring the base ESP Rainmaker SDK, authenticating the user, and wiring in your Matter adapter so the SDK can talk to native commissioning modules:

import { ESPRMBase, ESPRMMatterBase } from "@espressif/rainmaker-matter-sdk";
import { matterAdapter } from "./adapters/ESPMatterAdapter";

// Configure the base RainMaker SDK
ESPRMBase.configure({
  baseUrl: "https://api.rainmaker.espressif.com",
  version: "v1",
});

// Wire Matter SDK to the native adapter + vendor ID
ESPRMMatterBase.configure({
  matterAdapter,
  matterVendorId: 0x131b,
});

// Authenticate user via the base SDK
const authInstance = ESPRMBase.getAuthInstance();
const user = await authInstance.login("<USERNAME>", "<PASSWORD>");

Creating Matter Fabrics

Create a new Matter fabric to enable Matter device commissioning:

try {
  // Create a new Matter fabric
  const fabric = await user.createFabric({
    name: "My Smart Home Fabric",
    description: "Main fabric for smart home devices",
    type: "home",
  });

  // Get fabric details including certificates and keys
  const fabricDetails = await fabric.getFabricDetails();
} catch (error) {
  console.error("Failed to create fabric:", error.message);
}

Starting Matter Device Commissioning

Start the Matter device commissioning process using the high-level startCommissioning method:

try {
  // Prepare fabric for commissioning (ensures fabric details are loaded)
  const fabric = await user.prepareFabricForMatterCommissioning(
    await user.getFabricByName({ name: "My Smart Home Fabric" })
  );

  // Start commissioning with QR code or onboarding payload
  const cleanup = await fabric.startCommissioning(
    "<QR_CODE_OR_ONBOARDING_PAYLOAD>",
    (progress) => {
      console.log(`Commissioning: ${progress.description}`);
      // Handle progress updates (ON_PROGRESS, SUCCESS, FAILED)
    }
  );

  // Cleanup event listeners when done
  // cleanup();
} catch (error) {
  console.error("Commissioning failed:", error.message);
}

Adding Matter Nodes (Manual Flow)

For advanced use cases, you can manually handle the commissioning flow:

try {
  // Add a Matter node using a Certificate Signing Request (CSR)
  const commissioningRequest = await fabric.issueNodeNoC({
    csr: "<BASE64_ENCODED_CSR_FROM_DEVICE>",
    tags: ["device_type:light", "room:living_room"],
    metadata: {
      deviceName: "Smart Light",
      manufacturer: "Espressif",
      location: "Living Room",
    },
  });

  // Confirm commissioning for a RainMaker-enabled Matter device
  const confirmationResult =
    await commissioningRequest.confirmMatterNodeCommissioning({
      nodeType: "rainmaker_matter",
      status: "success",
      rainmakerNodeId: "<RAINMAKER_NODE_ID>",
      matterNodeId: "<MATTER_NODE_ID>",
      challengeResponse: "<SIGNED_CHALLENGE_RESPONSE>",
      metadata: {
        firmwareVersion: "1.0.0",
        deviceCapabilities: ["lighting", "dimming"],
      },
    });
} catch (error) {
  console.error("Device commissioning failed:", error.message);
}

Managing User Certificates

Issue user certificates for Matter fabric access (the CSR is generated automatically via the configured adapter):

try {
  // Issue a user certificate for fabric access
  const userCertResponse = await fabric.issueUserNoC();

  const userCert = userCertResponse.certificates?.[0];
  if (userCert) {
    const { userNoC, matterUserId, groupId } = userCert;
  }
} catch (error) {
  console.error("Certificate issuance failed:", error.message);
}

Advanced Fabric Management

Retrieve fabric information and manage subgroups:

try {
  // Get all fabrics for the user
  const fabricsResponse = await user.getGroupsAndFabrics({
    withFabricDetails: true,
    withNodeList: true,
  });

  // Get a specific fabric by name
  const fabricByName = await user.getFabricByName({
    name: "My Smart Home Fabric",
    withNodeList: true,
    withFabricDetails: true,
    withMatterNodeList: true,
  });

  // Get a specific fabric by ID (alternative to getFabricByName)
  const fabricById = await user.getFabricById({
    id: "<FABRIC_ID>",
    withFabricDetails: true,
    withNodeList: true,
  });

  // Prepare fabric for commissioning (ensures all details are loaded)
  const preparedFabric =
    await user.prepareFabricForMatterCommissioning(fabricByName);

  // Get Matter node mappings
  const nodeList = await preparedFabric.getRMMatterNodeList();
} catch (error) {
  console.error("Fabric management error:", error.message);
}

Converting Groups to Fabrics

Convert existing RainMaker groups to Matter fabrics:

try {
  // Get all groups and fabrics (response separates them into two arrays)
  const response = await user.getGroupsAndFabrics();

  // response.groups contains regular (non-Matter) groups
  // response.fabrics contains Matter-enabled fabrics

  // Find a regular group to convert (skip if already a Matter fabric)
  if (response.groups.length > 0) {
    const regularGroup = response.groups[0]; // Select any regular group

    // Convert the group to a Matter fabric
    const matterFabric = await regularGroup.convertToFabric();

    // Now you can use Matter features on this fabric
    const fabricDetails = await matterFabric.getFabricDetails();
  } else {
    console.log("No regular groups available to convert");
  }
} catch (error) {
  console.error("Conversion failed:", error.message);
}

Resources

• Changelog
• API Documentation
• Matter Protocol Specification
• ESP RainMaker Documentation

License

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