bledev.improv

Wi-Fi setup over BLE with the Improv standard (https://www.improv-wifi.com/ble/).

A board with no Wi-Fi credentials advertises the Improv service; a phone, a laptop or another board sends it a network name and password; the board joins and answers with a URL. ESPHome, WLED and Home Assistant speak the same protocol, so their tools can provision a bledev board too.

On the board (serve() returns once it has joined):

import bledev.mpble, bledev.improv as improv
url = await improv.serve(bledev.mpble.get(), name="kitchen")

From a laptop or another board:

import bledev.improv as improv
url = await improv.provision(ble, ssid, password, name="kitchen")

A network that can’t be joined raises ImprovError with code == ERROR_UNABLE_TO_CONNECT, which the board also reports in its error characteristic.

The credentials cross the air unencrypted; that is the Improv standard, and the reason a board should only serve it until it’s set up. serve() never logs them. Saving them for the next boot is the app’s job (on_join), so nothing here writes a credential to the filesystem.

bledev.improv.SERVICE_DATA = UUID(0x4677)

The 16-bit UUID the advertisement’s service data is filed under.

bledev.improv.AUTHORIZATION_MS = 60000

How long an authorization given with authorize() lasts (the standard suggests about a minute).

exception bledev.improv.ImprovError(code, message=None)[source]

Bases: BLEError

The device reported an Improv error. code is one of ERROR_*.

bledev.improv.checksum(data)[source]

The standard’s checksum: the sum of every byte, keeping the low byte.

bledev.improv.pack(command, *strings)[source]

An RPC command or result: command, length, (len, bytes)..., checksum.

bledev.improv.packet_length(buffer)[source]

The full length of the packet that starts buffer, or None until two bytes are in.

bledev.improv.unpack(packet)[source]

(command, [bytes, ...]) from one whole packet. Raises ImprovError.

bledev.improv.service_data(state, capabilities)[source]

The six bytes the advertisement carries under SERVICE_DATA.

async bledev.improv.wifi_connect(ssid, password, timeout_ms=20000)[source]

Join ssid with MicroPython’s network.WLAN; the IP address, or None.

A status that means failure (no such network, wrong password) ends the attempt after it has held for five seconds, since the ESP32 retries a few times on its own; otherwise it waits up to timeout_ms.

bledev.improv.wifi_scan()[source]

[(ssid, rssi, secured), ...] from network.WLAN.scan(), strongest first.

class bledev.improv.Server(ble, name=None, *, join=None, redirect='http://{ip}/', on_join=None, require_authorization=False, identify=None, scan=None, device_info=None)[source]

Bases: object

The Improv service on a peripheral adapter.

join(ssid, password) is an async callable returning the IP address as a string, or None if the network couldn’t be joined; the default is wifi_connect, on MicroPython. redirect is the URL the client is sent to afterwards, with {ip} filled in; None sends none. on_join(ssid, password, ip) runs after a successful join, so the app can store the credentials for the next boot.

require_authorization=True starts in “authorization required” until authorize (from a button, say). identify is a callable that makes the device noticeable (blink, beep); scan returns [(ssid, rssi, secured), ...]. Each one given turns on its capability.

authorize()[source]

Mark the device authorized for AUTHORIZATION_MS (from a button press).

async serve(timeout_ms=None)[source]

Advertise until a client provisions the device; return the redirect URL (or IP).

timeout_ms bounds each wait for a client to connect.

async session(connection)[source]

Serve one connected client. True once the device is provisioned.

async bledev.improv.serve(ble, name=None, *, timeout_ms=None, **options)[source]

Serve Improv on ble until provisioned; return the redirect URL (or the IP).

name is what it advertises as; by default the board’s name, boarddev.name().

options go to Server.

class bledev.improv.Client(connection, chars)[source]

Bases: object

A connection to an Improv device. Use connect, or provision.

async classmethod connect(ble, name=None, *, device=None, timeout_ms=10000)[source]

Find the device (by name, or the first advertising Improv), connect, subscribe.

async state()[source]

The device’s current STATE_*.

async error()[source]

The device’s current ERROR_*.

async send_wifi(ssid, password, timeout_ms=60000)[source]

Send credentials; return the redirect URL ("" if the device sends none).

Raises ImprovError (ERROR_UNABLE_TO_CONNECT for a network the device couldn’t join).

async device_info(timeout_ms=5000)[source]

[firmware, version, chip, device name, ...] as strings.

async scan(timeout_ms=20000)[source]

[(ssid, rssi, secured), ...] as the device sees them.

async bledev.improv.provision(ble, ssid, password, name=None, *, device=None, timeout_ms=60000)[source]

Connect to an Improv device, send it ssid and password, and return its redirect URL.

Raises ImprovError if it can’t join.