Provisioning

To add a RainMaker device, you must first locate the discoverable devices and then supply the necessary network credentials, which will automatically associate the device with the currently logged-in user.

信息

Provisioning adapter is required for below methods to work. Learn More.

备注

The userInstance used in further docs refers to ESPRMUser class instance obtained in User Sign in step.

Provisioning Flow Overview

The following diagram illustrates the complete device provisioning flow:

Step 1: Find Available Devices

The first step in provisioning is to discover and locate devices that are available for provisioning.

Search for Discoverable Devices

Search for discoverable devices using transport type and device prefix. Call the searchESPDevices method on the userInstance, passing in the desired devicePrefix and the transport type.

If a provisioning adapter is provided, this method returns a list of available devices.

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);
}

Search ESP Devices Parameters

Parameter	Type	Description
devicePrefix*	string	The prefix of the device to search for.
transport*	ESPTransport	The transport type to use for the search. Options include `ble` and `softap`.

Create ESPDevice Instance

After finding and selecting a device from the search results, create an ESPDevice instance. This instance provides access to all device-specific methods needed for the provisioning process.

RainMaker devices can be created using the ESPProvision adaptor on both iOS and Android platforms. The necessary information for device creation can be obtained from the QR code found in the logs of the RainMaker device.

Create an ESP device using the userInstance createESPDevice method:

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);
}

备注

To know all the methods and properties of ESPDevice, refer to the ESPDevice API documentation.

Create ESP Device Parameters

Parameter	Type	Description
name*	string	The name of the ESP device to be created.
transport*	ESPTransport	The transport type for the device. Options include `ble` and `softap`.
securityValue	ESPSecurity	The security type for the device. Options include `unsecure`, `secure`, and `secure2`.
pop	string	The Proof of Possession value required for secure device association.

Step 2: Establish Connection with ESP Device

Once you have created the ESPDevice instance, establish a connection to the device using either BLE or SoftAP transport. This connection is necessary to communicate with the device during the provisioning process.

Connect to Device

Connect to the device using the connect method:

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

Get Device Capabilities

After successfully connecting to the device, fetch its capabilities to check if POP (Proof of Possession) or username is required to set.

The getDeviceCapabilities method of ESPDevice instance returns an array of strings with device capabilities.

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

Set Proof of Possession (If Required)

This step is required when the app wants to connect securely to the device for data communication. The method is required when the security type of the device is either secure (1) or 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);
}

The setProofOfPossession method of ESPDevice instance returns a boolean indicating whether the proof of possession was successfully set.

Set Proof of Possession Parameters

Parameter	Type	Description
pop*	string	The Proof of Possession value required for secure device association.

Initialize Session

Initialize a secure session with the device. This step is required before you can proceed with provisioning.

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

The initializeSession method of ESPDevice instance returns a boolean indicating whether the session was successfully initialized.

Step 3: Start Provisioning

Once the device is connected and the session is initialized, you can proceed with provisioning. The ESPDevice instance helps you get the Wi-Fi list and provision the device with network credentials.

Fetch Available Wi-Fi Networks

Get all available Wi-Fi networks to list them in your application. The scanWifiList method of ESPDevice instance returns an array of Wi-Fi networks.

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

Provision Device

Provide network credentials to provision the device and map it to the logged-in user using the provision method of the ESPDevice instance.

Info: Group ID Support (SDK v2.0.3+)

Starting from SDK version 2.0.3, the SDK supports an optional groupId parameter during provisioning. When provided, the node will be automatically added to the specified group after successful provisioning. This feature simplifies the workflow of organizing nodes into groups immediately upon provisioning.

Important: onProgress Callback

The onProgress callback is a critical component of the provisioning process. This event handler receives all events emitted from the device during provisioning. You must implement this callback to:

Track the provisioning progress in real-time
Handle success and failure scenarios
Update your UI based on provisioning status
Detect when the device is successfully provisioned and mapped to the user

All provisioning events are emitted to this handler, making it essential for monitoring the entire provisioning flow.

// Import at top level of file
import {
  ESPProvProgressMessages,
  ESPProvResponseStatus,
} from "@espressif/rainmaker-base-sdk";

try {
  // Provision without group ID
  await device.provision(ssid, password, async (msg) => {
    // Handle all provisioning events here
    console.log("Provisioning event:", msg.description, msg.status);

    // Represents device is provisioned and added to logged-in user account.
    if (
      msg.description === ESPProvProgressMessages.USER_NODE_MAPPING_SUCCEED &&
      msg.status === ESPProvResponseStatus.succeed
    ) {
      console.log("Node mapping succeeded. Fetching nodes...");
      // Device is now provisioned and mapped to user
    }

    // Only applicable if user has set timezone (see info below)
    if (
      msg.description === ESPProvProgressMessages.NODE_TIMEZONE_SETUP_SUCCEED &&
      msg.status === ESPProvResponseStatus.succeed
    ) {
      console.log("Timezone successfully set on the device.");
    }

    // Handle other provisioning events as needed
    if (msg.status === ESPProvResponseStatus.failed) {
      console.error("Provisioning failed:", msg.description);
    }
  });

  // OR provision with group ID to automatically add node to a group
  await device.provision(
    ssid,
    password,
    async (msg) => {
      console.log("Provisioning event:", msg.description, msg.status);
      // ... handle provisioning events
    },
    groupId
  ); // Optional: Add node to specified group after provisioning
} catch (error) {
  console.error("Error during provisioning:", error);
}

信息

If the user has set a timezone using the setTimeZone method of the userInstance, the provisioning flow will attempt to set the same timezone to the device after the user node mapping succeeds. This is applicable only if the device has time service capabilities of type esp.service.time and includes a timezone parameter of type esp.param.tz. If these conditions are not met, the timezone setting will be skipped.

备注

The ESPProvProgressMessages and ESPProvResponseStatus constants are part of the @espressif/rainmaker-base-sdk package. They contain predefined provision progress messages and status used by the SDK to track and report the status of the provisioning process respectively.

Provision Parameters

Parameter	Type	Description
ssid*	string	The SSID of the Wi-Fi network to which the device will be connected.
password*	string	The password for the Wi-Fi network.
onProgress*	(message: ESPProvResponse) => void	Required callback function to handle all provisioning events and track progress.
groupId	string	Optional group ID to automatically add the provisioned node to a specific group after successful provisioning.

Provisioning Flow Overview​

Step 1: Find Available Devices​

Search for Discoverable Devices​

Search ESP Devices Parameters​

Create ESPDevice Instance​

Create ESP Device Parameters​

Step 2: Establish Connection with ESP Device​

Connect to Device​

Get Device Capabilities​

Set Proof of Possession (If Required)​

Set Proof of Possession Parameters​

Initialize Session​

Step 3: Start Provisioning​

Fetch Available Wi-Fi Networks​

Provision Device​

Provision Parameters​