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:
BLEErrorThe device reported an Improv error.
codeis one ofERROR_*.
- 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, orNoneuntil two bytes are in.
- bledev.improv.unpack(packet)[source]
(command, [bytes, ...])from one whole packet. RaisesImprovError.
- 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
ssidwith MicroPython’snetwork.WLAN; the IP address, orNone.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), ...]fromnetwork.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:
objectThe Improv service on a peripheral adapter.
join(ssid, password)is an async callable returning the IP address as a string, orNoneif the network couldn’t be joined; the default iswifi_connect, on MicroPython.redirectis the URL the client is sent to afterwards, with{ip}filled in;Nonesends none.on_join(ssid, password, ip)runs after a successful join, so the app can store the credentials for the next boot.require_authorization=Truestarts in “authorization required” untilauthorize(from a button, say).identifyis a callable that makes the device noticeable (blink, beep);scanreturns[(ssid, rssi, secured), ...]. Each one given turns on its capability.- authorize()[source]
Mark the device authorized for
AUTHORIZATION_MS(from a button press).
- async bledev.improv.serve(ble, name=None, *, timeout_ms=None, **options)[source]
Serve Improv on
bleuntil provisioned; return the redirect URL (or the IP).nameis what it advertises as; by default the board’s name,boarddev.name().optionsgo toServer.
- class bledev.improv.Client(connection, chars)[source]
Bases:
objectA connection to an Improv device. Use
connect, orprovision.- 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 send_wifi(ssid, password, timeout_ms=60000)[source]
Send credentials; return the redirect URL (
""if the device sends none).Raises
ImprovError(ERROR_UNABLE_TO_CONNECTfor a network the device couldn’t join).
- async bledev.improv.provision(ble, ssid, password, name=None, *, device=None, timeout_ms=60000)[source]
Connect to an Improv device, send it
ssidandpassword, and return its redirect URL.Raises
ImprovErrorif it can’t join.