@espressif/rainmaker-neo-matter-sdk
v1.0.1
Published
ESP RainMaker Neo Matter SDK for TypeScript/JavaScript applications – fabric management, Matter commissioning, and certificate handling built on top of the RainMaker Neo base SDK.
Keywords
Readme
ESP RainMaker Neo - Matter TypeScript SDK
Tools
Documentation
Introduction
ESP RainMaker Neo is a serverless, open-source IoT cloud for ESP devices that you deploy into your own AWS account. It scales with your fleet and is pay-as-you-go. Devices connect over MQTT through AWS IoT. Phone apps, the admin dashboard and voice assistants reach the same backend over REST APIs and MQTT.
Repositories
| Repository | Holds | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | esp-rainmaker-neo | Cloud backend, admin dashboard | | esp-rainmaker-neo-firmware | Device firmware SDK | | esp-rainmaker-homeesp-rainmaker-neo-app-sdk-tsesp-rainmaker-neo-matter-app-sdk-ts | ESP RainMaker Home phone app (iOS and Android)ESP RainMaker Neo App SDK (TypeScript)(this repository) ESP RainMaker Neo Matter App SDK (TypeScript) |
Get Started
@espressif/rainmaker-neo-matter-sdk extends the ESP RainMaker Neo base SDK with Matter support — fabric management, commissioning and certificate (NOC) issuance, local control over the Matter transport, and real-time attribute subscriptions. It re-exports the whole base SDK, so one import covers auth, groups, MQTT and Matter.
Table of Contents
Key Features
- [x] Fabric Management: Create, retrieve, and manage Matter fabrics with support for multi-fabric architectures
- [x] Matter Commissioning: End-to-end flow — node association, device and user NOC issuance, and user-node mapping confirmation
- [x] Local Matter Transport: Control devices over Matter through a pluggable native control adapter for iOS and Android
- [x] Subscription Channel: Native Matter attribute updates transformed into base-SDK device updates
- [x] Derived Node Configs: Optionally raise RainMaker-shaped configs for pure Matter nodes via the bundled attribute↔param mapping runtime
- [x] Base SDK Re-export: Auth, user, group, device and MQTT APIs available through a single import
- [x] Type Safety: Full TypeScript definitions for Matter-specific data models
Requirements
- Node.js 20+ (development uses 22, see
.nvmrc) - TypeScript 5+ (recommended)
- React Native 0.72+ with a native Matter controller: iOS 16.4+ or Android API 27+ with Google Play Services for Matter
The SDK does not bundle native Matter libraries. Your app supplies them through the commissioning, control and subscription adapter interfaces.
Installation
npm install @espressif/rainmaker-neo-matter-sdk
# or
yarn add @espressif/rainmaker-neo-matter-sdk
# or
pnpm add @espressif/rainmaker-neo-matter-sdk@espressif/rainmaker-neo-base-sdk is pulled in as a dependency.
Local development
npm install
npm run build
npm pack
# in your app:
npm install <PATH_TO_PACK_TARBALL_FILE>Quick Start
import { ESPRMNeoMatterBase } from "@espressif/rainmaker-neo-matter-sdk";
import type { ESPRMNeoMatterBaseConfig } from "@espressif/rainmaker-neo-matter-sdk";
const config: ESPRMNeoMatterBaseConfig = {
// Base SDK
baseUrl: "https://your-api-gateway.amazonaws.com/prod",
userApiBase: "https://your-user-api-gateway.amazonaws.com/prod",
awsRegion: "us-east-1",
iotEndpoint: "xxxxxxxx-ats.iot.us-east-1.amazonaws.com",
// Optional base adapters (provided by your app):
// mqttAdapter, customStorageAdapter, provisionAdapter, ...
// Matter
matterVendorId: "0x131B",
matterCommissioningAdaptor: yourMatterCommissioningAdaptor,
matterControlAdapter: yourMatterControlAdapter,
matterSubscriptionAdapter: yourMatterSubscriptionAdapter,
// Optional: write RainMaker-shaped ("derived") configs for pure Matter nodes
// and let the SDK report a derived node's params into its shadow.
derivedNodeConfig: true,
shadowReporter: (nodeId, shadowName, params) =>
yourMqtt.publish(
`$aws/things/${nodeId}/shadow/name/${shadowName}/update`,
JSON.stringify({ state: { reported: { params } } })
),
};
// configure() initializes the Matter layer and the base SDK together
ESPRMNeoMatterBase.configure(config);
// Register the Matter subscription channel with the base subscription manager
await ESPRMNeoMatterBase.initializeMatterSubscription();Examples
Manage fabrics
import {
ESPRMNeoBase,
ESPRMNeoFabric,
} from "@espressif/rainmaker-neo-matter-sdk";
const auth = ESPRMNeoBase.getAuthInstance();
const user = await auth.login("[email protected]", "password");
// Create a fabric
const fabric = await user.createNewFabric("Living Room Fabric");
// Look one up by group id or name (undefined when not found)
const byId = await user.getFabricById("your-group-id");
const byName = await user.getFabricByName("Living Room Fabric");
// Matter-capable groups come back as ESPRMNeoFabric instances
const groups = await user.getGroups();
const fabrics = groups.filter((g) => g instanceof ESPRMNeoFabric);
// Or construct one directly when the groupId is already known
const direct = new ESPRMNeoFabric({ groupId: "group-id", groupName: "" });Commission a pure Matter device
import { buildMatterNodeConfigPayload } from "@espressif/rainmaker-neo-matter-sdk";
const { request_id } = await fabric.initiateNodeAssociation();
// Device NOC from the device's CSR (NOCSRElements + attestation)
const verified = await fabric.addNodeToMatterFabric({
requestId: request_id,
nocsrElements: nocsrElementsHex,
attestationChallenge: attestationChallengeHex,
attestationSignature: attestationSignatureHex,
});
console.log("Matter node ID:", verified.matter_node_id);
// Finalize the user-node mapping and tag the node as pure Matter
await fabric.confirmUserNodeMappingWithRetry({
requestId: request_id,
capabilities: ["matter"],
});
// Store the endpoint/cluster topology so the node can be rebuilt for display
await fabric.setNodeConfig(
verified.node_id,
buildMatterNodeConfigPayload(matterMetadata)
);Add a RainMaker device to a Matter group
// No NOC is issued — the device proves itself with a signed challenge
const { request_id } = await fabric.initiateNodeAssociation();
await fabric.verifyNodeAssociation({
requestId: request_id,
challengeResponse: signedChallengeHex,
nodeId: "MySmartLight01",
});Join a fabric as a user
// Controller NOC for this phone/user, from a CSR generated natively
const userNoc = await fabric.issueUserNoC({ csr: csrPem });
console.log("Matter user ID:", userNoc.matter_user_id);Control a Matter node
import { ESPRMNeoMatterNode } from "@espressif/rainmaker-neo-matter-sdk";
// Pure Matter nodes come back as ESPRMNeoMatterNode with devices/params
// compiled from the cluster registry (or from a derived config).
const nodes = await fabric.getNodesWithDetails();
const matterNode = nodes.find(
(n) => n instanceof ESPRMNeoMatterNode && n.isMatter
) as ESPRMNeoMatterNode;
// setValue rides the matter_local transport through your control adapter
const power = matterNode.devices[0]?.params.find((p) => p.id === "Power");
await power?.setValue(true);Receive real-time updates
import {
ESPRMNeoBase,
ESPRMNeoMatterBase,
} from "@espressif/rainmaker-neo-matter-sdk";
// After configure()
await ESPRMNeoMatterBase.initializeMatterSubscription();
// The Matter channel is now one of the base subscription manager's channels.
// Native attribute reports arrive through your matterSubscriptionAdapter and
// are dispatched as {deviceId: {paramId: value}} updates like any other channel.
const channels = ESPRMNeoBase.subscriptionManager.getRegisteredChannels();
console.log("Registered channels:", channels);API Documentation
Browse the hosted API reference at https://espressif.github.io/esp-rainmaker-neo-matter-app-sdk-ts/.
To generate local docs from JSDoc:
npm run genDocsOpen docs/index.html in a browser. Docs are generated with TypeDoc.
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit and push your changes
- Open a Pull Request
See Changelog for release notes.
License
Apache 2.0 — see LICENSE.
