Getting Started

Install and configure @espressif/rainmaker-base-sdk so your app can call RainMaker APIs.

NPM Package: @espressif/rainmaker-base-sdk

What This Guide Covers ?

It covers installing the package, configuring ESPRMBase with your deployment URLs, and registering adapters so platform features (storage, BLE provisioning, notifications) work.

Use this first before User Management, Device Management, or Group Management.

Requires Node.js 20.17.0+ and a RainMaker API base URL — see Get Base URL.

Expected outcome: ESPRMBase.configure() completes successfully and you can obtain a logged-in ESPRMUser instance.

Common Workflows

Install the package using your favourite package manager

npm install @espressif/rainmaker-base-sdk

yarn add @espressif/rainmaker-base-sdk

pnpm add @espressif/rainmaker-base-sdk

Configure the SDK

import { ESPRMBase } from "@espressif/rainmaker-base-sdk";
import type { ESPRMBaseConfig } from "@espressif/rainmaker-base-sdk";

import asyncStorageAdapter from "./adapters/storage";
import { provisionAdapter } from "./adapters/provision";
// ... other adapters as needed

const config: ESPRMBaseConfig = {
  baseUrl: "https://api.rainmaker.espressif.com",
  version: "v1",

  // OAuth — only if third-party login is enabled
  authUrl: "https://3pauth.rainmaker.espressif.com",
  clientId: "your-client-id",
  redirectUrl: "rainmaker://your.app/success",

  customStorageAdapter: asyncStorageAdapter,
  provisionAdapter,
  // localDiscoveryAdapter, localControlAdapter, notificationAdapter, oauthAdapter, appUtilityAdapter
};

ESPRMBase.configure(config);

Implement adapters per Adapters. React Native examples: esp-rainmaker-home/adaptors.

Continue integration

Step	Guide
Sign in users	Authentication
Add a device	Provisioning
List and control devices	Node Management, Device Control
Organize devices	Group Management

Error Handling

try {
  ESPRMBase.configure(config);
} catch (error) {
  console.error("SDK configuration failed:", error);
}

Common issues:

• Missing storage adapter — customStorageAdapter is required
• Invalid baseUrl — confirm deployment URL from your RainMaker setup
• Provisioning fails at runtime — provisionAdapter not provided or native module not linked

Advanced Concepts

Configuration fields

Note: Fields marked with * are required for every app. Other once are optional by default—provide them when your app uses that feature (for example, provisionAdapter for device onboarding).

Field	Purpose
baseUrl*	RainMaker API host
version	API version (default v1)
authUrl, clientId, redirectUrl	Third-party login (OAuth)
customStorageAdapter*	Persistent storage
provisionAdapter	BLE/SoftAP onboarding
localDiscoveryAdapter	mDNS device discovery
localControlAdapter	Direct LAN control
notificationAdapter	Push notification bridge
oauthAdapter	Authorization code flow
appUtilityAdapter	Permission checks

For interface types, see ESPRMBaseConfig in TypeDoc.

note

OAuth redirect setup: Android · iOS

Adapter dependency map

Feature	Adapter
Sign-in / sessions	Storage (required)
Device provisioning	Provisioning
Local-first control	Discovery + Local control
Push node updates	Notification
Google/Apple login	OAuth

Best Practices

1. Configure before any SDK calls
2. Start with storage + auth, add provisioning when onboarding is ready
3. Keep secrets out of client bundles — use build-time env for clientId where possible
4. Match adapters to shipped features — omit unused adapters
5. Use the RainMaker Home App reference repo as a baseline for mobile apps

Related Resource

• RainMaker Home App
• API Reference:
  • ESPRMBase.configure()
  • ESPRMBaseConfig