python-can-canpal

CANPAL USB and TCP client backend for python-can.

0.1.0rc5 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 and pySerial 3.5. Platform wheels include the pinned CANPAL native SDK and required non-system runtime libraries.

Linux wheels require glibc 2.39 or newer and the system GLib runtime. On minimal Ubuntu 24.04 installations, install libglib2.0-0t64 before using the backend. The standard system libraries libstdc++6 and zlib1g must also be present.

The Windows win32 wheel requires 32-bit Python; it does not qualify a 32-bit Windows OS. Windows x86 installation was verified with Smart App Control off; enforced application control previously blocked the unsigned native runtime. ARM64 requires Python 3.12 and glibc 2.39 or newer. The vendor Ubuntu 22.04 image on the tested Firefly board cannot run this wheel directly; tests used an isolated Ubuntu 24.04 user space on its native ARM CPU and hardware drivers. ARM32, Windows ARM64 and Linux i686 are not part of this release.

python -m pip install --only-binary=:all: python-can-canpal==0.1.0rc5

The MIT license applies to the Python plugin, tests and documentation. The native SDK and bundled third-party libraries have separate terms included in the platform wheel. Firmware and OS device drivers remain separate. The bundle uses QtCore, QtNetwork and QtSerialPort under LGPLv3, with their third-party notices. The SDK is covered by LICENSE-CANPAL-SDK version 0.2. You may modify and replace compatible LGPL libraries under their terms; the package does not lock their release hashes at runtime. Replacement instructions, component licenses and source details are included in canpal/_native/licenses/.

Corresponding third-party sources are under CANPAL分析仪/二次开发/python-can-canpal/:

rc5 reuses these exact source archives and native binaries. The wheel also includes the upstream Qt QCalendar LGPL-header correction. For source requests or download problems, contact yongxiang.wu@hotmail.com, specifying version and platform. The installed wheel includes canpal/_native/licenses/THIRD-PARTY-SOURCES.md.

Hardware evidence and limits

The following x64 evidence was obtained with rc3 and checked again for rc4. rc5 retains the rc4 Windows x64/x86 and Linux x86_64 runtime bytes, with only version and documentation changes. Their recorded qualification is reused; this does not imply a fresh run of every historical hardware test.

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 current SDK checks verified 19,680 frames and 20 Windows reopen cycles. Of these, 4,384 frames were verified on Linux USB using usbipd-win 5.3.0 and Linux CDC ACM. Reversing attachment order swapped ttyACM0/ttyACM1 while UID selection still found the correct X5 and X6.

SDK software regressions passed 170 assertions on each of Windows x64, Windows x86, and Ubuntu x86_64, plus two Linux ThreadSanitizer checks. Windows x86 plugin candidate checks additionally verified USB, both mixed USB/WLAN directions, classic CAN/RTR and X6 ISO FD, with five reopen runs for each tested mode. These checks used X5 CAN1, X6 CAN1 and X6 CAN2 on one shared bus; X5 CAN2 was disconnected. X5 was uninitialized for X6 FD tests. This qualifies neither separate-bus isolation nor an independent FD reference. Repeated tests verified 1,080 classic/RTR frames and 5,200 FD frames with the 32-bit Python plugin. The target WLAN device was identified by BSSID and UID; its current IP was supplied explicitly. An X6 WLAN connection failure recovered after a device power cycle; its underlying cause was not established.

ARM64 was tested on a Firefly ROC-RK3588S-PC with kernel 5.10.160, using an Ubuntu 24.04 user space in rootless bubblewrap (native execution, no QEMU). 353 installed-plugin tests and matching public/internal ABI probes passed. Both CANPAL devices used the board's USB controller and Linux CDC ACM driver. Five reopen runs per mode verified 1,080 classic/RTR frames across dual USB and both mixed USB/WLAN directions, plus 5,200 X6 FD frames over USB/WLAN. UID selection also passed after ttyACM numbers swapped through driver rebind; this was not a physical cable hotplug test. The shared CAN wiring and independent-reference limits described above also apply to these ARM tests.

Firefly WLAN condition: wlan0 and p2p0 on this RTL8821CU share one radio and one channel. Managed-mode tests encountered multi-second TCP pauses during background scans. X6 repeated acceptance passed with a fixed hotspot BSSID and channel, background scanning disabled, and power saving off. This qualifies that configuration only; default managed-mode reliability is still open. Router and CANPAL hotspot access were tested sequentially, not concurrently. Other ARM boards, drivers and a complete Ubuntu 24.04 boot image were not tested.

Not yet qualified: independent-reference CAN/CAN FD interoperability, two simultaneous WLAN devices, full repeated physical renumbering/disconnection acceptance, rated-load/endurance runs, and native resource stability. Formal 0.1.0 retains the complete release acceptance requirements.

Native SDK and firmware requirements

The default runtime is SDK build 663eda8, bundled with each platform wheel. No CANPAL_LIBRARY, Qt installation or library search-path setting is needed for the default runtime. USB permissions and a reachable device IP remain OS configuration requirements.

An explicitly supplied library_path takes precedence over CANPAL_LIBRARY, then the bundled SDK, then legacy system lookup. Invalid explicit paths are errors; they do not silently select a different SDK. External SDK users may still request build 663eda8 through their existing CANPAL supplier.

The pinned source revision is 663eda823be0533754123695405033b38e115489. It adds stricter CAN ACK validation, TCP buffered-read handling, immediate OBD write-error propagation, UDS source filtering, and synchronized command handoff. It also includes cooperative worker shutdown and the Qt serial buffered-read fix. The firmware protocol has no transaction sequence, so a delayed ACK for an identical earlier request cannot be distinguished by the echoed fields alone.

The following are the original rc2 SDK input hashes. Packaging tools rewrite dependency names/paths, so final wheel hashes are recorded in each wheel's manifest.

Matching exported function names or the SDK version string alone does not identify this fixed build. rc3 adds platform runtime bundles and default library selection. rc4 adds the Windows 32-bit Python runtime and architecture selection; the CAN protocol remains unchanged. rc5 adds the Linux ARM64 runtime with the Firefly conditions above; formal hardware acceptance remains incomplete.

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.

For an external SDK only, set CANPAL_LIBRARY or pass library_path. On Windows, CANPAL_DEPENDENCY_DIRS supplies that external SDK's dependencies; it is ignored when the bundled SDK is selected. On Linux, external SDK users must arrange its matching dependencies. USB users need serial-port access through udev or the dialout group.

The bundled libraries can be replaced under their applicable terms. Hashes identify release artifacts and are not a runtime replacement lock.

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. Linux USB/IP and physical ARM host driver rebind order swaps have been verified; the full repeated physical renumbering acceptance remains 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.

Releases distribute platform wheels. Source and build inputs are archived separately; an incomplete source distribution is not offered as an automatic pip fallback.