Python 示例总览 - MotorBridge Python SDK

通道兼容说明（PCAN + slcan + CAN-FD + Damiao 串口桥）

Linux SocketCAN 直接使用接口名：can0、can1、slcan0。
USB-串口类 CAN 适配器需先创建并拉起 slcan0：sudo slcand -o -c -s8 /dev/ttyUSB0 slcan0 && sudo ip link set slcan0 up。
Hexfellow 示例必须使用 CAN-FD 链路（Controller.from_socketcanfd(...) / CLI --transport socketcanfd）。
Damiao 可选串口桥链路（CLI）：--transport dm-serial --serial-port /dev/ttyACM0 --serial-baud 921600。
Damiao 串口桥完整命令模板见 motor_cli/README.md（中文见 motor_cli/README.zh-CN.md 第 3.6 节）。
Linux SocketCAN 下 --channel 不要附加 @bitrate（例如 can0@1000000 无效）。
Windows（PCAN 后端）里，can0/can1 映射到 PCAN_USBBUS1/2，支持可选 @bitrate 后缀。

基于 Python SDK 的示例集合。

English version: README.md

新手优先（最简单的 2 个示例）

如果你是通过 pip 安装后想快速上手，建议先看：

../get_started/README.zh-CN.md（中文）
../get_started/README.md（英文）

如果你是第一次上手，建议先看并先跑这两个文件：

simple_01_motor_control.py：单电机最小模板（默认 Damiao，其他厂商以注释模板给出）。
simple_02_quad_motor_control.py：四电机最小多厂商往复示例（2 Damiao + 1 MyActuator + 1 RobStride）。

推荐顺序：

先跑 simple_01_motor_control.py，验证 CAN 通道和单电机正常。
再跑 simple_02_quad_motor_control.py，验证多控制器/多厂商并行控制。

快速运行命令：

# 1) 单电机（最稳妥起步）
PYTHONPATH=bindings/python/src LD_LIBRARY_PATH=$PWD/target/release:${LD_LIBRARY_PATH} \
python3 bindings/python/examples/simple_01_motor_control.py \
  --channel can0 --loop 120 --dt-ms 20 --pos 1.0 --vlim 1.0

# 2) 四电机往复
PYTHONPATH=bindings/python/src LD_LIBRARY_PATH=$PWD/target/release:${LD_LIBRARY_PATH} \
python3 bindings/python/examples/simple_02_quad_motor_control.py \
  --channel can0 --pos 1.0 --loop 240 --dt-ms 20 --swing-loop 60

参数速查（以上两个最简单脚本）

simple_01_motor_control.py

--channel：CAN 接口名，如 can0、can1、slcan0。
--loop：控制循环次数。
--dt-ms：控制周期（毫秒）。建议先用 20；总线繁忙可调到 30/50。
--pos：目标角度（弧度）。
--vlim：POS_VEL 模式速度上限。

simple_02_quad_motor_control.py

--channel：CAN 接口名。
--loop：总循环次数。
--dt-ms：控制周期（毫秒），同上建议。
--pos：往复幅值（弧度），按 +pos/-pos 切换。
--swing-loop：每 N 次循环切换一次方向。
--rs-dir-sign：-1 表示 RobStride 方向与其余电机相反；+1 表示同向。
--dm-vlim：Damiao 的 POS_VEL 速度上限。
--my-vlim：MyActuator 的 POS_VEL 速度上限。
--rs-kp / --rs-kd：RobStride 的 MIT 参数。

下一步看什么文档（推荐顺序）

../README.zh-CN.md 或 ../README.md 看 Python binding 的安装与 API 总览。
/zh/source/rust-cli/overview 或 /source/rust-cli/overview 用于扫描设备、确认 ID、查 CLI 参数。
/zh/source/examples/overview 或 /source/examples/overview 查看更广泛的示例目录（web/WS/其他集成）。

新手必看关键点

一个 Controller 实例不能混用多厂商电机；多厂商请分多个 controller。
os error 105 常见原因是发包过快，或有其它程序同时往 CAN 发包。
大多数控制链路需要周期发送，单次发送通常不足以稳定保持。
先扫描并确认 motor-id/feedback-id，再运行示例。

WS 示例快速指南（`quad_vendor_binding_ws_demo.py`）

这是一个基于 Python binding 的四电机 WS 桥接后端（dm1/dm2/my/rs）+ 配套网页前端。后端启动：

cd /path/to/rust_dm
python3 -m venv .venv-ws
source .venv-ws/bin/activate
pip install websockets
export PYTHONPATH=$PWD/bindings/python/src
export LD_LIBRARY_PATH=$PWD/target/release:${LD_LIBRARY_PATH}
python3 bindings/python/examples/quad_vendor_binding_ws_demo.py \
  --bind 127.0.0.1 --port 9010 --channel can0 --dt-ms 20

前端启动（新终端）：

cd /path/to/rust_dm/bindings/python/examples
python3 -m http.server 8080

浏览器打开：

http://127.0.0.1:8080/quad_vendor_binding_ws_demo.html
WS 地址填：ws://127.0.0.1:9010

如果你的电机 ID 不同，启动后端时可覆盖：

python3 bindings/python/examples/quad_vendor_binding_ws_demo.py \
  --channel can0 \
  --dm1-id 0x01 --dm1-fid 0x11 --dm1-model 4340P \
  --dm2-id 0x07 --dm2-fid 0x17 --dm2-model 4310 \
  --my-id 1 --my-fid 0x241 --my-model X8 \
  --rs-id 127 --rs-fid 0xFE --rs-model rs-06

文件列表

simple_01_motor_control.py：最简单单电机模板（默认 Damiao，含注释化厂商切换模板）
simple_02_quad_motor_control.py：最简单四电机多厂商示例（固定周期 + 往复目标）
python_wrapper_demo.py：最小 Damiao MIT 循环
damiao_maintenance_demo.py：Damiao 维护流程（clear_error / set_zero_position / set_can_timeout_ms / request_feedback）
damiao_register_rw_demo.py：Damiao 寄存器读写（f32 + u32 + 可选 store_parameters）
damiao_dm_serial_demo.py：Damiao 串口桥传输示例（Controller.from_dm_serial）
dm_serial_01_calibration_demo.py：SOP-01 串口桥维护/校准流程
dm_serial_02_control_modes_demo.py：SOP-02 串口桥常规控制（4 模式，不做校准/配置写入）
dm_serial_03_status_demo.py：SOP-03 串口桥状态监视
dm_serial_04_enable_setzero_no_delay_demo.py：SOP-04 串口桥复现（set_zero 后立刻控制）
dm_serial_05_setzero_timing_ab_test.py：SOP-05 串口桥置零等待 A/B 测试
dm_serial_06_recover_no_reboot_demo.py：SOP-06 串口桥软件恢复（不重启主机）
dm_serial_07_enable_setzero_enable_rotate_demo.py：SOP-07 串口桥稳健顺序（disable -> set_zero -> enable -> control）
dm_serial_08_negative_enable_setzero_guard_demo.py：SOP-08 串口桥负向测试（enable 态 set_zero 应被核心拒绝）
dm_serial_leader_monitor_demo.py：Damiao 串口桥 leader 监视（enable-all + 指定 ID 全状态流）
robstride_wrapper_demo.py：RobStride ping / 读参 / mit / vel 示例
quad_vendor_pos_binding_demo.py：Python binding 四电机同步位置示例（不经过 ws_gateway）
quad_vendor_binding_ws_demo.py：Python binding WS 桥后端（用于网页控制）
quad_vendor_binding_ws_demo.html：quad_vendor_binding_ws_demo.py 的网页 UI
hexfellow_canfd_demo.py：Hexfellow CAN-FD 示例（仅 mit / pos-vel）
full_modes_demo.py：Damiao 全模式示例
pid_register_tune_demo.py：Damiao 参数调优示例
scan_ids_demo.py：Damiao 快速扫描（历史辅助脚本）
pos_ctrl_demo.py：Damiao 一次性位置指令
multi_motor_ctrl_demo.py：Damiao 多电机控制（-id / -pos 一一映射）
mit_pos_switch_demo.py：两阶段模式切换示例（MIT 后切 POS_VEL）
pos_repl_demo.py：Damiao 交互式位置控制

快速运行（按厂商/场景）

Damiao：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/python_wrapper_demo.py \
  --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --pos 0 --vel 0 --kp 20 --kd 1 --tau 0 --loop 20 --dt-ms 20

Damiao maintenance：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/damiao_maintenance_demo.py \
  --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --can-timeout-ms 1000 --set-zero 0

Damiao register rw：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/damiao_register_rw_demo.py \
  --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --read-f32-rid 21 --read-u32-rid 10 --store 0

Damiao dm-serial：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/damiao_dm_serial_demo.py \
  --serial-port /dev/ttyACM0 --serial-baud 921600 --model 4310 \
  --motor-id 0x01 --feedback-id 0x11 --mode mit --loop 40 --dt-ms 20

SOP-01 dm-serial calibration：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/dm_serial_01_calibration_demo.py \
  --serial-port /dev/ttyACM0 --serial-baud 921600 --model 4310 \
  --motor-id 0x04 --feedback-id 0x14 --set-zero 0 --can-timeout-ms 1000

SOP-02 dm-serial normal control（no calibration/config writes）：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/dm_serial_02_control_modes_demo.py \
  --serial-port /dev/ttyACM0 --serial-baud 921600 --model 4310 \
  --motor-id 0x04 --feedback-id 0x14 --mode pos-vel --pos 0.8 --vlim 1.0 --loop 100 --dt-ms 20

SOP-03 dm-serial status monitor：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/dm_serial_03_status_demo.py \
  --serial-port /dev/ttyACM0 --serial-baud 921600 --model 4310 \
  --motor-id 0x04 --feedback-id 0x14 --loop 100 --dt-ms 50

SOP-05 dm-serial set-zero settle-time A/B test：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/dm_serial_05_setzero_timing_ab_test.py \
  --serial-port /dev/ttyACM0 --serial-baud 921600 --model 4310 \
  --motor-id 0x04 --feedback-id 0x14 --settle-list-ms 0,50,100,200 --rounds 10 --ensure-timeout-ms 500

SOP-06 dm-serial software recovery without reboot：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/dm_serial_06_recover_no_reboot_demo.py \
  --serial-port /dev/ttyACM0 --serial-baud 921600 --model 4310 \
  --motor-id 0x04 --feedback-id 0x14 --attempts 6 --timeout-ms 800

SOP-07 dm-serial robust set-zero + control sequence：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/dm_serial_07_enable_setzero_enable_rotate_demo.py \
  --serial-port /dev/ttyACM0 --serial-baud 921600 --model 4310 \
  --motor-id 0x04 --feedback-id 0x14 --target-pos 3.0 --vlim 1.0 \
  --loop 50 --dt-ms 20 --ensure-timeout-ms 800 \
  --post-setzero-ms 0

SOP-08 dm-serial negative test（enable then set_zero，expect guard reject）：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/dm_serial_08_negative_enable_setzero_guard_demo.py \
  --serial-port /dev/ttyACM0 --serial-baud 921600 --model 4310 \
  --motor-id 0x04 --feedback-id 0x14 --ensure-timeout-ms 800

dm-serial 时序说明（置零序列）

现象：执行 set_zero_position() 后紧接着 ensure_mode(...)，可能触发 register 10 not received 超时。
根因模式：通常是 dm-serial 的时序窗口（桥接延迟 + 电机内部状态切换），不是普通控制模式逻辑错误。
核心守卫规则：set_zero_position() 仅在 disable() 之后允许。
核心稳定等待规则：set_zero_position() 后核心层固定等待 20 ms（Python 不暴露该参数）。
推荐稳健序列：
1. disable（或 disable_all）
2. set_zero_position
3. enable（或 enable_all）
4. ensure_mode
5. 进入控制循环
一旦触发超时，先尝试软件恢复（disable -> clear_error -> enable -> retry），再考虑重启主机/设备。

Damiao dm-serial leader monitor（指定 ID 全状态流）：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/dm_serial_leader_monitor_demo.py \
  --serial-port /dev/ttyACM0 --serial-baud 921600 --model 4310 \
  -id 0x04 0x07 --loop 10000 --dt-ms 20 --hold-mode mit-zero

RobStride：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/robstride_wrapper_demo.py \
  --channel can0 --model rs-06 --motor-id 127 --mode ping

RobStride 读参数：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/robstride_wrapper_demo.py \
  --channel can0 --model rs-06 --motor-id 127 --mode read-param --param-id 0x7019

Hexfellow（仅 CAN-FD）：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/hexfellow_canfd_demo.py \
  --channel can0 --motor-id 0x01 --feedback-id 0x00 --mode mit --loop 20 --dt-ms 50

CLI 统一扫描所有厂商：

PYTHONPATH=bindings/python/src python3 -m motorbridge.cli scan \
  --vendor all --channel can0 --start-id 0x01 --end-id 0xFF

多电机 pos-vel（示例：电机 4 和 7，位置按顺序映射）：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/multi_motor_ctrl_demo.py \
  --channel can0 --model 4310 --mode pos-vel \
  -id 4 7 -pos 0.8 -0.6 -vlim 1.2 1.2 --loop 200 --dt-ms 20

MIT/POS_VEL 切换示例（仅 POS_VEL 运行，电机 4 和 7，目标 -3）：

PYTHONPATH=bindings/python/src python3 bindings/python/examples/mit_pos_switch_demo.py \
  --channel can0 --model 4310 -id 4 7 \
  --trajectory -3 \
  --mit-hold-loops 0 --pos-hold-loops 50 \
  --dt-ms 20 --print-state 1

Damiao 覆盖说明

Damiao 示例已经覆盖高层 SDK 的完整常用面：

控制模式：mit / pos-vel / vel / force-pos
传输路径：Controller(channel) + Controller.from_dm_serial(...)
维护接口：clear_error、set_zero_position、set_can_timeout_ms、request_feedback
寄存器接口：get/write f32、get/write u32、store_parameters
扫描与调参流程

变更范围说明

当前 v0.4.1 示例已对齐 ABI 加锁、Python 关闭后调用守卫、CoreController 自动清理行为和 Damiao gateway 状态同步修复。
浏览器控制推荐使用随包提供的 ws_gateway；脚本化联调可直接使用 Python binding 示例。

​通道兼容说明（PCAN + slcan + CAN-FD + Damiao 串口桥）

​新手优先（最简单的 2 个示例）

​参数速查（以上两个最简单脚本）

​下一步看什么文档（推荐顺序）

​新手必看关键点

​WS 示例快速指南（quad_vendor_binding_ws_demo.py）

​文件列表

​快速运行（按厂商/场景）

​dm-serial 时序说明（置零序列）

​Damiao 覆盖说明

​变更范围说明