Serial transport

Install with pip install improv-client[serial].

The device must run Improv on its serial port, which ESPHome does on the USB serial port by default (improv_serial:). Improv frames share the port with the device log; the client skips everything that isn’t a valid frame.

The serial client has two commands BLE doesn’t have: request_current_state() and get_network_state(). It has no identify.

Improv Wi-Fi over a serial port.

Requires the serial extra: pip install improv-client[serial].

Example:

import asyncio
from improv_client.serial import ImprovSerialClient

async def main():
    async with ImprovSerialClient("/dev/ttyUSB0") as client:
        print(await client.request_current_state())
        print(await client.get_device_info())
        url = await client.provision("MyWirelessAP", "mysecurepassword")
        print("Provisioned, next step:", url)

asyncio.run(main())
improv_client.serial.DEFAULT_BAUDRATE = 115200

Baud rate used by ESPHome and most other Improv serial implementations.

class improv_client.serial.ImprovSerialClient(port, baudrate=115200, *, timeout=10.0, disconnected_callback=None, **serial_kwargs)[source]

Bases: ImprovClient

Client for an Improv Wi-Fi device on a serial port.

Parameters:
  • port (str) – Serial port, e.g. /dev/ttyUSB0 or COM3.

  • baudrate (int) – Baud rate.

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

  • disconnected_callback (Callable[[ImprovSerialClient], None] | None) – Called with the client when the port closes, whether through disconnect() or because the device went away.

  • serial_kwargs (Any) – Extra arguments for serial.Serial.

property connected: bool

True while connected to the device.

async connect()[source]

Open the serial port.

Opening the port doesn’t tell whether the device speaks Improv. Call request_current_state() to find out.

Raises:

ImprovConnectionError – If the port can’t be opened.

Return type:

None

async disconnect()[source]

Close the serial port.

Return type:

None

async request_current_state(*, timeout=None)[source]

Ask the device for its current state (command 0x02).

A device that is already provisioned also sends the provisioning result again; that result is ignored here.

Raises:

ImprovTimeoutError – If the device doesn’t answer, which usually means it doesn’t run Improv on this port.

Parameters:

timeout (float | None)

Return type:

State

async get_network_state()[source]

Request the network flags and the device URLs (command 0x07).

This command is optional.

Raises:

ImprovNotSupportedError – If the device doesn’t implement it.

Return type:

NetworkState

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