xusbcan-cli 0.1.0__tar.gz → 0.1.2__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.
- xusbcan_cli-0.1.2/LICENSE +21 -0
- xusbcan_cli-0.1.2/PKG-INFO +337 -0
- xusbcan_cli-0.1.2/README.md +316 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/pyproject.toml +51 -42
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/__init__.py +7 -7
- xusbcan_cli-0.1.2/src/xusbcan/adapters/__init__.py +4 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/chuangxin/__init__.py +4 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/chuangxin/backend.py +12 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/chuangxin/bus.py +208 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/chuangxin/device_pool.py +80 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/chuangxin/dll.py +172 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/chuangxin/profiles.py +27 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/peak/__init__.py +1 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/peak/profiles.py +14 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/profile.py +25 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/registry.py +139 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/vector/__init__.py +1 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/vector/profiles.py +17 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/zlg/__init__.py +4 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/zlg/backend.py +31 -0
- xusbcan_cli-0.1.0/src/xusbcan/adapters/zlg/backend.py → xusbcan_cli-0.1.2/src/xusbcan/adapters/zlg/common.py +33 -57
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/adapters/zlg/dll.py +70 -4
- xusbcan_cli-0.1.2/src/xusbcan/adapters/zlg/profiles.py +21 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/zlg/usbcan2.py +22 -0
- xusbcan_cli-0.1.2/src/xusbcan/adapters/zlg/usbcan_2e_u.py +209 -0
- xusbcan_cli-0.1.2/src/xusbcan/cli/app.py +247 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/config/loader.py +43 -5
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/core/__init__.py +6 -1
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/core/commands.py +140 -17
- xusbcan_cli-0.1.2/src/xusbcan/core/filters.py +30 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/core/monitor.py +7 -1
- xusbcan_cli-0.1.2/src/xusbcan/core/periodic.py +230 -0
- xusbcan_cli-0.1.2/src/xusbcan/core/session.py +500 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/mcp/server.py +10 -2
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/mcp/tools.py +47 -2
- xusbcan_cli-0.1.2/src/xusbcan/mcp/transport.py +21 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/models/device.py +5 -4
- xusbcan_cli-0.1.2/src/xusbcan/scenario/__init__.py +9 -0
- xusbcan_cli-0.1.2/src/xusbcan/scenario/loader.py +24 -0
- xusbcan_cli-0.1.2/src/xusbcan/scenario/runner.py +945 -0
- xusbcan_cli-0.1.2/src/xusbcan_cli.egg-info/PKG-INFO +337 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan_cli.egg-info/SOURCES.txt +32 -1
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan_cli.egg-info/entry_points.txt +1 -0
- xusbcan_cli-0.1.2/tests/test_chuangxin_usb_can_2c.py +67 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/tests/test_config.py +47 -0
- xusbcan_cli-0.1.2/tests/test_core.py +752 -0
- xusbcan_cli-0.1.2/tests/test_dual_session_virtual.py +49 -0
- xusbcan_cli-0.1.2/tests/test_error_code_mapping.py +155 -0
- xusbcan_cli-0.1.2/tests/test_filters.py +53 -0
- xusbcan_cli-0.1.2/tests/test_registry.py +119 -0
- xusbcan_cli-0.1.2/tests/test_scenario.py +166 -0
- xusbcan_cli-0.1.2/tests/test_scenario_advanced.py +472 -0
- xusbcan_cli-0.1.2/tests/test_scenario_store.py +41 -0
- xusbcan_cli-0.1.2/tests/test_scenario_vars.py +67 -0
- xusbcan_cli-0.1.2/tests/test_session_capabilities.py +165 -0
- xusbcan_cli-0.1.2/tests/test_zlg_usbcan2.py +96 -0
- xusbcan_cli-0.1.0/PKG-INFO +0 -152
- xusbcan_cli-0.1.0/README.md +0 -138
- xusbcan_cli-0.1.0/src/xusbcan/adapters/__init__.py +0 -1
- xusbcan_cli-0.1.0/src/xusbcan/adapters/registry.py +0 -88
- xusbcan_cli-0.1.0/src/xusbcan/adapters/zlg/__init__.py +0 -23
- xusbcan_cli-0.1.0/src/xusbcan/cli/app.py +0 -106
- xusbcan_cli-0.1.0/src/xusbcan/core/periodic.py +0 -72
- xusbcan_cli-0.1.0/src/xusbcan/core/session.py +0 -282
- xusbcan_cli-0.1.0/src/xusbcan_cli.egg-info/PKG-INFO +0 -152
- xusbcan_cli-0.1.0/tests/test_core.py +0 -146
- xusbcan_cli-0.1.0/tests/test_registry.py +0 -52
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/setup.cfg +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/adapters/zlg/device_pool.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/cli/__init__.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/cli/__main__.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/config/__init__.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/mcp/__init__.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/models/__init__.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/models/frame.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan/models/result.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan_cli.egg-info/dependency_links.txt +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan_cli.egg-info/requires.txt +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/src/xusbcan_cli.egg-info/top_level.txt +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/tests/test_mcp_smoke.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/tests/test_mcp_stdio.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/tests/test_models.py +0 -0
- {xusbcan_cli-0.1.0 → xusbcan_cli-0.1.2}/tests/test_result.py +0 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 chaofan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,337 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: xusbcan-cli
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: 面向 AI Agent 的 CAN 总线调试工具(CLI + MCP)
|
|
5
|
+
Author: Archaofan
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Classifier: Programming Language :: Python :: 3
|
|
8
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
10
|
+
Requires-Python: >=3.11
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Requires-Dist: python-can>=4.4
|
|
14
|
+
Provides-Extra: mcp
|
|
15
|
+
Requires-Dist: mcp>=2.0; extra == "mcp"
|
|
16
|
+
Provides-Extra: dev
|
|
17
|
+
Requires-Dist: pytest; extra == "dev"
|
|
18
|
+
Requires-Dist: ruff; extra == "dev"
|
|
19
|
+
Requires-Dist: mypy; extra == "dev"
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
# xusbcan-cli
|
|
23
|
+
|
|
24
|
+
面向 AI Agent 的多厂商 CAN 总线调试工具。
|
|
25
|
+
|
|
26
|
+
以后端服务形态运行,同时提供标准 **CLI** 与 **MCP(Model Context Protocol)** 接口,让 AI Agent 能直接完成 CAN 报文的收发、监听、周期发送等调试操作——无需人工操作上位机软件,即可实现 **Agent 自动化联合调试**。
|
|
27
|
+
|
|
28
|
+
[](LICENSE)
|
|
29
|
+
[](https://www.python.org/)
|
|
30
|
+
[](https://pypi.org/project/xusbcan-cli/)
|
|
31
|
+
|
|
32
|
+
中文 | [English](README.en.md)
|
|
33
|
+
|
|
34
|
+
## 目标与展望
|
|
35
|
+
|
|
36
|
+
在 AI 时代,让 Agent 能像使用普通工具一样操作 CAN 总线:结构化输出、稳定契约、可被程序化调用。
|
|
37
|
+
|
|
38
|
+
我们的**目标**是让 xusbcan-cli 成为 AI 与车载 / 工业 CAN 总线之间的可靠桥梁,使「用 Agent 自动完成台架上的联调、诊断、验证」更常见。本项目以 [python-can](https://github.com/hardbyte/python-can) 为底座,在其上提供统一命令与会话。当前仍是早期版本:先把已确认的厂商与型号跑通,再按型号扩展,而不是宣称已经覆盖所有厂商或成为行业标准。
|
|
39
|
+
|
|
40
|
+
## 特性
|
|
41
|
+
|
|
42
|
+
- **同一套命令**:CLI / MCP 命令名不随厂商变化;驱动、环境变量与配置随卡变化
|
|
43
|
+
- **CLI 与 MCP 同源**:结构化 JSON 输出,便于 Agent 分支处理
|
|
44
|
+
- **python-can 优先**:已有后端可直接写 `interface`;需要通道映射或专有参数时再登记型号
|
|
45
|
+
- **可安装 Agent Skill**:先确认型号,再调用;厂商踩坑按型号分文件
|
|
46
|
+
|
|
47
|
+

|
|
48
|
+
|
|
49
|
+
## 会话层做什么
|
|
50
|
+
|
|
51
|
+
本项目在 python-can(或自研后端给出的 `can.Bus`)之上提供**统一会话与命令层**,而不是再实现一套总线协议栈。大致包括:
|
|
52
|
+
|
|
53
|
+

|
|
54
|
+
|
|
55
|
+
- **配置与别名**:`xusbcan.toml` 里用逻辑名引用设备,打开参数集中管理
|
|
56
|
+
- **会话生命周期**:按别名 `open` / `close`,多卡并存;关闭时收回周期任务与有界监听
|
|
57
|
+
- **统一结果契约**:`Result` + `error.code` 枚举,超时收帧等可程序化分支(不必解析人类日志)
|
|
58
|
+
- **常用调试原语**:有界 `monitor`、带时长的周期发送、ID 范围滤波、毫秒级 `scenario` 编排
|
|
59
|
+
- **双入口同源**:同一套 core 同时服务 CLI 与 MCP,避免「脚本一套、Agent 又一套」
|
|
60
|
+
- **应用层预算**:周期发送 / Scenario 的时长与发送次数等限制(非硬件失效保护)
|
|
61
|
+
|
|
62
|
+
底层怎么打开卡,仍由对应 `interface` 或本仓库登记的后端决定。
|
|
63
|
+
|
|
64
|
+
### 相对「已经直接用 python-can + AI」的意义
|
|
65
|
+
|
|
66
|
+
若团队已经让 Agent 写临时 `can.Bus` 脚本调卡,本项目**不替代** python-can,而是补一层**可复用的工具契约**:
|
|
67
|
+
|
|
68
|
+
| 直接 python-can + AI | 使用本项目 |
|
|
69
|
+
|----------------------|------------|
|
|
70
|
+
| 每次由模型拼后端参数与样板代码 | 配置一次,用稳定 CLI / MCP 工具名调用 |
|
|
71
|
+
| 输出形状随提示词变化 | 固定 JSON / `error.code`,便于 Agent 分支 |
|
|
72
|
+
| 会话、周期、监听、编排各自手写 | 会话层与 `scenario` 已提供 |
|
|
73
|
+
| 型号踩坑靠聊天上下文 | Skill 按型号分文件,先确认再调用 |
|
|
74
|
+
| python-can 没有的卡需自写封装 | 本仓库可提供/登记后端(如部分国产卡) |
|
|
75
|
+
|
|
76
|
+
已经精通 python-can、且只想本机写死脚本时,不必强行迁移。面向 **Agent 联调、多卡别名、MCP 工具化、结构化结果** 时,本项目更省事。安装本项目**不会**拦截或屏蔽 python-can 其它后端。
|
|
77
|
+
|
|
78
|
+
## 安装
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
pip install xusbcan-cli # CLI + 核心
|
|
82
|
+
pip install xusbcan-cli[mcp] # 追加 MCP
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
从源码:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
git clone https://github.com/Archaofan/xusbcan-cli.git
|
|
89
|
+
cd xusbcan-cli
|
|
90
|
+
pip install -e ".[mcp]"
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## 快速开始
|
|
94
|
+
|
|
95
|
+
1. 确认手上的**厂商与型号**,安装该卡要求的驱动 / SDK
|
|
96
|
+
2. 编写 `xusbcan.toml`(或设置 `XUSBCAN_CONFIG`)
|
|
97
|
+
3. 用别名调用 CLI / MCP
|
|
98
|
+
|
|
99
|
+
### 通用配置
|
|
100
|
+
|
|
101
|
+
```toml
|
|
102
|
+
[[devices]]
|
|
103
|
+
name = "bus0"
|
|
104
|
+
interface = "socketcan" # 任意 python-can 已声明的后端名
|
|
105
|
+
channel = "can0"
|
|
106
|
+
nominal = 500000
|
|
107
|
+
# data = 2000000 # 可选,CAN FD 数据段
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
- Python 3.11+(64 位)
|
|
111
|
+
- `name` 为逻辑别名;命令与 MCP 都用它
|
|
112
|
+
- 写了 `interface` 时按该后端打开;`vendor` / `model` 用于需要快捷映射的型号
|
|
113
|
+
- MCP 默认 stdio;`http` 仅绑定 `127.0.0.1`
|
|
114
|
+
|
|
115
|
+
### CLI
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
xusbcan list
|
|
119
|
+
xusbcan send bus0 --id 0x123 --data "01 02 03"
|
|
120
|
+
xusbcan receive bus0 --timeout 1
|
|
121
|
+
xusbcan monitor bus0 --duration 5
|
|
122
|
+
xusbcan status bus0
|
|
123
|
+
xusbcan receive bus0 --timeout 1 --from-id 0x100 --to-id 0x1FF
|
|
124
|
+
xusbcan periodic bus0 --name hb --id 0x123 --data "01" --period 0.1 --duration 5
|
|
125
|
+
xusbcan scenario --file steps.json
|
|
126
|
+
xusbcan scenario --dir scenarios/
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+

|
|
130
|
+
|
|
131
|
+
*台架 / lab 演示(路径已脱敏;非实车)*
|
|
132
|
+
|
|
133
|
+
`periodic` 在本进程发满 `--duration` 后停止。`scenario` 在同进程编排发→等→再发;`--dir` 按文件名批跑。跨多次调用保持会话时用 MCP。
|
|
134
|
+
|
|
135
|
+
### MCP
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
xusbcan-mcp
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Agent 使用 `open_device`、`send_frame`、`receive_frame`、`monitor`、`periodic_start` 等工具。`periodic_start` **必须**带 `duration_s`(上限 300 秒)。更长任务请用本机常驻进程,并明确授权台架环境。
|
|
142
|
+
|
|
143
|
+

|
|
144
|
+
|
|
145
|
+
*台架 / lab 演示:MCP 工具调用成绩单(配置路径已脱敏;非 Cursor UI 截图;非实车)*
|
|
146
|
+
|
|
147
|
+
注册时按所用适配器设置对应环境变量与 `XUSBCAN_CONFIG`(见下方各厂商小节)。
|
|
148
|
+
|
|
149
|
+
## 适配器准备
|
|
150
|
+
|
|
151
|
+
按厂商阅读对应小节。每家使用**自己的**驱动与环境变量;配置里写明该卡的 `vendor` / `model` 或 `interface`。
|
|
152
|
+
|
|
153
|
+
### 周立功(ZLG)
|
|
154
|
+
|
|
155
|
+
适用于已确认的 **USBCAN-2E-U**、**USBCAN-II**。
|
|
156
|
+
|
|
157
|
+
需要:
|
|
158
|
+
|
|
159
|
+
- 周立功 USB 驱动
|
|
160
|
+
- 二次开发 SDK(`zlgcan.dll` 与同目录 `kerneldlls/`)
|
|
161
|
+
- `ZLG_SDK_DIR` 指向该 SDK 目录
|
|
162
|
+
|
|
163
|
+
资料:https://manual.zlg.cn/web/#/152?page_id=5332
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
# 当前终端
|
|
167
|
+
set ZLG_SDK_DIR=D:\path\to\zlg-sdk-dir
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
```toml
|
|
171
|
+
[[devices]]
|
|
172
|
+
name = "bus0"
|
|
173
|
+
vendor = "zlg"
|
|
174
|
+
model = "USBCAN-2E-U" # 或 "USBCAN-II"
|
|
175
|
+
channel = 1 # 按实际接线:CAN1→0,CAN2→1
|
|
176
|
+
nominal = 250000
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
2E-U / II 均为双通道,`channel` 必须对应实际接线口。型号以铭牌与配置 `model` 为准;不要根据 SDK `GetDeviceInf` 一类字段改判型号或改走 CAN FD。滤波与周期发送路径因型号而异,见 Agent Skill 对应参考页。
|
|
180
|
+
|
|
181
|
+
```json
|
|
182
|
+
{
|
|
183
|
+
"mcpServers": {
|
|
184
|
+
"xusbcan": {
|
|
185
|
+
"command": "xusbcan-mcp",
|
|
186
|
+
"env": {
|
|
187
|
+
"ZLG_SDK_DIR": "D:\\path\\to\\zlg-sdk-dir",
|
|
188
|
+
"XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Vector
|
|
196
|
+
|
|
197
|
+
适用于已确认的 **VN1640A**(**VN1630** 已登记,本仓库未做真机确认)。
|
|
198
|
+
|
|
199
|
+
需要:
|
|
200
|
+
|
|
201
|
+
- Vector 驱动 / XL Driver(从官方渠道取得授权)
|
|
202
|
+
- `channel` 使用与 python-can / XL Driver **相同的全局通道索引**(无逻辑重映射)。硬件 Channel *N* 通常对应索引 `N - 1`,以本机枚举为准
|
|
203
|
+
|
|
204
|
+
打开时交给 **python-can 已有的 `vector` 后端**。本仓库**不**封装 XL Driver ABI,只提供型号快捷方式(通道数、`app_name=None` 等)以及 CLI / MCP / Skill 的统一用法与真机说明。
|
|
205
|
+
|
|
206
|
+
```toml
|
|
207
|
+
[[devices]]
|
|
208
|
+
name = "vn0"
|
|
209
|
+
vendor = "vector"
|
|
210
|
+
model = "VN1640A"
|
|
211
|
+
channel = 2
|
|
212
|
+
nominal = 250000
|
|
213
|
+
# data = 2000000 # 该通道支持 CAN FD 时可选
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
也可直接写 `interface = "vector"`。
|
|
217
|
+
|
|
218
|
+
```json
|
|
219
|
+
{
|
|
220
|
+
"mcpServers": {
|
|
221
|
+
"xusbcan": {
|
|
222
|
+
"command": "xusbcan-mcp",
|
|
223
|
+
"env": {
|
|
224
|
+
"XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### 创芯(Chuangxin)
|
|
232
|
+
|
|
233
|
+
适用于已确认的 **USB_CAN-2C**(**USB_CAN-2A-GD** 已登记为同后端族,**真机验证暂挂起**,勿标为已确认)。
|
|
234
|
+
|
|
235
|
+
需要:
|
|
236
|
+
|
|
237
|
+
- 创芯 USB 驱动
|
|
238
|
+
- 与 Python 位数匹配的 `ControlCAN.dll`
|
|
239
|
+
- `CHUANGXIN_SDK_DIR` 指向含该 DLL 的目录(本工具按绝对路径加载)
|
|
240
|
+
|
|
241
|
+
```bash
|
|
242
|
+
set CHUANGXIN_SDK_DIR=D:\path\to\chuangxin-controlcan-dir
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
```toml
|
|
246
|
+
[[devices]]
|
|
247
|
+
name = "cx0"
|
|
248
|
+
vendor = "chuangxin"
|
|
249
|
+
model = "USB_CAN-2C"
|
|
250
|
+
channel = 0
|
|
251
|
+
nominal = 250000
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
同一进程中请只加载一份你选用的 `ControlCAN.dll`;若其它软件也依赖各自的同名 DLL,请分目录或分进程使用。
|
|
255
|
+
|
|
256
|
+
```json
|
|
257
|
+
{
|
|
258
|
+
"mcpServers": {
|
|
259
|
+
"xusbcan": {
|
|
260
|
+
"command": "xusbcan-mcp",
|
|
261
|
+
"env": {
|
|
262
|
+
"CHUANGXIN_SDK_DIR": "D:\\path\\to\\chuangxin-controlcan-dir",
|
|
263
|
+
"XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
### 其它后端(python-can 直通)
|
|
271
|
+
|
|
272
|
+
以 Vector 等型号为证:**python-can 已有后端 + 本项目会话层** 这条路径已经走通。因此,凡在当前环境中 python-can 已声明且本机能打开的后端(如 socketcan、slcan、Kvaser、`pcan` 等),**大概率**只需配置 `interface` / `channel` / `extra` 即可用同一套 CLI / MCP;**不保证**每张卡都已在本仓库真机确认,驱动安装、通道写法、FD/滤波/无 ACK 等行为仍随后端而异,可能踩坑。
|
|
273
|
+
|
|
274
|
+
本仓库对 **PEAK PCAN-USB** 另有型号登记(通道映射),状态为「已登记,未在本仓库真机确认」。写了 `interface` 时不会改走别的后端,也不会阻止你继续在别的程序里直接使用 python-can。
|
|
275
|
+
|
|
276
|
+
## 支持范围
|
|
277
|
+
|
|
278
|
+
| 厂商 | 型号 | 状态 | 说明 |
|
|
279
|
+
|------|------|------|------|
|
|
280
|
+
| 周立功 | USBCAN-2E-U | 真机已确认 | 本仓库 `zlg` 后端;需 `ZLG_SDK_DIR` |
|
|
281
|
+
| 周立功 | USBCAN-II | 真机已确认 | 同上,按型号分发 |
|
|
282
|
+
| Vector | VN1640A | 真机已确认 | python-can `vector`;通道为 XL 全局索引 |
|
|
283
|
+
| Vector | VN1630 | 已登记 | python-can `vector` |
|
|
284
|
+
| 创芯 | USB_CAN-2C | 真机已确认 | 本仓库 ControlCAN 后端;需 `CHUANGXIN_SDK_DIR` |
|
|
285
|
+
| 创芯 | USB_CAN-2A-GD | 已登记(真机验证挂起) | 与 2C 同后端族;验证暂挂起 |
|
|
286
|
+
| PEAK | PCAN-USB | 已登记 | python-can `pcan` |
|
|
287
|
+
|
|
288
|
+
上表是带登记或真机说明的型号,不是准入白名单。其它 python-can 后端见上文「其它后端(python-can 直通)」:可打开 ≠ 本仓库已逐型号真机确认。python-can 无法打开的卡才需要新后端;若新后端要求用户自备 SDK,请在免责声明中追加该厂商。
|
|
289
|
+
|
|
290
|
+
### 真机验证说明
|
|
291
|
+
|
|
292
|
+
「真机已确认」表示:在**已获授权的台架**上,对本仓库公开的 CLI / 核心路径做过有限验证(打开与重开、收发、滤波、多开、`monitor` / `periodic`、`scenario` 等,视该型号当时测试范围而定)。
|
|
293
|
+
|
|
294
|
+
**该说明适用于本仓库标为真机已确认的全部型号**:验证仅覆盖对应测试台架与当时范围,**不构成**对任一厂商产品的性能、兼容性或适销性担保,也不保证每一台设备、每一种子卡 / 主机环境均已覆盖。未覆盖项通常包括主动构造错误帧、长时间 soak、实车网络等。细节与踩坑见 Agent Skill 中该型号参考页。
|
|
295
|
+
|
|
296
|
+
## Agent Skill
|
|
297
|
+
|
|
298
|
+
```bash
|
|
299
|
+
npx skills add Archaofan/xusbcan-cli --skill xusbcan
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
在项目目录执行可装到当前工程;`-g` 装到用户目录;`-a` 指定客户端(如 `cursor`)。Skill 先读通用契约,再按 `references/catalog.md` 只打开当前配置对应的型号页,避免把全部厂商知识塞进上下文。
|
|
303
|
+
|
|
304
|
+
## 参与
|
|
305
|
+
|
|
306
|
+
欢迎报告问题、提交 PR、贡献新的厂商或型号登记。公开约定摘要如下(细节见 [`CLAUDE.md`](CLAUDE.md)、[`skills/xusbcan/`](skills/xusbcan/)、[`third_party/ABI_PROVENANCE.md`](third_party/ABI_PROVENANCE.md)):
|
|
307
|
+
|
|
308
|
+
- **去耦合**:厂商差异只进 `src/xusbcan/adapters/<厂商>/`;`core` / `cli` / `mcp` 不出现厂商概念,只调用 python-can 通用接口(如 `set_filters` / `send_periodic`)。适配器可在后端钩子内使用厂商专有 API。配置里已有 `interface` 即可打开,不必先为每个型号改会话层。
|
|
309
|
+
- **可持续扩展**:python-can 已有后端 → 只加 `profiles.py`(及可选型号快捷方式);没有后端才加自研绑定并注册 `can.interface`。新增卡时改适配层 + Skill 的 `references/catalog.md` 一行 + 一份型号页;**不要**把各型号症状写进 Skill 根 `description`,也**不要**把全部厂商页塞进一次上下文。
|
|
310
|
+
- **Skill 契约**:根页写通用怎么用;型号页顺序为 Quick start → How this backend behaves → Field notes。Field notes 须标明是前人台架/开发中的现场报告,**未必可复现**,不作正式「不支持」清单,也不据此断言整型号缺陷。
|
|
311
|
+
- **真机与公开表述**:通用配置与该型号的驱动 / 环境变量分开写;真机确认前不要标成「已验证」。需用户自备 SDK 的新厂商,在 README 免责声明追加一条商标与交付边界。
|
|
312
|
+
- **合规**:不提交厂商 DLL / SDK 原文、本机绝对路径、客户/ECU 名等;提交前按 `CLAUDE.md` 脱敏清单自检。
|
|
313
|
+
|
|
314
|
+
## 安全使用
|
|
315
|
+
|
|
316
|
+
- 仅在**已获授权的台架 / 实验室**使用;不要在实车控制网或未授权产线上让 Agent 无人值守发报文
|
|
317
|
+
- 发送与周期发送前确认接线、波特率与 ID;长时任务请设明确时长或改用本机常驻进程
|
|
318
|
+
- MCP 默认本机使用;HTTP 仅 `127.0.0.1`,勿暴露公网
|
|
319
|
+
- **应用层预算(非硬件失效保护)**:MCP / Scenario 周期发送须带时长(上限 300 秒);Scenario 另有墙钟、单步与累计发送次数等限制。周期停止或关闭失败时返回结构化错误并尽量保留可查询任务/会话,便于重试——这不等于硬件失效保护,驱动或硬件异常时仍不能保证一定停止发送
|
|
320
|
+
|
|
321
|
+
## 免责声明
|
|
322
|
+
|
|
323
|
+
本项目是独立的第三方工具,与下列厂商及其产品没有关联、赞助、背书或利益关系。厂商名称、产品名称均为其各自权利人的商标。驱动与 SDK 的版权归权利人所有,由使用者从官方渠道自行获取。
|
|
324
|
+
|
|
325
|
+
本项目按 MIT 提供**自有代码**,不提供任何担保。`python-can` 等依赖与用户自备 SDK 各有其许可,详见 [`third_party/NOTICES`](third_party/NOTICES)。
|
|
326
|
+
|
|
327
|
+
**真机确认仅覆盖上文「真机验证说明」中的台架范围,不构成对任何已确认型号的性能、兼容性或适销性担保。**
|
|
328
|
+
|
|
329
|
+
每支持一家需要使用者自备 SDK 或专有驱动的厂商,在此追加商标与交付边界说明:
|
|
330
|
+
|
|
331
|
+
- **广州致远电子股份有限公司(周立功 / ZLG)**:经公开二次开发接口对接的型号包括 USBCAN-2E-U、USBCAN-II。"周立功"、"ZLG"、"zlgcan" 等为其商标。本项目不随附其驱动或 `zlgcan.dll`。
|
|
332
|
+
- **Vector Informatik GmbH(Vector)**:经 python-can `vector` 打开的型号包括 VN1640A。"Vector"、"VN1640A"、"XL Driver" 等为其商标。本项目不随附 Vector 驱动、XL Driver、CANoe/CANalyzer 或其它专有软件。
|
|
333
|
+
- **珠海创芯科技有限公司(创芯)**:经本仓库 ControlCAN(`VCI_*`)薄封装打开的型号包括 USB_CAN-2C。"创芯"、"USB_CAN-2C"、"CANalyst" 等为其商标。本项目不随附创芯驱动或 `ControlCAN.dll`。
|
|
334
|
+
|
|
335
|
+
## License
|
|
336
|
+
|
|
337
|
+
[MIT License](LICENSE)。第三方条款见 [`third_party/NOTICES`](third_party/NOTICES)。各厂商是「自研 ctypes 后端」还是「仅 python-can 快捷方式」,见 [`third_party/ABI_PROVENANCE.md`](third_party/ABI_PROVENANCE.md)。
|
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
# xusbcan-cli
|
|
2
|
+
|
|
3
|
+
面向 AI Agent 的多厂商 CAN 总线调试工具。
|
|
4
|
+
|
|
5
|
+
以后端服务形态运行,同时提供标准 **CLI** 与 **MCP(Model Context Protocol)** 接口,让 AI Agent 能直接完成 CAN 报文的收发、监听、周期发送等调试操作——无需人工操作上位机软件,即可实现 **Agent 自动化联合调试**。
|
|
6
|
+
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://www.python.org/)
|
|
9
|
+
[](https://pypi.org/project/xusbcan-cli/)
|
|
10
|
+
|
|
11
|
+
中文 | [English](README.en.md)
|
|
12
|
+
|
|
13
|
+
## 目标与展望
|
|
14
|
+
|
|
15
|
+
在 AI 时代,让 Agent 能像使用普通工具一样操作 CAN 总线:结构化输出、稳定契约、可被程序化调用。
|
|
16
|
+
|
|
17
|
+
我们的**目标**是让 xusbcan-cli 成为 AI 与车载 / 工业 CAN 总线之间的可靠桥梁,使「用 Agent 自动完成台架上的联调、诊断、验证」更常见。本项目以 [python-can](https://github.com/hardbyte/python-can) 为底座,在其上提供统一命令与会话。当前仍是早期版本:先把已确认的厂商与型号跑通,再按型号扩展,而不是宣称已经覆盖所有厂商或成为行业标准。
|
|
18
|
+
|
|
19
|
+
## 特性
|
|
20
|
+
|
|
21
|
+
- **同一套命令**:CLI / MCP 命令名不随厂商变化;驱动、环境变量与配置随卡变化
|
|
22
|
+
- **CLI 与 MCP 同源**:结构化 JSON 输出,便于 Agent 分支处理
|
|
23
|
+
- **python-can 优先**:已有后端可直接写 `interface`;需要通道映射或专有参数时再登记型号
|
|
24
|
+
- **可安装 Agent Skill**:先确认型号,再调用;厂商踩坑按型号分文件
|
|
25
|
+
|
|
26
|
+

|
|
27
|
+
|
|
28
|
+
## 会话层做什么
|
|
29
|
+
|
|
30
|
+
本项目在 python-can(或自研后端给出的 `can.Bus`)之上提供**统一会话与命令层**,而不是再实现一套总线协议栈。大致包括:
|
|
31
|
+
|
|
32
|
+

|
|
33
|
+
|
|
34
|
+
- **配置与别名**:`xusbcan.toml` 里用逻辑名引用设备,打开参数集中管理
|
|
35
|
+
- **会话生命周期**:按别名 `open` / `close`,多卡并存;关闭时收回周期任务与有界监听
|
|
36
|
+
- **统一结果契约**:`Result` + `error.code` 枚举,超时收帧等可程序化分支(不必解析人类日志)
|
|
37
|
+
- **常用调试原语**:有界 `monitor`、带时长的周期发送、ID 范围滤波、毫秒级 `scenario` 编排
|
|
38
|
+
- **双入口同源**:同一套 core 同时服务 CLI 与 MCP,避免「脚本一套、Agent 又一套」
|
|
39
|
+
- **应用层预算**:周期发送 / Scenario 的时长与发送次数等限制(非硬件失效保护)
|
|
40
|
+
|
|
41
|
+
底层怎么打开卡,仍由对应 `interface` 或本仓库登记的后端决定。
|
|
42
|
+
|
|
43
|
+
### 相对「已经直接用 python-can + AI」的意义
|
|
44
|
+
|
|
45
|
+
若团队已经让 Agent 写临时 `can.Bus` 脚本调卡,本项目**不替代** python-can,而是补一层**可复用的工具契约**:
|
|
46
|
+
|
|
47
|
+
| 直接 python-can + AI | 使用本项目 |
|
|
48
|
+
|----------------------|------------|
|
|
49
|
+
| 每次由模型拼后端参数与样板代码 | 配置一次,用稳定 CLI / MCP 工具名调用 |
|
|
50
|
+
| 输出形状随提示词变化 | 固定 JSON / `error.code`,便于 Agent 分支 |
|
|
51
|
+
| 会话、周期、监听、编排各自手写 | 会话层与 `scenario` 已提供 |
|
|
52
|
+
| 型号踩坑靠聊天上下文 | Skill 按型号分文件,先确认再调用 |
|
|
53
|
+
| python-can 没有的卡需自写封装 | 本仓库可提供/登记后端(如部分国产卡) |
|
|
54
|
+
|
|
55
|
+
已经精通 python-can、且只想本机写死脚本时,不必强行迁移。面向 **Agent 联调、多卡别名、MCP 工具化、结构化结果** 时,本项目更省事。安装本项目**不会**拦截或屏蔽 python-can 其它后端。
|
|
56
|
+
|
|
57
|
+
## 安装
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pip install xusbcan-cli # CLI + 核心
|
|
61
|
+
pip install xusbcan-cli[mcp] # 追加 MCP
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
从源码:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
git clone https://github.com/Archaofan/xusbcan-cli.git
|
|
68
|
+
cd xusbcan-cli
|
|
69
|
+
pip install -e ".[mcp]"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## 快速开始
|
|
73
|
+
|
|
74
|
+
1. 确认手上的**厂商与型号**,安装该卡要求的驱动 / SDK
|
|
75
|
+
2. 编写 `xusbcan.toml`(或设置 `XUSBCAN_CONFIG`)
|
|
76
|
+
3. 用别名调用 CLI / MCP
|
|
77
|
+
|
|
78
|
+
### 通用配置
|
|
79
|
+
|
|
80
|
+
```toml
|
|
81
|
+
[[devices]]
|
|
82
|
+
name = "bus0"
|
|
83
|
+
interface = "socketcan" # 任意 python-can 已声明的后端名
|
|
84
|
+
channel = "can0"
|
|
85
|
+
nominal = 500000
|
|
86
|
+
# data = 2000000 # 可选,CAN FD 数据段
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- Python 3.11+(64 位)
|
|
90
|
+
- `name` 为逻辑别名;命令与 MCP 都用它
|
|
91
|
+
- 写了 `interface` 时按该后端打开;`vendor` / `model` 用于需要快捷映射的型号
|
|
92
|
+
- MCP 默认 stdio;`http` 仅绑定 `127.0.0.1`
|
|
93
|
+
|
|
94
|
+
### CLI
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
xusbcan list
|
|
98
|
+
xusbcan send bus0 --id 0x123 --data "01 02 03"
|
|
99
|
+
xusbcan receive bus0 --timeout 1
|
|
100
|
+
xusbcan monitor bus0 --duration 5
|
|
101
|
+
xusbcan status bus0
|
|
102
|
+
xusbcan receive bus0 --timeout 1 --from-id 0x100 --to-id 0x1FF
|
|
103
|
+
xusbcan periodic bus0 --name hb --id 0x123 --data "01" --period 0.1 --duration 5
|
|
104
|
+
xusbcan scenario --file steps.json
|
|
105
|
+
xusbcan scenario --dir scenarios/
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+

|
|
109
|
+
|
|
110
|
+
*台架 / lab 演示(路径已脱敏;非实车)*
|
|
111
|
+
|
|
112
|
+
`periodic` 在本进程发满 `--duration` 后停止。`scenario` 在同进程编排发→等→再发;`--dir` 按文件名批跑。跨多次调用保持会话时用 MCP。
|
|
113
|
+
|
|
114
|
+
### MCP
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
xusbcan-mcp
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Agent 使用 `open_device`、`send_frame`、`receive_frame`、`monitor`、`periodic_start` 等工具。`periodic_start` **必须**带 `duration_s`(上限 300 秒)。更长任务请用本机常驻进程,并明确授权台架环境。
|
|
121
|
+
|
|
122
|
+

|
|
123
|
+
|
|
124
|
+
*台架 / lab 演示:MCP 工具调用成绩单(配置路径已脱敏;非 Cursor UI 截图;非实车)*
|
|
125
|
+
|
|
126
|
+
注册时按所用适配器设置对应环境变量与 `XUSBCAN_CONFIG`(见下方各厂商小节)。
|
|
127
|
+
|
|
128
|
+
## 适配器准备
|
|
129
|
+
|
|
130
|
+
按厂商阅读对应小节。每家使用**自己的**驱动与环境变量;配置里写明该卡的 `vendor` / `model` 或 `interface`。
|
|
131
|
+
|
|
132
|
+
### 周立功(ZLG)
|
|
133
|
+
|
|
134
|
+
适用于已确认的 **USBCAN-2E-U**、**USBCAN-II**。
|
|
135
|
+
|
|
136
|
+
需要:
|
|
137
|
+
|
|
138
|
+
- 周立功 USB 驱动
|
|
139
|
+
- 二次开发 SDK(`zlgcan.dll` 与同目录 `kerneldlls/`)
|
|
140
|
+
- `ZLG_SDK_DIR` 指向该 SDK 目录
|
|
141
|
+
|
|
142
|
+
资料:https://manual.zlg.cn/web/#/152?page_id=5332
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
# 当前终端
|
|
146
|
+
set ZLG_SDK_DIR=D:\path\to\zlg-sdk-dir
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
```toml
|
|
150
|
+
[[devices]]
|
|
151
|
+
name = "bus0"
|
|
152
|
+
vendor = "zlg"
|
|
153
|
+
model = "USBCAN-2E-U" # 或 "USBCAN-II"
|
|
154
|
+
channel = 1 # 按实际接线:CAN1→0,CAN2→1
|
|
155
|
+
nominal = 250000
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
2E-U / II 均为双通道,`channel` 必须对应实际接线口。型号以铭牌与配置 `model` 为准;不要根据 SDK `GetDeviceInf` 一类字段改判型号或改走 CAN FD。滤波与周期发送路径因型号而异,见 Agent Skill 对应参考页。
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"mcpServers": {
|
|
163
|
+
"xusbcan": {
|
|
164
|
+
"command": "xusbcan-mcp",
|
|
165
|
+
"env": {
|
|
166
|
+
"ZLG_SDK_DIR": "D:\\path\\to\\zlg-sdk-dir",
|
|
167
|
+
"XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Vector
|
|
175
|
+
|
|
176
|
+
适用于已确认的 **VN1640A**(**VN1630** 已登记,本仓库未做真机确认)。
|
|
177
|
+
|
|
178
|
+
需要:
|
|
179
|
+
|
|
180
|
+
- Vector 驱动 / XL Driver(从官方渠道取得授权)
|
|
181
|
+
- `channel` 使用与 python-can / XL Driver **相同的全局通道索引**(无逻辑重映射)。硬件 Channel *N* 通常对应索引 `N - 1`,以本机枚举为准
|
|
182
|
+
|
|
183
|
+
打开时交给 **python-can 已有的 `vector` 后端**。本仓库**不**封装 XL Driver ABI,只提供型号快捷方式(通道数、`app_name=None` 等)以及 CLI / MCP / Skill 的统一用法与真机说明。
|
|
184
|
+
|
|
185
|
+
```toml
|
|
186
|
+
[[devices]]
|
|
187
|
+
name = "vn0"
|
|
188
|
+
vendor = "vector"
|
|
189
|
+
model = "VN1640A"
|
|
190
|
+
channel = 2
|
|
191
|
+
nominal = 250000
|
|
192
|
+
# data = 2000000 # 该通道支持 CAN FD 时可选
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
也可直接写 `interface = "vector"`。
|
|
196
|
+
|
|
197
|
+
```json
|
|
198
|
+
{
|
|
199
|
+
"mcpServers": {
|
|
200
|
+
"xusbcan": {
|
|
201
|
+
"command": "xusbcan-mcp",
|
|
202
|
+
"env": {
|
|
203
|
+
"XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### 创芯(Chuangxin)
|
|
211
|
+
|
|
212
|
+
适用于已确认的 **USB_CAN-2C**(**USB_CAN-2A-GD** 已登记为同后端族,**真机验证暂挂起**,勿标为已确认)。
|
|
213
|
+
|
|
214
|
+
需要:
|
|
215
|
+
|
|
216
|
+
- 创芯 USB 驱动
|
|
217
|
+
- 与 Python 位数匹配的 `ControlCAN.dll`
|
|
218
|
+
- `CHUANGXIN_SDK_DIR` 指向含该 DLL 的目录(本工具按绝对路径加载)
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
set CHUANGXIN_SDK_DIR=D:\path\to\chuangxin-controlcan-dir
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
```toml
|
|
225
|
+
[[devices]]
|
|
226
|
+
name = "cx0"
|
|
227
|
+
vendor = "chuangxin"
|
|
228
|
+
model = "USB_CAN-2C"
|
|
229
|
+
channel = 0
|
|
230
|
+
nominal = 250000
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
同一进程中请只加载一份你选用的 `ControlCAN.dll`;若其它软件也依赖各自的同名 DLL,请分目录或分进程使用。
|
|
234
|
+
|
|
235
|
+
```json
|
|
236
|
+
{
|
|
237
|
+
"mcpServers": {
|
|
238
|
+
"xusbcan": {
|
|
239
|
+
"command": "xusbcan-mcp",
|
|
240
|
+
"env": {
|
|
241
|
+
"CHUANGXIN_SDK_DIR": "D:\\path\\to\\chuangxin-controlcan-dir",
|
|
242
|
+
"XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
### 其它后端(python-can 直通)
|
|
250
|
+
|
|
251
|
+
以 Vector 等型号为证:**python-can 已有后端 + 本项目会话层** 这条路径已经走通。因此,凡在当前环境中 python-can 已声明且本机能打开的后端(如 socketcan、slcan、Kvaser、`pcan` 等),**大概率**只需配置 `interface` / `channel` / `extra` 即可用同一套 CLI / MCP;**不保证**每张卡都已在本仓库真机确认,驱动安装、通道写法、FD/滤波/无 ACK 等行为仍随后端而异,可能踩坑。
|
|
252
|
+
|
|
253
|
+
本仓库对 **PEAK PCAN-USB** 另有型号登记(通道映射),状态为「已登记,未在本仓库真机确认」。写了 `interface` 时不会改走别的后端,也不会阻止你继续在别的程序里直接使用 python-can。
|
|
254
|
+
|
|
255
|
+
## 支持范围
|
|
256
|
+
|
|
257
|
+
| 厂商 | 型号 | 状态 | 说明 |
|
|
258
|
+
|------|------|------|------|
|
|
259
|
+
| 周立功 | USBCAN-2E-U | 真机已确认 | 本仓库 `zlg` 后端;需 `ZLG_SDK_DIR` |
|
|
260
|
+
| 周立功 | USBCAN-II | 真机已确认 | 同上,按型号分发 |
|
|
261
|
+
| Vector | VN1640A | 真机已确认 | python-can `vector`;通道为 XL 全局索引 |
|
|
262
|
+
| Vector | VN1630 | 已登记 | python-can `vector` |
|
|
263
|
+
| 创芯 | USB_CAN-2C | 真机已确认 | 本仓库 ControlCAN 后端;需 `CHUANGXIN_SDK_DIR` |
|
|
264
|
+
| 创芯 | USB_CAN-2A-GD | 已登记(真机验证挂起) | 与 2C 同后端族;验证暂挂起 |
|
|
265
|
+
| PEAK | PCAN-USB | 已登记 | python-can `pcan` |
|
|
266
|
+
|
|
267
|
+
上表是带登记或真机说明的型号,不是准入白名单。其它 python-can 后端见上文「其它后端(python-can 直通)」:可打开 ≠ 本仓库已逐型号真机确认。python-can 无法打开的卡才需要新后端;若新后端要求用户自备 SDK,请在免责声明中追加该厂商。
|
|
268
|
+
|
|
269
|
+
### 真机验证说明
|
|
270
|
+
|
|
271
|
+
「真机已确认」表示:在**已获授权的台架**上,对本仓库公开的 CLI / 核心路径做过有限验证(打开与重开、收发、滤波、多开、`monitor` / `periodic`、`scenario` 等,视该型号当时测试范围而定)。
|
|
272
|
+
|
|
273
|
+
**该说明适用于本仓库标为真机已确认的全部型号**:验证仅覆盖对应测试台架与当时范围,**不构成**对任一厂商产品的性能、兼容性或适销性担保,也不保证每一台设备、每一种子卡 / 主机环境均已覆盖。未覆盖项通常包括主动构造错误帧、长时间 soak、实车网络等。细节与踩坑见 Agent Skill 中该型号参考页。
|
|
274
|
+
|
|
275
|
+
## Agent Skill
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
npx skills add Archaofan/xusbcan-cli --skill xusbcan
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
在项目目录执行可装到当前工程;`-g` 装到用户目录;`-a` 指定客户端(如 `cursor`)。Skill 先读通用契约,再按 `references/catalog.md` 只打开当前配置对应的型号页,避免把全部厂商知识塞进上下文。
|
|
282
|
+
|
|
283
|
+
## 参与
|
|
284
|
+
|
|
285
|
+
欢迎报告问题、提交 PR、贡献新的厂商或型号登记。公开约定摘要如下(细节见 [`CLAUDE.md`](CLAUDE.md)、[`skills/xusbcan/`](skills/xusbcan/)、[`third_party/ABI_PROVENANCE.md`](third_party/ABI_PROVENANCE.md)):
|
|
286
|
+
|
|
287
|
+
- **去耦合**:厂商差异只进 `src/xusbcan/adapters/<厂商>/`;`core` / `cli` / `mcp` 不出现厂商概念,只调用 python-can 通用接口(如 `set_filters` / `send_periodic`)。适配器可在后端钩子内使用厂商专有 API。配置里已有 `interface` 即可打开,不必先为每个型号改会话层。
|
|
288
|
+
- **可持续扩展**:python-can 已有后端 → 只加 `profiles.py`(及可选型号快捷方式);没有后端才加自研绑定并注册 `can.interface`。新增卡时改适配层 + Skill 的 `references/catalog.md` 一行 + 一份型号页;**不要**把各型号症状写进 Skill 根 `description`,也**不要**把全部厂商页塞进一次上下文。
|
|
289
|
+
- **Skill 契约**:根页写通用怎么用;型号页顺序为 Quick start → How this backend behaves → Field notes。Field notes 须标明是前人台架/开发中的现场报告,**未必可复现**,不作正式「不支持」清单,也不据此断言整型号缺陷。
|
|
290
|
+
- **真机与公开表述**:通用配置与该型号的驱动 / 环境变量分开写;真机确认前不要标成「已验证」。需用户自备 SDK 的新厂商,在 README 免责声明追加一条商标与交付边界。
|
|
291
|
+
- **合规**:不提交厂商 DLL / SDK 原文、本机绝对路径、客户/ECU 名等;提交前按 `CLAUDE.md` 脱敏清单自检。
|
|
292
|
+
|
|
293
|
+
## 安全使用
|
|
294
|
+
|
|
295
|
+
- 仅在**已获授权的台架 / 实验室**使用;不要在实车控制网或未授权产线上让 Agent 无人值守发报文
|
|
296
|
+
- 发送与周期发送前确认接线、波特率与 ID;长时任务请设明确时长或改用本机常驻进程
|
|
297
|
+
- MCP 默认本机使用;HTTP 仅 `127.0.0.1`,勿暴露公网
|
|
298
|
+
- **应用层预算(非硬件失效保护)**:MCP / Scenario 周期发送须带时长(上限 300 秒);Scenario 另有墙钟、单步与累计发送次数等限制。周期停止或关闭失败时返回结构化错误并尽量保留可查询任务/会话,便于重试——这不等于硬件失效保护,驱动或硬件异常时仍不能保证一定停止发送
|
|
299
|
+
|
|
300
|
+
## 免责声明
|
|
301
|
+
|
|
302
|
+
本项目是独立的第三方工具,与下列厂商及其产品没有关联、赞助、背书或利益关系。厂商名称、产品名称均为其各自权利人的商标。驱动与 SDK 的版权归权利人所有,由使用者从官方渠道自行获取。
|
|
303
|
+
|
|
304
|
+
本项目按 MIT 提供**自有代码**,不提供任何担保。`python-can` 等依赖与用户自备 SDK 各有其许可,详见 [`third_party/NOTICES`](third_party/NOTICES)。
|
|
305
|
+
|
|
306
|
+
**真机确认仅覆盖上文「真机验证说明」中的台架范围,不构成对任何已确认型号的性能、兼容性或适销性担保。**
|
|
307
|
+
|
|
308
|
+
每支持一家需要使用者自备 SDK 或专有驱动的厂商,在此追加商标与交付边界说明:
|
|
309
|
+
|
|
310
|
+
- **广州致远电子股份有限公司(周立功 / ZLG)**:经公开二次开发接口对接的型号包括 USBCAN-2E-U、USBCAN-II。"周立功"、"ZLG"、"zlgcan" 等为其商标。本项目不随附其驱动或 `zlgcan.dll`。
|
|
311
|
+
- **Vector Informatik GmbH(Vector)**:经 python-can `vector` 打开的型号包括 VN1640A。"Vector"、"VN1640A"、"XL Driver" 等为其商标。本项目不随附 Vector 驱动、XL Driver、CANoe/CANalyzer 或其它专有软件。
|
|
312
|
+
- **珠海创芯科技有限公司(创芯)**:经本仓库 ControlCAN(`VCI_*`)薄封装打开的型号包括 USB_CAN-2C。"创芯"、"USB_CAN-2C"、"CANalyst" 等为其商标。本项目不随附创芯驱动或 `ControlCAN.dll`。
|
|
313
|
+
|
|
314
|
+
## License
|
|
315
|
+
|
|
316
|
+
[MIT License](LICENSE)。第三方条款见 [`third_party/NOTICES`](third_party/NOTICES)。各厂商是「自研 ctypes 后端」还是「仅 python-can 快捷方式」,见 [`third_party/ABI_PROVENANCE.md`](third_party/ABI_PROVENANCE.md)。
|