Skip to main content

python-can-hub

Native python-can backend for can-hub: consume remote CAN interfaces exported by can-hub agents, directly over the binary protocol — unix socket, plain TCP, TLS or QUIC, with mTLS identity and TOFU pinning on the encrypted transports. No bridge process in between.

import can

bus = can.Bus(
    interface="canhub",
    channel="truck42/can0",
    url="quic://hub.example.com:7227",
)
bus.send(can.Message(arbitration_id=0x123, data=b"\xDE\xAD\xBE\xEF"))
for message in bus:
    print(message)
  • channel: namespaced interface agent/iface (or the numeric id from can-hub-client list).
  • url: omit to connect to the local hub unix socket.
  • state_dir: client TLS identity + pin store location (tls/quic).
  • receive_own_messages: standard python-can echo semantics.
  • reliable: carry the channel on a dedicated reliable QUIC stream (lossless, ordered) instead of the lossy datagram plane. Needs a quic:// url and a hub that advertises the capability; otherwise the open fails.
  • ignore_rx_error_frames: drop the controller error frames (is_error_frame), received by default as on python-can's socketcan interface.

Received messages are canhub.CanHubMessage, a can.Message with one more attribute: bridged is true when the hub injected the frame into this bus along a bridge route or group.

Write access follows the hub client ACLs: if the ACL grants read-only, the bus opens read-only and send() raises.

The bus is thread-safe: a can.Notifier receiving in its thread while other threads call send() is supported. Calls into the native session are serialised first come, first served, and a blocking receive gives way to a waiting send within about 10 ms.

Drop counters

Two drops happen inside the library and never reach the hub, so the hub's own counters cannot show them: send() raises when the pace relayed by the hub leaves no budget for the frame, and the receive ring overwrites its oldest entry when you read slower than the bus produces. drop_counters() returns both as monotonic totals, so a quiet bus is distinguishable from a lossy one:

bus.drop_counters()     # {"rate_limited": 0, "ring_dropped": 12}

Configuring the interface

configure() reconfigures the bus's interface on its agent, everything in one step, with the keywords of ip link set ... type can; interface_settings() reads it back. The bus must be opened by its agent/iface name, and the hub allows it only with an rwa ACL grant (unix and plain tcp clients are trusted).

bus.configure(bitrate=500000, sample_point=0.875, fd=True, data_bitrate=2000000)
bus.configure(restart_ms=100, txqueuelen=1000, termination=120, listen_only=False, up=True)
from canhub import BitTiming
bus.configure(bit_timing=BitTiming(tq=125, prop_seg=6, phase_seg1=7, phase_seg2=2, sjw=1))
bus.interface_settings()
# InterfaceSettings(up=True, state='error-active', bitrate=500000, sample_point=0.875, ...)

Both return an InterfaceSettings with None where the device reports nothing (a vcan has no bit timing). A refusal raises CanOperationError with the reason.

Transactions

A transaction hands a request/response sequence to the agent, which runs it at its bus: each exchange costs a bus round trip instead of a network one (UDS flashing, broadcast upgrades; see the protocol's Transactions section). Open the bus with reliable=True:

from canhub import Advance, Pattern, Step, Template, TransactionAborted

response = Template(
    advance_on=Pattern(0x7E8, data=b"\x00\x76", data_mask=b"\x00\xff"),
    abort_on=Pattern(0x7E8, data=b"\x00\x7f", data_mask=b"\x00\xff"),
    extend_on=Pattern(0x7E8, data=b"\x00\x7f\x00\x78", data_mask=b"\x00\xff\x00\xff"),
    mode=Advance.COUNT,
    timeout=0.05,
)
try:
    with bus.transaction(exclusive=True) as transaction:
        transaction.template(0, response)
        transaction.send(Step(arbitration_id=0x7E0, data=block) for block in blocks)
        result = transaction.wait()
except TransactionAborted as aborted:
    print(aborted.result.reason, aborted.result.failing_step, aborted.result.frame)

send() takes any iterable, a generator included, and hands it over as the agent's window allows. wait() returns a TransactionResult or raises TransactionAborted with it. Leaving the with block on an exception (Ctrl-C included) cancels the transaction at the agent. A roster step waits for a set of nodes: bus.transaction(roster=range(32), origin=Origin(mask=0x1F)) tells the nodes apart by (id & mask) >> shift (or by payload bytes), and the result names who answered (answered) and who did not (missing). exclusive=True keeps other clients' frames off the bus meanwhile; their send() raises CanOperationError. When the client may lag behind the bus (a slow link, data produced as it goes), idle_timeout=60 lets the agent wait that long for steps, and keepalive=Keepalive(0x7E0, b"\x02\x3e\x80", period=2.0) is the frame it sends meanwhile, for instance to keep a device session open.

A transaction script describes the same in a file, and runs as it does from can-hub-client txn:

from canhub import ScriptError, TransactionAborted

try:
    result = bus.run_script("flash.txn", progress=lambda progress, total: print(progress.completed_steps, total))
except ScriptError as error:
    print(error.line, error)                      # flash.txn:5: no template has this name
except TransactionAborted as aborted:
    print(aborted.result.reason, sorted(aborted.result.missing))

progress(progress, total_steps) runs a few times a second; returning False cancels the transaction, and an exception raised in it (Ctrl-C included) cancels it and propagates. It must not use the bus.

ISO-TP steps

A template with isotp=Isotp(...) makes each of its steps one ISO-TP message (up to 4095 bytes in data) that the agent segments, honouring the ECU's flow control, and whose reassembled answer the patterns match. Begin with isotp=True; extend_timeout is the wait after a response pending (UDS P2*):

from canhub import Advance, Isotp, Pattern, Step, Template

transfer = Template(
    advance_on=Pattern(0x7E8, data=b"\x76\x00"),
    abort_on=Pattern(0x7E8, data=b"\x7f"),
    extend_on=Pattern(0x7E8, data=b"\x7f\x00\x78", data_mask=b"\xff\x00\xff"),
    mode=Advance.COUNT,
    timeout=0.05,
    extend_timeout=5.0,
    abort_on_mismatch=True,
    isotp=Isotp(0x7E8),                 # padding 0xCC, normal addressing, classic CAN
)
with bus.transaction(exclusive=True, isotp=True) as transaction:
    transaction.template(1, transfer)
    transaction.send(
        Step(template=1, arbitration_id=0x7E0, data=bytes([0x36, counter]) + block, expect=bytes([0x76, counter]))
        for counter, block in blocks
    )
    transaction.wait()

Isotp(response_id, tx_address=0x10, rx_address=0xF1) is extended addressing (one address for mixed), fd=True sends CAN FD frames of data_length bytes, and block_size/st_min are the flow control the agent answers with. Each message is handed over whole, as the agent's window takes it.

UDS itself (sessions, security access, negative response codes) is the job of a diagnostics library. python-can-isotp and udsoncan work over CanHubBus as over any python-can bus, but then the client segments and every frame crosses the network; a udsoncan connection over agent-side ISO-TP is tracked in #272.

Listing interfaces

CanHubBus.list_interfaces() asks a hub for the interfaces it exports. Each entry is a python-can config dict you can splat straight into can.Bus:

from canhub import CanHubBus
import can

for config in CanHubBus.list_interfaces(url="quic://hub.example.com:7227"):
    print(config["channel"])          # e.g. "can-agent/can0"
bus = can.Bus(**CanHubBus.list_interfaces()[0])   # first interface, local hub

It accepts the same connection arguments as the bus (url, identity_cert, identity_key, hub_fingerprint, state_dir); omit url to query the local hub unix socket.

This also wires python-can's discovery: can.detect_available_configs("canhub") returns the same dicts. With no explicit target it reads the connection from the environment — CANHUB_URL, CANHUB_STATE_DIR, CANHUB_IDENTITY_CERT, CANHUB_IDENTITY_KEY, CANHUB_HUB_FINGERPRINT — falling back to the local hub unix socket. So CANHUB_URL=quic://hub.example.com:7227 points discovery at a remote host without any code.

The wheel bundles libcanhub.so with the TLS/QUIC stack linked in statically; the only runtime dependency is glibc.

Testing

The unit tests stub the native library, so they run without a build:

pip install -e python/.[test]
pytest python/tests

The backend is also exercised end-to-end against real binaries (recv, send, list_interfaces, and can.detect_available_configs discovery) by test/e2e/tests/python_can.robot; run the whole bench with make e2e.

Building from source

./scripts/build-python-wheel.sh        # host arch, glibc-tagged (local dev)
pip install python/dist/*.whl

Distributable manylinux wheels are built per architecture in a manylinux container and repaired by auditwheel (needs docker, plus QEMU binfmt for the cross arches):

./scripts/build-python-wheel.sh x86_64   # python/dist/x86_64/*.whl
./scripts/build-python-wheel.sh aarch64
./scripts/build-python-wheel.sh armv7l

The release workflow builds these three on native runners (aarch64/armv7l on the arm64 hosted runner, no QEMU) plus a cross-compiled win_amd64 wheel, and publishes all four to PyPI on a v* tag.

Metadata

Release files for python-can-hub 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for python-can-hub 0.6.0
File Actions
python_can_hub-0.6.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for python_can_hub-0.6.0-py3-none-win_amd64.whl
python_can_hub-0.6.0-py3-none-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.28+ x86-64, Linux glibc 2.26+ x86-64 Details for python_can_hub-0.6.0-py3-none-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl
python_can_hub-0.6.0-py3-none-manylinux_2_26_armv7l.manylinux_2_31_armv7l.whl Python 3 none Linux glibc 2.31+ ARMv7l, Linux glibc 2.26+ ARMv7l Details for python_can_hub-0.6.0-py3-none-manylinux_2_26_armv7l.manylinux_2_31_armv7l.whl
python_can_hub-0.6.0-py3-none-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64, Linux glibc 2.26+ ARM64 Details for python_can_hub-0.6.0-py3-none-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl

Total release size: 3.3 MB

Release files / python_can_hub-0.6.0-py3-none-win_amd64.whl

Download URL python_can_hub-0.6.0-py3-none-win_amd64.whl
Size 751.2 kB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
adb4c97c17c83056d4881ead9a3f345943042fcae53a48e8c55edc9d3c739ea4
BLAKE2b-256 checksum
How to use checksums
ea9795ecc46851ec17a7070173c7fd4eaded7638a98cd4c34ec0797385446853
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / python_can_hub-0.6.0-py3-none-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl

Download URL python_can_hub-0.6.0-py3-none-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl
Size 966.6 kB
Tags Linux glibc 2.26+ x86-64 Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
c24397a79fa5cc4d7d8ef6f7dcaf786fa6ed3a1582a4f179621b9b0e0ae6786b
BLAKE2b-256 checksum
How to use checksums
ae042b2c88b3ba1eb58b624082d66cd0fe6e68ba249ebab550b91dfd3ee0be9d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / python_can_hub-0.6.0-py3-none-manylinux_2_26_armv7l.manylinux_2_31_armv7l.whl

Download URL python_can_hub-0.6.0-py3-none-manylinux_2_26_armv7l.manylinux_2_31_armv7l.whl
Size 789.2 kB
Tags Linux glibc 2.26+ ARMv7l Linux glibc 2.31+ ARMv7l Python 3
SHA-256 checksum
How to use checksums
aa35a54bdfaaae5c2667c9fedbacd5f35615ddd793ee4b1aea63644f93a4dc4d
BLAKE2b-256 checksum
How to use checksums
efe170806bd21561fd3519fd7be87a95943857878c41cd8beb81b435ff374d0c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / python_can_hub-0.6.0-py3-none-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl

Download URL python_can_hub-0.6.0-py3-none-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
Size 781.9 kB
Tags Linux glibc 2.26+ ARM64 Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
cbf3fd48dc78d7aa32c1f09067108f4be3c781aca2a60fb91fff8aea3a6751c4
BLAKE2b-256 checksum
How to use checksums
b13d9b6bae54c98d8f4d0cc29590a232e26809d54ef545182f7ee79cfbfd533a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Security for python-can-hub 0.6.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.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for python_can_hub-0.6.0-py3-none-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page