Skip to main content

Assisted Claiming

Register an unclaimed RainMaker device with the cloud and install a device certificate before provisioning.

info

Requires a connected ESPDevice instance (BLE session via connect()).

What This Module Does ?​

Assisted claiming gives a device its cloud identity before Wi-Fi provisioning: the SDK talks to the device over BLE, calls RainMaker claiming APIs, and installs a certificate.

Use this when the device is unclaimed, advertises assisted-claiming, you need ClaimCapabilities.CAMERA_CLAIM for video devices, or provisioning requires a claimed device first.

Skip if the device is already claimed — go to Provisioning.

Claiming (certificates) is separate from provisioning (user mapping + Wi-Fi). See Claiming.

Expected outcome: Certificate installed; device ready for provision().

Common Workflows​

Standard claiming​

import { ClaimCapabilities } from "@espressif/rainmaker-base-sdk";

await device.connect();

await device.startAssistedClaiming((response) => {
  console.log(response.status, response.message);
  if (response.status === "succeeded") {
    console.log("Ready for provisioning");
  }
});

Camera / video devices​

await device.startAssistedClaiming(
  handleClaimProgress,
  ClaimCapabilities.CAMERA_CLAIM
);

Claiming then provisioning​

await device.connect();
await device.startAssistedClaiming(onClaimProgress);
await device.scanWifiList();
await device.provision(ssid, password, onProvisionProgress);

Error Handling​

CodeMeaning
CLAIM_START_FAILEDDevice did not accept claim start
CSR_RETRIEVAL_FAILEDCould not read CSR from device
CLAIM_API_FAILEDCloud initiate/verify failed
CLAIM_ABORTEDOperation aborted mid-flow
try {
  await device.startAssistedClaiming(onProgress);
} catch (error) {
  console.error("Claiming failed:", error.code, error.message);
}

Advanced Concepts​

Mental model​

Claim with cloud → then provision to user.

Claiming flow​

When to claim vs skip​

Check getDeviceCapabilities() after connect().

Best Practices​

  1. Connect before claiming
  2. Skip if already claimed
  3. Use progress callbacks for multi-step UI
  4. Claim before provision()
  5. Use CAMERA_CLAIM for video devices

On this page