Skip to content

README.md

Latest commit

 

History

History
119 lines (77 loc) · 3.25 KB

README.md

File metadata and controls

119 lines (77 loc) · 3.25 KB

J2735 Codec - Python Bindings

This package provides high-performance Python bindings for the SAE J2735 (202409) V2X codec. Powered by WebAssembly (WASM), it allows for seamless, safe, and portable conversion between JSON (JER) and Packed Encoding Rules (UPER) within Python applications.

Installation

Runtime Requirements

  • Python: v3.13 or higher.
  • WASM Runtime: wasmtime (installed automatically as a dependency).

Installation via GitHub Release

The fastest way to install the bindings is to use the pre-built Wheel (.whl) from the Releases page.

Using uv (Recommended):

uv pip install "https://github.com/verizon/j2735codec/releases/download/v1.0.0/python-j2735codec-1.0.0-py3-none-any.whl

Using pip:

pip install "https://github.com/verizon/j2735codec/releases/download/v1.0.0/python-j2735codec-1.0.0-py3-none-any.whl"

Quick Start

The Python interface is designed to be simple and idiomatic.

from j2735codec import J2735Codec, EncodingRules, PDUTypes

# Initialize the codec
codec = J2735Codec()

# Example JSON Message Frame
json_content = '{"messageFrame": {"messageId": 20, "value": { ... }}}'

# 1. Transcode: JSON (JER) -> Packed (UPER)
uper_bytes = codec.transcode(
    input_encoding=EncodingRules.JER,
    output_encoding=EncodingRules.UNALIGNED_BASIC_PER,
    pdu=PDUTypes.MESSAGE_FRAME,
    buffer=json_content
)
print(f"Encoded UPER (Hex): {uper_bytes.hex().upper()}")

# 2. Transcode: Packed (UPER) -> JSON (JER)
decoded_json_raw = codec.transcode(
    input_encoding=EncodingRules.UNALIGNED_BASIC_PER,
    output_encoding=EncodingRules.JER,
    pdu=PDUTypes.MESSAGE_FRAME,
    buffer=uper_bytes
)
print(f"Decoded JSON: {decoded_json_raw.decode('utf-8')}")

Local Development & Build Artifacts

The recommended way of installing and building is through the root Makefile. If you wish to work on the bindings directly though, here are some tips to help.

1. Build the WASM Engine

The Python bindings require a compiled WebAssembly binary. If you modify the C++ core, refresh the artifacts from the project root:

# From the project root
make wasm

This places j2735.wasm and metadata into src/j2735codec/generated/.

2. Install for Local Development

We use uv for fast, reproducible environment management.

cd j2735codec/bindings/python
uv sync

3. Build the Python Wheel

To package the bindings for distribution, use the uv build command:

  • File: python-j2735codec-<version>-py3-none-any.whl
  • Purpose: This "Universal Wheel" contains the Python source and the bundled WASM binary.

4. Local Installation

pip install ./python-j2735codec-1.0.0-py3-none-any.whl

Testing

Run the test suite using pytest:

uv run pytest

Versioning Policy

This package follows Unified Versioning. The version in pyproject.toml must match the root VERSION file and CMakeLists.txt.

Warning: Do not bump versions manually. Use make sync-version from the root directory.

License

Licensed under the Apache License 2.0. See LICENSE for details.