Class ESPDevice

Represents an ESP device for provisioning and local communication. Provides methods for device discovery and WiFi provisioning.

Implements

Constructors

constructor

Properties

name provisionResumeState? security transport

Accessors

ESPProvisionAdapter

Methods

connect disconnect getDeviceCapabilities getDeviceVersion initializeSession initiateUserNodeMapping provision resetWifiStatus retryNetworkCredentials scanWifiList sendData setNetworkCredentials setProofOfPossession startAssistedClaiming verifyUserNodeMapping

Constructors

constructor

Properties

name

name: string

OptionalprovisionResumeState

provisionResumeState?: {
    groupId: string;
    nodeId: string;
    options?: Record<string, any>;
}

What a completed association produced, kept so retryNetworkCredentials can resume the flow instead of repeating it. Set once verification succeeds; undefined until then.

security

security: number

transport

transport: string

Accessors

ESPProvisionAdapter

Methods

connect

  • connect(): Promise<number>

    Connects to the ESP device using the configured provisioning adapter.

    Returns Promise<number>

    A promise that resolves to a connection status code (0 for success).

    Throws

    If the device cannot be connected or the adapter is not configured.

disconnect

getDeviceCapabilities

  • getDeviceCapabilities(): Promise<string[]>

    Retrieves the capabilities of the device.

    Returns Promise<string[]>

    A promise that resolves to an array of capability strings.

    Throws

    If the capabilities cannot be retrieved or the adapter is not configured.

getDeviceVersion

  • getDeviceVersion(): Promise<{ [key: string]: any }>

    Retrieves version information from the device.

    Returns Promise<{ [key: string]: any }>

    A promise that resolves to an object containing device version information.

    Throws

    If the version cannot be retrieved or the adapter is not configured.

initializeSession

  • initializeSession(): Promise<boolean>

    Initializes a provisioning session with the device.

    Returns Promise<boolean>

    A promise that resolves to true if session initialization was successful.

    Throws

    If session initialization fails or the adapter is not configured.

initiateUserNodeMapping

  • initiateUserNodeMapping(
        groupId: string,
        requestBody?: Record<string, unknown>,
    ): Promise<unknown>

    Initiates a user node mapping request.

    Parameters

    • groupId: string
    • OptionalrequestBody: Record<string, unknown>

      The request body for the user node mapping.

    Returns Promise<unknown>

    A promise that resolves to the response from the API.

provision

  • provision(
        ssid: string,
        passphrase: string,
        onProgress: (message: ESPProvResponse) => void,
        groupId: string,
        provisionType?: string,
        options?: ProvisionOptions,
    ): Promise<string>

    Provisions the device with WiFi credentials using challenge-response flow.

    Parameters

    • ssid: string

      The WiFi network SSID.

    • passphrase: string

      The WiFi network password.

    • onProgress: (message: ESPProvResponse) => void

      A callback function to report progress.

    • groupId: string

      The group ID for node association.

    • OptionalprovisionType: string

      The provisioning flow type. Default: ProvisionType.CHAL_RESP.

    • Optionaloptions: ProvisionOptions

      Optional step 6 (online wait via MQTT).

    Returns Promise<string>

    A promise that resolves with the node ID when provisioning is complete.

    Throws

    If provisioning fails at any stage.

resetWifiStatus

  • resetWifiStatus(): Promise<boolean>

    Asks the device to clear its Wi-Fi state over the open provisioning session.

    Sent on the network-control endpoint, so it needs an established session and leaves the user-node association intact — only Wi-Fi credentials are cleared. That is what makes retryNetworkCredentials possible after a wrong password, instead of making the user factory reset the board.

    Returns Promise<boolean>

    A promise resolving to true when the device acknowledged the reset.

retryNetworkCredentials

  • retryNetworkCredentials(
        ssid: string,
        passphrase: string,
        onProgress: (message: ESPProvResponse) => void,
    ): Promise<string>

    Re-sends Wi-Fi credentials after resetWifiStatus, resuming the flow the first attempt started rather than repeating its association.

    Sending credentials alone is not enough: the online wait and the success report follow them and need the node id the association produced, which only this SDK holds.

    Parameters

    • ssid: string

      The SSID, unchanged from the first attempt.

    • passphrase: string

      The corrected Wi-Fi password.

    • onProgress: (message: ESPProvResponse) => void

      Progress callback; emits the same messages as provision.

    Returns Promise<string>

    A promise resolving to the node id.

    Throws

    When no association has completed on this device yet.

scanWifiList

  • scanWifiList(): Promise<ESPWifiList[]>

    Scans for available WiFi networks using the device's provisioning adapter.

    Returns Promise<ESPWifiList[]>

    A promise that resolves to an array of available WiFi networks.

    Throws

    If the scan fails or the adapter is not configured.

sendData

  • sendData(endPoint: string, data: string): Promise<string>

    Sends data to the device at a specific endpoint.

    Parameters

    • endPoint: string

      The endpoint to send data to.

    • data: string

      The data string to send.

    Returns Promise<string>

    A promise that resolves to the response string from the device.

    Throws

    If sending data fails or the adapter is not configured.

setNetworkCredentials

setProofOfPossession

  • setProofOfPossession(proofOfPossession: string): Promise<boolean>

    Sets the proof of possession (PoP) for the device during provisioning.

    Parameters

    • proofOfPossession: string

      The proof of possession string.

    Returns Promise<boolean>

    A promise that resolves to true if PoP was set successfully.

    Throws

    If setting PoP fails or the adapter is not configured.

startAssistedClaiming

  • startAssistedClaiming(
        onProgress?: ESPClaimProgressCallback,
        claimCapability?: CAMERA_CLAIM,
    ): Promise<void>

    Starts the assisted claiming process.

    Flow:

    1. Send ClaimStart to device, which returns its device info
    2. Reserve a node ID for the device MAC (POST /v1/claim/initiate)
    3. Send ClaimInit with the cloud response to device
    4. Read the chunked CSR from device
    5. Exchange the CSR for a certificate (POST /v1/claim/verify)
    6. Stream the certificate response back to device

    Parameters

    Returns Promise<void>

    Promise that resolves when claiming is complete

    Throws

    ESPClaimError if claiming fails at any step

verifyUserNodeMapping

  • verifyUserNodeMapping(
        groupId: string,
        requestId: string,
        requestBody?: Record<string, unknown>,
    ): Promise<ESPAPIResponse>

    Verifies the mapping between a user and a node.

    Parameters

    • groupId: string

      The ID of the group.

    • requestId: string

      The node association request ID.

    • OptionalrequestBody: Record<string, unknown>

      The request body for the user node mapping verification.

    Returns Promise<ESPAPIResponse>

    A promise that resolves to the response from the API.

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods