跳到主要内容

ESPDevice Reference

Work with a single discoverable RainMaker device during discovery, connection, claiming, and provisioning.

信息

A provisioning adapter is required. See Adapters.

What This Module Does ?​

ESPDevice is your handle on one physical device during onboarding—before it becomes a node in the user's account.

Use this when connecting over BLE or SoftAP, running Assisted Claiming, executing Provisioning, or building a custom provisioning UI.

After provisioning, use Node Management and Device Control instead.

Expected outcome: A local session is established, provisioning or claiming completes, and the device appears as a node via getUserNodes().

Common Workflows​

Create, connect, and provision​

const device = await userInstance.createESPDevice(name, transport, security, pop);

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

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

Standard lifecycle steps​

  1. createESPDevice() — from discovery or QR data
  2. connect() — BLE/SoftAP session
  3. setProofOfPossession() or initializeSession()
  4. Optional startAssistedClaiming() if unclaimed
  5. scanWifiList() → provision() → disconnect()

Inspect device before provisioning​

await device.connect();
const caps = await device.getDeviceCapabilities();
const versionInfo = await device.getDeviceVersionInfo();

Use results to choose Assisted Claiming or Challenge-Response.

Error Handling​

try {
  await device.connect();
} catch (error) {
  console.error("Connection failed:", error);
}

try {
  await device.provision(ssid, password, onProgress);
} catch (error) {
  await device.disconnect();
  throw error;
}

Advanced Concepts​

Mental model​

ESPDevice is a temporary session object: connect locally, run claiming/provisioning, disconnect. After success, work with ESPRMNode.

Device properties​

Property / stateMeaning
device.connectedLocal session active
device.security"secure", "secure2", or "insecure" — POP vs session init
device.capabilitiesFeature strings (e.g. assisted claiming)
device.versionInfoFirmware version; flags like ch_resp
device.advertisementDataBLE data for BLE Device Search

Call connect() before other operations. Call disconnect() when done.

ESPDevice lifecycle​

Low-level endpoint communication​

sendData(endpoint, data) targets provisioning endpoints (ch_resp, rmaker_claim, cloud_user_assoc). Usually internal; use for custom UIs — see Challenge-Response Provisioning.

Custom provisioning UI​

Manual flow: initiateUserNodeMapping() → sendData("ch_resp", ...) → verifyUserNodeMapping() → setNetworkCredentials().

Best Practices​

  1. One ESPDevice per provisioning session
  2. Check device.security early
  3. Prefer provision() unless you need a custom UI
  4. Disconnect when done
  5. Switch to ESPRMNode after success

On this page