Development

Clone the repository before following the development commands below.

Installation and development

Install the package from PyPI in your uv project:

uv add automotive

For development, run the following from the repository root. The Nix shell provides uv, the Rust toolchain, and native build dependencies:

nix develop
cd python
uv sync
uv run python examples/uds.py
uv check
uv format

uv check runs ty; uv format runs Ruff with default settings and a 120-character line length. uv sync installs the project and development tools; the lockfile records their versions. Use uv run maturin develop after changing Rust code when working directly in the installed development environment. For Rust formatting, run cargo fmt --all.

The Python extension always includes every adapter supported on its platform: SocketCAN on Linux, panda and PEAK USB adapters, and Vector and J2534 on Windows. Vendor drivers/DLLs and USB permissions remain necessary. The Rust crate retains feature flags for Rust applications.

Examples and API documentation

The async Python examples and their counterparts in examples/sync/ mirror every Rust example, including CAN transmission, PEAK bitrate configuration, ISO-TP, UDS, and firmware queries. The synchronous firmware query visits ECUs sequentially; the async version queries them concurrently. Read installed API documentation using uv run python -m pydoc automotive.protocols.uds, or Python’s help().

Run uv run python examples/can_sender.py to send one Classic CAN frame. Use uv run python examples/sync/can_sender.py for the synchronous version.

Run uv run python examples/configure_bitrate.py to configure a PEAK PCAN-USB FD adapter, or use examples/sync/configure_bitrate.py for the synchronous version.

End-to-end regression tests

On Linux, create vcan0 from the repository root:

scripts/set_up_vcan.sh

The setup script requires sudo. Then run:

cd python
uv run pytest --run-vcan -q

The regression suite starts the existing Scapy ECU scripts, verifies readiness, and closes/reaps them after each scenario. It exercises all 14 implemented UDS service IDs through both APIs, transfer round trips, suppression and pending responses, strict validation, cancellation, and ISO-TP Classic/FD framing and flow control. Tests run serially on vcan0; do not run the Rust and Python virtual-CAN suites concurrently. Without --run-vcan, the hardware-dependent tests are skipped; explicit runs fail if prerequisites are unavailable.