Metadata-Version: 2.4
Name: python-can-canpal
Version: 0.1.0rc3
Summary: CANPAL USB and TCP backend for python-can
License-Expression: LicenseRef-CANPAL-Runtime-Bundle
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-BUNDLE
License-File: LICENSE-CANPAL-SDK
License-File: src/canpal/_native/licenses/Apache-2.0.txt
License-File: src/canpal/_native/licenses/Artistic.txt
License-File: src/canpal/_native/licenses/BSD.txt
License-File: src/canpal/_native/licenses/CC0-1.0.txt
License-File: src/canpal/_native/licenses/GFDL-1.2.txt
License-File: src/canpal/_native/licenses/GFDL-1.3.txt
License-File: src/canpal/_native/licenses/GFDL.txt
License-File: src/canpal/_native/licenses/GPL-1.txt
License-File: src/canpal/_native/licenses/GPL-2.txt
License-File: src/canpal/_native/licenses/GPL-3.txt
License-File: src/canpal/_native/licenses/GPL.txt
License-File: src/canpal/_native/licenses/LGPL-2.1.txt
License-File: src/canpal/_native/licenses/LGPL-2.txt
License-File: src/canpal/_native/licenses/LGPL-3.txt
License-File: src/canpal/_native/licenses/LGPL.txt
License-File: src/canpal/_native/licenses/LICENSE-CANPAL-SDK
License-File: src/canpal/_native/licenses/MPL-1.1.txt
License-File: src/canpal/_native/licenses/MPL-2.0.txt
License-File: src/canpal/_native/licenses/RUNTIME-REPLACEMENT.zh-CN.md
License-File: src/canpal/_native/licenses/THIRD-PARTY-SOURCES.md
License-File: src/canpal/_native/licenses/component-sources.json
License-File: src/canpal/_native/licenses/libcap2-copyright.txt
License-File: src/canpal/_native/licenses/libcom-err-NOTICES.txt
License-File: src/canpal/_native/licenses/libcom-err2-copyright.txt
License-File: src/canpal/_native/licenses/libdouble-conversion3-copyright.txt
License-File: src/canpal/_native/licenses/libgcc-s1-copyright.txt
License-File: src/canpal/_native/licenses/libglib2.0-0t64-copyright.txt
License-File: src/canpal/_native/licenses/libgssapi-krb5-2-copyright.txt
License-File: src/canpal/_native/licenses/libicu74-copyright.txt
License-File: src/canpal/_native/licenses/libk5crypto3-copyright.txt
License-File: src/canpal/_native/licenses/libkeyutils1-copyright.txt
License-File: src/canpal/_native/licenses/libkrb5-3-copyright.txt
License-File: src/canpal/_native/licenses/libkrb5support0-copyright.txt
License-File: src/canpal/_native/licenses/libpcre2-16-0-copyright.txt
License-File: src/canpal/_native/licenses/libpcre2-8-0-copyright.txt
License-File: src/canpal/_native/licenses/libqt5core5t64-copyright.txt
License-File: src/canpal/_native/licenses/libqt5network5t64-copyright.txt
License-File: src/canpal/_native/licenses/libqt5serialport5-copyright.txt
License-File: src/canpal/_native/licenses/libstdc++6-copyright.txt
License-File: src/canpal/_native/licenses/libudev1-copyright.txt
License-File: src/canpal/_native/licenses/libzstd1-copyright.txt
License-File: src/canpal/_native/licenses/qt-qcalendar-license-correction.json
License-File: src/canpal/_native/licenses/qt-qcalendar-license-correction.patch
License-File: src/canpal/_native/licenses/redistribution.json
License-File: src/canpal/_native/licenses/zlib1g-copyright.txt
Requires-Dist: python-can==4.6.1
Requires-Dist: pyserial==3.5
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Requires-Dist: build<2,>=1; extra == "test"
Requires-Dist: twine<8,>=6; extra == "test"
Dynamic: license-file

# python-can-canpal

CANPAL USB and TCP client backend for [python-can](https://python-can.readthedocs.io/).

**0.1.0rc3 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 64-bit 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. Windows 11 x64 and Ubuntu 24.04 x86_64 are the rc3 targets.
Linux ARM64 is planned but not qualified; 32-bit Python is not supported.

```text
python -m pip install --only-binary=:all: python-can-canpal==0.1.0rc3
```

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](https://pan.baidu.com/s/1mi2pbxI) are in
`CANPAL分析仪/二次开发/python-can-canpal/0.1.0rc3/third-party-sources/`.
Download `python-can-canpal-0.1.0rc3-third-party-sources.zip` (235600943 bytes).
Its SHA256 is `8919f717e793b6c021fc7cb35fe0cdd788383bbb554a4021320036c658caec4a`.
The wheel also includes the upstream Qt QCalendar LGPL-header correction.
For source requests or download problems, contact
[yongxiang.wu@hotmail.com](mailto:yongxiang.wu@hotmail.com), specifying version
and platform. See [source and license details](docs/THIRD-PARTY-SOURCES.md).

## Hardware evidence and limits

| Environment | Preview evidence |
| --- | --- |
| Windows 11 x64 | X5 classic CAN/RTR and X6 classic CAN/RTR/ISO FD over USB and explicit-IP WLAN TCP |
| Windows, multiple devices | Two USB devices, X5 USB + X6 WLAN, X5 WLAN + X6 USB; five reopen cycles per device/transport |
| Ubuntu 24.04 x86_64 in Hyper-V | Native Linux SDK with two USB devices through USB/IP; ttyACM number swap with UID selection; TCP checks through temporary SSH forwarding via Windows WLAN |

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 SDK
checks do not qualify a 32-bit Python plugin configuration.

**Not yet qualified:** independent-reference CAN/CAN FD interoperability, physical
Linux host USB controllers, direct Linux WLAN, 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 rc3 hashes are recorded in each wheel's manifest.

| Runtime input file | SHA256 |
| --- | --- |
| Windows x64 CANPAL.dll | `c5bf185e71d06171302163d47f9c709b791306ecddf911de464d5b432daa943a` |
| Ubuntu x86_64 libCANPAL.so | `a7b5d46e50bdb1fa5a580f59f43498fa78a05b959dd2d0c2bd01f9eba242c70d` |

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.
It does not expand the CAN protocol or hardware qualification scope.

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

```python
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. A Linux USB/IP enumeration-order swap has 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.

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