Protocol

Everything here is transport independent and has no third-party dependencies. The clients use it internally; you need it for the enums and result types, or to implement another transport.

Notes the specification leaves implicit:

  • The serial checksum is the sum of every frame byte from IMPROV through the data, keeping the low byte. Clients write a newline after each frame.

  • The RPC payload inside a serial frame has no checksum of its own. On BLE, the checksum is appended to the RPC payload.

  • On serial, a Wi-Fi scan returns one result per network, then an empty result. On BLE it returns one result with three strings per network.

Transport-independent parts of the Improv Wi-Fi protocol.

This module has no third-party dependencies. It contains the protocol constants and enums, the RPC encoding and decoding shared by serial and BLE, the serial frame codec, BLE service data parsing, and the dataclasses returned by the clients.

Specifications:

Example, encoding the Wi-Fi settings command from the specification:

>>> payload = encode_rpc_command(Command.WIFI_SETTINGS,
...                              encode_wifi_settings("MyWirelessAP", "mysecurepassword"))
>>> payload[:3].hex(" ")
'01 1e 0c'
improv_client.protocol.BLE_CAPABILITIES_UUID = '00467768-6228-2272-4663-277478268005'

Capabilities characteristic (read).

improv_client.protocol.BLE_CURRENT_STATE_UUID = '00467768-6228-2272-4663-277478268001'

Current state characteristic (read, notify).

improv_client.protocol.BLE_ERROR_STATE_UUID = '00467768-6228-2272-4663-277478268002'

Error state characteristic (read, notify).

improv_client.protocol.BLE_RPC_COMMAND_UUID = '00467768-6228-2272-4663-277478268003'

RPC command characteristic (write).

improv_client.protocol.BLE_RPC_RESULT_UUID = '00467768-6228-2272-4663-277478268004'

RPC result characteristic (read, notify).

improv_client.protocol.BLE_SERVICE_DATA_UUID = '00004677-0000-1000-8000-00805f9b34fb'

UUID of the service data in the advertisement (16-bit 4677).

improv_client.protocol.BLE_SERVICE_UUID = '00467768-6228-2272-4663-277478268000'

Improv GATT service.

improv_client.protocol.SERIAL_HEADER = b'IMPROV'

Header that starts every serial frame.

improv_client.protocol.SERIAL_VERSION = 1

Serial protocol version this library speaks.

class improv_client.protocol.Capabilities(*values)[source]

Bases: IntFlag

Capabilities advertised by a BLE device.

class improv_client.protocol.Command(*values)[source]

Bases: IntEnum

RPC command identifiers.

IDENTIFY = 2

Ask the device to identify itself, e.g. by blinking a LED (BLE only).

NETWORK_STATE = 7

Request the network state (serial only).

REQUEST_CURRENT_STATE = 2

Alias of IDENTIFY. On serial, command 0x02 requests the current state.

class improv_client.protocol.DeviceInfo(firmware_name, firmware_version, hardware, device_name, os_name=None, os_version=None)[source]

Bases: object

Device information returned by Command.DEVICE_INFO.

Variables:
  • firmware_name – Firmware name, e.g. ESPHome.

  • firmware_version – Firmware version.

  • hardware – Hardware chip or variant, e.g. esp32-s3-devkitc-1/esp32-s3.

  • device_name – User-facing device name.

  • os_name – Operating system name, sent by newer devices (e.g. ESPHome 2025.12 and later, where firmware_name is the project name instead).

  • os_version – Operating system version, when sent.

Parameters:
  • firmware_name (str)

  • firmware_version (str)

  • hardware (str)

  • device_name (str)

  • os_name (str | None)

  • os_version (str | None)

classmethod from_strings(strings)[source]

Build from the result strings.

>>> DeviceInfo.from_strings(["ESPHome", "2021.11.0", "esp32", "Temp"]).os_name is None
True
Raises:

ImprovProtocolError – If fewer than 4 strings were returned.

Parameters:

strings (Sequence[str])

Return type:

DeviceInfo

class improv_client.protocol.Error(*values)[source]

Bases: IntEnum

Error state reported by the device.

NOT_AUTHORIZED = 4

Credentials were sent but the device isn’t authorized (BLE only).

classmethod parse(value)[source]

Convert a raw error byte, mapping unknown values to UNKNOWN.

>>> Error.parse(3).name
'UNABLE_TO_CONNECT'
>>> Error.parse(0x42).name
'UNKNOWN'
Parameters:

value (int)

Return type:

Error

class improv_client.protocol.NetworkFlags(*values)[source]

Bases: IntFlag

Flags returned by Command.NETWORK_STATE.

ONLINE = 1

The device currently has network connectivity.

WIFI = 2

The device has a Wi-Fi interface (it may be disabled).

class improv_client.protocol.NetworkState(flags, urls=())[source]

Bases: object

Network state returned by Command.NETWORK_STATE.

Variables:
  • flags – Network interface and connectivity flags.

  • urls – URLs for the device, only present while online.

Parameters:
property online: bool

True if the device currently has network connectivity.

classmethod from_strings(strings)[source]

Build from the result strings: flags as a decimal string, then URLs.

>>> NetworkState.from_strings(["7", "http://192.168.1.10"]).online
True
Raises:

ImprovProtocolError – If the flags are missing or not a number.

Parameters:

strings (Sequence[str])

Return type:

NetworkState

class improv_client.protocol.PacketType(*values)[source]

Bases: IntEnum

Serial packet types.

class improv_client.protocol.RpcResult(command, strings)[source]

Bases: object

A decoded RPC result.

Variables:
  • command – The command this is a result for. A Command when known.

  • strings – The strings in the result. May be empty.

Parameters:
class improv_client.protocol.SerialPacket(packet_type, data)[source]

Bases: object

A decoded serial frame.

Variables:
  • packet_type – A PacketType when known, otherwise the raw byte.

  • data – The frame data, without header, length and checksum.

Parameters:
class improv_client.protocol.SerialPacketDecoder[source]

Bases: object

Incremental decoder that finds Improv frames in a serial byte stream.

Devices usually log text on the same port, so anything that isn’t a valid frame is skipped. Feed it bytes as they arrive; it returns the complete frames found so far and keeps any partial frame for the next call.

>>> decoder = SerialPacketDecoder()
>>> frame = encode_serial_packet(PacketType.CURRENT_STATE, b"\x02")
>>> decoder.feed(b"[I][log]: hello\n" + frame[:5])
[]
>>> decoder.feed(frame[5:] + b"\n")
[SerialPacket(packet_type=<PacketType.CURRENT_STATE: 1>, data=b'\x02')]
reset()[source]

Drop any buffered data.

Return type:

None

feed(data)[source]

Add received bytes and return the complete frames found.

Parameters:

data (bytes)

Return type:

list[SerialPacket]

class improv_client.protocol.ServiceData(state, capabilities)[source]

Bases: object

Improv service data from a BLE advertisement.

Variables:
  • state – Current provisioning state.

  • capabilities – Supported optional commands.

Parameters:
class improv_client.protocol.State(*values)[source]

Bases: IntEnum

Current provisioning state of the device.

STOPPED = 0

Provisioning is unavailable, for example because Wi-Fi is turned off (serial only).

AUTHORIZATION_REQUIRED = 1

Waiting for authorization through physical interaction (BLE only).

AUTHORIZED = 2

Ready to accept credentials.

PROVISIONING = 3

Credentials received, trying to connect.

PROVISIONED = 4

Connected to the network.

READY = 2

Alias of AUTHORIZED, the name the serial specification uses.

class improv_client.protocol.WifiNetwork(ssid, rssi, auth)[source]

Bases: object

A network found by Command.SCAN_WIFI.

Variables:
  • ssid – Network name.

  • rssi – Signal strength in dBm.

  • auth – Authentication as reported by the device. Serial devices send YES or NO; BLE devices send a type such as WPA2 or WPA/WPA2, or NO.

Parameters:
property secured: bool

True unless the device reported the network as open (NO).

classmethod from_strings(strings)[source]

Build from SSID, RSSI and auth strings.

>>> WifiNetwork.from_strings(["MyWirelessNetwork", "-60", "YES"])
WifiNetwork(ssid='MyWirelessNetwork', rssi=-60, auth='YES')
Raises:

ImprovProtocolError – If there are fewer than 3 strings or the RSSI isn’t a number.

Parameters:

strings (Sequence[str])

Return type:

WifiNetwork

improv_client.protocol.checksum(data)[source]

Return the Improv checksum: the sum of all bytes, keeping only the low byte.

>>> checksum(bytes([0x03, 0x00]))
3
>>> checksum(bytes([0xff, 0x02]))
1
Parameters:

data (bytes)

Return type:

int

improv_client.protocol.decode_ble_rpc_result(payload)[source]

Decode an RPC result read from the BLE RPC result characteristic.

The last byte is a checksum over everything before it.

Raises:

ImprovProtocolError – If the checksum doesn’t match or the payload is truncated.

Parameters:

payload (bytes)

Return type:

RpcResult

improv_client.protocol.decode_rpc_result(payload)[source]

Decode an RPC result without a checksum, as carried in a serial frame.

>>> decode_rpc_result(bytes([0x05, 0x04, 0x03]) + b"abc")
RpcResult(command=<Command.HOSTNAME: 5>, strings=('abc',))
Raises:

ImprovProtocolError – If the payload is truncated or malformed.

Parameters:

payload (bytes)

Return type:

RpcResult

improv_client.protocol.decode_strings(data)[source]

Decode a sequence of length-prefixed UTF-8 strings.

Invalid UTF-8 is replaced rather than rejected, since device names come from firmware we don’t control.

>>> decode_strings(b"\x03abc\x00\x01d")
['abc', '', 'd']
Raises:

ImprovProtocolError – If a length prefix runs past the end of the data.

Parameters:

data (bytes)

Return type:

list[str]

improv_client.protocol.encode_ble_rpc_command(command, data=b'')[source]

Encode an RPC command for BLE, with the checksum appended.

>>> encode_ble_rpc_command(Command.DEVICE_INFO).hex(" ")
'03 00 03'
Parameters:
Return type:

bytes

improv_client.protocol.encode_rpc_command(command, data=b'')[source]

Encode an RPC command: command, data length, data.

This is the payload used inside a serial frame. Use encode_ble_rpc_command() for BLE, which adds a checksum.

>>> encode_rpc_command(Command.DEVICE_INFO).hex(" ")
'03 00'
Parameters:
Return type:

bytes

improv_client.protocol.encode_serial_packet(packet_type, data)[source]

Encode a serial frame: IMPROV, version, type, length, data, checksum.

The checksum covers every byte from the header through the data. Clients write a newline after the frame; that isn’t part of the frame and isn’t added here.

>>> encode_serial_packet(PacketType.RPC_COMMAND, bytes([0x03, 0x00])).hex(" ")
'49 4d 50 52 4f 56 01 03 02 03 00 e6'
Parameters:
Return type:

bytes

improv_client.protocol.encode_string(value)[source]

Encode a string as UTF-8 with a one byte length prefix.

>>> encode_string("abc")
b'\x03abc'
Raises:

ValueError – If the encoded string is longer than 255 bytes.

Parameters:

value (str | bytes)

Return type:

bytes

improv_client.protocol.encode_strings(values)[source]

Encode a sequence of length-prefixed strings.

Parameters:

values (Iterable[str | bytes])

Return type:

bytes

improv_client.protocol.encode_wifi_settings(ssid, password)[source]

Encode the data part of Command.WIFI_SETTINGS.

>>> encode_wifi_settings("ab", "c")
b'\x02ab\x01c'
Parameters:
Return type:

bytes

improv_client.protocol.parse_service_data(data)[source]

Parse the Improv service data (UUID 4677) from a BLE advertisement.

>>> parse_service_data(bytes([0x02, 0x03, 0, 0, 0, 0])).state.name
'AUTHORIZED'
Raises:

ImprovProtocolError – If the data is too short or the state is unknown.

Parameters:

data (bytes)

Return type:

ServiceData

improv_client.protocol.parse_state(value)[source]

Convert a raw state byte to a State.

Raises:

ImprovProtocolError – If the value isn’t a known state.

Parameters:

value (int)

Return type:

State

improv_client.protocol.parse_wifi_networks(strings)[source]

Parse a BLE scan result: SSID, RSSI and auth repeated for each network.

Raises:

ImprovProtocolError – If the number of strings isn’t a multiple of 3.

Parameters:

strings (Sequence[str])

Return type:

list[WifiNetwork]