wddrive-maintain-cli
概述
wdd-maintain-cli 是面向无图形环境的设备维护命令行工具，用于发现威动电机驱动器、升级固件，并读取 / 写入 / 持久化 CAN ID、波特率与控制器协议。它的能力与 wddrive-studio 的「设备维护」页等价，适合在服务器、CI 或远程终端中使用。
它随 wddrive-studio 安装包一起提供，因此本页标题中的站点产品名是 wddrive-maintain-cli，而实际输入的命令名是 wdd-maintain-cli。
命令行有两种用法：
- 交互式 TUI：不带任何子命令直接运行，进入全屏界面，用按键完成发现、升级与设置。
- 一次性命令：带上子命令执行单个操作后退出，适合脚本或人工排障。
传输方式按平台自动选择：
- Linux：通过 SocketCAN 直连（如
can0）。 - Windows / macOS：经 gs_usb 直连 candleLight / gs_usb 适配器，接口名形如
GS_USB_<串号后 8 位>。
安装与运行
wdd-maintain-cli 随 wddrive-studio 安装包一并安装。安装后打开终端验证：
wdd-maintain-cli --version
wdd-maintain-cli --help
Linux：启用 CAN 接口
在读取设备前，先把 CAN 接口按驱动器使用的波特率启用（威动固件通常为 1 Mbit/s）：
sudo ip link set can0 up type can bitrate 1000000
用 ip -details link show can0 可以确认状态与波特率。
Windows：为适配器绑定 WinUSB
candleLight 等支持 WCID 的适配器由系统自动安装 WinUSB 驱动。若未自动安装，请用 Zadig 把该设备的接口 0 绑定到 WinUSB。未绑定时仍能列出设备，但打开会失败并提示使用 Zadig。
macOS：无需额外驱动
macOS 通过 gs_usb 直连 candleLight / gs_usb 适配器，无需安装额外驱动。
通用选项
所有一次性命令都接受以下全局选项：
| 选项 | 说明 |
|---|---|
--interface <名称> |
指定 CAN 接口；缺省自动选择第一个可用接口。 |
--baudrate <kbps> |
主机波特率（kbps）；缺省用驱动默认值，Linux SocketCAN 下忽略。 |
--firmware-dir <路径> |
固件目录；缺省为系统数据目录下的 wddrive/wddrive-studio/firmwares。 |
--lang <zh-CN|en> |
界面语言；缺省读本地配置，未配置时用 zh-CN。 |
--wait <秒> |
等待设备出现或信息拉取的秒数，默认 10。 |
wdd-maintain-cli --interface can0 --wait 15 scan
wdd-maintain-cli --lang en interfaces
枚举接口与发现设备
列出当前可用的 CAN 接口：
wdd-maintain-cli interfaces
发现设备并打印设备表：
wdd-maintain-cli scan
输出会先显示本地已加载的固件数量与目录，然后是为每台设备读取的 GET_INFO 与三项设置。设备表列包括：
| 列 | 含义 |
|---|---|
UUID |
设备唯一标识（十六进制）。 |
Node |
节点号。 |
Version |
固件版本。 |
Product |
产品编号。 |
CAN ID |
设备配置的 CAN ID。 |
Baud |
设备配置的波特率。 |
Protocol |
控制器协议（CiA402 / KLIPPER）。 |
Status |
在线、可更新、升级中等状态。 |
找不到设备时，请检查：接口是否已启用、波特率是否与设备一致、接线与 120 Ω 终端电阻是否正确，以及设备是否已复位进入更新模式。命令超时可加大
--wait。
持续监控设备
持续监控设备事件，直到按 Ctrl-C 退出：
wdd-maintain-cli monitor
界面会实时打印设备上线 / 下线、升级进度等事件，并刷新设备表。它适合在升级期间用另一个终端观察状态。
交互式 TUI
不带子命令直接运行，会进入交互式 TUI（ratatui）：
wdd-maintain-cli
界面分为三部分：顶部连接控件（接口、波特率、连接状态）、中部设备表、底部日志与帮助栏。常用按键：
| 按键 | 作用 |
|---|---|
c |
连接 / 断开 |
i |
选择 CAN 接口 |
b |
循环切换波特率 |
↑ / ↓ |
在设备表中选择设备 |
Enter |
就地编辑选中设备的设置 |
u |
更新选中设备 |
U |
更新全部设备 |
s |
保存选中设备的设置 |
j |
启动跳转（设备退出 IAP） |
L |
LED 定位 |
r |
重新扫描固件 |
n |
从网络拉取固件 |
l |
切换界面语言 |
q / Ctrl-C |
退出 |
编辑设备时，用 ↑ / ↓ 选择字段、← / → 选择选项、Enter 提交、Esc 取消。
固件管理
列出固件目录中已加载的固件：
wdd-maintain-cli firmware list
从网络拉取固件到本地目录并重新扫描：
wdd-maintain-cli firmware fetch
拉取需要网络，但不依赖 CAN 连接。若本地已有相同产品与版本的固件，会被跳过；拉取失败会报错。
固件升级
升级单台设备，把 <uuid> 换成 scan 中列出的设备 ID：
wdd-maintain-cli update DEADBEEF
升级当前所有可更新设备：
wdd-maintain-cli update all
用显式指定的固件 zip 升级单台设备（仅限单台，不能与 all 同用）：
wdd-maintain-cli update DEADBEEF --firmware /path/to/firmware.zip
设备需要处于 IAP（更新）模式：复位或重新给设备上电即可。开始前请把固件 zip 放入固件目录（或使用 --firmware 指定）。
升级过程中会依次显示 写入中 / 验证中 / 升级中 / 已完成 / 失败 等状态与进度百分比。
固件升级进行中切勿断电或断开连接。 设备忙（正在升级）时对它的其他操作会被拒绝。
设备设置
读取设备的三项设置：
wdd-maintain-cli settings get DEADBEEF
写入设置（写入 RAM，就地生效；可同时指定多项）：
wdd-maintain-cli settings set DEADBEEF --can-id 2 --baudrate 1000 --protocol 0
取值要求：
--can-id：1–127。--baudrate：100 / 125 / 250 / 500 / 800 / 1000（kbps）。--protocol：0 = CiA402，1 = KLIPPER。
把 RAM 中的设置持久化到设备存储（断电后保留）：
wdd-maintain-cli settings save DEADBEEF
settings set只改内存，重启会丢失；要长期生效，写入后必须执行settings save。更改 CAN ID 或波特率后，后续通讯需使用新值。
启动应用
让设备退出 IAP 并跳转到应用程序运行：
wdd-maintain-cli jump DEADBEEF
如果设备没有跳转，它会一直停留在更新模式，直到再次复位或重新上电。
常见问题
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 提示找不到 CAN 接口 | 接口未启用 | Linux 先 ip link set can0 up type can bitrate 1000000；确认接口名与 --interface 一致。 |
| 设备未在等待时间内出现 | 设备未进入 IAP / 总线异常 | 复位或重新上电设备；检查接线、终端电阻与波特率，必要时加大 --wait。 |
| Windows 打开设备失败 | 适配器未绑定 WinUSB | 用 Zadig 把接口 0 绑定到 WinUSB；支持 WCID 的设备应由系统自动安装。 |
| 发现不到任何设备 | 波特率不一致 | 主机波特率需与设备一致（威动 bootloader 固定 1 Mbit/s），可用 --baudrate 1000。 |
update all --firmware 报错 |
参数组合不合法 | --firmware 仅用于单台设备，批量升级用 update all 自动匹配固件。 |
| 固件拉取失败 | 网络不可用 | 检查网络后重试。 |
| 设置写入后重启丢失 | 只写了 RAM | 执行 settings save <uuid> 持久化到设备存储。 |
下一步
- 图形界面完整说明：wddrive-studio
- 第一次接线、连接与运行：快速上手
- 标准的 CiA-402 状态机与运行模式：CiA402
- 在 Klipper 下使用威动电机：Klipper