EmBody protocol codec
This is a Python based implementation library for the Aidee EmBody communication protocol.
Features
- High-performance message decoding with O(1) lookup using optimized message registries
- Comprehensive protocol support for all EmBody message types
- Robust error handling with detailed error messages and optional CRC validation bypass
- Type-safe implementations with full type annotations for better IDE support
- Zero dependencies for the core library
- Extensive test coverage ensuring protocol compliance
Requirements
- This library does not require any external libraries
- Requires Python 3.12+
Installation
You can install embody codec via pip from PyPI:
pip install embody-codec
Usage Examples
Basic Message Encoding/Decoding
from embodycodec import codec
# Create and encode a heartbeat message
heartbeat = codec.Heartbeat()
encoded_data = heartbeat.encode()
# Decode received data
decoded_msg = codec.decode(encoded_data)
print(f"Received: {type(decoded_msg).__name__}")
Working with Attributes
from embodycodec import codec, attributes
# Create a set attribute message
attr = attributes.BatteryLevelAttribute(value=85)
msg = codec.SetAttribute(attribute_id=attr.attribute_id, value=attr)
encoded = msg.encode()
# Decode and access attribute value
decoded = codec.decode(encoded)
print(f"Battery level: {decoded.value.value}%")
Error Handling
from embodycodec import codec
from embodycodec.exceptions import CrcError, DecodeError
try:
# Decode with CRC validation
msg = codec.decode(data)
except CrcError:
# Handle CRC error - optionally decode anyway
msg = codec.decode(data, accept_crc_error=True)
except DecodeError as e:
print(f"Decode failed: {e}")
Upgrading to 2.0.0
Every break below is the removal of an API that never worked correctly. Nothing here changes behaviour that was previously right.
codec.SendFileResponse.crc is renamed to file_crc. The old name collided with
Message.crc, which holds the message footer CRC and is assigned during decode — so the
file CRC was silently overwritten. Reading .crc on this class never returns the file
CRC, so it must be replaced rather than left alone:
SendFileResponse(crc=x) -> SendFileResponse(file_crc=x)
response.crc -> response.file_crc
file_codec.BatteryDiagnostics.length() returns 26, not 24. It excluded the two-byte
timestamp that every other message counts, so a parser walking a file by advancing
1 + length() desynced by two bytes on every such record. If you compensated for this,
remove the compensation.
file_codec.BatteryDiagnostics.struct_format is gone, replaced by unpack_format
(the name its base class actually reads). Note this is the file_codec class; the
unrelated types.BatteryDiagnostics.struct_format is unchanged.
file_codec.PulseBlockEcg.encode() and PulseBlockPpg.encode() raise
NotImplementedError. They previously returned two zero bytes regardless of contents.
File-format messages are produced by the device and are decode-only.
One fix that needs no code change but does change bytes on the wire: SetAttribute now
writes the true payload length for variable-length attributes (ModelAttribute,
VendorAttribute, SystemStatusNamesAttribute, SystemStatusAttribute,
PulseRawListAttribute). It previously wrote 0, so a conforming parser dropped those
values. Fixed-size attributes encode exactly as before.
Changelog
See the releases page for the changelog.
Contributing
Contributions are very welcome. To learn more, see the Contributor Guide.
License
Distributed under the terms of the MIT license.
Issues
If you encounter any problems, please file an issue along with a detailed description.
Credits
Inspiration collected from Cookiecutter UV template.
1 maintainer
Metadata
1 maintainer
Release files for embody-codec 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| embody_codec-2.0.0.tar.gz | 21.4 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| embody_codec-2.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 44.7 kB
Release files / embody_codec-2.0.0.tar.gz
| Download URL | embody_codec-2.0.0.tar.gz |
|---|---|
| Size | 21.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
587d54358f554328e2c08c701d178bf6db790c974cd342239a56e3de60d86bf4
|
|
BLAKE2b-256 checksum How to use checksums |
e9c80cb1a2421254482803505abc546c82beb1d0ce0c85a5a0cc857429884cbe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Release files / embody_codec-2.0.0-py3-none-any.whl
| Download URL | embody_codec-2.0.0-py3-none-any.whl |
|---|---|
| Size | 23.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d22293527da93aa32acb15ed55612e79dfbe8be6f7358eed45a9722340836b3e
|
|
BLAKE2b-256 checksum How to use checksums |
2992e219df6425bce3fe59270860a28dadc5c4afa3b92ed2b485e0ad816c9166
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Security for embody-codec 2.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.
