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:
ImprovClientClient for an Improv Wi-Fi device on a serial port.
- Parameters:
port (str) – Serial port, e.g.
/dev/ttyUSB0orCOM3.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.
- 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 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:
- 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:
- 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: