xusbcan-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. xusbcan_cli-0.1.0/PKG-INFO +152 -0
  2. xusbcan_cli-0.1.0/README.md +138 -0
  3. xusbcan_cli-0.1.0/pyproject.toml +42 -0
  4. xusbcan_cli-0.1.0/setup.cfg +4 -0
  5. xusbcan_cli-0.1.0/src/xusbcan/__init__.py +7 -0
  6. xusbcan_cli-0.1.0/src/xusbcan/adapters/__init__.py +1 -0
  7. xusbcan_cli-0.1.0/src/xusbcan/adapters/registry.py +88 -0
  8. xusbcan_cli-0.1.0/src/xusbcan/adapters/zlg/__init__.py +23 -0
  9. xusbcan_cli-0.1.0/src/xusbcan/adapters/zlg/backend.py +225 -0
  10. xusbcan_cli-0.1.0/src/xusbcan/adapters/zlg/device_pool.py +94 -0
  11. xusbcan_cli-0.1.0/src/xusbcan/adapters/zlg/dll.py +192 -0
  12. xusbcan_cli-0.1.0/src/xusbcan/cli/__init__.py +1 -0
  13. xusbcan_cli-0.1.0/src/xusbcan/cli/__main__.py +6 -0
  14. xusbcan_cli-0.1.0/src/xusbcan/cli/app.py +106 -0
  15. xusbcan_cli-0.1.0/src/xusbcan/config/__init__.py +5 -0
  16. xusbcan_cli-0.1.0/src/xusbcan/config/loader.py +78 -0
  17. xusbcan_cli-0.1.0/src/xusbcan/core/__init__.py +50 -0
  18. xusbcan_cli-0.1.0/src/xusbcan/core/commands.py +270 -0
  19. xusbcan_cli-0.1.0/src/xusbcan/core/monitor.py +178 -0
  20. xusbcan_cli-0.1.0/src/xusbcan/core/periodic.py +72 -0
  21. xusbcan_cli-0.1.0/src/xusbcan/core/session.py +282 -0
  22. xusbcan_cli-0.1.0/src/xusbcan/mcp/__init__.py +1 -0
  23. xusbcan_cli-0.1.0/src/xusbcan/mcp/server.py +41 -0
  24. xusbcan_cli-0.1.0/src/xusbcan/mcp/tools.py +90 -0
  25. xusbcan_cli-0.1.0/src/xusbcan/models/__init__.py +14 -0
  26. xusbcan_cli-0.1.0/src/xusbcan/models/device.py +27 -0
  27. xusbcan_cli-0.1.0/src/xusbcan/models/frame.py +68 -0
  28. xusbcan_cli-0.1.0/src/xusbcan/models/result.py +95 -0
  29. xusbcan_cli-0.1.0/src/xusbcan_cli.egg-info/PKG-INFO +152 -0
  30. xusbcan_cli-0.1.0/src/xusbcan_cli.egg-info/SOURCES.txt +39 -0
  31. xusbcan_cli-0.1.0/src/xusbcan_cli.egg-info/dependency_links.txt +1 -0
  32. xusbcan_cli-0.1.0/src/xusbcan_cli.egg-info/entry_points.txt +6 -0
  33. xusbcan_cli-0.1.0/src/xusbcan_cli.egg-info/requires.txt +9 -0
  34. xusbcan_cli-0.1.0/src/xusbcan_cli.egg-info/top_level.txt +1 -0
  35. xusbcan_cli-0.1.0/tests/test_config.py +57 -0
  36. xusbcan_cli-0.1.0/tests/test_core.py +146 -0
  37. xusbcan_cli-0.1.0/tests/test_mcp_smoke.py +67 -0
  38. xusbcan_cli-0.1.0/tests/test_mcp_stdio.py +45 -0
  39. xusbcan_cli-0.1.0/tests/test_models.py +52 -0
  40. xusbcan_cli-0.1.0/tests/test_registry.py +52 -0
  41. xusbcan_cli-0.1.0/tests/test_result.py +49 -0
@@ -0,0 +1,152 @@
1
+ Metadata-Version: 2.4
2
+ Name: xusbcan-cli
3
+ Version: 0.1.0
4
+ Summary: 面向 AI Agent 的 CAN 总线调试工具(CLI + MCP)
5
+ Requires-Python: >=3.11
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: python-can>=4.4
8
+ Provides-Extra: mcp
9
+ Requires-Dist: mcp>=2.0; extra == "mcp"
10
+ Provides-Extra: dev
11
+ Requires-Dist: pytest; extra == "dev"
12
+ Requires-Dist: ruff; extra == "dev"
13
+ Requires-Dist: mypy; extra == "dev"
14
+
15
+ # xusbcan-cli
16
+
17
+ 面向 AI Agent 的 CAN 总线调试工具。
18
+
19
+ 中文 | [English](README.en.md)
20
+
21
+ > **免责声明**:本项目与广州致远电子股份有限公司(周立功/ZLG)及其产品**没有任何关联、赞助、背书或利益关系**。"周立功"、"ZLG"、"zlgcan" 等名称均为其各自权利人的商标。本项目是独立的第三方工具,仅通过公开的二次开发接口对接其硬件;驱动与 SDK 版权归其权利人所有,由用户从官方渠道获取。
22
+
23
+ 以后端服务形态运行,同时提供标准 **CLI** 与 **MCP(Model Context Protocol)接口**,让 AI Agent 能直接完成 CAN 报文的收发、监听、周期发送等调试操作——无需人工操作上位机软件,即可实现 **Agent 自动化联合调试**。
24
+
25
+ ## 目标与展望
26
+
27
+ 在 AI 时代,让 Agent 能像使用普通工具一样操作 CAN 总线:结构化输出、稳定契约、可被程序化调用。
28
+
29
+ 我们希望 xusbcan-cli 成为 **AI 与车载 / 工业 CAN 总线之间的标准桥梁**,让「用 Agent 自动完成整条总线的联调、诊断、验证」成为常态。
30
+
31
+ ## 特性
32
+
33
+ - **统一设备抽象**:多家厂商 CAN 卡(周立功 / Vector / PEAK / 创芯 …)通过统一接口接入,Agent 看到的是同一套命令语义
34
+ - **CLI 与 MCP 共享核心**:行为一致,结构化 JSON / JSONL 输出,Agent 无需解析人类可读日志
35
+ - **轻量**:核心运行时依赖仅 `python-can`
36
+
37
+ ## 安装
38
+
39
+ ### 从源码安装(当前方式)
40
+
41
+ ```bash
42
+ git clone https://github.com/Archaofan/xusbcan-cli.git
43
+ cd xusbcan-cli
44
+ pip install -e . # 仅 CLI + 核心
45
+ pip install -e ".[mcp]" # 追加 MCP 服务器支持
46
+ ```
47
+
48
+ ### 从 PyPI 安装(即将提供)
49
+
50
+ ```bash
51
+ pip install xusbcan-cli # 仅 CLI + 核心
52
+ pip install xusbcan-cli[mcp] # 追加 MCP 服务器支持
53
+ ```
54
+
55
+ ## 快速开始
56
+
57
+ ### 1. 准备环境
58
+
59
+ **运行前提**:
60
+ - Python 3.11+(64 位)
61
+ - 一张周立功 USBCAN-2E-U 卡
62
+ - 周立功 USB 设备驱动(让系统识别设备)
63
+ - 周立功二次开发 SDK 资料包(提供 `zlgcan.dll`)
64
+
65
+ **获取 SDK**:从周立功官方资料页下载二次开发 SDK 资料包:
66
+
67
+ > https://manual.zlg.cn/web/#/152?page_id=5332
68
+
69
+ 下载后**解压即符合要求**——官方资料包解压出的 SDK 目录已包含运行所需的 `zlgcan.dll` 与 `kerneldlls/`(内核 DLL),无需额外整理。
70
+
71
+ **配置环境变量**:将解压后的 SDK 目录路径设为环境变量 `ZLG_SDK_DIR`:
72
+
73
+ ```bash
74
+ # Windows(PowerShell,用户级持久化)
75
+ [Environment]::SetEnvironmentVariable("ZLG_SDK_DIR", "D:\path\to\解压后的SDK目录", "User")
76
+
77
+ # 或临时设置(仅当前终端生效)
78
+ set ZLG_SDK_DIR=D:\path\to\解压后的SDK目录
79
+ ```
80
+
81
+ 指向的目录结构应为:
82
+
83
+ ```
84
+ <ZLG_SDK_DIR>/
85
+ ├── zlgcan.dll # 核心库(必需)
86
+ └── kerneldlls/ # 内核 DLL 目录(必需,与 zlgcan.dll 同目录)
87
+ ```
88
+
89
+ ### 2. 编写配置 `xusbcan.toml`
90
+
91
+ ```toml
92
+ [[devices]]
93
+ name = "ecu" # 逻辑别名,Agent 通过它引用设备
94
+ vendor = "zlg"
95
+ model = "USBCAN-2E-U"
96
+ channel = 1
97
+ nominal = 250000 # 波特率
98
+ ```
99
+
100
+ ### 3. 使用 CLI
101
+
102
+ ```bash
103
+ xusbcan list # 列出设备
104
+ xusbcan send ecu --id 0x123 --data "01 02 03" # 发送
105
+ xusbcan receive ecu --timeout 1 # 接收一帧
106
+ xusbcan monitor ecu --duration 5 # 监听
107
+ xusbcan status ecu # 状态
108
+ ```
109
+
110
+ ### 4. 启动 MCP 服务器
111
+
112
+ ```bash
113
+ xusbcan-mcp
114
+ ```
115
+
116
+ 在你的 MCP 客户端(Claude Desktop / Cursor / Claude Code 等)里注册它。配置示例:
117
+
118
+ ```json
119
+ {
120
+ "mcpServers": {
121
+ "xusbcan": {
122
+ "command": "xusbcan-mcp",
123
+ "env": {
124
+ "ZLG_SDK_DIR": "D:\\path\\to\\zlgcan_x64",
125
+ "XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
126
+ }
127
+ }
128
+ }
129
+ }
130
+ ```
131
+
132
+ 连接后,Agent 即可通过 `send_frame`、`receive_frame`、`monitor`、`periodic_start` 等工具直接调试 CAN 总线。
133
+
134
+ ## 支持的硬件
135
+
136
+ 当前已验证:**周立功 USBCAN-2E-U**。
137
+
138
+ 项目基于 [python-can](https://python-can.readthedocs.io/),天然覆盖大量厂商后端(Vector、PEAK、socketcan、slcan、Kvaser …)。新增一种 CAN 卡,通常只需增加一个后端适配或一条设备配置,即可让 Agent 用同一套接口操作它。
139
+
140
+ ### 欢迎适配更多 CAN 卡 🙌
141
+
142
+ 如果你手头有其它型号的 CAN 卡(Vector / PEAK / 创芯 / Kvaser / 国产卡 …),欢迎贡献后端适配或设备配置。让更多硬件能被 AI Agent 直接使用,是这个项目的核心目标之一。
143
+
144
+ ## 参与
145
+
146
+ - 报告问题、提出需求、提交 PR
147
+ - 贡献新的 CAN 卡适配
148
+ - 一起把「Agent 自动化联合调试 CAN」这件事做成通用能力
149
+
150
+ ## License
151
+
152
+ 第三方组件的许可条款见 [`third_party/NOTICES`](third_party/NOTICES)。
@@ -0,0 +1,138 @@
1
+ # xusbcan-cli
2
+
3
+ 面向 AI Agent 的 CAN 总线调试工具。
4
+
5
+ 中文 | [English](README.en.md)
6
+
7
+ > **免责声明**:本项目与广州致远电子股份有限公司(周立功/ZLG)及其产品**没有任何关联、赞助、背书或利益关系**。"周立功"、"ZLG"、"zlgcan" 等名称均为其各自权利人的商标。本项目是独立的第三方工具,仅通过公开的二次开发接口对接其硬件;驱动与 SDK 版权归其权利人所有,由用户从官方渠道获取。
8
+
9
+ 以后端服务形态运行,同时提供标准 **CLI** 与 **MCP(Model Context Protocol)接口**,让 AI Agent 能直接完成 CAN 报文的收发、监听、周期发送等调试操作——无需人工操作上位机软件,即可实现 **Agent 自动化联合调试**。
10
+
11
+ ## 目标与展望
12
+
13
+ 在 AI 时代,让 Agent 能像使用普通工具一样操作 CAN 总线:结构化输出、稳定契约、可被程序化调用。
14
+
15
+ 我们希望 xusbcan-cli 成为 **AI 与车载 / 工业 CAN 总线之间的标准桥梁**,让「用 Agent 自动完成整条总线的联调、诊断、验证」成为常态。
16
+
17
+ ## 特性
18
+
19
+ - **统一设备抽象**:多家厂商 CAN 卡(周立功 / Vector / PEAK / 创芯 …)通过统一接口接入,Agent 看到的是同一套命令语义
20
+ - **CLI 与 MCP 共享核心**:行为一致,结构化 JSON / JSONL 输出,Agent 无需解析人类可读日志
21
+ - **轻量**:核心运行时依赖仅 `python-can`
22
+
23
+ ## 安装
24
+
25
+ ### 从源码安装(当前方式)
26
+
27
+ ```bash
28
+ git clone https://github.com/Archaofan/xusbcan-cli.git
29
+ cd xusbcan-cli
30
+ pip install -e . # 仅 CLI + 核心
31
+ pip install -e ".[mcp]" # 追加 MCP 服务器支持
32
+ ```
33
+
34
+ ### 从 PyPI 安装(即将提供)
35
+
36
+ ```bash
37
+ pip install xusbcan-cli # 仅 CLI + 核心
38
+ pip install xusbcan-cli[mcp] # 追加 MCP 服务器支持
39
+ ```
40
+
41
+ ## 快速开始
42
+
43
+ ### 1. 准备环境
44
+
45
+ **运行前提**:
46
+ - Python 3.11+(64 位)
47
+ - 一张周立功 USBCAN-2E-U 卡
48
+ - 周立功 USB 设备驱动(让系统识别设备)
49
+ - 周立功二次开发 SDK 资料包(提供 `zlgcan.dll`)
50
+
51
+ **获取 SDK**:从周立功官方资料页下载二次开发 SDK 资料包:
52
+
53
+ > https://manual.zlg.cn/web/#/152?page_id=5332
54
+
55
+ 下载后**解压即符合要求**——官方资料包解压出的 SDK 目录已包含运行所需的 `zlgcan.dll` 与 `kerneldlls/`(内核 DLL),无需额外整理。
56
+
57
+ **配置环境变量**:将解压后的 SDK 目录路径设为环境变量 `ZLG_SDK_DIR`:
58
+
59
+ ```bash
60
+ # Windows(PowerShell,用户级持久化)
61
+ [Environment]::SetEnvironmentVariable("ZLG_SDK_DIR", "D:\path\to\解压后的SDK目录", "User")
62
+
63
+ # 或临时设置(仅当前终端生效)
64
+ set ZLG_SDK_DIR=D:\path\to\解压后的SDK目录
65
+ ```
66
+
67
+ 指向的目录结构应为:
68
+
69
+ ```
70
+ <ZLG_SDK_DIR>/
71
+ ├── zlgcan.dll # 核心库(必需)
72
+ └── kerneldlls/ # 内核 DLL 目录(必需,与 zlgcan.dll 同目录)
73
+ ```
74
+
75
+ ### 2. 编写配置 `xusbcan.toml`
76
+
77
+ ```toml
78
+ [[devices]]
79
+ name = "ecu" # 逻辑别名,Agent 通过它引用设备
80
+ vendor = "zlg"
81
+ model = "USBCAN-2E-U"
82
+ channel = 1
83
+ nominal = 250000 # 波特率
84
+ ```
85
+
86
+ ### 3. 使用 CLI
87
+
88
+ ```bash
89
+ xusbcan list # 列出设备
90
+ xusbcan send ecu --id 0x123 --data "01 02 03" # 发送
91
+ xusbcan receive ecu --timeout 1 # 接收一帧
92
+ xusbcan monitor ecu --duration 5 # 监听
93
+ xusbcan status ecu # 状态
94
+ ```
95
+
96
+ ### 4. 启动 MCP 服务器
97
+
98
+ ```bash
99
+ xusbcan-mcp
100
+ ```
101
+
102
+ 在你的 MCP 客户端(Claude Desktop / Cursor / Claude Code 等)里注册它。配置示例:
103
+
104
+ ```json
105
+ {
106
+ "mcpServers": {
107
+ "xusbcan": {
108
+ "command": "xusbcan-mcp",
109
+ "env": {
110
+ "ZLG_SDK_DIR": "D:\\path\\to\\zlgcan_x64",
111
+ "XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
112
+ }
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ 连接后,Agent 即可通过 `send_frame`、`receive_frame`、`monitor`、`periodic_start` 等工具直接调试 CAN 总线。
119
+
120
+ ## 支持的硬件
121
+
122
+ 当前已验证:**周立功 USBCAN-2E-U**。
123
+
124
+ 项目基于 [python-can](https://python-can.readthedocs.io/),天然覆盖大量厂商后端(Vector、PEAK、socketcan、slcan、Kvaser …)。新增一种 CAN 卡,通常只需增加一个后端适配或一条设备配置,即可让 Agent 用同一套接口操作它。
125
+
126
+ ### 欢迎适配更多 CAN 卡 🙌
127
+
128
+ 如果你手头有其它型号的 CAN 卡(Vector / PEAK / 创芯 / Kvaser / 国产卡 …),欢迎贡献后端适配或设备配置。让更多硬件能被 AI Agent 直接使用,是这个项目的核心目标之一。
129
+
130
+ ## 参与
131
+
132
+ - 报告问题、提出需求、提交 PR
133
+ - 贡献新的 CAN 卡适配
134
+ - 一起把「Agent 自动化联合调试 CAN」这件事做成通用能力
135
+
136
+ ## License
137
+
138
+ 第三方组件的许可条款见 [`third_party/NOTICES`](third_party/NOTICES)。
@@ -0,0 +1,42 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "xusbcan-cli"
7
+ version = "0.1.0"
8
+ description = "面向 AI Agent 的 CAN 总线调试工具(CLI + MCP)"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ dependencies = [
12
+ "python-can>=4.4",
13
+ ]
14
+
15
+ [project.optional-dependencies]
16
+ mcp = ["mcp>=2.0"]
17
+ dev = ["pytest", "ruff", "mypy"]
18
+
19
+ [project.scripts]
20
+ xusbcan = "xusbcan.cli.app:main"
21
+ xusbcan-mcp = "xusbcan.mcp.server:main"
22
+
23
+ [project.entry-points."can.interface"]
24
+ zlg = "xusbcan.adapters.zlg.backend:ZlgBus"
25
+
26
+ [tool.setuptools.packages.find]
27
+ where = ["src"]
28
+
29
+ [tool.pytest.ini_options]
30
+ testpaths = ["tests"]
31
+
32
+ [tool.ruff]
33
+ line-length = 100
34
+ target-version = "py311"
35
+
36
+ [tool.ruff.lint]
37
+ select = ["E", "F", "I", "UP", "B"]
38
+
39
+ [tool.mypy]
40
+ python_version = "3.11"
41
+ ignore_missing_imports = true
42
+
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,7 @@
1
+ """xusbcan —— 面向 AI Agent 的 CAN 总线调试工具。
2
+
3
+ 顶层包不得 import 任何厂商相关模块(如 adapters.zlg),以保证在 Linux
4
+ (无 zlgcan.dll)上也能 `import xusbcan`,`virtual` 后端测试才能运行。
5
+ """
6
+
7
+ __version__ = "0.1.0"
@@ -0,0 +1 @@
1
+ """适配层:唯一接触厂商 SDK 的地方。上层只通过 registry 访问,不 import 厂商代码。"""
@@ -0,0 +1,88 @@
1
+ """单一适配链路:DeviceSpec → registry → can.Bus。
2
+
3
+ zlg 是 python-can 的自定义 interface,经 entry point 注册,与官方 backend 地位平等。
4
+ 本模块模块级不 import adapters.zlg,保证 Linux 上可导入(virtual 后端测试可运行)。
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Callable
10
+ from dataclasses import dataclass
11
+
12
+ import can
13
+
14
+ from ..models.device import DeviceSpec
15
+ from ..models.result import ErrorCode, Result
16
+
17
+
18
+ @dataclass
19
+ class Profile:
20
+ """(vendor, model) → backend 的映射。options 是 backend 专属选项,进 can.Bus kwargs。"""
21
+
22
+ interface: str # python-can interface 名
23
+ channels: int = 1 # 通道数(能力查询 + 越界检查)
24
+ fd: bool = False # 是否支持 CAN FD
25
+ channel_map: Callable[[int], int | str] | None = None # 逻辑通道号 → 厂商通道地址
26
+ options: dict | None = None # backend 专属选项(不混入厂商联合体)
27
+
28
+
29
+ # 注意:周立功手册的 "CANalyst-II+" 走 zlgcan;python-can 官方 canalystii(创芯
30
+ # CANalyst-II)是否覆盖它尚未证实,暂不把创芯卡列为「改配置即可」。
31
+ PROFILES: dict[tuple[str, str], Profile] = {
32
+ ("zlg", "USBCAN-2E-U"): Profile(
33
+ "zlg", channels=2, fd=False, options={"device_type": 21, "device_index": 0}
34
+ ),
35
+ ("peak", "PCAN-USB"): Profile("pcan", channel_map=lambda n: f"PCAN_USBBUS{n + 1}"),
36
+ ("vector", "VN1630"): Profile("vector"),
37
+ }
38
+
39
+
40
+ def resolve(spec: DeviceSpec) -> Profile:
41
+ """按 (vendor, model) 查 Profile。找不到抛 KeyError,由调用方转 CONFIG_ERROR。"""
42
+ key = (spec.vendor, spec.model)
43
+ try:
44
+ return PROFILES[key]
45
+ except KeyError as e:
46
+ raise KeyError(f"未注册的设备: {spec.vendor}/{spec.model}") from e
47
+
48
+
49
+ def open_bus(spec: DeviceSpec) -> can.BusABC:
50
+ """把 DeviceSpec 解析为 can.Bus。channel 经 channel_map 映射;extra/options 透传。"""
51
+ profile = resolve(spec)
52
+
53
+ if spec.channel < 0 or spec.channel >= profile.channels:
54
+ raise ValueError(f"通道号越界: {spec.channel}(该设备 {profile.channels} 路)")
55
+
56
+ kwargs: dict = dict(profile.options or {})
57
+ kwargs.update(spec.extra or {})
58
+ # 禁止覆盖 interface / channel
59
+ kwargs.pop("interface", None)
60
+ kwargs.pop("channel", None)
61
+
62
+ channel: int | str = spec.channel
63
+ if profile.channel_map is not None:
64
+ channel = profile.channel_map(spec.channel)
65
+
66
+ bitrate = spec.bitrate.nominal if spec.bitrate else None
67
+
68
+ return can.Bus(
69
+ interface=profile.interface,
70
+ channel=channel,
71
+ bitrate=bitrate,
72
+ **kwargs,
73
+ )
74
+
75
+
76
+ def open_device(spec: DeviceSpec) -> Result:
77
+ """带错误转换的打开入口。core 通过它拿 can.Bus,不直接接触厂商异常。"""
78
+ try:
79
+ bus = open_bus(spec)
80
+ except KeyError as e:
81
+ return Result.err(ErrorCode.CONFIG_ERROR, str(e))
82
+ except ValueError as e:
83
+ return Result.err(ErrorCode.CHANNEL_OUT_OF_RANGE, str(e))
84
+ except can.CanError as e:
85
+ return Result.err(ErrorCode.DEVICE_OPEN_FAILED, f"打开设备失败: {e}")
86
+ except Exception as e: # noqa: BLE001 —— 收拢未知异常,避免接口层两套失败
87
+ return Result.err(ErrorCode.INTERNAL_ERROR, f"内部错误: {e}")
88
+ return Result.ok(bus)
@@ -0,0 +1,23 @@
1
+ """zlg python-can backend:把周立功 zlgcan.dll 适配成 ``can.Bus(interface='zlg')``。
2
+
3
+ 经 entry point ``zlg = xusbcan.adapters.zlg.backend:ZlgBus`` 注册,与官方 backend
4
+ 地位平等。本包模块级**不**加载 DLL(惰性 ``get_dll()``),Linux 上可安全导入。
5
+ """
6
+
7
+ from .backend import ZlgBus
8
+ from .device_pool import ZlgDevicePool
9
+ from .dll import (
10
+ ZlgConfigError,
11
+ ZlgDllNotFoundError,
12
+ ZlgError,
13
+ get_dll,
14
+ )
15
+
16
+ __all__ = [
17
+ "ZlgBus",
18
+ "ZlgDevicePool",
19
+ "get_dll",
20
+ "ZlgError",
21
+ "ZlgConfigError",
22
+ "ZlgDllNotFoundError",
23
+ ]
@@ -0,0 +1,225 @@
1
+ """ZlgBus:把 zlgcan.dll 适配成 python-can 的 ``interface='zlg'`` backend。
2
+
3
+ 经 entry point ``zlg = xusbcan.adapters.zlg.backend:ZlgBus`` 注册,与官方 backend
4
+ 地位平等。上层只面向 can.Bus / can.Message,看不到厂商细节。
5
+
6
+ 关键点(架构方案 v0.4 §4.4 / §11 / §12):
7
+ - 打开顺序:acquire 设备池 -> ZCAN_SetValue(baud_rate)(InitCAN 之前)
8
+ -> ZCAN_InitCAN -> ZCAN_StartCAN。
9
+ - InitCAN 成功但 StartCAN 失败时,构造内反向释放(ReleaseChannel + 归还池),
10
+ 不留半打开句柄。
11
+ - 实现 _recv_internal(有限等待轮询,绝不用 wait_time=-1)与 send 与 shutdown,
12
+ 不覆盖 recv。
13
+ - can_id 映射与 Linux socketcan 一致:arbitration_id = can_id & 0x1FFFFFFF;
14
+ is_extended = can_id & 0x80000000;is_remote = can_id & 0x40000000。
15
+ - 时间戳:设备上电微秒 -> 在 backend 内换算成 Unix 秒(float)。
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import ctypes
21
+ import time
22
+
23
+ import can
24
+ from can import BusABC, Message
25
+
26
+ from ...models.result import ErrorCode
27
+ from .device_pool import device_pool
28
+ from .dll import (
29
+ INVALID_HANDLE,
30
+ STATUS_OK,
31
+ TYPE_CAN,
32
+ ZCAN_USBCAN_2E_U,
33
+ ZCAN_Receive_Data,
34
+ ZCAN_Transmit_Data,
35
+ ZlgError,
36
+ get_dll,
37
+ make_init_config,
38
+ )
39
+
40
+
41
+ class ZlgCapabilityUnsupportedError(ZlgError):
42
+ """设备不支持该能力(对应 CAPABILITY_UNSUPPORTED),如 2E 卡发 CAN FD。"""
43
+
44
+ code: ErrorCode = ErrorCode.CAPABILITY_UNSUPPORTED
45
+
46
+
47
+ class ZlgBus(BusABC):
48
+ """周立功 zlgcan backend。channel 即 can_index(0/1)。"""
49
+
50
+ def __init__(self, channel, can_filters=None, **kwargs):
51
+ self._channel = int(channel)
52
+ self._device_type = int(kwargs.pop("device_type", ZCAN_USBCAN_2E_U))
53
+ self._device_index = int(kwargs.pop("device_index", 0))
54
+ # 2E 卡不支持 CAN FD,忽略 data_bitrate
55
+ kwargs.pop("data_bitrate", None)
56
+ bitrate = kwargs.pop("bitrate", None)
57
+ if bitrate is None:
58
+ raise can.CanInitializationError(
59
+ "zlg backend 需要 bitrate(标称波特率),2E 卡必须显式设置"
60
+ )
61
+ self._bitrate = int(bitrate)
62
+
63
+ # 惰性加载 DLL(此时才真正触碰 WinDLL / 环境变量)
64
+ self._dll = get_dll()
65
+ # acquire 设备池(首次才 OpenDevice)
66
+ self._entry = device_pool.acquire(self._device_type, self._device_index)
67
+ self._ch_handle = INVALID_HANDLE
68
+ self._ts_ref: tuple[int, float] | None = None # (设备微秒, Unix 秒) 参考点
69
+
70
+ try:
71
+ self._open_channel()
72
+ except Exception:
73
+ # 反向释放:InitCAN 已成功则 ReleaseChannel + 移除通道占用,再归还池引用
74
+ self._release_channel()
75
+ device_pool.release(self._device_type, self._device_index)
76
+ raise
77
+
78
+ self.channel_info = f"zlg: device_type={self._device_type}, can_index={self._channel}"
79
+ super().__init__(channel=channel, can_filters=can_filters, **kwargs)
80
+
81
+ # ---- 打开序列 ----
82
+ def _open_channel(self) -> None:
83
+ """SetValue(baud_rate) -> InitCAN -> StartCAN(顺序不可变)。"""
84
+ entry = self._entry
85
+ dll = self._dll
86
+ ch = self._channel
87
+ with entry.lock:
88
+ if ch in entry.open_channels:
89
+ raise can.CanInitializationError(f"通道 {ch} 已被本进程占用")
90
+ key = f"{ch}/baud_rate".encode("ascii")
91
+ ok = dll.ZCAN_SetValue(
92
+ entry.handle, key, str(self._bitrate).encode("ascii")
93
+ )
94
+ if ok != STATUS_OK:
95
+ raise can.CanInitializationError(
96
+ f"ZCAN_SetValue({key.decode()}) 失败,返回 {ok}"
97
+ )
98
+ cfg = make_init_config()
99
+ ch_handle = dll.ZCAN_InitCAN(entry.handle, ch, ctypes.byref(cfg))
100
+ if not ch_handle:
101
+ raise can.CanInitializationError(f"ZCAN_InitCAN 通道 {ch} 失败(空句柄)")
102
+ # InitCAN 成功,记录通道占用,供反向释放判断
103
+ self._ch_handle = ch_handle
104
+ entry.open_channels.add(ch)
105
+ r = dll.ZCAN_StartCAN(ch_handle)
106
+ if r != STATUS_OK:
107
+ raise can.CanInitializationError(
108
+ f"ZCAN_StartCAN 通道 {ch} 失败,返回 {r}"
109
+ )
110
+
111
+ def _release_channel(self) -> None:
112
+ """反向释放通道句柄(若已 InitCAN),并从设备池移除通道占用。幂等。
113
+
114
+ 只有真正持有通道句柄(InitCAN 成功)才移除 open_channels,避免失败重入
115
+ 的实例误删其它实例登记的通道占用。
116
+ """
117
+ entry = self._entry
118
+ if entry is None:
119
+ return
120
+ with entry.lock:
121
+ if self._ch_handle not in (INVALID_HANDLE, None):
122
+ # 通道随 CloseDevice(最后一路)释放;zlgcan 无独立 ReleaseChannel API,
123
+ # 这里只做簿记(移除通道占用 + 置空句柄)。
124
+ self._ch_handle = INVALID_HANDLE
125
+ entry.open_channels.discard(self._channel)
126
+
127
+ # ---- 发送 ----
128
+ def send(self, msg: Message, timeout=None) -> None:
129
+ if msg.is_fd:
130
+ # 2E 卡不支持 CAN FD,不送进 DLL
131
+ raise ZlgCapabilityUnsupportedError(
132
+ "USBCAN-2E-U 不支持 CAN FD(is_fd=True)"
133
+ )
134
+
135
+ data = bytes(msg.data) if msg.data is not None else b""
136
+ if msg.is_remote_frame:
137
+ dlc = int(msg.dlc or 0)
138
+ else:
139
+ dlc = len(data)
140
+ if dlc > 8:
141
+ raise can.CanOperationError(f"经典 CAN 数据长度 {dlc} 超过 8 字节")
142
+
143
+ can_id = msg.arbitration_id & 0x1FFFFFFF
144
+ if msg.is_extended_id:
145
+ can_id |= 0x80000000
146
+ if msg.is_remote_frame:
147
+ can_id |= 0x40000000
148
+
149
+ tx = ZCAN_Transmit_Data()
150
+ tx.frame.can_id = can_id
151
+ tx.frame.can_dlc = dlc
152
+ for i, b in enumerate(data[:8]):
153
+ tx.frame.data[i] = b
154
+ tx.transmit_type = 0 # 正常发送
155
+
156
+ # 同一张卡的发送 / 接收 / SetValue 都走设备池互斥锁
157
+ with self._entry.lock:
158
+ sent = self._dll.ZCAN_Transmit(self._ch_handle, ctypes.byref(tx), 1)
159
+ # 返回「成功帧数」;无 ACK 时 Transmit 阻塞约 3.5s 后返回 0
160
+ if sent != 1:
161
+ raise can.CanOperationError(
162
+ f"ZCAN_Transmit 发送失败,成功帧数 {sent}(期望 1)"
163
+ )
164
+
165
+ # ---- 接收 ----
166
+ def _recv_internal(self, timeout):
167
+ """有限等待轮询:GetReceiveNum + Receive(wait_time<=100),绝不用 -1 阻塞。"""
168
+ deadline = None if timeout is None else time.monotonic() + timeout
169
+ while not self._is_shutdown:
170
+ if deadline is None:
171
+ wait_ms = 100
172
+ else:
173
+ remain = deadline - time.monotonic()
174
+ if remain <= 0:
175
+ return None, False
176
+ wait_ms = min(100, max(1, int(remain * 1000)))
177
+
178
+ with self._entry.lock:
179
+ n = self._dll.ZCAN_GetReceiveNum(self._ch_handle, TYPE_CAN)
180
+ if n > 0:
181
+ rx = ZCAN_Receive_Data()
182
+ if self._dll.ZCAN_Receive(
183
+ self._ch_handle, ctypes.byref(rx), 1, 0
184
+ ) == 1:
185
+ return self._make_message(rx), False
186
+ rx = ZCAN_Receive_Data()
187
+ if self._dll.ZCAN_Receive(
188
+ self._ch_handle, ctypes.byref(rx), 1, wait_ms
189
+ ) == 1:
190
+ return self._make_message(rx), False
191
+ return None, False
192
+
193
+ def _make_message(self, rx: ZCAN_Receive_Data) -> Message:
194
+ can_id = int(rx.frame.can_id)
195
+ is_extended = bool(can_id & 0x80000000)
196
+ is_remote = bool(can_id & 0x40000000)
197
+ dlc = min(int(rx.frame.can_dlc), 8)
198
+ data = b"" if is_remote else bytes(rx.frame.data[:dlc])
199
+ return Message(
200
+ timestamp=self._device_ts_to_unix(int(rx.timestamp)),
201
+ arbitration_id=can_id & 0x1FFFFFFF,
202
+ is_extended_id=is_extended,
203
+ is_remote_frame=is_remote,
204
+ channel=self._channel,
205
+ dlc=dlc,
206
+ data=data,
207
+ is_fd=False,
208
+ check=False,
209
+ )
210
+
211
+ def _device_ts_to_unix(self, device_us: int) -> float:
212
+ """设备上电后微秒 -> Unix 秒(float)。首个接收帧建立参考点。"""
213
+ if self._ts_ref is None:
214
+ self._ts_ref = (device_us, time.time())
215
+ ref_us, ref_unix = self._ts_ref
216
+ return ref_unix + max(0, device_us - ref_us) / 1e6
217
+
218
+ # ---- 关闭 ----
219
+ def shutdown(self) -> None:
220
+ if getattr(self, "_is_shutdown", False):
221
+ return
222
+ super().shutdown() # 置 _is_shutdown + 停周期任务
223
+ # 释放通道句柄,再归还设备池引用(最后一路才 CloseDevice)
224
+ self._release_channel()
225
+ device_pool.release(self._device_type, self._device_index)