April 7, 2022

Instructions for Wi‑Fi provisioning
via Bluetooth BLE

This is the documentation for the Wi‑Fi provisioning method that we have implemented for the defsystems atoms mentioned in the previous post defsystem atoms ready.

LED states and configuration

  1. When you plug the device in (that is, you connect via its USB-C connector to an USB power source) and the LED shines BLUE it means that the device waits for provisioning. This is the default inital state of the defsystem devices. Use the provisioning app as described below in the section "device configuration".
  2. When you plug the device in and the LED shines GREEN it means that the device is provisioned and it tries to connect to the Wi‑Fi. If it stops being GREEN, that means it successfully connected.
  3. But if it continues to shine GREEN, it means the device does not find the network or cannot connect to it. You might want to do the provisioning all over again, which you can do by this the following procedure:
  4. When you hold the big butten (with the hole for the LED) while you reset the device (that is, you either (re-)connect it to the power source or you press the little reset button on the side), the LED will switch to YELLOW. That means it deleted the known Wi‑Fi credentials. If you release the button, the device will reboot and the LED should be BLUE. Continue with step 1.

device configuration – short version

TL;DR You need to use the app "ESP BLE Provisioning" by Espressif to use the device. You can find it in the App Stores of Google and Apple. Use it to tell the device how it connect to a Wi‑Fi network. It does not work without Wi‑Fi.
The provisioning is quite straight forward when using the apps. You can just try on your own. Only one important thing: In the step "Connect to System", you need to change the "Prefix" to "defsystem" to be able to find the device. Click on the button "CHANGE" to do so.

device configuration – long version

The uLisp systems on the M5Stack Atom Lite ESP32 run a version of m5stack-ulisp-esp that has Wi‑Fi provisioning activated. We have implemented it to use Espressif's Unified Provisioning using Bluetooth Low Energy (BLE) as the transport. Unified Provisioning is an extensible mechanism to transfer Wi‑Fi credentials and also other custom configuration. Unified Provisioning is documented on Espressif's provisioning documentation page.

That is, the device wants to run with Wi‑Fi and when it does not know any, it waits for you to configure it. When you plug them in and the LED shines BLUE it means that the device waits for provisioning. With this provisioning you configure the device and transfer Wi‑Fi crendentials to it via Bluetooth BLE from another device, a smartphone or a computer.

Espressif offeres example applications with code for Android, iOS and even also a python implementations that runs on Linux, MacOS, and Window. The example applications for BLE Provisioning are even available in the app stores (Apple App Store and Google Play Store), source code and more programs also for Windows, Linux, MacOSX can be found on Espressif's documentation pages, under provisioning-tools.

Direct links to the provisioning tools

Android
BLE Provisioning app in Google's Play Store
iOS
BLE Provisioning app in Apple's app store
Linux/MacOS/Windows
esp_prov (a python based command line tool for provisioning)

Note: Max has used the Android app "ESP BLE Provisioning" by Espressif during the demo at the European Lisp Symposium 2022.

Step by step explanation of the "ESP BLE Provisioning"

TL;DR The provisioning is quite straight forward when using the apps. You can just try without reading this whole section. Only one important thing: In the step "Connect to System", you need to change the "Prefix" to "defsystem" to be able to find the device. Click on the button "CHANGE" to do so.

Here is a complete walkthrough:

1.
This is the initial screen of the provisioning app. Just click on the button "Provision New Device".

2.
QR codes can be used to make provisioning easier …

3.
… but as there is no QR code on the defsystem device, just click on the button "I don't have a QR code".

4.
The app looks for devices to provision …

5.
… but as the search prefix is set to "DEFAULT", the app does not find any devices. So click on the button "CHANGE".

6.
Select the input field that shows "DEFAULT" …

7.
… and type in "defsystem" instead …

8.
… and click on the button "SAVE".

9.
The application should now list your device with name "defsystem" or "defsystem-xx" where "xx" is the two digit number that you should find on the bottom side of your device.

10.
Select your device by clicking on its name.

11.
The app asks for a "PIN" code as "Proof of Possession". As we have used the application's default code "abcd1234" you can leave this as it is and just click on the button "Next 🡒".

12.
The app should now talk to your device via Bluetooth BLE and make it search for Wi‑Fi networks.

13.
This may take a moment while the app shows a waiting animation.

14.
Hopefully after a short wait the app presents a list of networks that the defsystem device has discovered.

15.
In this demonstration we select "Falafel" as our example network.

16.
Enter the password for the network …

17.
… and click on the button "PROVISION".

18.
The actual provisioning starts. As a first step the app sends the Wi‑Fi credentials …

19.
… the second is to wait for the device to actually connect to that network and get a Wi‑Fi connection.

20.
… and the last step is to check for a confirmation by the device that provisioning was successful.

The device should reboot and connect to the configured Wi‑Fi network. While connecting the device's LED shines GREEN.

When it stops being GREEN, that means, it successfully connected. If it continues to shine GREEN, it means it does not find the network or cannot connect. In this case you might want to try provisioning again, see section "LED states and configuration" at the top of this page.

If you click on the button "OK" …

21.
… you get back to the starting screen of the provisioning app. You can end the app, or start over provisioning another device.