Shared client API

Both transports derive from ImprovClient, so code that only uses the methods below works with either of them.

Shared client logic for the serial and BLE transports.

ImprovClient holds the API both transports have in common. Use ImprovSerialClient or ImprovBleClient to talk to a device.

improv_client.client.DEFAULT_TIMEOUT = 10.0

Default time to wait for an answer, in seconds.

improv_client.client.DEFAULT_PROVISION_TIMEOUT = 60.0

Default time to wait for provisioning to finish, in seconds.

improv_client.client.DEFAULT_SCAN_TIMEOUT = 30.0

Default time to wait for a Wi-Fi scan, in seconds.

class improv_client.client.ImprovClient(*, timeout=10.0)[source]

Bases: ABC

Base class with the API shared by all transports.

Only one command runs at a time; concurrent calls wait for each other. The client can be used as an async context manager, which connects on entry and disconnects on exit.

Parameters:

timeout (float) – Default time in seconds to wait for an answer.

abstract property connected: bool

True while connected to the device.

abstractmethod async connect()[source]

Connect to the device.

Raises:

ImprovConnectionError – If the connection fails.

Return type:

None

abstractmethod async disconnect()[source]

Disconnect from the device. Does nothing if not connected.

Return type:

None

property state: State | None

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

property error: Error

The last error state reported by the device.

register_state_callback(callback)[source]

Call callback whenever the device state changes.

Returns:

A function that removes the callback again.

Parameters:

callback (Callable[[State], None])

Return type:

Callable[[], None]

register_error_callback(callback)[source]

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]

async wait_for_state(*states, timeout=None)[source]

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 provision(ssid, password, *, timeout=60.0)[source]

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

async get_device_info()[source]

Request firmware, hardware and device name information.

Return type:

DeviceInfo

async scan_wifi(*, timeout=30.0)[source]

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

Request the device hostname.

Return type:

str

async set_hostname(hostname)[source]

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

async get_device_name()[source]

Request the user-facing device name.

Return type:

str

async set_device_name(name)[source]

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