Microduck自定义动作开发：继承Move类，三步为双足机器人添加新技能

Microduck 是一个基于树莓派与 Dynamixel 舵机的紧凑型双足机器人项目，内置强化学习行走策略。本教程讲解 Microduck 自定义动作开发方法：通过继承Move基类，三步即可为双足机器人添加点头、深蹲等全新动作技能，并用键盘按键或手柄按钮一键触发。

一、先看懂 Move 基类：所有动作背后的状态机

在 microduck/src/moves/move.py 中，Move是所有运动行为的抽象基类。每个动作的生命周期由四态状态机MoveState驱动：

调度器 microduck/src/scheduler.py 以 50 Hz 的频率运行主循环，每 tick 会：

1. 由Observer读取 IMU 姿态与全部舵机的位置/速度，打包成Observation；
2. 遍历所有已注册动作，根据状态分发调用on_start/step/on_stop；
3. 把动作写入MotorCommand的目标角度批量下发到舵机，并执行过流保护（总电流连续超阈值即自动断电，阈值见 microduck/src/constants.py 中的OVERCURRENT_CUTOFF_A）。

也就是说，你的动作类只需要回答一个问题："这一 tick，各关节应该转到哪个角度？"把它写进command.target_angles即可。

二、第一步：写一个继承 Move 的动作类

在microduck/src/moves/目录下新建文件即可。以"点头"动作为例，核心结构如下（完整实现可参考头颈旋转动作 microduck/src/moves/rotate_head.py）：

from moves.move import Move, MotorCommand, MoveState class NodMove(Move): def on_start(self, obs, command): # 用 lerp 在 0.5 秒内把头部平滑过渡到起始角，然后进入 ACTIVE ... def step(self, obs, command): # 每个 tick 生成正弦点头目标角（弧度） command.target_angles["head_pitch"] = 0.3 * math.sin(2 * math.pi * 0.3 * t) def on_stop(self, obs, command): # 平滑回到 NEUTRAL_POSE，完成后置 state = MoveState.INACTIVE ...

三个要点：

• 单位是弧度：target_angles以关节名为键（键名与 microduck/src/constants.py 中MOTOR_TO_ID一致），值为目标角度；中立站姿定义在NEUTRAL_POSE中，MotorCommand初始化时会自动填充它，未覆盖的关节保持不动；
• 平滑过渡：on_start/on_stop中做 lerp（线性插值）过渡，是现有动作（点头、深蹲）的共同套路，避免关节跳变；
• 善用观测数据：obs.robot_state里提供陀螺仪、投影重力向量、各关节位置与速度，做需要平衡补偿的动作时直接读取即可。

三、第二步：把动作注册进 Scheduler

Scheduler构造时接收一个moves字典，动作名就是之后触发它的"标签"。默认注册如下（见 microduck/src/scheduler.py）：

registered_moves = { "head": RotateHeadMove(), "squat": SquatMove(), "walk": WalkMove(), }

在入口 microduck/src/main.py 中，把新动作加入Scheduler的moves参数即可。若动作需要加载较重资源（如行走策略加载 ONNX 模型），可覆写preload()方法——main.py会在启动控制循环前统一调用所有动作的preload()。

四、第三步：绑定按键，用键盘或手柄触发

输入源（键盘 microduck/src/input/keyboard_input.py 或手柄 microduck/src/input/gamepad_input.py）通过一张"键 → 动作名"映射表来开关动作。在main.py中：

MOVE_KEYS = {"v": "walk"} # 键盘：按 v 切换行走 GAMEPAD_BUTTON_MOVES = {"A": "walk"} # 手柄：按 A 切换行走

只需追加一行映射，例如{"n": "nod"}，运行后终端会打印按键帮助。触发逻辑非常简单——同一按键再按一次即停止，调度器会自动让动作走STOPPING流程回到中立姿势。除触发动作外，还可用方向键调节行走速度、i切换 IMU 显示、q紧急停止。

五、实用技巧与避坑指南

• 先仿真验证：项目提供 MuJoCo 仿真入口（microduck/Makefile 中的sim目标，对应 microduck/src/sim/sim_main.py），新动作先在仿真里看效果，再上实机，避免不必要的摔倒风险；
• 过渡时间要够长：lerp_duration过短会造成关节冲击；深蹲动作 microduck/src/moves/squat.py 用了 1 秒过渡，可供参考；
• 别忘记安全网：调度器内置过流保护，若动作让总电流持续超限会自动切断全部舵机扭矩——动作设计应尽量小步幅、低速试错；
• 调试工具：microduck/src/debug/下提供了各动作的日志绘图脚本（如 plot_squat_log.py），配合各动作文件顶部的LOGGING = False开关，可导出关节角度曲线分析动作质量。

六、相关文件速查

按照"写类 → 注册 → 绑键"三步，一个完全属于你的 Microduck 自定义动作就开发完成了。