Skip to main content

Provisioning

Provisioning is how an unconfigured device becomes a node in your ESP RainMaker Neo deployment: the app connects to it over BLE or SoftAP, proves the device belongs to the signed-in user, and hands it Wi-Fi credentials. ESPDevice is the class that represents a device during this window, before it has a node ID and before any group contains it.

Everything here needs a provisioning adaptor configured; without one, the first call throws ESPProvError with code MISSING_PROV_ADAPTER. See Adaptors.

The path through this page​

Two decisions shape the flow: whether the device needs assisted claiming first, and which group it joins — provision() requires a group ID, so decide before you call it.

Get an ESPDevice​

Two routes, both on the signed-in user. Search when you want to show the user a list:

import { ESPTransport, ESPSecurity } from "@espressif/rainmaker-neo-base-sdk";

const devices = await user.searchESPDevices("PROV_", ESPTransport.ble);

searchESPDevices(devicePrefix, transport) returns Promise<ESPDevice[]>, one per device whose advertised name starts with the prefix.

Create when you already know the device name, typically from a scanned QR code:

const device = await user.createESPDevice(
  "PROV_XXXXXX",
  ESPTransport.ble,
  ESPSecurity.secure2,
  "<proof-of-possession>",
);

createESPDevice(name, transport, security?, proofOfPossession?, softAPPassword?, username?) returns Promise<ESPDevice>. transport is ble or softap; security is unsecure, secure or secure2. Supply proofOfPossession for Security 1 and username for Security 2, and softAPPassword when joining a SoftAP network.

Connect and pick a network​

await device.connect();
const networks = await device.scanWifiList();

connect() resolves to a status code, 0 for success. scanWifiList() returns Promise<ESPWifiList[]>, each entry carries ssid, rssi, auth, and optionally bssid and channel. Present these to the user rather than asking them to type an SSID.

initializeSession() and setProofOfPossession() exist for flows that need to drive the handshake in steps; connect() covers the common case.

Provision​

One call runs the whole challenge-response flow:

const nodeId = await device.provision(
  "<ssid>",
  "<passphrase>",
  (progress) => console.log(progress.description),
  group.groupId,
);

await device.disconnect();

provision(ssid, passphrase, onProgress, groupId, provisionType?, options?) returns Promise<string>, the node ID the device reported. groupId is required: a node is always associated into a group, so decide which group before provisioning.

onProgress fires with an ESPProvResponse at each stage — status is onProgress until the final call, which is succeed, and description carries a human-readable message you can surface directly.

provisionType defaults to the challenge-response flow, which is the only flow this SDK implements.

What the five stages do​

The device proves ownership by signing a cloud-issued challenge, which is why the node ID comes from the device rather than being assigned by the app.

Association completes at stage 3, before the device has network credentials. A device that then fails to join Wi-Fi is already claimed by the user, so a retry re-runs stage 4 only; you do not re-associate.

Wait for the node to come online​

By default provision() resolves as soon as credentials are delivered; the device has not yet joined Wi-Fi or reached the cloud. Pass options to wait for it:

const nodeId = await device.provision(ssid, passphrase, onProgress, groupId, undefined, {
  waitForOnline: true,
  user,
  onlineTimeoutMs: 120_000,
});

waitForOnline requires user in the same object; the wait polls the node's shadow through that user's session, and passing waitForOnline without user throws. onlineTimeoutMs defaults to 120000, or two minutes.

The option types are not exported yet

ProvisionOptions is declared inside the SDK but not re-exported from the package root, so you cannot import it to type this object. Pass an inline object literal for now, and expect an import to become available in a later release.

Clean up​

await device.disconnect();

Call disconnect() whether provisioning succeeded or failed; the adaptor holds a native BLE or SoftAP handle that is not released otherwise.