esp-idf/tools/esp_prov

****# ESP Provisioning Tool

NAME

esp_prov - A python based utility for testing the provisioning examples over a host

SYNOPSIS

python esp_prov.py --transport < mode of provisioning : softap \ ble \ console > [ Optional parameters... ]

DESCRIPTION

Usage of esp-prov assumes that the provisioning app has specific protocomm endpoints active. These endpoints are active in the provisioning examples and accept specific protobuf data structures:

Endpoint Name	URI (HTTP server on ip:port)	Description
prov-session	http://ip:port/prov-session	Security endpoint used for session establishment
prov-config	http://ip:port/prov-config	Endpoint used for configuring Wi-Fi credentials on device
proto-ver	http://ip:port/proto-ver	Version endpoint for checking protocol compatibility
prov-scan	http://ip:port/prov-scan	Endpoint used for scanning Wi-Fi APs
custom-data	http://ip:port/custom-data	Optional endpoint for sending custom data (refer wifi_prov_mgr example)

PARAMETERS

• --help Print the list of options along with brief descriptions

• --verbose, -v Sets the verbosity level of output log

• --transport <mode>

  • Three options are available:
    • softap - for SoftAP + HTTPD based provisioning
      • Requires the device to be running in Wi-Fi SoftAP mode and hosting an HTTP server supporting specific endpoint URIs
      • The client needs to be connected to the device softAP network before running the esp_prov tool.
    • ble - for BLE based provisioning
      • Supports Linux only; on Windows/macOS, it is redirected to console
      • Assumes that the provisioning endpoints are active on the device with specific BLE service UUIDs
    • console - for debugging via console-based provisioning
      • The client->device commands are printed to STDOUT and device->client messages are accepted via STDIN.
      • This is to be used when the device is accepting provisioning commands on UART console.

• --service_name <name> (Optional)

  • When transport mode is ble, this specifies the BLE device name to which connection is to be established for provisioned.
  • When transport mode is softap, this specifies the HTTP server hostname / IP which is running the provisioning service, on the SoftAP network of the device which is to be provisioned. This defaults to 192.168.4.1:80 if not specified

• --ssid <AP SSID> (Optional)

  • For specifying the SSID of the Wi-Fi AP to which the device is to connect after provisioning.
  • If not provided, scanning is initiated and scan results, as seen by the device, are displayed, of which an SSID can be picked and the corresponding password specified.

• --passphrase <AP Password> (Optional)

  • For specifying the password of the Wi-Fi AP to which the device is to connect after provisioning.
  • Only used when corresponding SSID is provided using the --ssid option

• --sec_ver <Security version number>

  • For specifying the version of protocomm endpoint security to use. Following 3 versions are supported:
    • 0 for protocomm_security0 - No security
    • 1 for protocomm_security1 - X25519 key exchange + Authentication using Proof of Possession (PoP) + AES-CTR encryption
    • 2 for protocomm_security2 - Secure Remote Password protocol (SRP6a) + AES-GCM encryption

• --pop <Proof of possession string> (Optional)

  • For specifying optional Proof of Possession string to use for protocomm endpoint security version 1
  • Ignored when other security versions are used

• --sec2_username <SRP6a Username> (Optional)

  • For specifying optional username to use for protocomm endpoint security version 2
  • Ignored when other security versions are used

• --sec2_pwd <SRP6a Password> (Optional)

  • For specifying optional password to use for protocomm endpoint security version 2
  • Ignored when other security versions are used

• --sec2_gen_cred (Optional)

  • For generating the SRP6a credentials (salt and verifier) from the provided username and password for protocomm endpoint security version 2
  • Ignored when other security versions are used

• --sec2_salt_len <SRP6a Salt Length> (Optional)

  • For specifying the optional SRP6a salt length to be used for generating protocomm endpoint security version 2 credentials
  • Ignored when other security versions are used and the ``--sec2_gen_cred` option is not set

• --custom_data <some string> (Optional) An information string can be sent to the custom-data endpoint during provisioning using this argument. (Assumes the provisioning app has an endpoint called custom-data - see provisioning/wifi_prov_mgr example for implementation details).

AVAILABILITY

esp_prov is intended as a cross-platform tool, but currently BLE communication functionality is only available on Linux (via BlueZ and DBus)

For Android, a provisioning tool along with source code is available here

On macOS and Windows, running with --transport ble option falls back to console mode, ie. write data and target UUID are printed to STDOUT and read data is input through STDIN. Users are free to use their app of choice to connect to the BLE device, send the write data to the target characteristic and read from it.

Dependencies

This requires the following python libraries to run (included in requirements.txt):

• future
• protobuf
• cryptography

Run pip install -r $IDF_PATH/tools/esp_prov/requirements.txt

Note :

• The packages listed in requirements.txt are limited only to the ones needed AFTER fully satisfying the requirements of ESP-IDF
• BLE communication is only supported on Linux (via Bluez and DBus), therefore, the dependencies for this have been made optional

Optional Dependencies (Linux Only)

These dependencies are for enabling communication with BLE devices using Bluez and DBus on Linux:

• dbus-python

Run pip install -r $IDF_PATH/tools/esp_prov/requirements_linux_extra.txt

EXAMPLE USAGE

Please refer to the README.md file with the wifi_prov_mgr example present under $IDF_PATH/examples/provisioning/.

This example uses specific options of the esp_prov tool and gives an overview of simple as well as advanced usage scenarios.