> ## Documentation Index
> Fetch the complete documentation index at: https://motorbridge.seeedstudio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI 命令行工具
`motorbridge-cli` 命令行工具提供无需编写 Python 代码即可进行快速电机测试、扫描和配置。
## 安装
CLI 随 Python 包自动安装：
```bash theme={null}
pip install motorbridge
motorbridge-cli --help
```
网关以独立命令提供（与 CLI 同级 PATH）：
```bash theme={null}
motorbridge-gateway --help
```
> `--` 可选：`motorbridge-gateway -- --help` 与 `motorbridge-gateway --help` 等价。\
> 三平台网关启动命令（Ubuntu / Windows / macOS）见 [安装环境](../setup) 的 “WS Gateway 启动（三平台）”。
## 全局选项
```bash theme={null}
motorbridge-cli [选项] 命令 [参数]
```
| 选项 | 描述 |
| ----------------- | --------------------------------- |
| `--help` | 显示帮助信息并退出 |
| `-v`, `--version` | 打印已安装 `motorbridge` Python 包版本并退出 |
从 v0.3.3 开始，`motorbridge-cli` 关闭 argparse 长参数缩写。
例如 `robstride-write-param --mode save` 会直接报未识别参数，不会再被误解成 `--model save`。
## 命令概览
| 命令 | 描述 |
| ----------------------- | --------------- |
| `run` | 向电机发送控制命令 |
| `scan` | 扫描 CAN 总线上的活动电机 |
| `id-dump` | 读取达妙 ID/模式寄存器 |
| `id-set` | 写入达妙 ID 寄存器 |
| `robstride-read-param` | 读取 RobStride 参数 |
| `robstride-write-param` | 写入 RobStride 参数 |
| `damiao-read-param` | 读取达妙参数/寄存器 |
| `damiao-write-param` | 写入达妙参数/寄存器 |
***
## run
在循环中运行电机控制命令。
### 用法
```bash theme={null}
motorbridge-cli run [选项]
```
### 选项
| 选项 | 默认值 | 描述 |
| --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--vendor` | `damiao` | 电机厂商：damiao, myactuator, robstride, hightorque, hexfellow |
| `--channel` | `can0` | CAN 接口名称 |
| `--transport` | `auto` | 传输方式：auto, socketcan, socketcanfd, dm-serial, dm-device |
| `--serial-port` | `/dev/ttyACM0` | 串口（用于 dm-serial 传输） |
| `--serial-baud` | `921600` | 串口波特率 |
| `--dm-device-type` | `usb2canfd-dual` | DM\_Device 适配器：usb2canfd, usb2canfd-dual, linkx4c |
| `--dm-channel` | `0` | DM\_Device SDK 通道：usb2canfd=0, usb2canfd-dual=0/1, linkx4c=0/1/2/3 |
| `--model` | `4340` | 电机型号字符串 |
| `--motor-id` | `0x01` | 电机 CAN ID（支持十六进制） |
| `--feedback-id` | `0x11` | 反馈 CAN ID（支持十六进制） |
| `--mode` | `mit` | 控制模式：enable, disable, mit, pos-vel, vel, force-pos, ping, zero, set-zero, save, zero-by-offset, read-param, write-param |
| `--loop` | `100` | 控制迭代次数 |
| `--dt-ms` | `20` | 控制周期（毫秒） |
| `--ensure-mode` | `1` | 是否在控制前确保模式 |
| `--ensure-strict` | `0` | 模式切换失败时是否失败 |
| `--ensure-timeout-ms` | `1000` | 模式切换超时 |
| `--print-state` | `1` | 每次迭代打印状态 |
| `--pos` | `0.0` | 目标位置（rad） |
| `--vel` | `0.0` | 目标速度（rad/s） |
| `--kp` | `30.0` | 位置刚度（MIT 模式） |
| `--loc-kp` | 空 | RobStride `pos-vel` 位置环增益；未传时回退使用 `--kp` |
| `--kd` | `1.0` | 速度阻尼（MIT 模式） |
| `--tau` | `0.0` | 前馈力矩（Nm） |
| `--vlim` | `1.0` | 速度限制（rad/s） |
| `--ratio` | `0.3` | 力比例（force-pos 模式） |
| `--zero-exp` | `0` | 启用 RobStride 实验性置零序列（传 `1` 才真正执行） |
| `--offset-negate` | `0` | RobStride zero-by-offset 预留参数；当前固件路径已禁用 |
| `--store` | `1` | `run --mode write-param` / 置零后持久化保存 |
| `--param-id` | `0x0` | `run --mode read-param/write-param` 使用的 RobStride 参数 ID |
| `--param-value` | 空 | `run --mode write-param` 使用的 RobStride 写入值 |
| `--param-type` | 自动推断 | RobStride 参数类型：i8, u8, u16, u32, f32 |
| `--timeout-ms` | `500` | 参数读写超时 |
| `--set-motor-id` | 空 | Damiao/RobStride 的 Rust 风格改 ID 快捷入口 |
| `--set-feedback-id` | 空 | Damiao MST\_ID 改写入口；RobStride feedback\_id/host\_id 不会被修改 |
| `--verify-id` | `1` | 改 ID 后回读验证 |
| `--verify-model` | `1` | Damiao 主动控制前读取 PMAX/VMAX/TMAX 校验型号 |
| `--verify-timeout-ms` | `500` | Damiao 型号/ID 验证超时 |
| `--verify-tol` | `0.2` | Damiao 型号验证容差 |
### 模式与参数生效关系
* `mit`：`--pos/--vel/--kp/--kd/--tau` 全部生效。
* `pos-vel`：只使用 `--pos/--vlim`；RobStride 的 Python CLI 已与 WS gateway 对齐，走原生寄存器路径（`limit_spd` `0x7017`、`loc_kp` `0x701E`、`loc_ref` `0x7016`）。写一次目标位置用 `--loop 1`；`--vel/--kd/--tau` 按设计忽略。
* `zero` / `set-zero`：当前仅 RobStride 支持；必须传 `--zero-exp 1` 才会下发置零序列。RobStride 置零流程中 MotorBridge 会内部写 `zero_sta=1`。
* `save`：当前仅 RobStride 支持；发送保存参数命令，并等待 RobStride 状态 ACK。
* `zero-by-offset`：当前仅 RobStride 支持，但因固件一致性问题保持禁用；只打印 warning，不发送校准帧。
* `read-param` / `write-param`：`run` 中当前仅 RobStride 支持；使用 `--param-id`、`--param-type`、`--param-value`。
* `--set-motor-id` / `--set-feedback-id`：存在时 `run` 会进入与 `id-set` 相同的改 ID 流程。Damiao 支持二者；RobStride 只支持设备 ID。
### 示例
#### 达妙 — 仅使能电机
```bash theme={null}
motorbridge-cli run --vendor damiao --channel can0 --motor-id 0x01 --feedback-id 0x11 --mode enable --loop 1
```
#### 达妙 — MIT 模式控制
```bash theme={null}
motorbridge-cli run \
--vendor damiao \
--channel can0 \
--model 4340P \
--motor-id 0x01 \
--feedback-id 0x11 \
--mode mit \
--loop 100 \
--dt-ms 20 \
--pos 1.0 \
--kp 30.0 \
--kd 1.0
```
#### 达妙 — 位置-速度模式
```bash theme={null}
motorbridge-cli run \
--vendor damiao \
--channel can0 \
--model 4340P \
--motor-id 0x01 \
--feedback-id 0x11 \
--mode pos-vel \
--loop 200 \
--pos 2.0 \
--vlim 1.5
```
#### 达妙 — 串口传输
```bash theme={null}
motorbridge-cli run \
--vendor damiao \
--transport dm-serial \
--serial-port /dev/ttyACM0 \
--serial-baud 921600 \
--model 4340P \
--motor-id 0x01 \
--feedback-id 0x11 \
--mode mit \
--loop 50
```
#### RobStride — MIT 模式控制
```bash theme={null}
motorbridge-cli run \
--vendor robstride \
--channel can0 \
--model rs-00 \
--motor-id 2 \
--feedback-id 0xFD \
--mode mit \
--pos 0.5 \
--vel 0 \
--kp 20.0 \
--kd 0.5 \
--tau 0 \
--ensure-strict 1 \
--loop 100 \
--dt-ms 20
```
#### RobStride — 位置-速度模式
```bash theme={null}
motorbridge-cli run \
--vendor robstride \
--channel can0 \
--model rs-00 \
--motor-id 2 \
--feedback-id 0xFD \
--mode pos-vel \
--pos 1.5 \
--vlim 1.0 \
--loc-kp 5.0 \
--loop 1 \
--dt-ms 20
```
反方向写入相反的绝对位置：
```bash theme={null}
motorbridge-cli run \
--vendor robstride \
--channel can0 \
--model rs-00 \
--motor-id 2 \
--feedback-id 0xFD \
--mode pos-vel \
--pos -1.5 \
--vlim 1.0 \
--loc-kp 5.0 \
--loop 1 \
--dt-ms 20
```
#### RobStride — Ping 探测
```bash theme={null}
motorbridge-cli run \
--vendor robstride \
--channel can0 \
--model rs-06 \
--motor-id 127 \
--feedback-id 0xFD \
--mode ping \
--loop 1
```
#### RobStride — 置零（`set-zero` 为等价别名）
```bash theme={null}
motorbridge-cli run \
--vendor robstride \
--channel can0 \
--model rs-06 \
--motor-id 127 \
--feedback-id 0xFD \
--mode set-zero \
--zero-exp 1 \
--store 1 \
--loop 1 \
--dt-ms 100
```
#### MyActuator — 位置-速度模式
```bash theme={null}
motorbridge-cli run \
--vendor myactuator \
--channel can0 \
--model X8 \
--motor-id 1 \
--feedback-id 0x241 \
--mode pos-vel \
--loop 100 \
--pos 1.0 \
--vlim 2.0
```
#### Hexfellow — MIT 模式（需要 CAN-FD）
```bash theme={null}
motorbridge-cli run \
--vendor hexfellow \
--transport socketcanfd \
--channel can0 \
--model hexfellow \
--motor-id 0x00 \
--feedback-id 0x00 \
--mode mit \
--loop 100 \
--pos 0.5 \
--kp 2.0 \
--kd 0.1
```
***
## scan
扫描 CAN 总线上的活动电机。
### 用法
```bash theme={null}
motorbridge-cli scan [选项]
```
### 选项
| 选项 | 默认值 | 描述 |
| -------------------- | -------------------------- | -------------------------------------------------------------- |
| `--vendor` | `damiao` | 扫描厂商：damiao, myactuator, robstride, hightorque, hexfellow, all |
| `--channel` | `can0` | CAN 接口 |
| `--transport` | `auto` | 传输类型 |
| `--serial-port` | `/dev/ttyACM0` | 串口 |
| `--serial-baud` | `921600` | 串口波特率 |
| `--model` | `4340` | 电机型号 |
| `--start-id` | `0x01` | 扫描起始 ID |
| `--end-id` | `0x10` | 扫描结束 ID |
| `--feedback-ids` | `0xFD,0xFF,0xFE,0x00,0xAA` | RobStride 扫描时尝试的 host\_id 列表；不是电机 ID |
| `--feedback-base` | `0x10` | Damiao 扫描反馈 ID 基址 |
| `--timeout-ms` | `80` | 每个 ID 的超时（ms） |
| `--param-id` | `0x7019` | RobStride 参数探测 ID |
| `--param-timeout-ms` | `120` | RobStride 参数探测超时（ms） |
### 示例
#### 扫描所有厂商
```bash theme={null}
motorbridge-cli scan --vendor all --channel can0 --start-id 1 --end-id 255
```
#### 仅扫描达妙
```bash theme={null}
motorbridge-cli scan --vendor damiao --channel can0 --start-id 0x01 --end-id 0x20
```
#### 仅扫描 RobStride
```bash theme={null}
motorbridge-cli scan --vendor robstride --channel can0 --start-id 1 --end-id 127 --feedback-ids 0xFD,0xFF,0xFE,0x00,0xAA
```
RobStride 输出中，`probe` / `device_id` 是电机 ID；`feedback_id` / `host_id`（如 `0xFD`）是上位机侧 ID。
#### 仅扫描 MyActuator
```bash theme={null}
motorbridge-cli scan --vendor myactuator --channel can0 --start-id 1 --end-id 32
```
#### 仅扫描 HighTorque
```bash theme={null}
motorbridge-cli scan --vendor hightorque --channel can0 --start-id 1 --end-id 127
```
#### 仅扫描 Hexfellow（需要 CAN-FD）
```bash theme={null}
motorbridge-cli scan --vendor hexfellow --transport socketcanfd --channel can0 --start-id 0 --end-id 255
```
***
## id-dump
从达妙电机读取关键 ID 和配置寄存器。
### 用法
```bash theme={null}
motorbridge-cli id-dump [选项]
```
### 选项
| 选项 | 默认值 | 描述 |
| --------------- | ------------------- | ------------------- |
| `--vendor` | `damiao` | 必须为 damiao |
| `--channel` | `can0` | CAN 接口 |
| `--transport` | `auto` | 传输类型 |
| `--serial-port` | `/dev/ttyACM0` | 串口（用于 dm-serial 传输） |
| `--serial-baud` | `921600` | 串口波特率 |
| `--model` | `4340` | 电机型号 |
| `--motor-id` | `0x01` | 电机 ID |
| `--feedback-id` | `0x11` | 反馈 ID |
| `--timeout-ms` | `500` | 寄存器读取超时 |
| `--rids` | `7,8,9,10,21,22,23` | 要读取的寄存器 ID |
### 示例
```bash theme={null}
motorbridge-cli id-dump \
--vendor damiao \
--channel can0 \
--motor-id 0x01 \
--feedback-id 0x11 \
--rids 7,8,9,10,21,22,23
```
***
## id-set
向电机写入 ID 并可选保存到闪存。Damiao 支持 `ESC_ID/MST_ID`；RobStride 支持修改 `device_id`。
### 用法
```bash theme={null}
motorbridge-cli id-set [选项]
```
### 选项
| 选项 | 默认值 | 描述 |
| ------------------- | -------------- | ------------------------------------ |
| `--vendor` | `damiao` | `damiao` 或 `robstride` |
| `--channel` | `can0` | CAN 接口 |
| `--transport` | `auto` | 传输类型 |
| `--serial-port` | `/dev/ttyACM0` | 串口（用于 dm-serial 传输） |
| `--serial-baud` | `921600` | 串口波特率 |
| `--model` | `4340` | 电机型号 |
| `--motor-id` | `0x01` | 当前电机 ID |
| `--feedback-id` | `0x11` | 当前反馈 ID |
| `--new-motor-id` | (相同) | 要设置的新电机 ID |
| `--new-feedback-id` | (相同) | Damiao 新反馈 ID；RobStride 不修改 host\_id |
| `--store` | `1` | 写入后保存到闪存 |
| `--verify` | `1` | 写入后验证 |
| `--timeout-ms` | `800` | 验证超时 |
### 示例
```bash theme={null}
# 将电机 ID 从 0x01 改为 0x05
motorbridge-cli id-set \
--vendor damiao \
--channel can0 \
--motor-id 0x01 \
--feedback-id 0x11 \
--new-motor-id 0x05 \
--new-feedback-id 0x15 \
--store 1 \
--verify 1
```
```bash theme={null}
# RobStride：将 device_id 从 0x7F 改为 0x7E
motorbridge-cli id-set \
--vendor robstride \
--channel can0 \
--model rs-06 \
--motor-id 0x7F \
--feedback-id 0xFD \
--new-motor-id 0x7E \
--store 1 \
--verify 1
```
***
## robstride-read-param
从 RobStride 电机读取参数。
### 用法
```bash theme={null}
motorbridge-cli robstride-read-param [选项]
```
### 选项
| 选项 | 默认值 | 描述 |
| --------------- | ------ | -------------------------------------------------------- |
| `--channel` | `can0` | CAN 接口 |
| `--transport` | `auto` | 传输方式：auto, socketcan, socketcanfd |
| `--model` | 真实型号 | 真实 RobStride 型号（`rs-00` 到 `rs-06`）；参数表使用第 4 章通用运行参数，必须指定 |
| `--motor-id` | `127` | 电机 ID |
| `--feedback-id` | `0xFD` | RobStride 默认 host\_id；不是电机 ID |
| `--param-id` | (必需) | 要读取的参数 ID |
| `--type` | (必需) | 数据类型：i8, u8, u16, u32, f32 |
| `--timeout-ms` | `500` | 读取超时 |
### 示例
```bash theme={null}
motorbridge-cli run \
--vendor robstride \
--channel can0 \
--model rs-06 \
--motor-id 127 \
--feedback-id 0xFD \
--mode read-param \
--param-id 0x7019 \
--param-type f32
motorbridge-cli robstride-read-param \
--channel can0 \
--model rs-06 \
--motor-id 127 \
--param-id 0x7019 \
--type f32
```
***
## robstride-write-param
向 RobStride 电机写入参数。
### 用法
```bash theme={null}
motorbridge-cli robstride-write-param [选项]
```
### 选项
| 选项 | 默认值 | 描述 |
| --------------- | ------ | -------------------------------------------------------- |
| `--channel` | `can0` | CAN 接口 |
| `--transport` | `auto` | 传输方式：auto, socketcan, socketcanfd |
| `--model` | 真实型号 | 真实 RobStride 型号（`rs-00` 到 `rs-06`）；参数表使用第 4 章通用运行参数，必须指定 |
| `--motor-id` | `127` | 电机 ID |
| `--feedback-id` | `0xFD` | RobStride 默认 host\_id；不是电机 ID |
| `--param-id` | (必需) | 要写入的参数 ID |
| `--type` | (必需) | 数据类型：i8, u8, u16, u32, f32 |
| `--value` | (必需) | 要写入的值（根据 `--type` 解析） |
| `--verify` | `1` | 回读并验证 |
| `--store` | `0` | 写入/验证成功后发送 RobStride 保存参数命令（通信类型 22） |
| `--timeout-ms` | `500` | 验证超时 |
### 示例
```bash theme={null}
motorbridge-cli run \
--vendor robstride \
--channel can0 \
--model rs-06 \
--motor-id 127 \
--feedback-id 0xFD \
--mode write-param \
--param-id 0x7019 \
--param-type f32 \
--param-value 2.0
motorbridge-cli robstride-write-param \
--channel can0 \
--model rs-06 \
--motor-id 127 \
--param-id 0x7019 \
--type f32 \
--value 2.0 \
--verify 1 \
--store 1
```
***
## damiao-read-param
读取 Python binding 暴露的达妙参数/寄存器。
### 用法
```bash theme={null}
motorbridge-cli damiao-read-param [选项]
```
### 选项
| 选项 | 默认值 | 描述 |
| --------------- | ------ | -------------------------------------------- |
| `--channel` | `can0` | CAN 接口 |
| `--transport` | `auto` | 传输方式：auto, socketcan, socketcanfd, dm-serial |
| `--model` | `4340` | 达妙型号 |
| `--motor-id` | `0x01` | 达妙 ESC\_ID |
| `--feedback-id` | `0x11` | 达妙 MST\_ID |
| `--param-id` | (必需) | 参数/寄存器 ID |
| `--type` | (必需) | 数据类型：u32 或 f32 |
| `--timeout-ms` | `500` | 读取超时 |
### 示例
```bash theme={null}
motorbridge-cli damiao-read-param \
--channel can0 \
--model 4340P \
--motor-id 0x01 \
--feedback-id 0x11 \
--param-id 21 \
--type f32
```
***
## damiao-write-param
写入达妙参数/寄存器，并可选回读验证。
### 用法
```bash theme={null}
motorbridge-cli damiao-write-param [选项]
```
### 选项
| 选项 | 默认值 | 描述 |
| --------------- | ------ | -------------------------------------------- |
| `--channel` | `can0` | CAN 接口 |
| `--transport` | `auto` | 传输方式：auto, socketcan, socketcanfd, dm-serial |
| `--model` | `4340` | 达妙型号 |
| `--motor-id` | `0x01` | 达妙 ESC\_ID |
| `--feedback-id` | `0x11` | 达妙 MST\_ID |
| `--param-id` | (必需) | 参数/寄存器 ID |
| `--type` | (必需) | 数据类型：u32 或 f32 |
| `--value` | (必需) | 要写入的值 |
| `--verify` | `1` | 写入后回读验证 |
| `--store` | `0` | 写入/验证成功后调用 Damiao `store_parameters()` |
| `--timeout-ms` | `500` | 验证超时 |
### 示例
```bash theme={null}
motorbridge-cli damiao-write-param \
--channel can0 \
--model 4340P \
--motor-id 0x01 \
--feedback-id 0x11 \
--param-id 8 \
--type u32 \
--value 0x01 \
--verify 1 \
--store 1
```
***
## 退出代码
| 代码 | 含义 |
| -- | ---- |
| 0 | 成功 |
| 1 | 一般错误 |
| 2 | 无效参数 |
## 另见
* [快速开始](quickstart) - 入门指南
* [教程](tutorials/01-scan-and-identify) - 分步教程
* [接口手册](api/controller) - Python API 文档