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
IMPROVthrough 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:
IntFlagCapabilities advertised by a BLE device.
- class improv_client.protocol.Command(*values)[source]
Bases:
IntEnumRPC 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).
- class improv_client.protocol.DeviceInfo(firmware_name, firmware_version, hardware, device_name, os_name=None, os_version=None)[source]
Bases:
objectDevice 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_nameis the project name instead).os_version – Operating system version, when sent.
- Parameters:
- 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:
- Return type:
- class improv_client.protocol.Error(*values)[source]
Bases:
IntEnumError state reported by the device.
- NOT_AUTHORIZED = 4
Credentials were sent but the device isn’t authorized (BLE only).
- class improv_client.protocol.NetworkFlags(*values)[source]
Bases:
IntFlagFlags 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:
objectNetwork state returned by
Command.NETWORK_STATE.- Variables:
flags – Network interface and connectivity flags.
urls – URLs for the device, only present while online.
- Parameters:
flags (NetworkFlags)
- 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:
- Return type:
- class improv_client.protocol.RpcResult(command, strings)[source]
Bases:
objectA decoded RPC result.
- class improv_client.protocol.SerialPacket(packet_type, data)[source]
Bases:
objectA decoded serial frame.
- Variables:
packet_type – A
PacketTypewhen known, otherwise the raw byte.data – The frame data, without header, length and checksum.
- Parameters:
- class improv_client.protocol.SerialPacketDecoder[source]
Bases:
objectIncremental 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')]
- class improv_client.protocol.ServiceData(state, capabilities)[source]
Bases:
objectImprov service data from a BLE advertisement.
- Variables:
state – Current provisioning state.
capabilities – Supported optional commands.
- Parameters:
state (State)
capabilities (Capabilities)
- class improv_client.protocol.State(*values)[source]
Bases:
IntEnumCurrent 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:
objectA 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
YESorNO; BLE devices send a type such asWPA2orWPA/WPA2, orNO.
- Parameters:
- 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:
- Return type:
- 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
- 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:
- 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:
- 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:
- 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'
- 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'
- 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'
- 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:
- Return type:
- improv_client.protocol.encode_strings(values)[source]
Encode a sequence of length-prefixed strings.
- 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'
- 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:
- 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:
- 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:
- Return type: