esp-protocomm

A Python client for protocomm, Espressif's transport for ESP-IDF unified provisioning: the security1 handshake, the BLE transport, and Wi-Fi provisioning. It talks to any ESP32 device running protocomm, over Bluetooth Low Energy, from a laptop or a server.

Unofficial. Not affiliated with, endorsed by, or supported by Espressif Systems. Portions are adapted from ESP-IDF under the Apache License 2.0; see NOTICE for per-file attribution and a list of the changes made.

Install

pip install esp-protocomm          # the session: handshake, Wi-Fi provisioning
pip install "esp-protocomm[ble]"   # adds the radio (bleak)

The base install needs no Bluetooth stack, so the handshake and the protobuf schemas can be exercised in CI. Only BleTransport requires the extra.

Use

import asyncio
from esp_protocomm import Security1, establish_session, provision_wifi
from esp_protocomm.ble import BleTransport

async def main():
    async with BleTransport("XX:XX:XX:XX:XX:XX") as transport:
        security = await establish_session(transport, Security1(pop="abcd1234"))
        status = await provision_wifi(transport, security, ssid="my-network", passphrase="...")
        print(status)

asyncio.run(main())

The endpoint name-to-UUID map is read from the device's 0x2901 descriptors rather than hardcoded, so a product that registers its own endpoint alongside the standard ones works without changes here.

Scope

What this is: the protocomm session and the standard prov-session / prov-config endpoints.

What it is not: a device's own application commands. Those ride over the session this library establishes, on their own endpoint, and belong in that product's code. Keeping that boundary is why this is a separate library.

Security scheme support is security1 (X25519 key exchange, AES-CTR, proof-of-possession). The protobuf definitions for security0 and security2 are present because they ship together upstream, but only security1 has a client here.

Development

pip install -e ".[dev]"
pytest tests/ -v
ruff check . && ruff format --check .

Tests run against an in-process fake device that implements the device side of the handshake with the same primitives as the client, so they exercise the real key exchange, the real AES-CTR keystream, and the real framing. No radio, no hardware.

Releasing

Publishing uses PyPI Trusted Publishing (OIDC), so there is no API token in this repository and there should not be one. Tag a version and the Release workflow builds, checks that the wheel carries LICENSE and NOTICE, and publishes.

git tag v0.1.0 && git push origin v0.1.0

PyPI is configured to trust exactly one workflow. Two of these are easy to get wrong: the workflow name is a filename, not the name: declared inside it, and the environment must match the publishing job's environment: key.

Field	Value
Owner	electrification-bus
Repository	esp-protocomm
Workflow	release.yml
Environment	pypi

License

Apache-2.0. See LICENSE and NOTICE.