跳到主要内容

配网

要添加 RainMaker 设备，首先需要定位可发现的设备，然后提供必要的网络凭证，设备会自动与当前已登录的用户关联。

信息

要让以下方法生效，需要配网适配器。了解更多。

备注

后续文档中的 userInstance 指的是在用户登录步骤中获得的 ESPRMUser 类实例。

配网流程概览​

下图展示了完整的设备配网流程：

步骤 1：查找可用设备​

配网的第一步是发现并定位可进行配网的设备。

搜索可发现的设备​

使用传输类型和设备前缀来搜索可发现的设备。在 userInstance 上调用 searchESPDevices 方法，传入所需的 devicePrefix 和 transport type。

如果提供了配网适配器，该方法会返回可用设备列表。

try {
  const response = await userInstance.searchESPDevices(
    devicePrefix,
    ESPTransport.ble
  );
  console.log("RainMaker BLE devices fetched:", response);
} catch (error) {
  console.error("Error scanning RainMaker BLE devices:", error);
}
搜索 ESP 设备的参数​
参数类型说明
devicePrefix*字符串要搜索的设备前缀。
transport*ESPTransport用于搜索的传输类型。可选 ble 和 softap。

创建 ESPDevice 实例​

在从搜索结果中找到并选择设备之后，创建一个 ESPDevice 实例。该实例提供配网流程所需的全部设备相关方法。

可以在 iOS 和 Android 平台上使用 ESPProvision 适配器创建 RainMaker 设备。创建设备所需的信息可从 RainMaker 设备日志中的二维码获取。

使用 userInstance 的 createESPDevice 方法创建一个 ESP 设备：

try {
  const device = await userInstance.createESPDevice(
    name,
    transport,
    securityValue,
    pop
  );
  console.log("RainMaker device created:", device);
} catch (error) {
  console.error("Error in device creation:", error);
}
备注

要了解 ESPDevice 的全部方法和属性，请参阅 ESPDevice API 文档。

创建 ESP 设备的参数​
参数类型说明
name*字符串要创建的 ESP 设备名称。
transport*ESPTransport设备的传输类型。可选 ble 和 softap。
securityValueESPSecurity设备的安全类型。可选 unsecure、secure、secure2。
pop字符串在安全关联设备时需要的持有证明值。

步骤 2：与 ESP 设备建立连接​

创建好 ESPDevice 实例后，使用 BLE 或 SoftAP 传输与设备建立连接。该连接是配网过程中与设备通信所必需的。

连接到设备​

使用 connect 方法连接到设备：

try {
  const response = await device.connect();
  console.log("Connected to device", response);
} catch (error) {
  console.error("Error while connecting to device", error);
}

获取设备能力​

成功连接设备后，获取设备能力以检查是否需要设置 POP（持有证明）或用户名。

ESPDevice 实例的 getDeviceCapabilities 方法会返回一个包含设备能力的字符串数组。

try {
  const response = await device.getDeviceCapabilities();
  console.log("Device capabilities", response);
} catch (error) {
  console.error("Error fetching device capabilities", error);
}

设置持有证明（如需）​

当应用希望与设备建立安全连接进行数据通信时，需要执行此步骤。当设备的安全类型为 secure（1）或 secure2（2）时需要该方法。

try {
  const connectStatus = await device.setProofOfPossession(pop);
  console.log("Proof of Possession set successfully:", connectStatus);
} catch (error) {
  console.error("Error setting Proof of Possession:", error);
}

ESPDevice 实例的 setProofOfPossession 方法会返回一个布尔值，指示 POP 是否设置成功。

设置持有证明的参数​
参数类型说明
pop*字符串在安全关联设备时需要的 POP 值。

初始化会话​

与设备初始化安全会话。在继续配网之前需要完成此步骤。

try {
  const isSessionInitialized = await device.initializeSession();
  if (isSessionInitialized) {
    console.log("Session initialized successfully.");
  }
} catch (error) {
  console.error("Error initializing session:", error);
}

ESPDevice 实例的 initializeSession 方法会返回一个布尔值，指示会话是否初始化成功。

步骤 3：开始配网​

设备连接且会话初始化完成后，就可以进行配网。ESPDevice 实例可帮助获取 Wi‑Fi 列表，并使用网络凭证为设备配网。

获取可用 Wi‑Fi 网络​

获取所有可用的 Wi‑Fi 网络，以便在应用中进行展示。ESPDevice 实例的 scanWifiList 方法会返回一个 Wi‑Fi 网络数组。

try {
  const wifiList = await device.scanWifiList();
  console.log("Available Wi-Fi networks:", wifiList);
} catch (error) {
  console.error("Error fetching Wi-Fi networks:", error);
}

设备配网​

提供网络凭证，通过 ESPDevice 实例的 provision 方法为设备配网，并将其映射到已登录用户。

信息：支持 Group ID（SDK v2.0.3+）

从 SDK 版本 2.0.3 开始，SDK 在配网时支持可选的 groupId 参数。提供该参数后，配网成功时会将节点自动加入指定分组。此功能可在配网完成后立即简化将节点组织到分组中的流程。

重要：onProgress 回调

onProgress 回调是配网流程中的关键组件。该事件处理器会接收设备在配网期间发出的所有事件。必须实现此回调以：

  • 实时跟踪配网进度。
  • 处理成功与失败场景。
  • 根据配网状态更新 UI。
  • 侦测设备何时成功配网并映射到用户。

所有配网事件都会发送到该处理器，因此它对于监控整个配网流程至关重要。

// 在文件顶层导入
import {
  ESPProvProgressMessages,
  ESPProvResponseStatus,
} from "@espressif/rainmaker-base-sdk";

try {
  // 不带 group ID 的配网
  await device.provision(ssid, password, async (msg) => {
    // 在此处理所有配网事件
    console.log("Provisioning event:", msg.description, msg.status);

    // 表示设备已完成配网并添加到已登录用户账户
    if (
      msg.description === ESPProvProgressMessages.USER_NODE_MAPPING_SUCCEED &&
      msg.status === ESPProvResponseStatus.succeed
    ) {
      console.log("Node mapping succeeded. Fetching nodes...");
      // 设备现已配网并关联至用户
    }

    // 仅当用户设置了时区时适用（参见下方说明）
    if (
      msg.description === ESPProvProgressMessages.NODE_TIMEZONE_SETUP_SUCCEED &&
      msg.status === ESPProvResponseStatus.succeed
    ) {
      console.log("Timezone successfully set on the device.");
    }

    // 根据需要处理其他配网事件
    if (msg.status === ESPProvResponseStatus.failed) {
      console.error("Provisioning failed:", msg.description);
    }
  });

  // 或使用 group ID 进行配网，自动将节点加入群组
  await device.provision(
    ssid,
    password,
    async (msg) => {
      console.log("Provisioning event:", msg.description, msg.status);
      // ... 处理配网事件
    },
    groupId
  ); // 可选：配网后将节点添加到指定群组
} catch (error) {
  console.error("Error during provisioning:", error);
}
信息

如果用户已通过 userInstance 的 setTimeZone 方法设置了时区，配网流程会在用户节点映射成功后尝试将相同的时区设置到设备上。此功能仅适用于具备 esp.service.time 类型时间服务能力且包含 esp.param.tz 类型时区参数的设备。如果不满足这些条件，时区设置将被跳过。

备注

@espressif/rainmaker-base-sdk 包含常量 ESPProvProgressMessages 和 ESPProvResponseStatus。这两个常量分别包含 SDK 用于跟踪和上报配网流程状态的预定义配网进度消息与状态。

配网的参数​
参数类型说明
ssid*字符串要连接的 Wi‑Fi 网络 SSID。
password*字符串该 Wi‑Fi 网络的密码。
onProgress*(message: ESPProvResponse) => void必需的回调函数，用于处理全部配网事件并跟踪进度。
groupId字符串可选的 group ID，用于在配网成功后将已配网的节点自动加入指定分组。

On this page