Skip to main content

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.

Source: motor_cli/README.zh-CN.md

motor_cli(中文)

Rust motor_cli 的全参数完整说明。
  • Crate: motor_cli
  • 推荐(release 压缩包):./bin/motor_cli [参数...]
  • 可选(源码编译后):./target/release/motor_cli [参数...]

优先使用 Release 二进制

先从 GitHub Releases 下载并解压对应包(例如 motor-cli-vX.Y.Z-linux-x86_64.tar.gz),再直接运行:
./bin/motor_cli -h
./bin/motor_cli --vendor damiao --mode scan --start-id 1 --end-id 16
如果你希望直接输入 motor_cli 命令:
export PATH="$(pwd)/bin:$PATH"
motor_cli -h

Damiao 指令与寄存器进阶文档

  • 中文详表(指令/寄存器/调参): DAMIAO_API.zh-CN.md
  • English version: DAMIAO_API.md

RobStride 指令与参数进阶文档

  • 中文详表(参数/能力边界): ROBSTRIDE_API.zh-CN.md
  • English version: ROBSTRIDE_API.md

MyActuator 指令与模式进阶文档

  • 中文详表(命令/模式/参数): MYACTUATOR_API.zh-CN.md
  • English version: MYACTUATOR_API.md

HighTorque 补充说明

  • 协议深度分析文档:../docs/zh/hightorque_protocol_analysis.md
  • 当前 vendor=hightorque 为 原生 ht_can v1.5.5 的“直连 CAN”模式,不是官方的“串口->CANboard”传输链路。

CAN 调试入口

  • Linux slcan + Windows pcan 专业排障:../docs/zh/can_debugging.md
  • English guide: ../docs/en/can_debugging.md

传输标识

  • [STD-CAN] => --transport auto|socketcan
  • [CAN-FD] => --transport socketcanfd(仅 Linux;Hexfellow 必须使用)
  • [DM-SERIAL] => --transport dm-serial(仅 Damiao)
当前状态:
  • Hexfellow:socketcanfd 路径已实测,统一 mit / pos-vel 可用。
  • HighTorque:标准 CAN 下统一 mit / vel 已实测可用(协议层忽略 kp/kd)。
  • Damiao:统一 mit / pos-vel / vel / force-pos 的基线实现。

1. 参数解析规则

  • 仅解析 --key value 形式。
  • 支持裸 mode 简写,例如 motor_cli scan --vendor robstride ... 等价于 --mode scan
  • 单独开关(如 --help)会按值 1 处理。
  • ID 类参数支持十进制(如 20)与十六进制(如 0x14)。
  • 未被代码使用的参数即使传入,也不会生效。

1.1 统一调用范式(CLI 大一统)

所有品牌都遵循同一个调用骨架,只是 vendor/model/mode 与附加参数不同:
motor_cli \
  --vendor <damiao|robstride|hightorque|myactuator|all> \
  --transport <auto|socketcan|socketcanfd|dm-serial> \
  --channel <can0|slcan0|can0@1000000...> \
  --model <model-name> \
  --motor-id <id> --feedback-id <id> \
  --mode <mode-name> \
  [模式参数...] \
  --loop <n> --dt-ms <ms>
说明:
  • socketcanfd 为 Hexfellow 必需链路;Damiao 可按型号做 CAN-FD 验证;dm-serial 仅 Damiao 可用。
  • vendor=all 当前仅用于统一扫描(--mode scan)。

1.2 通用参数语义(先理解这些)

参数语义
--vendor选择品牌驱动实现(统一入口下发到不同 vendor backend)
--transport选择传输层(标准 CAN 或 Damiao 串口桥)
--channelCAN 通道名(Linux 为网卡名;Windows 可带 @bitrate
--model型号名称,用于该品牌下的限值/能力边界与编码映射
--motor-id目标电机 ID(发送命令目标)
--feedback-id反馈帧/主机侧 ID;RobStride 下是 host_id,不是电机 ID
--mode控制/查询动作类型(不同品牌支持集合不同)
--loop / --dt-ms循环发送次数 / 周期
--ensure-mode控制前是否自动切控制模式(Damiao 等支持)

1.3 各品牌参数变量怎么传(统一调用下的差异)

品牌--model 传入--motor-id / --feedback-id 传入常用 --mode
Damiao必传且建议按电机真实型号(混型场景不要写死一个 model)motor-idfeedback-id 都需要按实际设备传入scanenabledisablemit(当前串口桥建议这四个)
RobStride必须传真实型号:rs-00rs-06motor-id 必传;feedback-id 常用 0xFDpingscanmitvelread-paramwrite-param
HighTorquehightorque(hint)按设备 ID 传入readmitposveltqescan
MyActuator传运行时型号字符串(默认 X8标准 11-bit 规则(常用 0x140+id / 0x240+idstatusscancurrentvelposenable/disable
all分品牌 hint(--damiao-model 等)仅扫描场景使用scan

2. 顶层通用参数(所有 vendor)

参数类型默认值说明
--helpflag关闭输出帮助并退出
--vendorstringdamiaodamiao / robstride / hightorque / myactuator / hexfellow / all
--transportstringautoauto / socketcan / socketcanfd / dm-serialsocketcanfd 为 Hexfellow 必需;dm-serial 仅 Damiao)
--channelstringcan0Linux:SocketCAN 网卡名(can0/slcan0);Windows(PCAN 后端):can0/can1,可加 @bitrate(如 can0@1000000);macOS(PCBUSB 后端):can0/can1
--serial-portstring/dev/ttyACM0--transport dm-serial 时使用
--serial-baudu64921600--transport dm-serial 时使用
--modelstring按 vendor 决定Damiao 默认 4340;RobStride 必须使用真实 rs-00rs-06 型号;HighTorque 默认 hightorque;MyActuator 默认 X8
--motor-idu16(hex/dec)0x01电机 CAN ID
--feedback-idu16(hex/dec)按 vendor 决定Damiao 默认 0x11;RobStride 默认 0xFD;HighTorque 默认 0x01;MyActuator 默认 0x241(motor-id=1)
--modestring按 vendor 决定Damiao 默认 mit;RobStride 默认 ping;HighTorque 默认 read;MyActuator 默认 statusall 默认 scan
--loopu641控制循环次数
--dt-msu6420循环间隔毫秒
--ensure-mode0/11控制前自动切模式

2.1 通道速查(--channel

  • Linux SocketCAN:
    • 直接使用网卡名:can0can1slcan0
    • 波特率在网卡初始化阶段设置(ip link / slcand),不要写到 --channel
    • can0@1000000 在 Linux SocketCAN 下无效。
  • Windows PCAN:
    • can0 映射 PCAN_USBBUS1can1 映射 PCAN_USBBUS2
    • 支持可选波特率后缀:can0@1000000
  • macOS PCBUSB(PCAN 后端):
    • can0 映射 PCAN_USBBUS1can1 映射 PCAN_USBBUS2
    • 需先安装 libPCBUSB.dylib(见仓库根目录 README.zh-CN.md 的 macOS 章节)。

2.2 Damiao 串口桥速查(--transport dm-serial

  • 该链路为适配器私有路径,面向 Damiao 电机。
  • 常用参数:--transport dm-serial --serial-port /dev/ttyACM1 --serial-baud 921600
  • dm-serial 模式下,传输层创建会忽略 --channel
  • dm-serial 仅改变“传输层”(走串口桥),Damiao 的业务参数与模式接口保持一致(--mode--motor-id--feedback-id--verify-model--ensure-mode 等)。

2.3 Damiao 独立 CAN-FD 链路速查(--transport socketcanfd

  • 该链路为 Linux 专用,并与经典 socketcan 链路并存。
  • 常用参数:--transport socketcanfd --channel can0
  • 使用前先确保网口处于 FD 模式(scripts/canfd_restart.sh can0)。
  • 当前状态:链路已接入,尚未标注“已完成 CAN-FD 电机验证”的型号列表。

3. vendor=damiao

3.1 支持模式

  • scan
  • enable
  • disable
  • mit
  • pos-vel
  • vel
  • force-pos

3.2 Damiao 专用参数

参数类型默认值作用范围说明
--verify-model0/11非 scan校验 PMAX/VMAX/TMAX 与 --model 一致
--verify-timeout-msu64500非 scan型号握手读取超时
--verify-tolf320.2非 scan限值匹配容差
--start-idu161scan扫描起始 ID(1..255)
--end-idu16255scan扫描结束 ID(1..255)
--set-motor-idu16 可选改 ID 流程写 ESC_ID(RID 8)
--set-feedback-idu16 可选改 ID 流程写 MST_ID(RID 7)
--store0/11改 ID 流程是否保存参数
--verify-id0/11改 ID 流程是否回读 RID7/RID8 校验

3.3 各模式控制参数

模式参数默认值
mit--pos --vel --kp --kd --tau0 0 2 1 0
pos-vel--pos --vlim0 1.0
vel--vel0
force-pos--pos --vlim --ratio0 1.0 0.1
enable / disable无额外参数n/a

3.4 扫描行为细节

  • 扫描逻辑本质上是“型号无关”的:内部会遍历内置 model-hint 列表。
  • 每个候选 ID 会尝试多个 feedback-hint:推断值(id+0x10)、用户给定 --feedback-id0x110x17
  • 优先用寄存器(RID 21/22/23)检测,失败再走反馈回退检测。

3.5 Damiao 示例

# 扫描 1..16
motor_cli \
  --vendor damiao --channel can0 --mode scan --start-id 1 --end-id 16
# [STD-CAN]

# MIT 控制
motor_cli \
  --vendor damiao --channel can0 --model 4310 --motor-id 0x04 --feedback-id 0x14 \
  --mode mit --pos 1.57 --vel 2.0 --kp 35 --kd 1.2 --tau 0.3 --loop 120 --dt-ms 20
# [STD-CAN]

# 通过 Damiao 串口桥执行 MIT
motor_cli \
  --vendor damiao --transport dm-serial --serial-port /dev/ttyACM1 --serial-baud 921600 \
  --model 4310 --motor-id 0x04 --feedback-id 0x14 \
  --mode mit --verify-model 0 --ensure-mode 0 \
  --pos 1.0 --vel 0 --kp 2 --kd 1 --tau 0 --loop 80 --dt-ms 20
# [DM-SERIAL]

# 位置速度控制
motor_cli \
  --vendor damiao --channel can0 --model 4310 --motor-id 0x04 --feedback-id 0x14 \
  --mode pos-vel --pos 3.14 --vlim 4.0 --loop 120 --dt-ms 20
# [STD-CAN]

# 改 ID + 保存 + 校验
motor_cli \
  --vendor damiao --channel can0 --model 4310 --motor-id 0x01 --feedback-id 0x11 \
  --set-motor-id 0x04 --set-feedback-id 0x14 --store 1 --verify-id 1

3.6 Damiao 串口桥完整接口与用法(--transport dm-serial

先定义公共前缀(建议):
DM_SERIAL="--vendor damiao --transport dm-serial --serial-port /dev/ttyACM1 --serial-baud 921600 --model 4310"

3.6.1 串口桥下必用/常用参数

参数是否建议显式传入说明
--transport dm-serial必须切到 Damiao 串口桥链路
--serial-port必须串口设备,如 /dev/ttyACM1
--serial-baud必须串口波特率,常用 921600
--channel可省略该模式下会被忽略
--motor-id / --feedback-id控制时必须与扫描命中结果一致
--verify-model建议按现场开关若握手链路不稳定可先设 0 做联通验证
--ensure-mode建议按现场开关若电机模式切换流程不稳定可先设 0
当前串口桥场景对外推荐仅使用:scan / enable / disable / mit

3.6.2 串口桥下常用四模式命令模板

# 1) 扫描
motor_cli $DM_SERIAL --mode scan --start-id 1 --end-id 16

# 2) 使能
motor_cli $DM_SERIAL --motor-id 0x04 --feedback-id 0x14 --mode enable --verify-model 0 --loop 1

# 3) 失能
motor_cli $DM_SERIAL --motor-id 0x04 --feedback-id 0x14 --mode disable --verify-model 0 --loop 1

# 4) MIT
motor_cli $DM_SERIAL --motor-id 0x04 --feedback-id 0x14 \
  --mode mit --verify-model 0 --ensure-mode 0 \
  --pos 0.5 --vel 0 --kp 2 --kd 1 --tau 0 --loop 80 --dt-ms 20

3.6.3 推荐测试顺序

  1. scan 先确认在线 ID。
  2. enable --loop 1 做最小动作验证。
  3. mit 小步参数(小 pos、中低 kp/kd)验证控制闭环。
  4. 最后再上业务参数与连续循环。

4. vendor=robstride

4.1 支持模式

  • ping
  • scan
  • enable
  • disable
  • mit
  • pos-vel
  • vel
  • read-param
  • write-param

4.2 RobStride 专用参数

参数类型默认值作用范围说明
--start-idu161scan扫描起始 ID(1..255)
--end-idu16255scan扫描结束 ID(1..255)
--feedback-idscsv u160xFD,0xFF,0xFE,0x00,0xAAscanRobStride host_id 候选列表,范围 0..255;不是电机 ID
--timeout-msu6480scanping 探测超时
--param-timeout-msu64120scan参数回退探测超时
--manual-velf320.2scan 回退盲探速度
--manual-msu64200scan 回退每个 ID 脉冲时长
--manual-gap-msu64200scan 回退ID 间隔
--set-motor-idu16 可选改 ID 流程设置新设备 ID,范围 1..255
--store0/11改 ID 流程保存参数
--param-idu16参数模式必填读写参数参数 ID
--param-value类型化值写参数必填write-param按所选 RobStride 型号的参数元数据解析

4.3 各模式控制参数

模式参数默认值
mit--pos --vel --kp --kd --tau0 0 8 0.2 0
pos-vel--pos --vlim [--kp]0 1.0 [无]
vel--vel0
enable / disable无额外参数n/a
说明:
  • RobStride 统一高层当前支持 MIT / POS_VEL / VEL
  • 当前支持 RobStride 型号:rs-00rs-01rs-02rs-03rs-04rs-05rs-06
  • RobStride 必须按真实电机传 --model。基础控制命令的上层形态一致,但原生功能码/参数表使用第 4 章通用运行参数;同一个功能码在不同型号上可能对应不同名称或类型。
  • 内置 RS00-RS06 参数表对齐 RobStride/Product_Information commit ba7236bc26417766fda71e75ae128c66dbd21aba
  • TORQUE/CURRENT 目前仍是参数级能力(通过 write-paramiq_ref 与限幅参数),尚未开放统一模式。
  • RobStride 的 mit 五个参数都生效:--pos--vel--kp--kd--tau
  • RobStride 的 mit 单位:pos(rad)vel(rad/s)tau(Nm)kp/kd 为 MIT 闭环增益。
  • RobStride 的 pos-vel 仅消费 --pos--vlim、可选 --kp/--loc-kp
  • RobStride 的 pos-vel 会忽略 --vel--kd--tau(CLI 在传入时会打印 warning)。

4.4 扫描行为细节

  • 第一阶段:每个 ID 做 ping + 参数查询探测。
  • 全范围无命中时:进入盲探速度脉冲模式(人工观察是否转动)。
  • 回退阶段若有状态反馈,也会计入命中。

4.5 RobStride 示例

# ping
motor_cli \
  --vendor robstride --channel can0 --model rs-06 --motor-id 20 --feedback-id 0xFD --mode ping

# 扫描
motor_cli \
  --vendor robstride --channel can0 --model rs-06 --mode scan --start-id 1 --end-id 255

# MIT 控制
motor_cli \
  --vendor robstride --channel can0 --model rs-00 --motor-id 2 --feedback-id 0xFD \
  --mode mit --ensure-mode 1 \
  --pos 0.5 --vel 0 --kp 20.0 --kd 0.5 --tau 0 \
  --loop 100 --dt-ms 20

# POS_VEL(映射到原生 Position)
motor_cli \
  --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

# 速度模式
motor_cli \
  --vendor robstride --channel can0 --model rs-06 --motor-id 20 --feedback-id 0xFD \
  --mode vel --vel 2.0 --loop 100 --dt-ms 20

# 读参数
motor_cli \
  --vendor robstride --channel can0 --model rs-06 --motor-id 20 --feedback-id 0xFD \
  --mode read-param --param-id 0x7005

# 写参数
motor_cli \
  --vendor robstride --channel can0 --model rs-06 --motor-id 20 --feedback-id 0xFD \
  --mode write-param --param-id 0x7005 --param-value 2

# 改 ID(旧 1 -> 新 11)并存参
motor_cli \
  --vendor robstride --channel can0 --model rs-06 --motor-id 1 --feedback-id 0xFD \
  --set-motor-id 11 --store 1

# Python CLI 等价改 ID
motorbridge-cli id-set \
  --vendor robstride --channel can0 --model rs-06 \
  --motor-id 1 --feedback-id 0xFD --new-motor-id 11 --store 1 --verify 1

# 设零(实验时序)
motor_cli \
  --vendor robstride --channel can0 --model rs-06 --motor-id 11 --feedback-id 0xFD \
  --mode zero --zero-exp 1 --store 1

5. vendor=all

vendor=all 当前仅支持 --mode scan

5.1 all-scan 额外参数

参数默认值说明
--damiao-model4340P传给 Damiao 扫描流程的 model hint
--robstride-modelrs-00传给 RobStride 扫描流程的 model hint
--hightorque-modelhightorque传给 HighTorque 扫描流程的 model hint
--myactuator-modelX8传给 MyActuator 扫描流程的 model hint
--start-id1同时传给各扫描流程
--end-id255传给 Damiao/RobStride;MyActuator 会自动截断到 32

5.2 示例

motor_cli \
  --vendor all --channel can0 --mode scan --start-id 1 --end-id 255

5.3 vendor=hightorque(原生 ht_can v1.5.5)

  • 当前实现走 HighTorque 原生 ht_can v1.5.5 直连 CAN 协议路径。
  • 用于 SocketCAN(can0 等)直连电机场景。
  • HighTorque 官方 Panthera SDK 的“USB 串口 -> CANboard -> 电机”链路与当前 CLI 直连 CAN 路径相互独立。
  • 支持模式:scan | read | ping | mit | pos | vel | tqe | pos-vel-tqe | volt | cur | stop | brake | rezero | conf-write | timed-read
  • 统一单位接口:
    • --posrad
    • --velrad/s
    • --tauNm
    • --kp--kd 为统一 MIT 参数签名保留,ht_can 协议本身不使用。
    • 原始调试参数:--raw-pos--raw-vel--raw-tqe

6. vendor=myactuator

6.1 支持模式

  • scan
  • enable
  • disable
  • stop
  • set-zero
  • status
  • current
  • vel
  • pos
  • version
  • mode-query

6.2 MyActuator 专用参数

参数类型默认值作用范围说明
--start-idu161scan扫描起始 ID(1..32)
--end-idu1632scan扫描结束 ID(1..32,传入大于 32 会自动截断)
--currentf320.0current电流目标值(A)
--velf320.0vel速度目标值(rad/s,内部转换为 deg/s)
--posf320.0pos绝对位置目标值(rad,内部转换为 deg)
--max-speedf328.726646pos位置模式最大速度(rad/s,内部转换)
状态输出说明:
  • angle 来自 0x9C 状态2近圈角。
  • mt_angle 来自 0x92 多圈角,绝对位置判定应优先看它。

6.3 MyActuator 示例

# 扫描 1..32
motor_cli \
  --vendor myactuator --channel can0 --mode scan --start-id 1 --end-id 32

# 连续状态读取
motor_cli \
  --vendor myactuator --channel can0 --model X8 --motor-id 1 --feedback-id 0x241 \
  --mode status --loop 40 --dt-ms 50

# 速度模式
motor_cli \
  --vendor myactuator --channel can0 --model X8 --motor-id 1 --feedback-id 0x241 \
  --mode vel --vel 0.5236 --loop 100 --dt-ms 20

# 位置模式
motor_cli \
  --vendor myactuator --channel can0 --model X8 --motor-id 1 --feedback-id 0x241 \
  --mode pos --pos 3.1416 --max-speed 5.236 --loop 1

# 将当前位置设为零点(持久生效需断电重启)
motor_cli \
  --vendor myactuator --channel can0 --model X8 --motor-id 1 --feedback-id 0x241 \
  --mode set-zero --loop 1

7. vendor=hexfellow

链路限制:
  • Hexfellow 在本仓库按“仅 CAN-FD”接入(--transport socketcanfd)。
  • 当前支持范围:scan / status / pos-vel / mit / enable / disable
  • 当前状态:链路已接入,电机验证矩阵待补。

7.1 Hexfellow 示例

# 扫描 ID
motor_cli \
  --vendor hexfellow --transport socketcanfd --channel can0 \
  --mode scan --start-id 1 --end-id 32

# 状态查询
motor_cli \
  --vendor hexfellow --transport socketcanfd --channel can0 \
  --model hexfellow --motor-id 1 --feedback-id 0 \
  --mode status

# 位置速度(pos 单位 rad,vlim 单位 rad/s)
motor_cli \
  --vendor hexfellow --transport socketcanfd --channel can0 \
  --model hexfellow --motor-id 1 --feedback-id 0 \
  --mode pos-vel --pos 3.1415926 --vlim 2.0

# MIT(pos/vel 单位 rad/rad/s)
motor_cli \
  --vendor hexfellow --transport socketcanfd --channel can0 \
  --model hexfellow --motor-id 1 --feedback-id 0 \
  --mode mit --pos 0.0 --vel 0.0 --kp 1000 --kd 100 --tau 0

8. 实用建议

  • Damiao 改 ID 建议始终使用 --store 1 --verify-id 1
  • 若扫描偶发漏检,重启 CAN 后重试。
  • RobStride 已支持 CLI 的 --mode pos-vel(映射到原生 Position);该模式下仅使用 --pos/--vlim/[--kp|--loc-kp]

已验证能力矩阵(Damiao + RobStride,2026-04)

能力DamiaoRobStride
Scan支持支持
Ping/在线探测支持(scan/寄存器路径)支持(ping
Enable/Disable支持支持
MIT (pos/vel/kp/kd/tau)支持支持
POS_VEL 统一模式支持支持(映射到原生 Position)
VEL 统一模式支持支持
参数读写支持支持
置零支持(建议先 disable)支持(实验序列;ACK 可能偶发超时)
改电机 ID支持(--set-motor-id支持(--set-motor-id
改反馈 ID支持(--set-feedback-id不支持(RobStride 通过 --feedback-id 设定 host 路径)
说明:
  • RobStride 默认 --feedback-id0xFD,内部会回退探测 0xFF/0xFE
  • RobStride 的 pos-vel--vel/--kd/--tau 为无效参数,仅告警不报错。
  • MyActuator 若 0x9A 返回错误码 0x0004(欠压),电机会在线但不转,需要先恢复供电电压。