python-can-canpal 0.1.0rc2__tar.gz

python_can_canpal-0.1.0rc2/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Python CANPAL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This license applies to the newly developed PythonCAN plugin, test harness,
+and documentation. The separately supplied CANPAL SDK, its headers, firmware,
+Qt, and other third-party components retain their respective licenses.

python_can_canpal-0.1.0rc2/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE README.md pyproject.toml
+include docs/INSTALL.md docs/TESTING.md docs/RELEASE.md docs/hardware-lab.example.json
+recursive-include native/fake *.cpp *.pro
+include native/sdk-revision.txt
+include tools/sdk_source.py tools/build_fake.py tools/build_sdk.py tools/inspect_devices.py tools/release_check.py
+recursive-include tests *.py
+prune build
+prune dist
+prune artifacts
+exclude PLAN.zh-CN.md

python_can_canpal-0.1.0rc2/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: python-can-canpal
+Version: 0.1.0rc2
+Summary: CANPAL USB and TCP backend for python-can
+License-Expression: MIT
+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
+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.0rc2 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.
+
+```text
+python -m pip install python-can-canpal==0.1.0rc2
+```
+
+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
+
+| 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
+
+Request **CANPAL native SDK build `663eda8`** from your CANPAL supplier through
+the existing supplier channel. Windows x64 and Ubuntu 24.04 x86_64 runtime bundles
+are supplied on request, separately from PyPI. Match the binary SHA256 below and
+the bundle manifest before use; updating this Python package alone does not
+update your installed native SDK.
+
+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.
+
+| Runtime 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. rc2 updates the SDK baseline, validation tooling and documentation;
+its Python runtime behavior is unchanged from rc1.
+
+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
+
+```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.
+
+The source distribution includes Chinese installation, testing and release notes.

python_can_canpal-0.1.0rc2/README.md

@@ -0,0 +1,114 @@
+# python-can-canpal
+
+CANPAL USB and TCP client backend for [python-can](https://python-can.readthedocs.io/).
+
+**0.1.0rc2 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.
+
+```text
+python -m pip install python-can-canpal==0.1.0rc2
+```
+
+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
+
+| 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
+
+Request **CANPAL native SDK build `663eda8`** from your CANPAL supplier through
+the existing supplier channel. Windows x64 and Ubuntu 24.04 x86_64 runtime bundles
+are supplied on request, separately from PyPI. Match the binary SHA256 below and
+the bundle manifest before use; updating this Python package alone does not
+update your installed native SDK.
+
+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.
+
+| Runtime 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. rc2 updates the SDK baseline, validation tooling and documentation;
+its Python runtime behavior is unchanged from rc1.
+
+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
+
+```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.
+
+The source distribution includes Chinese installation, testing and release notes.

python_can_canpal-0.1.0rc2/docs/INSTALL.md

@@ -0,0 +1,105 @@
+# 安装与连接
+
+当前 0.1.0rc2 为实验性预览版。正式发布资格以 RELEASE.md 和验收报告为准，构建成功不表示硬件验收完成。
+
+## 环境
+
+首版目标是 Python 3.12、Windows 11 x64 和 Ubuntu 24.04 x86_64。
+python-can 固定 4.6.1，pySerial 固定 3.5。WSL 可用于开发，但不能代替原生 Linux 硬件验收。
+
+安装 Python 包后，还需要单独安装兼容的 CANPAL 原生 SDK、设备驱动和 Qt/编译器运行库。
+已发布 0.1.0rc1 的验收基线为 e222ccf48f29c530fd09617df6e3a83a8095d25f。
+rc2 的 SDK 基线为 SDK 提交 663eda823be0533754123695405033b38e115489，
+在协作退出及 Qt 串口缓冲修复上，补充 CAN ACK 校验、TCP 缓冲读取、OBD 写失败返回、UDS 来源过滤与跨线程命令同步。
+Windows x64 DLL 和 Ubuntu 24.04 x86_64 SO 通过现有厂商渠道按需提供；请向供应方索取构建 663eda8，并核对 README 与交付包 manifest.json 中的 SHA256。
+升级 Python 包不会自动更新 SDK，须替换 CANPAL_LIBRARY 指向的原生文件。
+旧版 SDK 仅凭导出函数相同不能认定兼容；应使用供应方提供并经过本插件验收的修复版本。
+原生 SDK、固件和第三方库不包含在 PyPI 包内，也不适用本插件的 MIT 许可证。
+
+RTR 接收还需要设备固件保留远程帧 DLC 的修复。已发现的原 X5 0x0332、X6 0x0127
+会把收到的 RTR DLC 清零；插件不能从接收记录中恢复丢失的值。两台测试设备已刷入
+修复构建，并通过 USB/WLAN 双向 RTR DLC 0–8 检查。诊断构建仍报告原版本号，
+因此只比较 SWVer 不足以判断已修复；应向设备供应方确认具体固件构建包含该修复。
+
+
+```text
+python -m pip install python-can-canpal==0.1.0rc2
+```
+
+实际支持范围与未验收项见包首页 README。开发时从源码执行：
+
+```text
+python -m pip install -e ".[test]"
+```
+
+Windows 设置 CANPAL_LIBRARY 为 DLL 绝对路径；若依赖不在 DLL 同目录，
+可设置 CANPAL_DEPENDENCY_DIRS，多个目录使用分号分隔。
+Linux 设置 CANPAL_LIBRARY 为 SO 绝对路径，通过系统链接器安装 Qt 依赖。
+也可在 can.Bus 中传 library_path。导入模块不会加载库或打开设备。
+
+Linux 串口为 /dev/ttyACM数字；通过 udev 或 dialout 组授予当前用户权限，正常运行不要求 root。
+首版不接受任意 ttyUSB 路径。WSL 下调用 Windows python.exe 仍属于 Windows 测试。
+
+## USB 与 UID
+
+```python
+import can
+
+bus = can.Bus(interface="canpal", ignore_config=True,
+              transport="usb", device_id="0123456789abcdef01234567",
+              channel=0, bitrate=500_000)
+try:
+    print(bus.recv(1))
+finally:
+    bus.shutdown()
+```
+
+UID 为实际设备的 12 字节标识，用 24 位十六进制表示。不要把 USB 描述符序列号直接当 UID。
+插件先枚举 CANPAL VID/PID 端口，再读取原生设备身份；不会发送网络广播。
+端口改号后关闭并重新创建 Bus，仍使用相同 UID。
+
+可以同时提供 usb_port="COM9" 作为优先探测提示。
+有 UID 时旧端口不匹配会继续寻找其他候选；仅传 usb_port 则不保证拔插后的设备身份。
+COM1000 等完整编号会被解析，不截取末三位。
+
+## WLAN
+
+```python
+bus = can.Bus(interface="canpal", ignore_config=True,
+              transport="wlan", host="192.0.2.10", port=8000,
+              channel=0, bitrate=500_000,
+              device_id="0123456789abcdef01234567")
+```
+
+IP 与端口必须来自设备实际配置。只支持 PC 为 TCP 客户端、设备为 TCP 服务端的模式。
+可不传 device_id，但仍会读取真实 UID 并检查本进程是否已经占用。
+IP 直连完全不依赖 UDP/广播发现；无自动重连、监听或 UDP 回退。
+
+## 多设备和 CAN FD
+
+为每台不同 UID 设备创建一个 Bus。每台只能选择一个 CAN 通道。
+不同设备可使用相同 channel=0 和相同 CAN ID；应用应在监听器或日志中带上来源 UID。
+每台使用独立 Notifier，避免应用自己把多台设备合并成共享故障处理单元。
+
+X6 开启 FD 时提供 fd=True、data_bitrate=2_000_000。
+fd=False 时仍使用 X6 的原生 FD API承载经典帧。
+完整位时序取自 SDK 的 80/100 MHz 表，由型号和固件版本选择；不支持的速率明确拒绝。
+FD 的非标准物理长度（如 9 字节）会补零到下一合法长度（12），不修改调用者的 Message。
+
+同一个 Bus 只使用一个接收者：直接 recv 或一个 Notifier。
+需要多个消费者时在该 Notifier 上增加监听器，不要并发调用 recv。
+
+## 行为与排错
+
+- send 成功表示原生队列接受，不表示线缆 ACK 或对端收到；Python 不自动重发。
+- send 的 timeout 只约束进入原生调用之前的本地等待；不能取消在途 DLL 调用。
+- recv(None) 等待至收到消息、关闭或离线；软件过滤使用 python-can 基类。
+- 收发时的故障转换为标准 python-can 异常。关闭应用前先停止 Notifier。
+- 设备配置会临时关闭硬件过滤、自动发送、桥接和 spy 功能；不调用保存设置，不写非易失存储。
+- termination=None 保留读取到的终端电阻；True/False 显式设置，listen_only=True 禁止发送。
+- 周期发送使用上游实现，停止后睡眠线程可能在当前周期结束时才退出；关闭后不会再次进入原生发送。
+- 时间戳是每设备初始化采样后的相对换算，含连接采样误差，不提供多设备精确时间同步。
+- 配置失败后关闭本次连接；不在不确定的命令流上继续发送配置或回滚命令。
+- “找不到库”检查绝对路径、64 位架构和 Qt/运行库依赖；禁止用 fake 库处理真实设备。
+- “未找到或不可访问”检查 UID、串口权限、其他进程占用和实际 USB 型号。
+- 本进程 UID 去重不能协调其他应用；同一物理设备应由一个应用独占。

python_can_canpal-0.1.0rc2/docs/RELEASE.md

@@ -0,0 +1,61 @@
+# PyPI 发布流程
+
+用户已指定公开 PyPI，包名 python-can-canpal，新插件代码使用 MIT。
+原生 SDK、头文件、固件与 Qt 不纳入 Python 发布包；其许可独立。
+
+用户已批准先公开发布明确限界的 0.1.0rc1 预览版。版本号本身不代表上传成功或正式验收完成。
+正式 0.1.0 必须完成既定双平台硬件矩阵；没有硬件证据时停止在候选产物阶段。
+
+1. 完成 Windows/Python 3.12 和 Linux/Python 3.12 无硬件回归、三方 ABI、真实 SDK 回归。
+2. 在 Windows 11 x64 与原生 Ubuntu 24.04 x86_64 运行完整硬件 release profile。
+3. 核对 26 组验收、资源计数、实际设备能力、失败记录及支持矩阵。未运行、skip、xfail 均未完成。
+4. 冻结最终代码、SDK 构建哈希、包版本；清洁环境从 sdist 重建 wheel 并安装验证。
+5. 运行 python -m twine check dist/*，审计包内文件，不包含 fake 二进制、私有端点、凭据或 SDK。
+6. 用 tools/release_check.py 检查最终产物和全部证据。任何缺项返回非零。
+7. 通过已有 PyPI 账号的安全凭据或可信发布完成上传；不要把 token 写进源码、日志或聊天。
+8. 从 PyPI JSON 核对版本和 SHA256，并在干净环境从 PyPI 安装该精确版本验证入口和依赖。
+
+发布授权已经给出，不再额外要求一次重复批准。凭据或硬件信息缺失时需要用户补充；
+未通过验收不能将候选包上传后称为正式完成。
+新建公网仓库、上传原生 SDK 或更改 SDK 许可不包含在此发布动作中。
+
+环境及原始报告位于本地 artifacts，默认不随 PyPI 包发布。内部 release-evidence.json
+必须列出最终产物 SHA256、四份无跳过的测试报告（两平台 unit/hardware）、两平台 SDK 回归，
+以及 26 项验收的证据文件。模板允许完整保留 pending 状态。
+
+## 0.1.0rc1 预览版例外
+
+本次例外来自用户明确选择“先发布明确限界的预览版 0.1.0rc1”。
+只允许该预发布版本：README/PyPI 必须列出已验证平台/组合、未验收项目及修复版 SDK/固件要求。
+两平台软件、ABI、真实 SDK 回归和干净安装必须通过；两台刷写后的 12 组补充实机报告必须通过且哈希匹配。
+包内禁止分发原生库、固件、凭据和内部验收资料。正式版检查器默认行为保持完整门槛。
+
+```text
+python tools/release_check.py --profile preview --evidence artifacts/release-evidence.json --dist dist
+```
+
+预览版检查只对本次明确授权的 0.1.0rc1 生效；不将未运行的正式硬件测试标为通过。
+上传后须核对 PyPI 的两份分发文件哈希，并从公共索引在干净环境安装精确版本。
+正式版继续使用默认 release profile，仍需完整双平台矩阵、独立参考设备和额定/长时间验收。
+
+## 0.1.0rc2 预览版
+
+rc2 已获执行授权，继续保持预览版范围。原生 SDK 构建 663eda8 由用户通过现有厂商渠道按需提供；Python 包说明应明确索取方式及两平台 SDK 文件哈希。
+
+rc2 检查器使用独立规则，不扩大 rc1 例外，也不改变正式版门槛。它要求：
+
+- 两平台 unit、installed、真实 SDK JUnit 无失败或跳过；
+- SDK 固定提交、实际 DLL/SO、SDK 构建上下文和交付 ZIP 内文件一致；
+- 两平台干净安装上下文绑定最终 wheel 哈希、SDK 哈希、版本和插件入口；
+- Windows x64/x86、Linux 各 170 项回归，以及 Linux TSan 两项检查通过；
+- 12 份指定收发报告使用交付 SDK，其中 Linux 双 USB 报告必须显示同一 UID 的端口确实变化；
+- X5/X6 各 USB/WLAN 五次重新打开报告通过；
+- SDK 获取方式可用，wheel/sdist 的版本、哈希和预览版限制说明正确。
+
+仅版本号、文档和发布工具变化时可复用与交付 SDK 哈希完全一致的实机报告；运行时代码或 SDK 二进制变化则重新验证受影响路径。
+
+```text
+python tools/release_check.py --profile preview --evidence artifacts/rc2-release/release-evidence.json --dist dist/0.1.0rc2
+```
+
+从最终 sdist 在干净构建环境生成 wheel，再在 Windows 与 Ubuntu 的干净环境安装测试。上传后核对公共 PyPI JSON 中两个文件的 SHA256，分别安装精确版本验证插件入口及短程实机收发。SDK、固件、Qt/MinGW 运行库仍不进入 Python 包，MIT 范围不变。

python_can_canpal-0.1.0rc2/docs/TESTING.md

@@ -0,0 +1,88 @@
+# 自动化测试与真实验收
+
+## 本地回归
+
+从独立安装的、记录提交版本的 CANPALAPI 源码构建 fake：
+
+```text
+python tools/build_fake.py --sdk /path/to/CANPALAPI --compiler /path/to/g++
+python -m pip install -e ".[test]"
+python -m pytest -m "not hardware" --junitxml=artifacts/unit.xml
+```
+
+Windows 的 MinGW 线程运行库目录应加入 CANPAL_DEPENDENCY_DIRS。
+同一份 C++ fake 导出真实 ABI，模拟四个设备、独立句柄/队列、断线、调用失败及发送阻塞。
+fake 不进入生产 wheel；测试只通过显式路径加载它。
+
+构建脚本生成 abi.json 与 abi-internal.json，分别来自公开头文件与 SDK 实际内部定义；
+两者必须一致，pytest 再与 ctypes 的所有字段逐一对照。
+SDK 源码不复制进本项目，运行环境和头文件哈希进入内部验收记录。
+
+## 真实 SDK 回归
+
+执行以下命令可复现构建并保存原生 JUnit、二进制哈希及构建日志：
+
+```text
+python tools/build_sdk.py --sdk /path/to/CANPALAPI --qmake /path/to/qmake --make /path/to/make
+```
+
+Windows 使用 MinGW 配套 qmake/mingw32-make，Linux 使用系统 Qt 5 工具。
+两个构建脚本强制核对 native/sdk-revision.txt 中的 SDK 提交，并拒绝修改过的 SDK 源文件。
+CI 在两平台依次运行上述构建、pytest 和包构建命令，SDK 源码须由其授权渠道提供。
+再次运行会将旧报告保存到 artifacts/history，保留失败与重跑记录。
+每次使用独立构建目录，防止 SDK 切换版本后复用旧目标文件；实际 DLL/SO 路径记录在 artifacts/{windows,linux}-sdk-context.json 的 library 字段。
+版本校验允许生成的二进制、安装器和 IDE 文件变化，仍拒绝修改过的编译输入和新增的根目录源码。
+
+native/fake/sdk_smoke.pro 是真实库回归工程，名称所在目录不表示它链接 fake。
+qmake 参数 SDK_ROOT 指向 SDK 源码，SDK_BUILD 指向真实 DLL/SO 和导入库目录。
+测试包括命令/通道/条目不匹配的 ACK，以及两台设备对象同时存在时 200 次线程协作回收。
+Linux 还使用真实 Qt 串口与伪终端：先缓冲 128 字节，再停止输入，分批读完，防止等待新数据时遗漏已缓冲数据。
+伪终端没有 DTR 引脚，因此夹具直接打开 Qt 串口，只检查生产 process() 读取路径；真实设备的 DTR 初始化仍须通过 USB 硬件验收。
+这项测试已验证修复前失败、修复后通过。以上回归不打开真实 CAN 设备，不能替代连接故障和硬件验收。
+
+固定版本 SDK 另提供 tests/regression/run.py：170 项原生断言覆盖 ACK 字段与超时、TCP 缓冲边界、OBD 重试、UDS ExpectedMask 和双设备命令交接；Linux --tsan 检查线程生命周期与命令同步。该套件的源码快照、提交号、编译器、库哈希和 JUnit 应一并保存。
+
+## 硬件配置
+
+复制 hardware-lab.example.json 到不纳入版本管理的内部位置，并填写：
+
+- 独立且已隔离的测试总线确认、真实 SDK 路径、至少两台设备 UID 和网络端点；
+- 每台的独立参考 CAN 接口，不能用 canpal 或 virtual 作为参考；
+- 两条隔离物理 CAN 网络及各自终端电阻/位时序；
+- 控制 USB 断开/连接/改号与网络断开的命令数组；
+- 阻断和恢复发现广播的命令数组。
+
+控制脚本由测试台提供，pytest 通过 subprocess 参数数组调用，不使用 shell 展开。
+命令须同步完成对应动作后返回；不支持的控制不能填写一个空操作来冒充。
+系统实际 COM/ttyACM 编号必须发生变化，否则不计入改号次数。
+
+```text
+python -m pytest -m hardware --hardware-config /path/to/lab.json --junitxml=artifacts/hardware.xml
+```
+
+profile=smoke 用于短联调，不能放行正式版；profile=release 启用每组合 30 分钟和混合连接两小时运行，
+以及 10 次改号、每拓扑 5 次断线、USB/TCP 各 20 次重新打开。
+实际平均发送率至少达到预设 500 fps 的 98%，不在失败后降低目标。
+硬件套件会验证数据序号、载荷、丢失/重复、跨设备隔离、监听和关闭清理。
+线缆矩阵逐向校验标准/扩展 ID 的零值和最大值、经典 CAN 的 0–8 字节及 RTR DLC、
+FD 的 0–64 字节和 BRS 开关，并检查完整标志位、DLC、补零和原消息不变。
+参考接口发送 FD 时使用合法线缆长度；任意长度补零由 CANPAL 发送路径负责验证。
+RTR 没有数据不代表 DLC 必须为零，接收 DLC 与请求不符必须判失败。
+没有配置时硬件用例明确 skip，完整验收仍未完成。
+
+Windows 与原生 Linux 分别执行；WSL 的 release profile 被拒绝。
+Hyper-V 中的 Ubuntu 可运行原生 Linux SDK。USB/IP 透传验收应记录宿主、来宾系统、USB/IP 版本、CDC ACM 端口和设备 UID；它验证 Linux USB 协议栈与真实设备，不能声称已覆盖物理 Linux 主机的 USB 控制器或拔线电气行为。
+还须保存原生句柄/线程/端口资源计数、广播阻断抓包、型号/固件矩阵及实际重试/时间戳行为记录。
+这些设备和系统级证据不能由 fake 或 Python 对象数量替代。
+
+## 与方案对应
+
+测试名称中的 T 编号对应 PLAN.zh-CN.md 的 26 组要求。
+一个用例可能覆盖多组要求，同一组也可能需要 fake、真实库和硬件三种证据。
+自动化套件成功不是整个需求组自动关闭：尚未实测的型号、固件行为、
+故障清理和资源观察必须留在发布验收记录中，不允许补填“通过”。
+
+发布前从最终 sdist 构建 wheel，并在干净环境安装、检查 can.interface 入口、运行消息与 fake 回归。
+最终 SDK 二进制、wheel、sdist、代码提交及报告必须匹配。
+
+0.1.0rc1 和 0.1.0rc2 经用户明确授权采用各自预览版门槛，见 RELEASE.md。预览版补充检查不关闭上述正式硬件验收缺项。

python_can_canpal-0.1.0rc2/docs/hardware-lab.example.json

@@ -0,0 +1,47 @@
+{
+  "isolated_test_bench": false,
+  "profile": "smoke",
+  "library_path": "/absolute/path/to/real/CANPAL/library",
+  "devices": [
+    {
+      "device_id": "REPLACE_WITH_24_HEX_UID",
+      "channel": 0,
+      "fd": false,
+      "host": "192.0.2.1",
+      "port": 8001,
+      "reference": {
+        "interface": "pcan",
+        "channel": "PCAN_USBBUS1"
+      },
+      "controls": {
+        "disconnect_usb": [],
+        "connect_usb": [],
+        "remap_usb": [],
+        "disconnect_wlan": [],
+        "connect_wlan": []
+      }
+    },
+    {
+      "device_id": "REPLACE_WITH_24_HEX_UID",
+      "channel": 0,
+      "fd": true,
+      "host": "192.0.2.2",
+      "port": 8002,
+      "reference": {
+        "interface": "pcan",
+        "channel": "PCAN_USBBUS2"
+      },
+      "controls": {
+        "disconnect_usb": [],
+        "connect_usb": [],
+        "remap_usb": [],
+        "disconnect_wlan": [],
+        "connect_wlan": []
+      }
+    }
+  ],
+  "controls": {
+    "block_discovery": [],
+    "restore_discovery": []
+  }
+}