BLE transport
Install with pip install improv-client[ble].
Find devices with discover(), or pass a
bleak.backends.device.BLEDevice from your own scanner (for example the
Home Assistant Bluetooth integration) to ImprovBleClient.
Devices may start in AUTHORIZATION_REQUIRED
and need a button press before they accept credentials. Wait for that with
wait_for_state().
Commands that the device’s capabilities don’t include raise
ImprovNotSupportedError without being sent.
The device name commands have no capability bit and are always sent.
Improv Wi-Fi over Bluetooth Low Energy.
Requires the ble extra: pip install improv-client[ble]. Built on
bleak and
bleak-retry-connector.
The client connects on demand: every command connects first if needed, and the connection closes after a period without commands (90 seconds by default). This follows the design of py-improv-ble-client (MIT), as do the retrying connector and matching results to commands by command id.
Example:
import asyncio
from improv_client.ble import ImprovBleClient, discover
from improv_client.protocol import State
async def main():
devices = await discover()
if not devices:
return
async with ImprovBleClient(devices[0].device) as client:
if client.state is State.AUTHORIZATION_REQUIRED:
print("Press the button on the device")
await client.wait_for_state(State.AUTHORIZED, timeout=60)
url = await client.provision("MyWirelessAP", "mysecurepassword")
print("Provisioned, next step:", url)
asyncio.run(main())
- improv_client.ble.DEFAULT_IDLE_DISCONNECT_DELAY = 90.0
Seconds without commands before the client disconnects.
- class improv_client.ble.DiscoveredDevice(device, name, rssi, service_data)[source]
Bases:
objectAn Improv device found by
discover().- Variables:
device – The bleak device, pass this to
ImprovBleClient.name – Advertised name, if any.
rssi – Signal strength in dBm.
service_data – State and capabilities from the advertisement, if present.
- Parameters:
device (bleak.backends.device.BLEDevice)
name (str | None)
rssi (int | None)
service_data (ServiceData | None)
- class improv_client.ble.ImprovBleClient(device, *, timeout=10.0, idle_disconnect_delay=90.0, disconnected_callback=None)[source]
Bases:
ImprovClientClient for an Improv Wi-Fi device over BLE.
Commands connect automatically, so calling
connect()first is optional.- Parameters:
device (BLEDevice) – The device, from
discover(),find_device()or a bleak scanner.timeout (float) – Default time in seconds to wait for an answer.
idle_disconnect_delay (float | None) – Seconds without commands before disconnecting, or
Noneto stay connected untildisconnect().disconnected_callback (Callable[[ImprovBleClient], None] | None) – Called with the client whenever the connection closes, including idle and explicit disconnects.
- property capabilities: Capabilities | None
Capabilities read from the device, or
Nonebefore the first connection.
- set_ble_device(device)[source]
Replace the device used for the next connection, e.g. from a newer advertisement.
- Parameters:
device (bleak.backends.device.BLEDevice)
- Return type:
None
- async connect()[source]
Connect, read capabilities, state and error, and subscribe to notifications.
- Raises:
ImprovConnectionError – If connecting fails or the device has no Improv service.
- Return type:
None
- async identify()[source]
Ask the device to identify itself, e.g. by blinking a LED.
- Raises:
ImprovNotSupportedError – If the device lacks the identify capability.
- Return type:
None
- async get_device_info()
Request firmware, hardware and device name information.
- Return type:
- async provision(ssid, password, *, timeout=60.0)
Send Wi-Fi credentials and wait until the device has connected.
- Parameters:
- Returns:
The URL the device wants the user to open next, or
None.- Raises:
ImprovDeviceError – With
UNABLE_TO_CONNECTif the credentials didn’t work, orNOT_AUTHORIZEDon an unauthorized BLE device.- Return type:
str | None
- register_error_callback(callback)
Call
callbackwhenever the device error state changes.
- register_state_callback(callback)
Call
callbackwhenever the device state changes.
- async scan_wifi(*, timeout=30.0)
Ask the device to scan for Wi-Fi networks.
- Parameters:
timeout (float) – Seconds to wait for the scan to finish.
- Returns:
The networks found, in the order the device sent them.
- Return type:
- async set_device_name(name)
Set the user-facing device name.
The device must be authorized. If you set both, set the device name before the hostname.
- async set_hostname(hostname)
Set the device hostname.
The device must be authorized. Hostnames may contain letters, digits and hyphens (RFC 1123).
- Returns:
The hostname reported back by the device.
- Raises:
ImprovDeviceError – With
BAD_HOSTNAMEif the device rejects the hostname.- Parameters:
hostname (str)
- Return type:
- async wait_for_state(*states, timeout=None)
Wait until the device reports one of
states.Returns at once if the current state already matches. On BLE, use this to wait for the user to authorize the device:
await client.wait_for_state(State.AUTHORIZED, timeout=60).- Parameters:
- Returns:
The matching state.
- Raises:
ImprovTimeoutError – If no matching state arrives in time.
ImprovConnectionError – If the connection is lost while waiting.
- Return type:
- async improv_client.ble.discover(timeout=5.0, **scanner_kwargs)[source]
Scan for Improv devices.
- Parameters:
timeout (float) – Seconds to scan.
scanner_kwargs (Any) – Extra arguments for
bleak.BleakScanner.
- Returns:
The devices found, strongest signal first.
- Return type:
- async improv_client.ble.find_device(address, timeout=10.0)[source]
Find a device by address (a UUID on macOS), or
Noneif not seen in time.
- improv_client.ble.is_improv_advertisement(advertisement)[source]
Trueif the advertisement carries the Improv service UUID or service data.- Parameters:
advertisement (bleak.backends.scanner.AdvertisementData)
- Return type:
- improv_client.ble.service_data_from_advertisement(advertisement)[source]
Return the parsed Improv service data, or
Noneif it’s missing or invalid.- Parameters:
advertisement (bleak.backends.scanner.AdvertisementData)
- Return type:
ServiceData | None