Skip to main content

ESPDevice reference

ESPDevice represents a physical device during provisioning, after the app has found it over BLE or SoftAP, before it exists as a node. This page documents every method on the class. For the flow that strings them together, read Provisioning first.

Every method forwards to the configured provisioning adaptor with this device's name applied, so each one throws if no adaptor is configured.

Properties​

PropertyContents
nameAdvertised device name
transport"ble" or "softap"
securitySecurity level as a number

You normally obtain an instance from user.createESPDevice() or user.searchESPDevices(). Constructing one directly with new ESPDevice({ name, transport, security }) works and is what the search path does internally, but it skips the adaptor's own device-creation step.

Session​

connect​

const status = await device.connect();

Returns Promise<number> — 0 for success. Opens the transport session using the security level and credentials the device was created with.

initializeSession​

const ok = await device.initializeSession();

Returns Promise<boolean>. Performs the security handshake on its own, for flows that drive the steps separately rather than letting connect() cover them.

setProofOfPossession​

const ok = await device.setProofOfPossession("<pop>");

Returns Promise<boolean>. Supplies the Security 1 proof-of-possession string when it was not passed to createESPDevice().

disconnect​

await device.disconnect();

Returns Promise<ESPAPIResponse>. Releases the native handle. Call it on both the success and failure paths.

Interrogation​

getDeviceCapabilities​

const capabilities = await device.getDeviceCapabilities();

Returns Promise<string[]>, the capability strings the device advertises. Use it to decide whether a device needs assisted claiming, or supports a given flow, before committing to it.

getDeviceVersion​

const version = await device.getDeviceVersion();

Returns Promise<{ [key: string]: any }>. The shape is whatever the firmware reports, so read defensively.

scanWifiList​

const networks = await device.scanWifiList();

Returns Promise<ESPWifiList[]>. Each entry carries ssid, rssi and auth, and optionally bssid and channel.

Association​

initiateUserNodeMapping​

const response = await device.initiateUserNodeMapping(group.groupId, {});

Returns Promise<unknown>. Asks the cloud to begin associating this device with the signed-in user in the given group; the response carries a request_id and a challenge.

Because the return type is unknown, cast it to InitiateNodeAssociationResponse to read those fields. provision() does this for you; call it directly only when driving the flow by hand.

verifyUserNodeMapping​

await device.verifyUserNodeMapping(group.groupId, requestId, {
  challenge_response: signedChallenge,
  node_id: nodeId,
});

Returns Promise<ESPAPIResponse>. Completes the association by returning the device's signed challenge to the cloud.

Provisioning​

setNetworkCredentials​

const status = await device.setNetworkCredentials("<ssid>", "<passphrase>");

Returns Promise<ESPProvisionStatus> — success or failure. Hands the device its Wi-Fi credentials without doing any of the association steps.

provision​

const nodeId = await device.provision(ssid, passphrase, onProgress, groupId, provisionType?, options?);

Returns Promise<string>, the node ID. Runs association and credential delivery as one operation, reporting each stage through onProgress. This is the method to use; the individual steps above exist for apps that need to interleave their own logic. See Provisioning.

startAssistedClaiming​

await device.startAssistedClaiming(onProgress, claimCapability);

Returns Promise<void>. Obtains and installs the device's cloud certificate. Run it before provision(). See Assisted claiming.

Raw transport​

sendData​

const response = await device.sendData("<endpoint>", "<base64-data>");

Returns Promise<string>. Sends one request to a named device endpoint and returns its response. The SDK uses this for the challenge-response and claiming exchanges; reach for it directly only for a custom endpoint your firmware defines.

Both the payload and the response are strings; protocol buffer payloads are base64-encoded in each direction, and encoding them is your responsibility on a custom endpoint.