|
JBImprov
Improv Wi-Fi provisioning over serial and Bluetooth LE
|
An Arduino library for Improv Wi-Fi provisioning over serial and Bluetooth LE.
JBImprov lets users send Wi-Fi credentials to your device without hardcoding them in the firmware. It works the same way as in ESPHome: from a browser over USB, or from a browser, Home Assistant or a phone over Bluetooth.
It implements the device side of both Improv protocols:
You can use one or both. They share a single Wi-Fi state, so a device provisioned over BLE also reports provisioned over serial.
| Board | Serial | BLE |
|---|---|---|
| ESP32, ESP32-S3, ESP32-C3, ESP32-C6 (Arduino core 2.x and 3.x) | ✅ | ✅ |
| ESP32-S2 | ✅ | ❌ (no Bluetooth) |
| ESP8266 | ✅ | ❌ (no Bluetooth) |
| Other boards | ✅ with your own Wi-Fi adapter | ❌ |
JBImprov is available in the Arduino Library Manager:
Wi-Fi and Bluetooth together take about 1.6 MB of flash on ESP32 core 3.x, more than the default 1.25 MB app partition. Pick a bigger app partition:
Serial-only sketches fit the default partition.
Flash the sketch, open improv-wifi.com, select Connect device to Wi-Fi and pick the serial port.
You can keep printing log output on Serial. Clients skip anything that isn't an Improv frame. JBImprov reads all incoming bytes on the port, though. If your sketch needs serial input too, call improvSerial.setAutoRead(false), read the port yourself and pass each byte to improvSerial.handleByte(byte). It returns false for bytes that aren't Improv data.
On boards with native USB (ESP32-S3, ESP32-C3, ESP32-C6), enable Tools > USB CDC On Boot so that Serial is the USB port.
JBImprovBLE owns the ESP32 BLE stack, so don't run other BLE server code next to it. Like ESPHome, it stops advertising once the device is provisioned, and starts again if the Wi-Fi connection is lost for more than 10 seconds. Call improvBLE.setAdvertiseWhenProvisioned(true) to keep it available.
By default, anyone within Bluetooth range can provision the device while it isn't connected to Wi-Fi. To require a physical action first:
Until authorize() is called, the device reports authorization required. It rejects Wi-Fi credentials, hostname changes and device name changes.
Add both transports to the same JBImprov instance:
See examples/SerialAndBLE. It also serves a web page as the redirect URL and stores the hostname and device name in Preferences.
Full code documentation is available at https://jonnybergdahl.github.io/jbimprov/.
Call these before begin().
| Method | Description |
|---|---|
| setFirmware(name, version) | Firmware name and version in device info. Not copied, string literals are fine. |
| setDeviceName(name) | User-facing name. Defaults to the hostname. |
| setHostname(hostname) | Hostname used when connecting. Defaults to the core's hostname, e.g. esp32s3-4F44C0. Returns false for an invalid hostname. |
| setHardware(hardware) | Override the hardware string. Defaults to the chip, e.g. ESP32-S3. |
| setRedirectUrl(url) | URL the client offers after provisioning, e.g. "http://{{ip_address}}/". Not copied. |
| setConnectTimeout(ms) | How long to wait for a connection before reporting unable to connect. Default 30 s. |
| addTransport(transport) | Add a JBImprovSerial or JBImprovBLE. Up to three transports. |
| Method | Called when |
|---|---|
| onProvisioned(void(const char* ssid, const char* password)) | The device connected with credentials from a client |
| onStateChanged(void(JBImprovState state)) | The state changes (Ready, Provisioning, Provisioned) |
| onIdentify(void()) | A client asks the device to identify itself. Setting this enables the identify capability. |
| onHostnameChanged(void(const char* hostname)) | A client sets a new hostname |
| onDeviceNameChanged(void(const char* name)) | A client sets a new device name |
On ESP32 and ESP8266 the callbacks can be lambdas that capture variables (std::function).
| Method | Returns |
|---|---|
| state() | JBImprovState::Ready, Provisioning or Provisioned |
| isProvisioned() | true while connected to Wi-Fi |
| deviceName(), hostname() | The current values, including ones set by a client |
On boards other than the ESP32 and ESP8266, derive a class from JBImprovWiFi and pass it to the constructor. It has methods to connect, report the connection status, scan, and get the IP address. See src/JBImprovWiFi.h.
improv-client is a command-line client for testing from a computer:
The docs use the doxygen-awesome-css theme as a Git submodule. After cloning, run git submodule update --init.
MIT, see LICENSE.