Skip to main content

Provisioning

Add a new RainMaker device to the signed-in user's account by discovering it, connecting over BLE or SoftAP, and sending Wi-Fi credentials.

info

Default flow (SDK v2.3.0+): ESPDevice.provision() uses Challenge-Response Provisioning automatically. Pass ProvisionType.MQTT for the legacy MQTT association flow.

info

A provisioning adapter is required. See Getting Started and Adapters.

note

The userInstance refers to ESPRMUser from User Sign in.

What This Module Does ?​

Provisions an unconfigured device: discover nearby hardware, connect locally, send Wi-Fi credentials, and map the device to the signed-in user.

Use this when setting up a new device, re-provisioning onto another network, or adding a node to a group via optional groupId.

Before provisioning, unclaimed devices may need Assisted Claiming. White-label apps may use BLE Device Search to filter by customer ID.

Expected outcome: The device joins Wi-Fi, appears in getUserNodes(), and reports progress through the required onProgress callback.

Common Workflows​

Provision end-to-end​

import {
  ESPTransport,
  ESPProvProgressMessages,
  ESPProvResponseStatus,
} from "@espressif/rainmaker-base-sdk";

const { devices } = await userInstance.searchESPDevices("PROV_", ESPTransport.ble);
const device = await userInstance.createESPDevice(
  devices[0].name,
  ESPTransport.ble,
  devices[0].security,
  devices[0].pop
);

await device.connect();
if (device.security === "secure" || device.security === "secure2") {
  await device.setProofOfPossession(devices[0].pop);
} else {
  await device.initializeSession();
}

await device.provision(ssid, password, (msg) => {
  if (
    msg.description === ESPProvProgressMessages.USER_NODE_MAPPING_SUCCEED &&
    msg.status === ESPProvResponseStatus.succeed
  ) {
    console.log("Device provisioned and mapped to user");
  }
});

Discover and create a device​

const response = await userInstance.searchESPDevices(devicePrefix, ESPTransport.ble);
const device = await userInstance.createESPDevice(name, transport, securityValue, pop);

Devices can also be created from QR code data in RainMaker firmware logs.

Connect and secure the session​

await device.connect();

if (device.security === "secure" || device.security === "secure2") {
  await device.setProofOfPossession(pop);
} else {
  await device.initializeSession();
}

Scan Wi-Fi and provision​

const wifiList = await device.scanWifiList();

await device.provision(ssid, password, async (msg) => {
  if (msg.status === ESPProvResponseStatus.failed) {
    console.error("Provisioning failed:", msg.description);
  }
});

Provision into a group (SDK v2.0.3+)​

await device.provision(ssid, password, onProgress, groupId);

Handle provisioning progress​

await device.provision(ssid, password, async (msg) => {
  if (
    msg.description === ESPProvProgressMessages.USER_NODE_MAPPING_SUCCEED &&
    msg.status === ESPProvResponseStatus.succeed
  ) {
    await userInstance.getUserNodes(); // refresh device list
  }
});
info

If the user has a timezone set, the SDK may apply it after mapping when the device supports the time service.

Error Handling​

try {
  const response = await userInstance.searchESPDevices(prefix, ESPTransport.ble);
  if (!response.length) {
    console.warn("No devices found — ensure device is in provisioning mode");
    return;
  }
  await device.connect();
  await device.provision(ssid, password, onProgress);
} catch (error) {
  console.error("Provisioning error:", error);
}

Common failures: adapter not configured, POP mismatch, wrong Wi-Fi credentials, device not in provisioning mode.

Advanced Concepts​

Mental model​

Find device → connect → Wi-Fi credentials → node in user's account.

Full provisioning flow​

Claiming before provisioning​

Unclaimed devices may need Assisted Claiming. Check capabilities after connect().

Low-level APIs​

For manual challenge-response or MQTT steps, see Challenge-Response Provisioning and ESPDevice Reference.

Best Practices​

  1. Always implement onProgress — required for UI and success detection
  2. Stop BLE scan when done — stopESPDevicesSearch()
  3. Check device.security before POP vs session init
  4. Refresh node list after mapping succeeds
  5. Use customer ID search for white-label apps — BLE Device Search

On this page