Adapters

Supported adapters

Adapter	Platforms	Connection
SocketCAN	Linux	OS-configured CAN and virtual CAN interfaces
panda	Linux, macOS, Windows	USB
PEAK PCAN-USB FD	Linux, macOS, Windows	USB
Vector XL	Windows	Vector XL driver
J2534	Windows	Vendor PassThru DLL; raw CAN and native ISO-TP

Each adapter page documents its configuration and both async and sync classes.

Discovery and shared interface

Use CanAdapter() for discovery, or choose a backend from the table above. available_adapters() reports the backends compiled for the current platform; it does not probe connected hardware. Constructors open hardware immediately and block until ready in both APIs. The named adapter classes inherit the send, receive, and lifecycle methods documented below.

Hardware is released when its last owner is dropped. For deterministic cleanup, use aclose() or async with in the async API, or close() or with in the sync API.

await adapter.recv_for(duration) collects CAN frames for the given number of seconds and returns them as a list in receive order, including transmit echoes. Use adapter.recv_for(duration) in the sync API. Each call closes its own subscription on return and leaves existing recv() subscriptions unaffected. Reception starts when awaited (or called in the sync API) and finishes early if the adapter closes.

Asynchronous API

automotive.adapters.AdapterConfig: TypeAlias = automotive.adapters.SocketCanConfig | automotive.adapters.PandaConfig | automotive.adapters.PeakConfig | automotive.adapters.VectorConfig | automotive.adapters.J2534Config

Represent a union type

E.g. for int | str

automotive.adapters.available_adapters() → tuple[str, ...]

Return compiled backend names; this does not probe connected hardware.

class automotive.adapters.CanAdapter(config: SocketCanConfig | PandaConfig | PeakConfig | VectorConfig | J2534Config | None = None)

Open a CAN adapter immediately, using discovery when no config is supplied.

Parameters:

config – Reusable backend configuration; None discovers an adapter with Rust defaults. Named classes such as PeakAdapter select a backend.

Construction blocks until hardware is ready, including inside an async function. Sends and receives are awaitable. Hardware is released when its last owner is dropped; transports, clients, and receivers retain ownership. Use await aclose() or async with for deterministic cleanup. Explicit closure invalidates dependent operations. A closed adapter cannot be reopened.

Raises:

• ValueError – Explicit configuration is invalid.

• NotSupportedError – The backend is unavailable on this platform.

• AdapterError – Opening failed or discovery found no usable adapter.

property config: SocketCanConfig | PandaConfig | PeakConfig | VectorConfig | J2534Config | None

Backend configuration, or None for automatic discovery.

async open() → Self

Return this already-open adapter; raise RuntimeError after closure.

async aclose() → None

Close this adapter and wake dependent operations; repeated calls are safe.

property closed: bool

Whether this adapter has been explicitly closed.

async send(frame: Frame) → None

Send a frame and await the backend’s transmit confirmation.

Parameters:

frame – Validated Classic, FD, or remote frame supported by the adapter.

Raises:

• TimeoutError – A configured transmit deadline expired.

• TransmissionCancelledError – A queue clear invalidated this send.

• NotSupportedError – This backend cannot encode the frame.

• AdapterError – The hardware operation failed.

Confirmation strength depends on the backend; some emulate ACKs at submission. Cancelling this await cannot undo an already-sent frame.

recv() → Receiver[Frame]

Subscribe immediately to all frames, including transmit echoes.

Returns:

An async iterator of Frame objects. Create it before sending. Dropping it releases the subscription; aclose() releases it early. Slow consumers retain Rust’s drop/lag behavior.

async recv_for(duration: float) → list[Frame]

Collect CAN frames, including transmit echoes, for duration seconds.

Returns frames in receive order, or finishes early if the adapter closes. Uses an independent subscription that closes on return or cancellation; existing recv() subscriptions are unaffected. Reception starts when awaited. duration must be finite and nonnegative.

Synchronous API

Named adapters in automotive.sync.adapters inherit the blocking lifecycle, send, and receive methods from CanAdapter and accept the same configuration as the async API.

class automotive.sync.adapters.CanAdapter(config: SocketCanConfig | PandaConfig | PeakConfig | VectorConfig | J2534Config | None = None)

Open a CAN adapter immediately, using discovery when no config is supplied.

Parameters:

config – Shared backend configuration; None discovers an adapter with Rust defaults. Named classes such as PeakAdapter select a backend.

Hardware is released when its last owner is dropped. Transports, clients, and receivers retain ownership. close() and with support deterministic cleanup. Explicit closure invalidates dependent operations, and a closed adapter cannot be reopened. Opening errors are raised by construction.

property config: SocketCanConfig | PandaConfig | PeakConfig | VectorConfig | J2534Config | None

Backend configuration, or None for automatic discovery.

open() → Self

Return this already-open adapter; raise RuntimeError after closure.

send(frame: Frame) → None

Send a frame and block for the backend’s transmit confirmation.

Parameters:

frame – A Classic, FD, or remote frame supported by the adapter.

Raises:

• TimeoutError – A configured transmit deadline expired.

• TransmissionCancelledError – A queue clear invalidated this send.

• NotSupportedError – The backend cannot encode this frame.

• AdapterError – The hardware operation failed.

Confirmation strength depends on the backend. Interrupting this call cannot undo a frame that has already been sent.

recv() → Receiver[Frame]

Subscribe immediately to CAN frames, including transmit echoes.

Returns:

A blocking iterator of Frame objects supporting with and close(). Subscribe before sending. Dropping the receiver releases its subscription; close() releases it early.

recv_for(duration: float) → list[Frame]

Collect CAN frames, including transmit echoes, for duration seconds.

Returns frames in receive order, or finishes early if the adapter closes. Uses an independent subscription that closes on return; existing recv() subscriptions are unaffected. duration must be finite and nonnegative.

close() → None

Release the resource and wake pending operations; idempotent.

property closed: bool

Whether this resource or its owning parent has been closed.