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 callbacks - Serial only:
request_current_stateandget_network_state - BLE only:
identify, discovery with advertised state and capabilities, connect on demand and disconnect when idle - Handles device info with OS name and version (ESPHome 2025.12 and later)
- Results come back as dataclasses with
strfields, and device errors as exceptions - A 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 |
|---|---|
ImprovDeviceError |
The device reported an error, e.g. Error.UNABLE_TO_CONNECT for wrong credentials |
ImprovNotSupportedError |
The device doesn't support the command |
ImprovTimeoutError |
The device didn't answer in time (also a TimeoutError) |
ImprovConnectionError |
Connecting failed or the connection was lost |
ImprovProtocolError |
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.
Metadata
Release files for improv-client 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| improv_client-1.0.0.tar.gz | 29.9 kB | Without provenance | Details for improv_client-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| improv_client-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for improv_client-1.0.0-py3-none-any.whl |
Total release size: 55.5 kB
Release files / improv_client-1.0.0.tar.gz
| Download URL | improv_client-1.0.0.tar.gz |
|---|---|
| Size | 29.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e414a34b7c313b7fcbd26e38dd3510f48ab17ff786ed8dc80ea296e045e4f526
|
|
BLAKE2b-256 checksum How to use checksums |
eb930d9e1cbc7fb0a45d94275a5daf81907f721d1452ca21d432d37370102108
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.5
|
Release files / improv_client-1.0.0-py3-none-any.whl
| Download URL | improv_client-1.0.0-py3-none-any.whl |
|---|---|
| Size | 25.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9320bc62af7fe83e4ca53816cb981f23b8b3682ce5262cfca35f88c2449ed995
|
|
BLAKE2b-256 checksum How to use checksums |
9867921ef5a0bc0d7b207ad84ce27c0d49d342cc3bc823e1d3fd8a2e8ec4a319
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.5
|
Security for improv-client 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.