Skip to main content

Python Improv Client

PyPI version PyPI pyversions PyPI license

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_state and get_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 str fields, and device errors as exceptions
  • A protocol layer with no dependencies, for writing other transports
  • An improv-client command 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)

Source distribution for improv-client 1.0.0
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)

Table of built distributions (wheels) for improv-client 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page