Skip to main content

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 资料包:

https://manual.zlg.cn/web/#/152?page_id=5332

下载后解压即符合要求——官方资料包解压出的 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)

Source distribution for xusbcan-cli 0.1.0
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)

Table of built distributions (wheels) for xusbcan-cli 0.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page