Arduino BLE Provisioning Example

This repo is a bare bones example of how to provision your Arduino-based ESP32 project using BLE.

This is a great option for provisioning devices that can spare the extra flash space required. It is generally easier for consumers to provision their devices with an app over BLE than to connect to a custom access point created by the ESP32.

Why IDF and not Arduino IDE or PlatformIO

This project uses the ESP-IDF directly and is the recommended way of doing a project like this. This is not supported out-of-the-box in the standard Arduino IDE and, while possible, is not recommended because it requires changes to the sdkconfig file. It can be done in PlatformIO but, again, when using the Arduino library it is non-trivial. It's actually super simple to use the native ESP-IDF, use the Arduino coding style, and get BLE provisioning in just a few minutes as you will see in the instructions given below.

Instructions

Windows and Mac

While it is possible to use this repo in a Docker Dev Container on Windows and Mac, it's easier to simply install the ESP-IDF natively using the VSCode extension.

Install VSCode if you haven't already
In VSCode, install the Espressif IDF extension
Clone this repo with git clone --recurse-submodules https://github.com/deploythefleet/arduino_ble_provisioning.git
Open the repo in VSCode
Connect your ESP32 development board to USB

Linux

Linux supports docker and USB devices within Docker containers natively. As such, all you need to install are VSCode and Docker. With those two dependencies installed the instructions are very simple. You do NOT have to install the ESP-IDF on your machine. It will be installed in the dev container for you 🙌.

Install Docker if you haven't already
Install VSCode if you haven't already
Clone this repo with git clone --recurse-submodules https://github.com/deploythefleet/arduino_ble_provisioning.git
Connect your ESP32 development board to USB
Open the repo in VSCode
In VSCode open the Command Palette with Ctrl-Shift-P or from the View menu.
Type "open in container" and select the Dev Containers: Reopen in Container option. This will pull the necessary Docker image and build a dev container for you. It can take several minutes.
Open a new shell prompt in VSCode
Run idf.py flash monitor
Your device will flash after the project builds and you will be ready to provision your device using the sample Espressif provisioning app for Apple or Android (instructions below).

Note The Dev Container will fail to launch if your ESP32 Dev board does not enumerate as /dev/ttyUSB0 on your linux system. If your device has a different /dev path simply modify line 34 in the .devcontainer/devcontainer.json file of this repo to match your device's path and try to reopen in the dev container.

Use the Example App to Provision

Once your device has been flashed you are ready to provision it with the sample BLE provisioning app from Espressif. This is available for both Android and Apple:

With the app installed and the firmware running on your device:

Open the provisioning app on your phone
On the first screen click Provision Device
The following screen will ask to scan a QR code. Click I don't have a QR code
On the BLE Devices screen, after a brief scan, the device PROV_DTF will appear in the list. Click on it.
Enter the proof of posession PIN. Unless you changed it, the default is "abcd1234"
Click Next
Select your WiFi network from the list. It must be a 2.4GHz network with a password
Enter your WiFi password
Click Provision