Skip to main content

Assisted claiming

Assisted claiming gives a device its cloud certificate through the app instead of at the factory. The device generates a certificate signing request, the app carries it to your ESP RainMaker Neo deployment's claiming service, and the signed certificate goes back to the device, after which the device can connect to the cloud on its own.

Use it for devices that ship without pre-provisioned certificates. A device that was claimed in the factory needs none of this; go straight to Provisioning.

Claim a device​

Claiming runs on a connected ESPDevice, before provisioning:

await device.connect();

await device.startAssistedClaiming((progress) => {
  console.log(progress.status, progress.message);
});

const nodeId = await device.provision(ssid, passphrase, onProgress, group.groupId);

startAssistedClaiming(onProgress?, claimCapability?) returns Promise<void>. It resolves when the device has accepted its certificate; the node ID comes later, from provision().

Both arguments are optional. onProgress receives an ESPClaimResponse carrying three fields: a status from ESPClaimStatus (inProgress, success, failed or aborted), a message, and an error string when something went wrong.

What the six steps do​

The app never holds a private key; the device generates the request and keeps the key, and the app only carries bytes between the device and the claiming service.

Step 2 is idempotent per device and caller, so a retry after a mid-flow failure does not consume another node ID.

The device's payloads are forwarded whole rather than field-by-field, because firmware sends its own request flags alongside the MAC and the CSR. The SDK tolerates several spellings for both; a MAC may arrive as mac_addr, mac or a few variants, and a CSR either wrapped in JSON or as a bare certificate block.

Capabilities​

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

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

A capability tells the claiming service the device needs more than the default IoT permissions. CAMERA_CLAIM is the only value currently defined, for devices that stream video.

Capability policies are deployment decisions

The SDK ships no extra IoT policies attached to any capability; passing one requests the capability without widening permissions on its own. Which policies a capability needs is configured on the deployment side, so confirm with whoever owns your cloud before relying on it.

Omit the argument for an ordinary device.

Failures​

Every failure throws ESPClaimError, whose code names the step that failed:

CodeMeaning
CLAIM_START_FAILEDThe device rejected claim start
DEVICE_MAC_UNAVAILABLENo usable MAC in the device's response
CSR_RETRIEVAL_FAILEDReading the request from the device failed
CSR_STALLEDThe device stopped streaming mid-request
CLAIM_API_FAILEDThe claiming service rejected the call
CLAIM_API_NOT_CONFIGUREDNo claiming host configured
CERTIFICATE_SEND_FAILEDThe device rejected the certificate
CLAIM_ABORTEDClaiming was aborted

The claiming service returns a reason on every failure and the SDK appends it to the error message in parentheses. Those reasons are actionable (a node quota reached, a device that is not claimable, a rejected request), so surface the message rather than replacing it with generic text.