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: object

An 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:
property address: str

The Bluetooth address (a UUID on macOS).

class improv_client.ble.ImprovBleClient(device, *, timeout=10.0, idle_disconnect_delay=90.0, disconnected_callback=None)[source]

Bases: ImprovClient

Client 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 None to stay connected until disconnect().

  • disconnected_callback (Callable[[ImprovBleClient], None] | None) – Called with the client whenever the connection closes, including idle and explicit disconnects.

property address: str

The Bluetooth address of the device.

property capabilities: Capabilities | None

Capabilities read from the device, or None before the first connection.

property connected: bool

True while connected to the device.

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 disconnect()[source]

Disconnect from the device.

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

property error: Error

The last error state reported by the device.

async get_device_info()

Request firmware, hardware and device name information.

Return type:

DeviceInfo

async get_device_name()

Request the user-facing device name.

Return type:

str

async get_hostname()

Request the device hostname.

Return type:

str

async provision(ssid, password, *, timeout=60.0)

Send Wi-Fi credentials and wait until the device has connected.

Parameters:
  • ssid (str) – Network name.

  • password (str) – Network password, empty for an open network.

  • timeout (float) – Seconds to wait for the device to connect.

Returns:

The URL the device wants the user to open next, or None.

Raises:

ImprovDeviceError – With UNABLE_TO_CONNECT if the credentials didn’t work, or NOT_AUTHORIZED on an unauthorized BLE device.

Return type:

str | None

register_error_callback(callback)

Call callback whenever the device error state changes.

Returns:

A function that removes the callback again.

Parameters:

callback (Callable[[Error], None])

Return type:

Callable[[], None]

register_state_callback(callback)

Call callback whenever the device state changes.

Returns:

A function that removes the callback again.

Parameters:

callback (Callable[[State], None])

Return type:

Callable[[], None]

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:

list[WifiNetwork]

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.

Returns:

The device name reported back by the device.

Parameters:

name (str)

Return type:

str

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_HOSTNAME if the device rejects the hostname.

Parameters:

hostname (str)

Return type:

str

property state: State | None

The last state reported by the device, or None if none has been seen.

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:
  • timeout (float | None) – Seconds to wait, or None to wait forever.

  • states (State)

Returns:

The matching state.

Raises:
Return type:

State

async improv_client.ble.discover(timeout=5.0, **scanner_kwargs)[source]

Scan for Improv devices.

Parameters:
Returns:

The devices found, strongest signal first.

Return type:

list[DiscoveredDevice]

async improv_client.ble.find_device(address, timeout=10.0)[source]

Find a device by address (a UUID on macOS), or None if not seen in time.

Parameters:
Return type:

BLEDevice | None

improv_client.ble.is_improv_advertisement(advertisement)[source]

True if the advertisement carries the Improv service UUID or service data.

Parameters:

advertisement (bleak.backends.scanner.AdvertisementData)

Return type:

bool

improv_client.ble.service_data_from_advertisement(advertisement)[source]

Return the parsed Improv service data, or None if it’s missing or invalid.

Parameters:

advertisement (bleak.backends.scanner.AdvertisementData)

Return type:

ServiceData | None