xusbcan-cli
面向 AI Agent 的 CAN 总线调试工具。
中文 | English
免责声明:本项目与广州致远电子股份有限公司(周立功/ZLG)及其产品没有任何关联、赞助、背书或利益关系。"周立功"、"ZLG"、"zlgcan" 等名称均为其各自权利人的商标。本项目是独立的第三方工具,仅通过公开的二次开发接口对接其硬件;驱动与 SDK 版权归其权利人所有,由用户从官方渠道获取。
以后端服务形态运行,同时提供标准 CLI 与 MCP(Model Context Protocol)接口,让 AI Agent 能直接完成 CAN 报文的收发、监听、周期发送等调试操作——无需人工操作上位机软件,即可实现 Agent 自动化联合调试。
目标与展望
在 AI 时代,让 Agent 能像使用普通工具一样操作 CAN 总线:结构化输出、稳定契约、可被程序化调用。
我们希望 xusbcan-cli 成为 AI 与车载 / 工业 CAN 总线之间的标准桥梁,让「用 Agent 自动完成整条总线的联调、诊断、验证」成为常态。
特性
- 统一设备抽象:多家厂商 CAN 卡(周立功 / Vector / PEAK / 创芯 …)通过统一接口接入,Agent 看到的是同一套命令语义
- CLI 与 MCP 共享核心:行为一致,结构化 JSON / JSONL 输出,Agent 无需解析人类可读日志
- 轻量:核心运行时依赖仅
python-can
安装
从源码安装(当前方式)
git clone https://github.com/Archaofan/xusbcan-cli.git
cd xusbcan-cli
pip install -e . # 仅 CLI + 核心
pip install -e ".[mcp]" # 追加 MCP 服务器支持
从 PyPI 安装(即将提供)
pip install xusbcan-cli # 仅 CLI + 核心
pip install xusbcan-cli[mcp] # 追加 MCP 服务器支持
快速开始
1. 准备环境
运行前提:
- Python 3.11+(64 位)
- 一张周立功 USBCAN-2E-U 卡
- 周立功 USB 设备驱动(让系统识别设备)
- 周立功二次开发 SDK 资料包(提供
zlgcan.dll)
获取 SDK:从周立功官方资料页下载二次开发 SDK 资料包:
下载后解压即符合要求——官方资料包解压出的 SDK 目录已包含运行所需的 zlgcan.dll 与 kerneldlls/(内核 DLL),无需额外整理。
配置环境变量:将解压后的 SDK 目录路径设为环境变量 ZLG_SDK_DIR:
# Windows(PowerShell,用户级持久化)
[Environment]::SetEnvironmentVariable("ZLG_SDK_DIR", "D:\path\to\解压后的SDK目录", "User")
# 或临时设置(仅当前终端生效)
set ZLG_SDK_DIR=D:\path\to\解压后的SDK目录
指向的目录结构应为:
<ZLG_SDK_DIR>/
├── zlgcan.dll # 核心库(必需)
└── kerneldlls/ # 内核 DLL 目录(必需,与 zlgcan.dll 同目录)
2. 编写配置 xusbcan.toml
[[devices]]
name = "ecu" # 逻辑别名,Agent 通过它引用设备
vendor = "zlg"
model = "USBCAN-2E-U"
channel = 1
nominal = 250000 # 波特率
3. 使用 CLI
xusbcan list # 列出设备
xusbcan send ecu --id 0x123 --data "01 02 03" # 发送
xusbcan receive ecu --timeout 1 # 接收一帧
xusbcan monitor ecu --duration 5 # 监听
xusbcan status ecu # 状态
4. 启动 MCP 服务器
xusbcan-mcp
在你的 MCP 客户端(Claude Desktop / Cursor / Claude Code 等)里注册它。配置示例:
{
"mcpServers": {
"xusbcan": {
"command": "xusbcan-mcp",
"env": {
"ZLG_SDK_DIR": "D:\\path\\to\\zlgcan_x64",
"XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
}
}
}
}
连接后,Agent 即可通过 send_frame、receive_frame、monitor、periodic_start 等工具直接调试 CAN 总线。
支持的硬件
当前已验证:周立功 USBCAN-2E-U。
项目基于 python-can,天然覆盖大量厂商后端(Vector、PEAK、socketcan、slcan、Kvaser …)。新增一种 CAN 卡,通常只需增加一个后端适配或一条设备配置,即可让 Agent 用同一套接口操作它。
欢迎适配更多 CAN 卡 🙌
如果你手头有其它型号的 CAN 卡(Vector / PEAK / 创芯 / Kvaser / 国产卡 …),欢迎贡献后端适配或设备配置。让更多硬件能被 AI Agent 直接使用,是这个项目的核心目标之一。
参与
- 报告问题、提出需求、提交 PR
- 贡献新的 CAN 卡适配
- 一起把「Agent 自动化联合调试 CAN」这件事做成通用能力
License
第三方组件的许可条款见 third_party/NOTICES。
Metadata
Release files for xusbcan-cli 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xusbcan_cli-0.1.0.tar.gz | 33.5 kB | Without provenance | Details for xusbcan_cli-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xusbcan_cli-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for xusbcan_cli-0.1.0-py3-none-any.whl |
Total release size: 68.5 kB
Release files / xusbcan_cli-0.1.0.tar.gz
| Download URL | xusbcan_cli-0.1.0.tar.gz |
|---|---|
| Size | 33.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e45c871f5ab334d44af5a971f5b3ec8544c9eb3a8ffd1ffcc952f2f4c5a8f07e
|
|
BLAKE2b-256 checksum How to use checksums |
21e1276615c6407d266cfa97584ba956e6dda76b972a504b946ae0cc6a3b387e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / xusbcan_cli-0.1.0-py3-none-any.whl
| Download URL | xusbcan_cli-0.1.0-py3-none-any.whl |
|---|---|
| Size | 35.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fd8246cf6542487bfece3210e3863435744ab6341a12fea4379584803642ea50
|
|
BLAKE2b-256 checksum How to use checksums |
f79116dfe45e3297625e22fe0de4d9dde14929f5cb9f3d559f855cb05c7693a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for xusbcan-cli 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.