python-can-canpal

CANPAL USB and TCP client backend for python-can.

0.1.0rc1 is an experimental preview. Full hardware release acceptance is incomplete. Use it for evaluation on an isolated test bench. It is not the qualified 0.1.0 release.

Install

Requires Python 3.12, python-can 4.6.1, pySerial 3.5, and a separately supplied 64-bit CANPAL native SDK with the fixes described below.

python -m pip install python-can-canpal==0.1.0rc1

The Python package does not include the CANPAL SDK, firmware, device drivers, Qt/MinGW runtime, or fake binaries. Obtain compatible native components from your CANPAL supplier before attempting hardware access. The MIT license applies to the new Python plugin, tests and documentation; native components have separate licenses.

What has been verified

Both devices had CAN1 wired to their own CAN2 on separate physical buses. These checks do not use an independent reference CAN interface. Classic checks covered standard/extended frames and RTR DLC 0–8 in both directions. X6 FD checks covered lengths 0–64 and BRS off/on. The post-fix checks verified 5,280 frames in total.

Not yet qualified: independent-reference CAN/CAN FD interoperability, native Linux USB or direct Linux WLAN, two simultaneous WLAN devices, controlled physical port renumbering/disconnection, rated-load/endurance runs, and native resource stability. Fake tests cover additional error paths but do not establish those hardware claims. Formal 0.1.0 retains the complete release acceptance requirements.

Native SDK and firmware requirements

The tested SDK source revision is e222ccf48f29c530fd09617df6e3a83a8095d25f. It includes command ACK matching, cooperative worker shutdown and a Qt serial buffered-read fix. Matching exported function names alone does not establish compatibility.

Classic RTR also requires firmware that preserves the received DLC. The original X5 firmware reporting 0x0332 and X6 firmware reporting 0x0127 cleared RTR DLC to zero. Supplier-signed diagnostic builds fixed this on the two test devices. Those builds still report the same version numbers: ask your supplier to identify the actual fixed build. The plugin cannot recover DLC that firmware has discarded.

Set CANPAL_LIBRARY to the absolute DLL/SO path, or pass library_path. On Windows, CANPAL_DEPENDENCY_DIRS may list Qt/MinGW runtime directories, separated by semicolons. On Linux, install the matching Qt 5 runtime and grant serial-port access through udev or the dialout group.

Connect by UID or IP

import can

with can.Bus(interface="canpal", ignore_config=True,
             transport="usb", device_id="YOUR_24_HEX_DIGIT_UID",
             channel=0, bitrate=500_000) as bus:
    message = bus.recv(timeout=1)

The device UID remains the selector when a COM/ttyACM number changes. After a reconnection, close and recreate the Bus using the same UID; automatic reconnect is not implemented. Physical port renumbering acceptance is still pending.

Use transport="wlan", host="192.0.2.10", port=8000 for TCP direct connection. The IP and port must match the actual device; no network discovery is attempted. Keep device_id to verify identity at that endpoint. X6 CAN FD additionally uses fd=True, data_bitrate=2_000_000.

Different physical devices use independent Bus objects. A device can have one Bus and one selected CAN channel at a time. Use one Notifier per device for independent fault handling. UDP, server mode, transmit echo and concurrent channels on one device are not implemented.

A successful send() means the native queue accepted the frame, not that the CAN bus acknowledged it. Use a single receiver per Bus, stop its Notifier before shutdown, and handle python-can exceptions. Timestamp alignment is approximate per device and does not provide precise synchronization between devices.

The source distribution includes Chinese installation, testing and release notes.