Skip to main content

Getting Started

The @espressif/rainmaker-base-sdk package, developed in TypeScript, offers a core SDK that assists mobile app developers in efficiently integrating with the ESP Rainmaker ecosystem. It facilitates smooth provisioning, control, and management of devices.

NPM Package: @espressif/rainmaker-base-sdk

To start using the SDK, follow these steps:

Prerequisites​

Before diving in, ensure you have the following:

Installation​

Package Manager​

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

With npm:​

npm install @espressif/rainmaker-base-sdk

With Yarn:​

yarn add @espressif/rainmaker-base-sdk

With pnpm:​

pnpm add @espressif/rainmaker-base-sdk

Configuring the ESPRMBase SDK​

  1. Define the Configuration Object: Create an object that adheres to the ESPRMBaseConfig interface, specifying the necessary parameters.

  2. Call the configure Method: Use the static configure method of the ESPRMBase class to initialize the SDK with your configuration.

Note: The SDK follows an adapter approach. For any of the provisioning, local discovery, local control, or notifications to work, they require communication with native code that can be provided through an adapter to the SDK. Learn more about implementing adapters.

  1. Set Adapters: Provide the custom implementations of adapters for storage, provisioning, local discovery, local control, and notifications.

Here's an example of how to configure the ESPRMBase:

import { ESPRMBase } from "@espressif/rainmaker-base-sdk";
import { CustomStorageAdapter } from "./path/to/CustomStorageAdapter";
import { CustomProvisionAdapter } from "./path/to/CustomProvisionAdapter";

/*
 * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */

import asyncStorageAdapter from "@/adaptors/implementations/ESPAsyncStorage";
import { provisionAdapter } from "@/adaptors/implementations/ESPProvAdapter";
import { EspLocalDiscoveryAdapter } from "@/adaptors/implementations/ESPDiscoveryAdapter";
import ESPLocalControlAdapter from "@/adaptors/implementations/ESPLocalControlAdapter";
import { ESPNotificationAdapter } from "@/adaptors/implementations/ESPNotificationAdapter";
import { espOauthAdapter } from "@/adaptors/implementations/ESPOauthAdapter";
import ESPAppUtilityAdapter from "@/adaptors/implementations/ESPAppUtilityAdapter";

const config: ESPRMBaseConfig = {
  // Base configuration
  baseUrl: "https://api.rainmaker.espressif.com",
  version: "v1",
  authUrl: "https://3pauth.rainmaker.espressif.com",
  clientId: "your-client-id", // Replace with your actual client ID
  redirectUrl: "rainmaker://com.espressif.novahome/success",

  // Adapters configuration
  customStorageAdapter: asyncStorageAdapter, // For persistent storage
  provisionAdapter: provisionAdapter, // For device provisioning
  localDiscoveryAdapter: EspLocalDiscoveryAdapter, // For local device discovery
  localControlAdapter: ESPLocalControlAdapter, // For local device control
  notificationAdapter: ESPNotificationAdapter, // For push notifications
  oauthAdapter: espOauthAdapter, // For OAuth authentication
  appUtilityAdapter: ESPAppUtilityAdapter, // For app utility functions
};

// Configure the ESPRMBase SDK
ESPRMBase.configure(config);

// Now you can use the SDK with the configured settings
note

Third-Party Login Configuration: The configuration fields authUrl, clientId, and redirectUrl are optional and only required if third-party login (OAuth) is enabled in your application. If you're not using third-party authentication, these fields can be omitted from the SDK configuration.

SDK Configuration Fields​

The following fields are available in the SDK configuration:

FieldTypeDescription
baseUrl*stringConsistent part of each API endpoint. Follow Get Base Url steps to fetch the endpoint.
versionstringThe version of the API to use. By default version v1 is used by the SDK.
authUrlstringOptional. The authentication URL for third-party login (OAuth). Only required if third-party login is enabled.
clientIdstringOptional. The client ID for third-party login (OAuth). Only required if third-party login is enabled.
redirectUrlstringOptional. The redirect URL for third-party login (OAuth). Only required if third-party login is enabled. See Android Redirect URI Setup or iOS Redirect URL Setup for configuration steps.
customStorageAdapterESPRMStorageAdapterInterfaceRequired. A custom storage adapter for managing persistent local data storage.
provisioningAdapterESPProvisionAdapterInterfaceOptional. An adapter to enable provisioning of ESP devices via BLE or SoftAP.
localDiscoveryAdapterESPLocalDiscoveryAdapterInterfaceOptional. An adapter for discovering devices on the local network using mDNS.
localControlAdapterESPLocalControlAdapterInterfaceOptional. An adapter for direct local control of devices without cloud.
notificationAdapterESPNotificationAdapterInterfaceOptional. An adapter for handling push notifications from the platform.
oauthAdapterESPOauthAdapterInterfaceOptional. An adapter for third-party authentication (OAuth) flows.
appUtilityAdapterESPAppUtilityAdapterInterfaceOptional. An adapter for platform-specific utility functions like permission checks.

Next Steps​

After setting up the SDK, follow these steps to get started:

Step 1: User Management​

Set up user authentication and account management:

Step 2: Device Management​

Start managing your devices:

Step 3: Group Management​

Organize devices into groups:

On this page