DOCSEARCHbyAlgolia
Submit Docs

ESP Provisioning Library for Android

repository·master·Indexed 43 days ago

https://github.com/espressif/esp-idf-provisioning-android

An Android library for sending Wi-Fi credentials and custom data to ESP32 and ESP8266 devices. It simplifies discovering, connecting to, and configuring devices via BLE or SoftAP using abstractions like ESPProvisionManager and ESPDevice. Supports Android 8.0 (API level 26) and above, featuring QR code scanning and manual device connection workflows.

Tokens
1.6K
Snippets
4
Records
6
Agent score
5%

What's inside ESP Provisioning Library

  1. How ESPDevice and ESPProvisionManager work together

    master

    The library uses two primary abstractions to manage the provisioning lifecycle:

    • ESPProvisionManager: A singleton class that serves as the entry point. It provides APIs for searching for devices via BLE or SoftAP and for scanning QR codes.
    • ESPDevice: A virtual representation of the target ESP32/ESP32-S2/ESP8266 device. Once you obtain an ESPDevice instance (via scanning or manual creation), you use it to perform connection, security configuration, network scanning, and the final provisioning steps.

    Once an ESPDevice is obtained, you can maintain it for subsequent API calls or retrieve the same instance later using ESPProvisionManager.getInstance(context).getEspDevice().

  2. Provision a device with Wi-Fi credentials

    master

    After establishing a connection and configuring security (PoP/Username), follow these steps to provision the device with network credentials:

    1. Scan for available networks: Use the device to scan for nearby Wi-Fi networks to allow the user to select one.
    2. Provision: Send the chosen SSID and passphrase to the device.

    Workflow:

    1. Call espDevice.scanNetworks(wifiScanListener) to get a list of networks.
    2. Call espDevice.provision(ssid, passphrase, provisionListener) to apply the credentials.
    // 1. Scan networks
espDevice.scanNetworks(new WiFiScanListener() {
    @Override
    public void onScanCompleted(List<WiFiNetwork> networks) {
        // User selects a network from the list
    }
});

// 2. Provision the device
espDevice.provision("MY_SSID", "MY_PASSWORD", new ProvisionListener() {
    @Override
    public void onProvisionSuccess() {
        // Device is provisioned!
    }
    @Override
    public void onProvisionError(int error) {
        // Handle error
    }
});

  3. Obtain an ESPDevice via QR Code Scan

    master

    You can extract device information by scanning a valid QR code. The QR code payload must be a JSON string.

    QR Code Payload Schema:

    KeyDetailValuesRequired
    verVersion of the QR codev1Yes
    nameName of the devicePROV_XXXXXXYes
    popProof of possessionDevice POP valueNo
    transportWi-Fi provisioning transport typesoftap or bleYes
    securitySecurity version0, 1, or 2No
    passwordPassword of SoftAP deviceConnection passwordNo

    Implementation Options:

    1. Using CameraSourcePreview: Include <com.espressif.provisioning.CameraSourcePreview> in your layout and pass it to the API.

    2. Using CodeScanner: Add implementation 'com.budiyev.android:code-scanner:2.1.0' to your dependencies, include <com.budiyev.android.codescanner.CodeScannerView> in your layout, and pass the CodeScanner instance to the API.

    // Option 1: Using CameraSourcePreview
ESPProvisionManager.getInstance(context).scanQRCode(activityContext, cameraSourcePreview, qrCodeScanListener);

// Option 2: Using CodeScanner
ESPProvisionManager.getInstance(context).scanQRCode(codeScanner, qrCodeScanListener);

  4. Manually create and connect to an ESPDevice

    master

    If no QR code is available, you can manually create an ESPDevice and connect via BLE or SoftAP.

    1. Create the device

    ESPProvisionManager.getInstance(context).createESPDevice(TransportType transportType, SecurityType securityType);

    2. Connect based on Transport Type

    For BLE Transport: First, search for discoverable devices using a prefix:

    ESPProvisionManager.getInstance(context).searchBleEspDevices(String prefix, BleScanListener bleScannerListener);

    Once a device is selected, connect using the BluetoothDevice and the primaryServiceUuid obtained from the scan result:

    // Use the ESPDevice instance obtained from createESPDevice
espDevice.connectBLEDevice(bluetoothDevice, primaryServiceUuid);

    For SoftAP Transport: Connect directly using the ESPDevice instance:

    espDevice.connectWiFiDevice();

    3. Configure Security

    After connection, set the Proof of Possession (PoP) and, if using Security Version 2, the username:

    espDevice.setProofOfPossession(pop);
espDevice.setUserName(username);
    // Manual creation example
ESPDevice device = ESPProvisionManager.getInstance(context).createESPDevice(TransportType.BLE, SecurityType.SEC2);

// Connect BLE
device.connectBLEDevice(bluetoothDevice, "SERVICE_UUID");

// Set security credentials
device.setProofOfPossession("abcd1234");
device.setUserName("user_name");

  5. Install the ESP Provisioning Library

    master

    To use the provisioning library in your Android project, follow these two steps:

    1. Add the JitPack repository to your root build.gradle file:

    2. Add the library dependency to your app module's build.gradle file.

    Requirements:

    • Supports Android 8.0 (API level 26) and above.
    // In root build.gradle
allprojects {
    repositories {
        ... 
        maven { url 'https://jitpack.io' }
    }
}

// In app/build.gradle
dependencies {
    implementation 'com.github.espressif:esp-idf-provisioning-android:lib-2.4.4'
}