RobStride 三通道对照手册（Core CLI / Python CLI / Python SDK）

本文只聚焦 RobStride，并按“同一功能、三种入口”组织：

Core CLI：motor_cli（Rust，基准实现）
Python CLI：motorbridge-cli 或 python -m motorbridge.cli
Python SDK：from motorbridge import Controller, Mode

目标：把相同语义合并写，只把差异点单独标注，便于快速查证。

通道说明（仅 SocketCAN）

本文只讨论 SocketCAN（can0、can1）。
Linux 下 --channel 不要写 @bitrate（例如 can0@1000000 无效）。
排障参考：../../docs/zh/can_debugging.md。

0）前置

0.1 环境

cd motorbridge
cargo build -p motor_cli --release
CLI=./target/release/motor_cli
export LD_LIBRARY_PATH=$PWD/target/release:${LD_LIBRARY_PATH}

0.2 通用参数（示例）

CH=can0
MODEL=rs-06
MID=127
FID=0xFD

MODEL must be the physical RobStride model. Supported values are rs-00 through rs-06; parameter read/write selects the function-code table from this value, so do not use rs-00 as a generic default for every RS motor.

0.3 默认值与原厂协议关系（总览）

统一默认反馈 ID：0xFD（运行时可回退尝试 0xFF/0xFE）。
统一模式与原厂语义映射：
- mit -> 原厂 MIT/阻抗控制帧（pos/vel/kp/kd/tau 全有效）。
- pos-vel -> 原厂位置流程：run_mode=1，loc_ref(0x7016)，limit_spd(0x7017)。
- vel -> 原厂速度流程：run_mode=2，spd_ref(0x700A)。
- zero/set-zero -> 原厂置零命令序列（需 --zero-exp 1 才真正下发）。
常用原厂参数：
- 0x7005 run_mode
- 0x7016 loc_ref
- 0x7017 limit_spd
- 0x700A spd_ref
- 0x7019 mechPos
- 0x701B mechVel

0.4 入口差异（你关心的“不同点”）

控制语义本身：Core CLI / Python CLI / Python SDK 一致。
型号语义：Core CLI / Python CLI / Python SDK 都需要传真实 rs-00 到 rs-06 型号，尤其是参数读写场景。
主要差异只在入口：
- CLI：命令行参数入口（--mode ...）。
- SDK：先 Controller(\"can0\")，再 add_robstride_motor(motor_id, feedback_id, model)。
例外覆盖面：
Python CLI 已支持 RobStride id-set，但只修改 device_id；
feedback_id / host_id 是上位机侧 ID，不是电机 ID。
ID 范围会显式校验：device_id/motor_id/new_motor_id 为 1..255，feedback_id/host_id 为 0..255，避免底层 u8/ctypes 静默截断。

1）扫描（scan）

共同语义：

在 ID 范围内探测在线设备。

参数有效性：

有效：start-id/end-id/feedback-ids/param-timeout-ms。

默认值：

默认完整回退列表：feedback-ids=0xFD,0xFF,0xFE,0x00,0xAA。
扫描输出中的 probe / device_id 是电机 ID；feedback_id / host_id 不是电机 ID。

原厂协议对应：

先走 ping 探测；必要时走参数读取探测。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --mode scan --start-id 120 --end-id 130

Python CLI

motorbridge-cli scan \
  --vendor robstride --channel "$CH" --model "$MODEL" \
  --start-id 120 --end-id 130 --feedback-ids 0xFD --param-timeout-ms 60

Python SDK

from motorbridge import Controller

found = []
with Controller("can0") as ctrl:
    for mid in range(120, 131):
        try:
            m = ctrl.add_robstride_motor(mid, 0xFD, "rs-06")
            try:
                print(mid, m.robstride_ping())
                found.append(mid)
            finally:
                m.close()
        except Exception:
            pass
print("found:", found)

2）连通性（ping）

共同语义：

验证某个 motor_id + feedback_id 是否可通信。

参数有效性：

有效：motor-id/feedback-id。

默认值：

feedback-id 建议 0xFD。

原厂协议对应：

原厂 ping 帧。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" --mode ping

Python CLI

motorbridge-cli run \
  --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode ping

Python SDK

from motorbridge import Controller

with Controller("can0") as ctrl:
    m = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    print(m.robstride_ping())
    m.close()

3）使能（enable）/ 4）失能（disable）

共同语义：

开启或关闭驱动输出。

参数有效性：

有效：mode=enable|disable。

默认值：

Python CLI 推荐 loop=1。

原厂协议对应：

原厂使能/失能控制命令。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" --mode enable
$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" --mode disable

Python CLI

motorbridge-cli run --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" --mode enable --loop 1 --dt-ms 20
motorbridge-cli run --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" --mode disable --loop 1 --dt-ms 20

Python SDK

from motorbridge import Controller

with Controller("can0") as ctrl:
    m = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    m.enable()
    m.disable()
    m.close()

5）MIT（统一阻抗）

共同语义：

五参数闭环控制：pos/vel/kp/kd/tau。

参数有效性：

有效：pos、vel、kp、kd、tau、loop、dt-ms。
无效：无。

默认值：

经验建议：kp=3 比 kp=0.5 更容易看见位置收敛效果。

原厂协议对应：

直接映射到 RobStride 原厂 MIT 控制帧。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode mit --ensure-strict 1 --pos 0.5 --vel 0 --kp 20.0 --kd 0.5 --tau 0 --loop 100 --dt-ms 20

Python CLI

motorbridge-cli run \
  --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode mit --ensure-strict 1 --pos 0.5 --vel 0 --kp 20.0 --kd 0.5 --tau 0 --loop 100 --dt-ms 20

Python SDK

from motorbridge import Controller, Mode

with Controller("can0") as ctrl:
    m = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    m.enable()
    m.ensure_mode(Mode.MIT, 1000)
    for _ in range(40):
        m.send_mit(0.5, 0.0, 20.0, 0.5, 0.0)
    m.close()

6）POS_VEL（统一位置速度）

共同语义：

发“目标位置 + 限速”命令。

参数有效性：

有效：pos、vlim（可选 kp/loc_kp）。
无效：vel、kd、tau（会被忽略）。

默认值：

建议先 loop=1 做到位命令，再观察反馈。

原厂协议对应：

run_mode=1，loc_ref(0x7016)，limit_spd(0x7017)。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode pos-vel --pos 1.5 --vlim 1.0 --loc-kp 5.0 --loop 1 --dt-ms 20

Python CLI

motorbridge-cli run \
  --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode pos-vel --pos 1.5 --vlim 1.0 --loc-kp 5.0 \
  --ensure-strict 1 --ensure-timeout-ms 1500 \
  --loop 1 --dt-ms 20

Python SDK

from motorbridge import Controller, Mode

with Controller("can0") as ctrl:
    m = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    m.enable()
    m.ensure_mode(Mode.POS_VEL, 1500)
    m.send_pos_vel(1.0, 0.8)
    m.close()

7）VEL（统一速度）

共同语义：

速度命令闭环。

参数有效性：

有效：vel、loop、dt-ms。
无效：pos、kp、kd、tau。

默认值：

示例：vel=0.3。

原厂协议对应：

run_mode=2，spd_ref(0x700A)。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode vel --vel 0.3 --loop 40 --dt-ms 50

Python CLI

motorbridge-cli run \
  --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode vel --vel 0.3 --loop 40 --dt-ms 50

Python SDK

from motorbridge import Controller, Mode

with Controller("can0") as ctrl:
    m = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    m.enable()
    m.ensure_mode(Mode.VEL, 1000)
    for _ in range(40):
        m.send_vel(0.3)
    m.close()

8）读参数（read-param）

共同语义：

读取原厂参数寄存器。

参数有效性：

有效：param-id、type、timeout-ms。

默认值：

位置常读：0x7019 (mechPos)，类型 f32。

原厂协议对应：

原厂 29-bit 扩展帧参数读取通道。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode read-param --param-id 0x7019

Python CLI

motorbridge-cli run \
  --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode read-param --param-id 0x7019 --param-type f32 --timeout-ms 200

motorbridge-cli robstride-read-param \
  --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --param-id 0x7019 --type f32 --timeout-ms 200

Python SDK

from motorbridge import Controller

with Controller("can0") as ctrl:
    m = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    print(m.robstride_get_param_f32(0x7019, 200))
    m.close()

9）写参数（write-param）

共同语义：

写入原厂参数，可回读验证。

参数有效性：

有效：param-id、value、type、verify。

默认值：

示例：0x700A 写 f32=0.3。

原厂协议对应：

原厂 29-bit 扩展帧参数写入通道。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode write-param --param-id 0x700A --param-value 0.3 --store 1

Python CLI

motorbridge-cli run \
  --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode write-param --param-id 0x700A --param-type f32 --param-value 0.3 --timeout-ms 200 --store 1

motorbridge-cli robstride-write-param \
  --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --param-id 0x700A --type f32 --value 0.3 --verify 1 --timeout-ms 200 --store 1

Python SDK

from motorbridge import Controller

with Controller("can0") as ctrl:
    m = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    m.robstride_write_param_f32(0x700A, 0.3)
    print(m.robstride_get_param_f32(0x700A, 200))
    m.close()

10）改 ID（set-motor-id）

共同语义：

修改设备 ID，并建议持久化。

参数有效性：

Core CLI：--set-motor-id、--store。
Python CLI：id-set --vendor robstride --new-motor-id ... --store ... --verify ...。
Python SDK：robstride_set_device_id() + store_parameters()。

默认值：

示例改到 126。

原厂协议对应：

原厂 set-id 命令流程。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --set-motor-id 126 --store 1

Python CLI

motorbridge-cli id-set \
  --vendor robstride --channel "$CH" --model "$MODEL" \
  --motor-id "$MID" --feedback-id "$FID" \
  --new-motor-id 126 --store 1 --verify 1

Python SDK

from motorbridge import Controller

with Controller("can0") as ctrl:
    m = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    m.robstride_set_device_id(126)
    m.store_parameters()
    m.close()

11）写零点（zero / set-zero）

共同语义：

设置当前机械位置为零点；可选择持久化。

参数有效性：

有效：mode=zero|set-zero、zero-exp、store。
关键：--zero-exp 1 必须开启，否则不发送实验序列。
当前 RobStride 置零流程会内部写 zero_sta(0x7029)=1。

默认值：

store=1（建议）。

原厂协议对应：

disable -> set_zero_position -> write zero_sta(0x7029)=1 -> (optional) store_parameters。

Core CLI

$CLI --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode zero --zero-exp 1 --store 1

Python CLI

motorbridge-cli run \
  --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode zero --zero-exp 1 --store 1

motorbridge-cli run \
  --vendor robstride --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --mode set-zero --zero-exp 1 --store 1

Python SDK

from motorbridge import Controller

with Controller("can0") as ctrl:
    m = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    m.disable()
    m.robstride_set_zero_position(zero_range="neg-pi-pi", store=True)
    m.close()

验证建议：

motorbridge-cli robstride-read-param \
  --channel "$CH" --model "$MODEL" --motor-id "$MID" --feedback-id "$FID" \
  --param-id 0x7019 --type f32 --timeout-ms 200

12）最终口径（给查证者）

三通道在 RobStride 上的控制语义已对齐；主要差异在“入口形式”和少量命令覆盖面。
Python CLI 已支持 RobStride scan / ping(run) / read-param / write-param / save / id-set。
read-param / write-param 既可使用专用子命令，也可使用 Rust CLI 风格的 motorbridge-cli run --mode read-param/write-param。
参数“有效/无效”请以本手册各节为准，尤其：
- mit：pos/vel/kp/kd/tau 全有效。
- pos-vel：仅 pos/vlim 主有效；vel/kd/tau 无效。
- vel：仅 vel 主有效。
若要做最严格复现实验，优先以 Core CLI 作为基准，再对照 Python CLI/SDK。

​通道说明（仅 SocketCAN）

​0）前置

​0.1 环境

​0.2 通用参数（示例）

​0.3 默认值与原厂协议关系（总览）

​0.4 入口差异（你关心的“不同点”）

​1）扫描（scan）

​Core CLI

​Python CLI

​Python SDK

​2）连通性（ping）

​Core CLI

​Python CLI

​Python SDK

​3）使能（enable）/ 4）失能（disable）

​Core CLI

​Python CLI

​Python SDK

​5）MIT（统一阻抗）

​Core CLI

​Python CLI

​Python SDK

​6）POS_VEL（统一位置速度）

​Core CLI

​Python CLI

​Python SDK

​7）VEL（统一速度）

​Core CLI

​Python CLI

​Python SDK

​8）读参数（read-param）

​Core CLI

​Python CLI

​Python SDK

​9）写参数（write-param）

​Core CLI

​Python CLI

​Python SDK

​10）改 ID（set-motor-id）

​Core CLI

​Python CLI

​Python SDK

​11）写零点（zero / set-zero）

​Core CLI

​Python CLI

​Python SDK

​12）最终口径（给查证者）

通道说明（仅 SocketCAN）

0）前置

0.1 环境

0.2 通用参数（示例）

0.3 默认值与原厂协议关系（总览）

0.4 入口差异（你关心的“不同点”）

1）扫描（scan）

Core CLI

Python CLI

Python SDK

2）连通性（ping）

Core CLI

Python CLI

Python SDK

3）使能（enable）/ 4）失能（disable）

Core CLI

Python CLI

Python SDK

5）MIT（统一阻抗）

Core CLI

Python CLI

Python SDK

6）POS_VEL（统一位置速度）

Core CLI

Python CLI

Python SDK

7）VEL（统一速度）

Core CLI

Python CLI

Python SDK

8）读参数（read-param）

Core CLI

Python CLI

Python SDK

9）写参数（write-param）

Core CLI

Python CLI

Python SDK

10）改 ID（set-motor-id）

Core CLI

Python CLI

Python SDK

11）写零点（zero / set-zero）

Core CLI

Python CLI

Python SDK

12）最终口径（给查证者）