roboto_usb2can 是一款面向机器人开发与 CAN 总线调试场景的单通道 USB 转 CAN2.0 适配器。本文档面向初次接触的开发者，提供从开箱到稳定通信的完整路径，涵盖 Windows 免驱使用、Linux SocketCAN 接入、上位机工具操作以及固件更新方法。通过本指南，你可以在 10 分钟内完成首次 CAN 数据收发。

Sources: readme_cn.md

产品概览与硬件规格

适配器基于 STM32G431CBT6 微控制器构建，运行 Zephyr RTOS 实时操作系统，通过开源 gs_usb 协议（candleLight 兼容）与主机通信。核心优势在于跨平台免驱：Windows 8.1 及以上系统通过 WinUSB 描述符自动绑定驱动，Linux 内核 3.16 以上版本则自带 gs_usb 驱动实现即插即用。

硬件规格如下表所示：

Sources: readme_cn.md roboto_usb2can.dts

系统架构

下图展示了适配器在两种主流操作系统中的工作方式。Windows 环境下通过 WinUSB 与上位机工具交互；Linux 环境下由内核 gs_usb 驱动自动创建 SocketCAN 接口，直接兼容 can-utils 工具链。

graph LR
    subgraph 主机端
        A[Windows 应用] -->|WinUSB| B[USB 总线]
        C[Linux 应用<br/>candump/cansend] -->|SocketCAN| B
    end
    B -->|USB 2.0 FS| D[roboto_usb2can<br/>STM32G431]
    D -->|CAN2.0| E[CAN 总线网络]

Sources: main.c prj.conf

快速开始

本节提供两条并行的最短路径：如果你使用 Windows，请直接阅读「Windows 上位机工具」小节；如果你使用 Linux，请跳至「Linux SocketCAN 接入」小节。两条路径均不需要手动编译固件。

固件获取

出厂设备已预烧录固件。如需更新或恢复，可前往 GitHub Releases 页面下载预编译的 roboto_usb2can_vX.X.X_YYYYMMDD.bin 文件，再通过 STM32CubeProgrammer、J-Link、OpenOCD 或 Probe-rs 等工具烧录。对大多数用户而言，出厂固件已满足日常调试需求。

Sources: readme_cn.md

LED 状态速查

设备板载三颗 LED，用于直观展示系统运行状态。首次上电时，请根据下表核对指示灯行为，以确认硬件工作正常。

上电后，若蓝灯以中速闪烁，说明 USB 枚举成功；此时若尚未启动 CAN 通道，黄灯应处于极慢闪烁状态。绿灯仅在总线上有真实数据流动时才会闪动。

Sources: readme_cn.md roboto_usb2can.h

Windows 上位机工具

Windows 系统无需安装额外驱动，插入设备后自动识别为 WinUSB 设备。我们提供了基于 Python + Tkinter 的跨平台上位机工具，支持同时管理多个适配器，适合通过 USB Hub 扩展多路 CAN 的场景。

环境准备与启动

确保已安装 Python 3.8 或更高版本，并安装 pyusb 依赖：

pip install pyusb

将设备通过 Type-C 线缆连接电脑，随后进入 scripts 目录运行工具：

cd roboto_usb2can/scripts
python roboto_usb2can_tool.py

在 Windows 环境下，需确保同目录下存在 libusb-1.0.dll，或该动态库已加入系统 PATH。

Sources: readme_cn.md requirements.txt

界面功能与操作流程

工具界面采用三栏式布局：顶部为连接与总线控制工具栏，中部为报文收发区与实时日志，底部为已连接设备列表。典型使用流程如下图所示：

flowchart TD
    A[插入设备] --> B[点击 Connect All]
    B --> C{是否识别到设备?}
    C -->|否| D[检查 USB 线缆与驱动]
    C -->|是| E[选择波特率]
    E --> F[点击 Start CAN]
    F --> G[输入 ID 与 Data]
    G --> H[点击 Send 或启用 Periodic]
    H --> I[查看 Traffic Log 收发信息]

核心功能说明如下：

• 多设备管理：底部列表实时显示所有在线设备的总线地址与序列号，支持同时连接并区分不同适配器（日志中以 [Dev X] 标注来源）。
• 全局连接：一键扫描并连接所有匹配 VID/PID（0x1D50/0x606F）的设备。
• 波特率设置：下拉框预设 125K、250K、500K、1M bps 四档，默认 1 Mbps。
• 报文发送：支持十六进制输入 CAN ID 与数据负载；可选择向所有设备广播，或向指定设备单发。
• 周期发送：勾选 Enable Periodic 后按设定毫秒间隔自动循环发送，便于压力测试。
• 接收过滤：在 Filter ID 输入框填入十六进制 ID，日志区将只显示匹配帧。

Sources: roboto_usb2can_tool.py roboto_usb2can_tool.py

打包为独立可执行文件（可选）

若目标电脑未安装 Python，可使用 PyInstaller 将工具打包为单文件 EXE：

pip install pyinstaller
cd scripts
pyinstaller --noconfirm --onefile --windowed --clean --icon="icon.ico" --add-data "icon.ico;." roboto_usb2can_tool.py

生成的可执行文件位于 scripts/dist/roboto_usb2can.exe，可直接拷贝运行。

Sources: readme_cn.md

Linux SocketCAN 接入

Linux 内核对 gs_usb 驱动的原生支持使适配器在插入后即可自动生成 can0 接口，无需额外安装内核模块。

设备识别与接口启动

插入设备后，通过以下命令确认系统已正确识别：

dmesg | grep gs_usb
# 期望输出包含: Configuring for 1 channels

随后使用 ip 命令设置波特率并启动接口。以下示例配置为 1 Mbps：

sudo ip link set can0 up type can bitrate 1000000

启动成功后，ip link show can0 应显示接口状态为 UP。若需关闭接口，执行 sudo ip link set can0 down。

Sources: readme_cn.md

基础收发测试（can-utils）

安装 can-utils 工具包后，即可在命令行完成收发验证：

# 终端 A：监听总线
candump can0

# 终端 B：发送测试帧
cansend can0 123#DEADBEEF

其中 123 为 CAN ID（十六进制），DEADBEEF 为 8 字节数据负载。若配置正确，终端 A 将实时打印接收到的帧信息。

Sources: readme_cn.md

自动化压力测试

scripts 目录下提供了 test_roboto_usb2can.sh 脚本，可快速验证多设备并发场景下的稳定性。该脚本会自动配置接口、启动 cangen 流量发生器，并以仪表盘形式实时展示各接口的收发速率、错误计数与总线状态。

使用前请确保已安装 can-utils 与 iproute2，然后执行：

chmod +x scripts/test_roboto_usb2can.sh
sudo ./scripts/test_roboto_usb2can.sh

脚本默认以 0.5 毫秒间隔发送随机 ID 的标准 CAN 帧，并启用 100 毫秒自动 Bus-Off 恢复机制，适合检验硬件在高负载下的表现。按 Ctrl+C 即可停止测试并清理后台进程。

Sources: test_roboto_usb2can.sh

udev 规则配置

为避免每次操作 SocketCAN 或运行上位机工具时都使用 sudo，建议安装项目提供的 udev 规则。该规则赋予 plugdev 用户组对设备的读写权限，并支持创建友好的 /dev/roboto_usb2can* 符号链接。

在工作区根目录执行以下命令完成安装：

sudo cp roboto_usb2can/scripts/99-roboto-usb2can.rules /etc/udev/rules.d/
sudo chmod 644 /etc/udev/rules.d/99-roboto-usb2can.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

随后将当前用户加入 plugdev 与 dialout 组：

sudo usermod -a -G plugdev,dialout $USER
# 重新登录后生效

验证规则是否生效的方法：

lsusb | grep 1d50:606f
ls -l /dev/roboto_usb2can*
ip link show type can

Sources: readme_cn.md 99-roboto-usb2can.rules

固件编译与烧录

如果你需要修改固件功能、调整 CAN 参数或进行二次开发，可参考以下步骤基于 Zephyr RTOS 重新编译。

编译环境准备

本项目依赖 Zephyr SDK 与 west 工具链。首先确保已按 Zephyr 官方指南完成基础环境搭建，随后在 Zephyr 工作区的 submanifests 目录中添加 CANnectivity 模块声明，并执行 west update 同步依赖。最后将本仓库克隆至 zephyr/samples/roboto_usb2can 目录。

Sources: readme_cn.md west.yml

编译与烧录命令

进入项目目录后，使用以下命令编译：

cd roboto_usb2can
west build -b roboto_usb2can

编译成功后，根据手头调试器选择对应烧录方式：

构建系统在 Release 模式下会自动生成带版本号的二进制文件，位于 build/zephyr/roboto_usb2can_vX.X.X_YYYYMMDD.bin，可直接用于量产烧录。

Sources: readme_cn.md CMakeLists.txt

常见问题排查

下表整理了初学者最常遇到的三种场景及其排查思路：

Sources: readme_cn.md main.c

下一步

完成本指南后，你已具备 roboto_usb2can 适配器的基础使用能力。若希望深入理解其内部实现，建议按以下顺序阅读后续文档：

• 如需了解硬件引脚定义、时钟树与设备树配置，请阅读 硬件架构与接口规范。
• 如需深入 gs_usb 协议栈、USB 描述符与 WinUSB 免驱原理，请阅读 Zephyr RTOS 与 USB 协议栈。
• 如需研究 CAN 总线错误监控、Bus-Off 自动恢复与错误洪水保护机制，请阅读 CAN 总线监控与错误保护机制。
• 如需解析 LED 控制状态机与活动指示逻辑，请阅读 状态指示与 LED 控制系统。
• 如需基于现有上位机进行二次开发或理解 gs_usb 报文封装，请阅读 上位机工具开发。
• 如遇疑难故障，请查阅 常见问题与故障排查。