跳到主要内容

快速入门

@espressif/rainmaker-base-sdk 核心 SDK 基于 TypeScript，能帮助移动应用开发者高效集成 ESP RainMaker 生态系统，支持设备的顺畅配网、控制和管理。

NPM 包：@espressif/rainmaker-base-sdk

请按照以下步骤开始使用 SDK：

准备条件​

在开始之前，请确保已具备以下条件：

安装​

包管理器​

要从 npm 仓库安装最新版本的 @espressif/rainmaker-base-sdk 包，可以根据个人喜好选择包管理器：

使用 npm：​

npm install @espressif/rainmaker-base-sdk

使用 Yarn：​

yarn add @espressif/rainmaker-base-sdk

使用 pnpm：​

pnpm add @espressif/rainmaker-base-sdk

配置 ESPRMBase SDK​

  1. 定义配置对象：创建符合 ESPRMBaseConfig 接口的对象，指定必要的参数。

  2. 调用 configure 方法：使用 ESPRMBase 类的静态方法 configure 来初始化 SDK 配置。

注意：SDK 采用适配器模式。配网、本地发现、本地控制或通知功能需要与原生代码通信，可以通过适配器提供给 SDK。更多信息请参阅 适配器。

  1. 设置适配器：为存储、配网、本地发现、本地控制和通知提供自定义适配器实现。

以下是配置 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 = {
  // 基础配置
  baseUrl: "https://api.rainmaker.espressif.com",
  version: "v1",
  authUrl: "https://3pauth.rainmaker.espressif.com",
  clientId: "your-client-id", // 替换为实际客户端 ID
  redirectUrl: "rainmaker://com.espressif.novahome/success",

  // 适配器配置
  customStorageAdapter: asyncStorageAdapter, // 用于持久化存储
  provisionAdapter: provisionAdapter, // 用于设备配网
  localDiscoveryAdapter: EspLocalDiscoveryAdapter, // 用于本地设备发现
  localControlAdapter: ESPLocalControlAdapter, // 用于本地设备控制
  notificationAdapter: ESPNotificationAdapter, // 用于推送通知
  oauthAdapter: espOauthAdapter, // 用于 OAuth 身份验证
  appUtilityAdapter: ESPAppUtilityAdapter, // 用于应用工具函数
};

// 配置 ESPRMBase SDK
ESPRMBase.configure(config);

// 现在可以使用配置好的 SDK
说明

第三方登录配置：authUrl、clientId 和 redirectUrl 为可选字段，仅当应用启用第三方登录 (OAuth) 时才需要。如果不使用第三方身份验证，可以从 SDK 配置中跳过这些字段。

SDK 配置字段​

SDK 配置中可用的字段如下：

字段类型描述
baseUrl*字符串每个 API 端点的基础部分，按照 获取基础 URL 的步骤获取端点。
version字符串要使用的 API 版本，SDK 默认使用 v1 版本。
authUrl字符串可选，第三方登录 (OAuth) 的身份验证 URL，仅当启用第三方登录时才需要。
clientId字符串可选，第三方登录 (OAuth) 的客户端 ID，仅当启用第三方登录时才需要。
redirectUrl字符串可选，第三方登录 (OAuth) 的重定向 URL，仅当启用第三方登录时才需要。请参阅 Android 重定向 URI 设置 或 iOS 重定向 URL 设置 了解配置步骤。
customStorageAdapterESPRMStorageAdapterInterface必需，用于管理本地持久化数据存储的自定义存储适配器。
provisioningAdapterESPProvisionAdapterInterface可选，用于通过 BLE 或 SoftAP 配网 ESP 设备的适配器。
localDiscoveryAdapterESPLocalDiscoveryAdapterInterface可选，使用 mDNS 在本地网络上发现设备的适配器。
localControlAdapterESPLocalControlAdapterInterface可选，用于无需云端直接本地控制设备的适配器。
notificationAdapterESPNotificationAdapterInterface可选，用于处理来自平台的推送通知的适配器。
oauthAdapterESPOauthAdapterInterface可选，用于第三方身份验证 (OAuth) 流程的适配器。
appUtilityAdapterESPAppUtilityAdapterInterface可选，用于权限检查等平台特定工具函数的适配器。

后续步骤​

设置好 SDK 后，请按照以下步骤进行操作：

步骤 1：用户管理​

设置用户身份验证和账号管理：

步骤 2：设备管理​

开始管理设备：

步骤 3：群组管理​

将设备添加到群组中：

On this page