improv-client documentation
- Author:
Jonny Bergdahl
- Version:
1.0.0
Python Improv Client
Python library that implements an Improv Wi-Fi client, for provisioning Wi-Fi credentials to devices over serial and Bluetooth Low Energy (BLE).
Full documentation: https://jonnybergdahl.github.io/improv-client/
Features
Async (
asyncio) clients for both transports: serial (pyserial-asyncio) and BLE (bleak with bleak-retry-connector)The same API on both:
provision,get_device_info,scan_wifi,get_hostname/set_hostname,get_device_name/set_device_name,wait_for_state, plus state and error callbacksSerial only:
request_current_stateandget_network_stateBLE only:
identify, discovery with advertised state and capabilities, connect on demand and disconnect when idleHandles device info with OS name and version (ESPHome 2025.12 and later)
Results come back as dataclasses with
strfields, and device errors as exceptionsA protocol layer with no dependencies, for writing other transports
An
improv-clientcommand line tool
Installation
Install with the extra for the transport you need:
pip install improv-client[serial] # serial only
pip install improv-client[ble] # BLE only
pip install improv-client[all] # both
Python 3.10 or newer is required.
Usage
Serial
import asyncio
from improv_client.serial import ImprovSerialClient
async def main():
async with ImprovSerialClient("/dev/ttyUSB0") as client:
print("State:", (await client.request_current_state()).name)
info = await client.get_device_info()
print(info.firmware_name, info.firmware_version, info.device_name)
for network in await client.scan_wifi():
print(network.ssid, network.rssi, network.secured)
url = await client.provision("MyWirelessAP", "mysecurepassword")
print("Provisioned, next step:", url)
asyncio.run(main())
BLE
import asyncio
from improv_client import State
from improv_client.ble import ImprovBleClient, discover
async def main():
devices = await discover()
if not devices:
print("No Improv devices found")
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())
The BLE client also connects by itself when you call a command, and
disconnects after 90 seconds without commands. Pass
idle_disconnect_delay=None to stay connected.
Errors
Every exception derives from ImprovError:
Exception |
Raised when |
|---|---|
|
The device reported an error,
e.g. |
|
The device doesn’t support the command |
|
The device didn’t answer in time (also a
|
|
Connecting failed or the connection was lost |
|
The device sent data that couldn’t be parsed |
Command line tool
improv-client discover
improv-client serial /dev/ttyUSB0 state
improv-client serial /dev/ttyUSB0 info
improv-client serial /dev/ttyUSB0 network
improv-client serial /dev/ttyUSB0 provision MyWirelessAP # prompts for the password
improv-client ble AA:BB:CC:DD:EE:FF scan
improv-client ble AA:BB:CC:DD:EE:FF hostname new-hostname
improv-client ble AA:BB:CC:DD:EE:FF identify
On macOS, BLE addresses are UUIDs. Use the one discover prints. Add
-v to log the protocol traffic.
Development
pip install -e .[dev]
pytest
./build.sh # builds the docs
Credits
The BLE client borrows design ideas from py-improv-ble-client (MIT): the retrying connector, disconnecting when idle, and matching results to commands by command id.
API reference
- Serial transport
- BLE transport
- Shared client API
- Protocol
BLE_CAPABILITIES_UUIDBLE_CURRENT_STATE_UUIDBLE_ERROR_STATE_UUIDBLE_RPC_COMMAND_UUIDBLE_RPC_RESULT_UUIDBLE_SERVICE_DATA_UUIDBLE_SERVICE_UUIDSERIAL_HEADERSERIAL_VERSIONCapabilitiesCommandDeviceInfoErrorNetworkFlagsNetworkStatePacketTypeRpcResultSerialPacketSerialPacketDecoderServiceDataStateWifiNetworkchecksum()decode_ble_rpc_result()decode_rpc_result()decode_strings()encode_ble_rpc_command()encode_rpc_command()encode_serial_packet()encode_string()encode_strings()encode_wifi_settings()parse_service_data()parse_state()parse_wifi_networks()
- Exceptions