Thanks for your interest in contributing! esp-protocomm is a Python client for protocomm, Espressif's transport for ESP-IDF unified provisioning: the security1 handshake, the BLE transport, and Wi-Fi provisioning. It is deliberately vendor-neutral, applies to any ESP32 device running protocomm, and has no coupling to any particular product that consumes it.
This is an unofficial client. It is not affiliated with, endorsed by, or supported by Espressif Systems.
Use Discussions for:
- Open-ended questions about protocomm, ESP-IDF unified provisioning, or how a device's own endpoint should be modeled on top of the session.
- Proposals for new capabilities (a security scheme beyond security1, an additional transport, a higher-level provisioning workflow) worth aligning on before writing the code.
- Reports of behavior against real hardware that differs from what the client expects.
- Thinking out loud about a change before scoping it.
Use Issues for actionable changes:
- Bug reports with reproduction steps. For a handshake or framing problem, the useful detail is the endpoint, the bytes sent, and the bytes received.
- Divergences from ESP-IDF's own implementation, citing the upstream file.
- Concrete feature requests with a clear scope and use case.
- Documentation gaps.
If you are not sure whether something is an Issue or a Discussion, start with a Discussion.
Pull requests are welcome.
- For small fixes (a codec correction with a test, a docstring tweak, a low-risk bug fix with a test), open a PR directly.
- For substantive changes (a new security scheme, a change to the
TransportorSecurity1API, a new dependency), open a Discussion or Issue first so we can align on scope. - Keep it vendor-neutral. Protocomm applies to any ESP32 device, which is why this is a separate library. A device's own application commands ride over the session on their own endpoint and belong in that product's code, not here. The endpoint name-to-UUID map is read from the device's
0x2901descriptors precisely so a product adding an endpoint needs no change here; keep it that way. - Do not guess wire formats. The protobuf schemas and the handshake come from ESP-IDF. When a change is normative, cite the upstream file it follows. If you cannot check it against ESP-IDF, say so in the PR rather than inferring.
- Attribution is not optional. Code adapted from ESP-IDF must be recorded in
NOTICEwith the upstream path and a description of what was changed. That file is what makes the Apache-2.0 obligations verifiable rather than asserted, and the release workflow refuses to publish a wheel that does not carry it. - Never commit secrets or captured device data. Proofs of possession, Wi-Fi credentials, device identifiers and real captures stay out of this repo. Tests use synthetic values throughout.
- Prefer tests that exercise the real thing.
tests/fake_device.pyimplements the device side of the handshake with the same primitives as the client, so the suite runs the real X25519 exchange, the real AES-CTR keystream and the real framing over an in-process link. A test that asserts agreement between two mocks proves very little; extend the fake device instead. - Lint and test before sending. The repo enforces ruff and pytest. Run
ruff check .,ruff format --check ., andpytest tests/locally; CI runs them on Python 3.10 and 3.12. - Keep comments to a minimum. Prefer self-explanatory code, with comments reserved for non-obvious why (a protocol quirk, a deliberate divergence from upstream).
CI cannot exercise the BLE transport, which needs a radio. For a step closer to reality, point the client at an ESP32 dev board running ESP-IDF's wifi_prov_mgr example. State in the PR what you exercised against real hardware and what you did not.
Be respectful and constructive. We appreciate everyone who files an issue, starts a discussion, or sends a pull request.
esp-protocomm is an active alpha project. Updates and maintenance, including responses to issues, take place on an "as time and resources permit" basis.