# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""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.
"""
import asyncio
import boarddev
import sys
from . import (
BLEError,
BLETimeoutError,
BusyError,
Characteristic,
DisconnectedError,
MAX_MTU,
Service,
UUID,
sleep_ms,
wait_ms,
)
SERVICE = UUID("00467768-6228-2272-4663-277478268000")
STATE = UUID("00467768-6228-2272-4663-277478268001")
ERROR = UUID("00467768-6228-2272-4663-277478268002")
RPC = UUID("00467768-6228-2272-4663-277478268003")
RESULT = UUID("00467768-6228-2272-4663-277478268004")
CAPABILITIES = UUID("00467768-6228-2272-4663-277478268005")
#: The 16-bit UUID the advertisement's service data is filed under.
SERVICE_DATA = UUID(0x4677)
STATE_AUTHORIZATION_REQUIRED = 0x01
STATE_AUTHORIZED = 0x02
STATE_PROVISIONING = 0x03
STATE_PROVISIONED = 0x04
ERROR_NONE = 0x00
ERROR_INVALID_RPC = 0x01
ERROR_UNKNOWN_RPC = 0x02
ERROR_UNABLE_TO_CONNECT = 0x03
ERROR_NOT_AUTHORIZED = 0x04
ERROR_BAD_HOSTNAME = 0x05
ERROR_UNKNOWN = 0xFF
CMD_WIFI_SETTINGS = 0x01
CMD_IDENTIFY = 0x02
CMD_DEVICE_INFO = 0x03
CMD_WIFI_SCAN = 0x04
CMD_HOSTNAME = 0x05
CMD_DEVICE_NAME = 0x06
CAP_IDENTIFY = 0x01
CAP_DEVICE_INFO = 0x02
CAP_WIFI_SCAN = 0x04
CAP_HOSTNAME = 0x08
#: How long an authorization given with ``authorize()`` lasts (the standard
#: suggests about a minute).
AUTHORIZATION_MS = 60000
_ERROR_NAMES = {
ERROR_INVALID_RPC: "invalid RPC packet",
ERROR_UNKNOWN_RPC: "unknown RPC command",
ERROR_UNABLE_TO_CONNECT: "unable to connect",
ERROR_NOT_AUTHORIZED: "not authorized",
ERROR_BAD_HOSTNAME: "bad hostname",
ERROR_UNKNOWN: "unknown error",
}
[docs]
class ImprovError(BLEError):
"""The device reported an Improv error. ``code`` is one of ``ERROR_*``."""
def __init__(self, code, message=None):
super().__init__(message or "Improv error 0x{:02x}: {}".format(code, _ERROR_NAMES.get(code, "?")))
self.code = code
# ---------------------------------------------------------------- packets
[docs]
def checksum(data):
"""The standard's checksum: the sum of every byte, keeping the low byte."""
return sum(data) & 0xFF
def _encode(s):
return s.encode() if isinstance(s, str) else bytes(s)
[docs]
def pack(command, *strings):
"""An RPC command or result: ``command, length, (len, bytes)..., checksum``."""
body = bytearray()
for s in strings:
s = _encode(s)
if len(s) > 255:
raise ValueError("an Improv string is at most 255 bytes")
body.append(len(s))
body.extend(s)
if len(body) > 255:
raise ValueError("an Improv packet carries at most 255 bytes")
packet = bytes((command, len(body))) + bytes(body)
return packet + bytes((checksum(packet),))
[docs]
def packet_length(buffer):
"""The full length of the packet that starts ``buffer``, or ``None`` until two bytes are in."""
if len(buffer) < 2:
return None
return buffer[1] + 3
[docs]
def unpack(packet):
"""``(command, [bytes, ...])`` from one whole packet. Raises `ImprovError`."""
packet = bytes(packet)
if len(packet) < 3 or len(packet) != packet[1] + 3:
raise ImprovError(ERROR_INVALID_RPC, "Improv packet has the wrong length")
if checksum(packet[:-1]) != packet[-1]:
raise ImprovError(ERROR_INVALID_RPC, "Improv packet checksum mismatch")
body = packet[2:-1]
strings = []
i = 0
while i < len(body):
n = body[i]
if i + 1 + n > len(body):
raise ImprovError(ERROR_INVALID_RPC, "Improv string runs past the packet")
strings.append(body[i + 1 : i + 1 + n])
i += 1 + n
return packet[0], strings
[docs]
def service_data(state, capabilities):
"""The six bytes the advertisement carries under `SERVICE_DATA`."""
return bytes((state, capabilities, 0, 0, 0, 0))
# ---------------------------------------------------------------- joining Wi-Fi on a board
# network.WLAN statuses that mean the attempt failed rather than is under way.
_FAILED = (200, 201, 202, 203, 204) # beacon timeout, no AP, wrong password, assoc fail, handshake timeout
_FAIL_AFTER_MS = 5000
[docs]
async def wifi_connect(ssid, password, timeout_ms=20000):
"""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``.
"""
import network
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
try:
wlan.disconnect()
except OSError:
pass
wlan.connect(ssid, password)
waited = 0
failing = 0
while waited < timeout_ms:
if wlan.isconnected():
ip = wlan.ifconfig()[0]
if ip and ip != "0.0.0.0":
return ip
status = wlan.status()
failing = failing + 250 if status in _FAILED or status == getattr(network, "STAT_IDLE", -1) else 0
if failing >= _FAIL_AFTER_MS:
break
await sleep_ms(250)
waited += 250
try:
wlan.disconnect()
except OSError:
pass
return None
[docs]
def wifi_scan():
"""``[(ssid, rssi, secured), ...]`` from ``network.WLAN.scan()``, strongest first."""
import network
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
found = {}
for ssid, _bssid, _channel, rssi, security, _hidden in wlan.scan():
ssid = ssid.decode("utf-8", "replace") if isinstance(ssid, bytes) else ssid
if ssid and (ssid not in found or found[ssid][1] < rssi):
found[ssid] = (ssid, rssi, security != 0)
return sorted(found.values(), key=lambda n: -n[1])
def _default_device_info(name):
impl = sys.implementation
version = ".".join(str(v) for v in impl.version[:3])
chip = sys.platform
try:
import os
chip = os.uname().machine
except (ImportError, AttributeError):
pass
return (impl.name, version, chip, name)
# ---------------------------------------------------------------- the device side
[docs]
class Server:
"""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.
"""
def __init__(
self,
ble,
name=None,
*,
join=None,
redirect="http://{ip}/",
on_join=None,
require_authorization=False,
identify=None,
scan=None,
device_info=None,
):
self.ble = ble
if name is None:
name = boarddev.name()
self.name = name
self._join = join or wifi_connect
self.redirect = redirect
self._on_join = on_join
self._identify = identify
if scan is None and sys.implementation.name == "micropython":
scan = wifi_scan
self._scan = scan
self._device_info = tuple(device_info or _default_device_info(name))
caps = CAP_DEVICE_INFO
if identify is not None:
caps |= CAP_IDENTIFY
if scan is not None:
caps |= CAP_WIFI_SCAN
self.capabilities = caps
self.state = STATE_AUTHORIZATION_REQUIRED if require_authorization else STATE_AUTHORIZED
self.error = ERROR_NONE
self.url = None
self.ip = None
self._require_authorization = require_authorization
self._authorized_until = None
self._connection = None
self.service = Service(SERVICE)
self._state = Characteristic(self.service, STATE, read=True, notify=True, initial=bytes((self.state,)))
self._error = Characteristic(self.service, ERROR, read=True, notify=True, initial=b"\x00")
self._rpc = Characteristic(
self.service, RPC, write=True, write_no_response=True, capture=True, max_len=MAX_MTU - 3
)
self._result = Characteristic(self.service, RESULT, read=True, notify=True, max_len=260)
self._caps = Characteristic(self.service, CAPABILITIES, read=True, initial=bytes((caps,)))
self._registered = False
# -- state
[docs]
def authorize(self):
"""Mark the device authorized for `AUTHORIZATION_MS` (from a button press)."""
if self.state == STATE_AUTHORIZATION_REQUIRED:
self._authorized_until = AUTHORIZATION_MS
self.state = STATE_AUTHORIZED
self._state.write(bytes((STATE_AUTHORIZED,)))
if self._connection is not None:
asyncio.create_task(self._notify(self._state, bytes((STATE_AUTHORIZED,))))
async def _set_state(self, state):
self.state = state
self._state.write(bytes((state,)))
await self._notify(self._state, bytes((state,)))
async def _set_error(self, error):
self.error = error
self._error.write(bytes((error,)))
await self._notify(self._error, bytes((error,)))
async def _notify(self, characteristic, data):
connection = self._connection
if connection is None:
return
size = connection.mtu - 3
for i in range(0, len(data), size):
while True:
try:
characteristic.notify(connection, data[i : i + size])
break
except BusyError:
await sleep_ms(2)
except DisconnectedError:
return
async def _send_result(self, command, *strings):
packet = pack(command, *strings)
self._result.write(packet)
await self._notify(self._result, packet)
# -- serving
def _register(self):
if not self._registered:
self.ble.register_services(self.service)
self._registered = True
[docs]
async def serve(self, timeout_ms=None):
"""Advertise until a client provisions the device; return the redirect URL (or IP).
``timeout_ms`` bounds each wait for a client to connect.
"""
self._register()
while True:
connection = await self.ble.advertise(
name=self.name,
services=[SERVICE],
service_data=[(SERVICE_DATA, service_data(self.state, self.capabilities))],
timeout_ms=timeout_ms,
)
if await self.session(connection):
return self.url if self.url is not None else self.ip
[docs]
async def session(self, connection):
"""Serve one connected client. True once the device is provisioned."""
self._connection = connection
buffer = bytearray()
clock = 0
try:
while connection.is_connected():
try:
writer, data = await self._rpc.written(timeout_ms=250)
except BLETimeoutError:
clock += 250
await self._tick(250)
if self.state == STATE_PROVISIONED and clock > 3000:
break # the client has had time to read the result
continue
if writer is not connection and writer != connection:
continue
buffer.extend(data)
while True:
size = packet_length(buffer)
if size is None or len(buffer) < size:
break
packet, buffer = bytes(buffer[:size]), buffer[size:]
clock = 0
await self._handle(packet)
finally:
self._connection = None
if connection.is_connected() and self.state == STATE_PROVISIONED:
try:
await connection.disconnect()
except BLEError:
pass
return self.state == STATE_PROVISIONED
async def _tick(self, ms):
if self._authorized_until is not None:
self._authorized_until -= ms
if self._authorized_until <= 0:
self._authorized_until = None
if self.state == STATE_AUTHORIZED:
await self._set_state(STATE_AUTHORIZATION_REQUIRED)
async def _handle(self, packet):
try:
command, strings = unpack(packet)
except ImprovError as e:
await self._set_error(e.code)
return
if command == CMD_WIFI_SETTINGS:
await self._wifi(strings)
elif command == CMD_IDENTIFY and self._identify is not None:
await self._set_error(ERROR_NONE)
self._identify()
elif command == CMD_DEVICE_INFO:
await self._set_error(ERROR_NONE)
await self._send_result(CMD_DEVICE_INFO, *self._device_info)
elif command == CMD_WIFI_SCAN and self._scan is not None:
await self._set_error(ERROR_NONE)
for ssid, rssi, secured in self._scan():
await self._send_result(CMD_WIFI_SCAN, ssid, str(rssi), "YES" if secured else "NO")
await self._send_result(CMD_WIFI_SCAN)
else:
await self._set_error(ERROR_UNKNOWN_RPC)
async def _wifi(self, strings):
if len(strings) != 2:
await self._set_error(ERROR_INVALID_RPC)
return
if self.state == STATE_AUTHORIZATION_REQUIRED:
await self._set_error(ERROR_NOT_AUTHORIZED)
return
ssid = strings[0].decode()
password = strings[1].decode()
await self._set_error(ERROR_NONE)
await self._set_state(STATE_PROVISIONING)
try:
ip = await self._join(ssid, password)
except Exception:
ip = None
if not ip:
await self._set_error(ERROR_UNABLE_TO_CONNECT)
await self._set_state(STATE_AUTHORIZATION_REQUIRED if self._require_authorization and self._authorized_until is None else STATE_AUTHORIZED)
return
self.ip = ip
self.url = self.redirect.format(ip=ip) if self.redirect else None
if self._on_join is not None:
self._on_join(ssid, password, ip)
await self._set_state(STATE_PROVISIONED)
if self.url:
await self._send_result(CMD_WIFI_SETTINGS, self.url)
else:
await self._send_result(CMD_WIFI_SETTINGS)
[docs]
async def serve(ble, name=None, *, timeout_ms=None, **options):
"""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`.
"""
return await Server(ble, name, **options).serve(timeout_ms)
# ---------------------------------------------------------------- the client side
[docs]
class Client:
"""A connection to an Improv device. Use `connect`, or `provision`."""
def __init__(self, connection, chars):
self.connection = connection
self._state, self._error, self._rpc, self._result, self._caps = chars
self._events = []
self._event = asyncio.Event()
self._tasks = []
self.capabilities = 0
[docs]
@classmethod
async def connect(cls, ble, name=None, *, device=None, timeout_ms=10000):
"""Find the device (by ``name``, or the first advertising Improv), connect, subscribe."""
if device is None:
device = await ble.find(name=name, service=SERVICE, timeout_ms=timeout_ms)
connection = await device.connect(timeout_ms=timeout_ms)
try:
try:
await connection.exchange_mtu(MAX_MTU)
except BLEError:
pass
service = await connection.service(SERVICE)
if service is None:
raise BLEError("{!r} has no Improv service".format(device))
chars = []
for uuid in (STATE, ERROR, RPC, RESULT, CAPABILITIES):
c = await service.characteristic(uuid)
if c is None:
raise BLEError("{!r}: the Improv service lacks {}".format(device, uuid))
chars.append(c)
client = cls(connection, chars)
await client._start()
except BaseException:
if connection.is_connected():
await connection.disconnect()
raise
return client
async def _start(self):
for kind, c in (("state", self._state), ("error", self._error), ("result", self._result)):
await c.subscribe(notify=True)
self._tasks.append(asyncio.create_task(self._watch(kind, c)))
caps = await self._caps.read()
self.capabilities = caps[0] if caps else 0
async def _watch(self, kind, characteristic):
try:
while True:
# Await first: ``self._events`` is replaced between commands.
data = await characteristic.notified()
self._events.append((kind, data))
self._event.set()
except BLEError as e:
self._events.append(("gone", e))
self._event.set()
async def _next_event(self, timeout_ms):
while not self._events:
self._event.clear()
await wait_ms(self._event.wait(), timeout_ms, "Improv reply")
return self._events.pop(0)
[docs]
async def state(self):
"""The device's current ``STATE_*``."""
return (await self._state.read())[0]
[docs]
async def error(self):
"""The device's current ``ERROR_*``."""
return (await self._error.read())[0]
async def close(self):
for task in self._tasks:
task.cancel()
self._tasks = []
if self.connection.is_connected():
await self.connection.disconnect()
async def _command(self, packet):
size = self.connection.mtu - 3
for i in range(0, len(packet), size):
await self._rpc.write(packet[i : i + size])
async def _results(self, command, timeout_ms):
"""Collect RPC results for ``command``; raise on a device error."""
buffer = bytearray()
while True:
kind, data = await self._next_event(timeout_ms)
if kind == "gone":
raise data
if kind == "error" and data and data[0] != ERROR_NONE:
raise ImprovError(data[0])
if kind == "state":
continue
if kind == "result":
buffer.extend(data)
size = packet_length(buffer)
if size is not None and len(buffer) >= size:
packet, buffer = bytes(buffer[:size]), buffer[size:]
got_command, strings = unpack(packet)
if got_command == command:
return strings
[docs]
async def send_wifi(self, ssid, password, timeout_ms=60000):
"""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).
"""
state = await self.state()
if state == STATE_AUTHORIZATION_REQUIRED:
state = await self._await_state(STATE_AUTHORIZED, timeout_ms)
self._events = []
await self._command(pack(CMD_WIFI_SETTINGS, ssid, password))
strings = await self._results(CMD_WIFI_SETTINGS, timeout_ms)
state = await self.state()
if state != STATE_PROVISIONED:
raise ImprovError(ERROR_UNKNOWN, "the device sent a result but reports state {}".format(state))
return strings[0].decode() if strings else ""
async def _await_state(self, want, timeout_ms):
while True:
try:
kind, data = await self._next_event(timeout_ms)
except BLETimeoutError:
raise ImprovError(ERROR_NOT_AUTHORIZED, "the device was not authorized in time")
if kind == "gone":
raise data
if kind == "state" and data and data[0] == want:
return want
[docs]
async def device_info(self, timeout_ms=5000):
"""``[firmware, version, chip, device name, ...]`` as strings."""
self._events = []
await self._command(pack(CMD_DEVICE_INFO))
return [s.decode() for s in await self._results(CMD_DEVICE_INFO, timeout_ms)]
async def identify(self):
await self._command(pack(CMD_IDENTIFY))
[docs]
async def scan(self, timeout_ms=20000):
"""``[(ssid, rssi, secured), ...]`` as the device sees them."""
self._events = []
await self._command(pack(CMD_WIFI_SCAN))
found = []
while True:
strings = await self._results(CMD_WIFI_SCAN, timeout_ms)
if not strings:
return found
found.append((strings[0].decode(), int(strings[1]), strings[2] == b"YES"))
[docs]
async def provision(ble, ssid, password, name=None, *, device=None, timeout_ms=60000):
"""Connect to an Improv device, send it ``ssid`` and ``password``, and return its redirect URL.
Raises `ImprovError` if it can't join.
"""
client = await Client.connect(ble, name, device=device, timeout_ms=min(timeout_ms, 20000))
try:
return await client.send_wifi(ssid, password, timeout_ms)
finally:
await client.close()