ESP RainMaker Neo TypeScript SDK

RainMaker Neo (short: RMNeo) is Espressif’s AIoT stack. @espressif/rainmaker-neo-base-sdk is the TypeScript SDK that powers JavaScript-based apps integrating with RainMaker Neo — authentication, groups/nodes, device provisioning, real-time MQTT control, and group sharing.

Table of Contents

• Key Features
• Requirements
• Installation
  • Local development
• Quick Start
• Examples
  • Login and user info
  • Connect MQTT and control a node
  • Group-wide control
  • Create groups and share
  • Accept a sharing request
  • Provision a device
• API Documentation
• Contributing
• License

Key Features

• [x] AWS Cognito Authentication: Secure user authentication with automatic session management and token refresh
• [x] MQTT Real-time Communication: Direct AWS IoT Core integration with automatic credential provisioning
• [x] Device Provisioning: Complete device setup workflow with WiFi provisioning and cloud binding
• [x] Type Safety: Full TypeScript support with comprehensive type definitions
• [x] Modular Design: Clean architecture with separate modules for authentication, device management, and communication
• [x] Automatic Storage: Seamless data persistence via app-supplied storage adapters
• [x] Error Handling: Comprehensive error handling with detailed logging

Requirements

• Node.js 18+
• TypeScript 5+ (recommended)

Installation

npm install @espressif/rainmaker-neo-base-sdk
# or
yarn add @espressif/rainmaker-neo-base-sdk
# or
pnpm add @espressif/rainmaker-neo-base-sdk

Local development

npm install
npm run build
npm pack
# in your app:
npm install <PATH_TO_PACK_TARBALL_FILE>

Quick Start

import { ESPRMNeoBase } from "@espressif/rainmaker-neo-base-sdk";

ESPRMNeoBase.init({
  baseUrl: "https://your-api-gateway.amazonaws.com/prod",
  userApiBase: "https://your-user-api-gateway.amazonaws.com/prod",
  identityId: "your-identity-pool-id",
  awsRegion: "us-east-1",
  userPoolId: "your-user-pool-id",
  clientId: "your-cognito-client-id",
  iotEndpoint: "xxxxxxxx-ats.iot.us-east-1.amazonaws.com",
  // Optional adapters (provided by your app):
  // mqttAdapter, customStorageAdapter, provisionAdapter, ...
});

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

await user.getTemporaryAWSCredentials();
const connected = await user.connectMQTT();

Examples

Login and user info

import { ESPRMNeoBase } from "@espressif/rainmaker-neo-base-sdk";

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

const info = await user.getUserInfo();
console.log(info);

Connect MQTT and control a node

await user.getTemporaryAWSCredentials();
await user.connectMQTT();

const groups = await user.getGroups();
const home = groups[0];
const node = await home.getNode("your-node-id");

// Device params
const light = node.devices.find((d) => d.name === "Light");
const power = light?.params.find((p) => p.id === "Power");
const brightness = light?.params.find((p) => p.id === "Brightness");

await power?.setValue(true);
await brightness?.setValue(80);

// Service params (e.g. Time)
const time = node.services.find((s) => s.name === "Time");
const tz = time?.params.find((p) => p.id === "TZ");
await tz?.setValue("Asia/Shanghai");

Group-wide control

// Broadcasts the same command to every node in the group
await home.setParams({
  Light: {
    Power: false,
  },
});

Create groups and share

// High-level group: location / site / home
const home = await user.createGroup("Home");

// Rooms as subgroups under the home
const livingRoom = await home.createSubGroup("Living Room");
const bedroom = await home.createSubGroup("Bedroom");

// Share the home (or a room subgroup) with another user
await home.share({
  userCode: "ABCD1234",
  accessType: "secondary",
});

Accept a sharing request

const requests = await user.listSharingRequests();

for (const request of requests) {
  await request.accept();
}

Provision a device

import { ESPDevice } from "@espressif/rainmaker-neo-base-sdk";

const device = new ESPDevice({
  name: "PROV_XXXXXX",
  transport: "ble",
  security: 1,
});

await device.connect();

const networks = await device.scanWifiList();
console.log(networks);

const nodeId = await device.provision(
  "HomeWiFi",
  "wifi-password",
  (progress) => console.log(progress.description),
  livingRoom.groupId // associate with a room subgroup
);

console.log("Provisioned node:", nodeId);
await device.disconnect();

API Documentation

Generate local docs from JSDoc:

npm run genDocs

Open docs/index.html in a browser. Docs are generated with TypeDoc.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit and push your changes
4. Open a Pull Request

See Changelog for release notes.

License

Apache 2.0 — see LICENSE.