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.

​

Damiao Python Binding 完整接口参考（bindings/python）

​

0. 完整性声明（重要）

• 本文档已按 bindings/python/src/motorbridge/core.py 中 Controller 与 Motor 的 Damiao 可用方法进行覆盖。
• 若方法属于其他厂商专用（如 robstride_*），本文不展开。
• 建议把本文作为 Damiao 路径的“完整接口基准文档”；若后续 SDK 增删接口，请同步更新本文件。

​

1. 适用范围

• 包路径：bindings/python/src/motorbridge
• 主要对象：Controller、Motor、Mode、MotorState
• 传输：
  • 标准 CAN：Controller(channel="can0")
  • Damiao 串口桥：Controller.from_dm_serial("/dev/ttyACM0", 921600)

​

2. 基础准备

cd /home/w0x7ce/Downloads/dm_candrive/rust_dm
export PYTHONPATH=bindings/python/src
export LD_LIBRARY_PATH=$PWD/target/release:${LD_LIBRARY_PATH}

​

2.1 参数中文释义总表（常用）

​

A) 连接与设备参数

​

B) 模式与循环参数

​

C) 控制目标参数

​

D) 寄存器相关参数

​

3. 数据结构与常量

​

3.1 Mode（控制模式）

• Mode.MIT = 1
• Mode.POS_VEL = 2
• Mode.VEL = 3
• Mode.FORCE_POS = 4

​

3.2 MotorState（反馈状态）

• can_id: int
• arbitration_id: int
• status_code: int
• pos: float（rad）
• vel: float（rad/s）
• torq: float（Nm）
• t_mos: float（C）
• t_rotor: float（C）

​

3.3 Damiao 常用寄存器常量

• RID_CTRL_MODE = 10
• RID_MST_ID = 7
• RID_ESC_ID = 8
• RID_TIMEOUT = 9
• RID_PMAX = 21
• RID_VMAX = 22
• RID_TMAX = 23
• RID_KP_ASR = 25
• RID_KI_ASR = 26
• RID_KP_APR = 27
• RID_KI_APR = 28

​

4. Controller 接口（Damiao 相关）

​

4.1 构造

• Controller(channel: str = "can0")
• Controller.from_dm_serial(serial_port: str = "/dev/ttyACM0", baud: int = 921600)

​

4.2 生命周期 / 总线控制

• close()
• shutdown()
• close_bus()
• __enter__() -> Controller
• __exit__(exc_type, exc, tb) -> None

​

4.3 广播控制

• enable_all()
• disable_all()
• poll_feedback_once()

​

4.4 添加电机

• add_damiao_motor(motor_id: int, feedback_id: int, model: str) -> Motor

说明：add_myactuator_motor/add_robstride_motor/add_hightorque_motor 为跨厂商入口，不属于 Damiao 专项参考范围。

​

5. Motor 接口（Damiao 相关）

​

5.1 基础动作

• enable()
• disable()
• clear_error()
• set_zero_position()
• close()

​

5.2 模式切换

• ensure_mode(mode: Mode, timeout_ms: int = 1000)

• timeout_ms 是模式切换校验超时（毫秒）
• 常用建议：
  • 标准 CAN：150~300
  • dm-serial：200~500（常用 300）

​

5.3 控制命令

• send_mit(pos: float, vel: float, kp: float, kd: float, tau: float)
• send_pos_vel(pos: float, vlim: float)
• send_vel(vel: float)
• send_force_pos(pos: float, vlim: float, ratio: float)

• pos: rad
• vel / vlim: rad/s
• tau: Nm
• ratio: 0~1

​

5.4 反馈与状态

• request_feedback()
• get_state() -> MotorState | None

​

5.5 寄存器

• get_register_u32(rid: int, timeout_ms: int = 1000) -> int
• get_register_f32(rid: int, timeout_ms: int = 1000) -> float
• write_register_u32(rid: int, value: int)
• write_register_f32(rid: int, value: float)
• store_parameters()
• set_can_timeout_ms(timeout_ms: int)

​

5.6 Damiao 全方法签名清单（对照 core.py）

​

Controller（Damiao 使用时）

• Controller(channel: str = "can0")
• Controller.from_dm_serial(serial_port: str = "/dev/ttyACM0", baud: int = 921600) -> Controller
• close() -> None
• shutdown() -> None
• close_bus() -> None
• enable_all() -> None
• disable_all() -> None
• poll_feedback_once() -> None
• add_damiao_motor(motor_id: int, feedback_id: int, model: str) -> Motor
• __enter__() -> Controller
• __exit__(exc_type, exc, tb) -> None

​

Motor（Damiao 使用时）

• close() -> None
• enable() -> None
• disable() -> None
• clear_error() -> None
• set_zero_position() -> None
• ensure_mode(mode: Mode, timeout_ms: int = 1000) -> None
• send_mit(pos: float, vel: float, kp: float, kd: float, tau: float) -> None
• send_pos_vel(pos: float, vlim: float) -> None
• send_vel(vel: float) -> None
• send_force_pos(pos: float, vlim: float, ratio: float) -> None
• request_feedback() -> None
• set_can_timeout_ms(timeout_ms: int) -> None
• store_parameters() -> None
• write_register_f32(rid: int, value: float) -> None
• write_register_u32(rid: int, value: int) -> None
• get_register_f32(rid: int, timeout_ms: int = 1000) -> float
• get_register_u32(rid: int, timeout_ms: int = 1000) -> int
• get_state() -> MotorState | None

​

5.7 方法说明（作用 / 联动调用 / 参数范围）

​

A) Controller 方法说明

​

B) Motor 方法说明

​

C) 标准联动顺序（建议）

1. Controller.from_dm_serial(...)
2. add_damiao_motor(...)
3. 维护预处理：clear_error()（可选 set_zero_position()）
4. enable_all()（或 enable()）
5. ensure_mode(...)
6. send_xxx(...) 循环
7. 需要新鲜状态时：request_feedback() + poll_feedback_once() + get_state()
8. 结束：disable()/disable_all() + shutdown()/close()

​

5.8 set_zero_position() 时序说明（dm-serial 重点）

​

A) 命令语义

• set_zero_position() 是“把当前位置设为零点参考”，不是“让电机转回 0”。
• 底层发送的是 Damiao 置零命令帧（data FF FF FF FF FF FF FF FE）。

​

B) 是否必须等待

• 协议层面：不是硬性必须等待。
• 当前项目实现：set_zero_position() 内部固定执行 20ms 稳定等待（核心层），调用方无需再传入等待参数。
• Python 绑定 set_zero_position() 签名为 set_zero_position() -> None，不提供 ms 入参。

​

B.1) 项目约束（重点）

• 在本项目 dm-serial 实操规范中，set_zero_position() 前 必须先 disable。
• 建议按“强约束流程”执行：disable -> set_zero_position(核心内置20ms) -> enable -> ensure_mode -> control。
• 原因：可显著降低 set_zero 后寄存器读超时（如 RID 10）导致的后续控制失败风险。

​

C) 推荐顺序（校准后要继续控制时）

1. disable（或 disable_all）
2. set_zero_position
3. enable（或 enable_all）
4. ensure_mode
5. send_xxx 控制

​

D) 触发异常后的软件恢复（不重启优先）

• 建议顺序：disable -> clear_error -> enable -> 重试 ensure_mode
• 如果仍失败，先 scan 确认当前在线 ID（避免把 0x07/0x17 当成 0x04/0x14）。
• 若反馈帧有但寄存器读持续失败，再考虑设备侧重新上电。

​

6. 常用读写模式（推荐）

​

6.1 查询“当前模式 + 实时状态”

from motorbridge import Controller, RID_CTRL_MODE

with Controller.from_dm_serial("/dev/ttyACM0", 921600) as ctrl:
    m = ctrl.add_damiao_motor(0x07, 0x17, "4310")
    m.request_feedback()
    ctrl.poll_feedback_once()
    st = m.get_state()
    mode = m.get_register_u32(RID_CTRL_MODE, 300)  # 1/2/3/4
    print("mode=", mode, "state=", st)
    m.close()

​

6.2 推荐控制流程

1. enable_all()
2. ensure_mode(...)
3. send_xxx(...)
4. request_feedback() + poll_feedback_once() + get_state()
5. 结束时 disable() 或 disable_all()

​

7. Python CLI（python -m motorbridge.cli）Damiao 子集

​

7.1 扫描

python3 -m motorbridge.cli scan \
  --vendor damiao --transport dm-serial --serial-port /dev/ttyACM0 --serial-baud 921600 \
  --model 4310 --start-id 0x01 --end-id 0x10

​

7.2 控制

python3 -m motorbridge.cli run \
  --vendor damiao --transport dm-serial --serial-port /dev/ttyACM0 --serial-baud 921600 \
  --model 4310 --motor-id 0x07 --feedback-id 0x17 \
  --mode mit --ensure-mode 1 --ensure-timeout-ms 300 \
  --pos 0 --vel 0 --kp 8 --kd 0.2 --tau 0 --loop 40 --dt-ms 20

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

​

7.3 ID/寄存器辅助命令

• id-dump（读取 ID/模式/关键寄存器）
• id-set（写入 ESC_ID / MST_ID，可选 store+verify）

​

8. dm-serial 实战建议

• dm-serial 仅用于 --vendor damiao
• 先扫描再控制，ID 必须匹配
• 切模式建议 ensure_mode=1
• 高频下更易抖动，建议从 dt-ms=20 起步
• 若模式切换异常，先 disable -> clear_error -> enable -> ensure_mode 再继续

​

9. 现成示例脚本（Damiao）

• bindings/python/examples/damiao_dm_serial_demo.py
• bindings/python/examples/dm_serial_mode_switch_200_demo.py
• bindings/python/examples/dm_serial_status_like_cli_demo.py
• bindings/python/examples/scan_ids_demo.py（标准 CAN 路径）