Hands On Series

手把手系列总览

这个系列不是字段手册，而是一组循序渐进的代码课。所有章节围绕同一个具体例子展开：

SinWaveState

它一开始只是一个让手臂按 sin() 摆动的简单状态。后面会逐步加上：

• YAML 参数。
• 键盘和手柄绑定。
• remote_events。
• 自动返回。
• action 暂停。
• 第一帧。
• 自定义过渡行为。
• 自定义遥控器 driver。
• 复杂组合键。
• 发布保护。

最终目标不是只会写一个 sin()，而是学会这套框架的完整扩展方式。

学习路径

第 1 课：从零写一个自定义状态

页面：手把手 1：从零写一个自定义状态

你会写代码：

• 新建 states/ 子包。
• 写 SinWaveState。
• 在 robot_states.py 导入。
• 在 setup.py 注册子包。
• 先不接遥控器，直接把 initial_state 临时改成 sin_wave 验证状态代码。
• 加 params。
• 加 get_first_frame()。
• 加 action。
• 加安全退出。

第 2 课：从零添加模型动作状态

页面：手把手 2：从零添加模型动作状态

你会写工程代码：

• 把 .npz / .onnx 放进 data/。
• 在 launch 的 npz_file_dict / onnx_file_dict 增加 key。
• 在 BxiExample 中实例化 policy。
• 写一个 WaveMotionState。
• 实现模型预热、第一帧、播放结束、暂停 action。
• 把 model_keys 写进发布保护。

第 3 课：绑定按键并接入状态机

页面：手把手 3：从零绑定按键并接入状态机

你会写配置：

• sources.keyboard.signals。
• controls。
• outputs.edge。
• remote_events。
• states.normal.transitions.on_event。
• 手柄组合键。
• 派生 command.*。

第 4 课：从零写一个自定义过渡行为

页面：手把手 4：从零写一个自定义过渡行为

你会写代码：

• 理解 transition 生命周期。
• 在 robot_state_base.py 增加一个 first_frame_blend_pose_gain 行为。
• 让位置从当前姿态插值到目标第一帧。
• 让 kp/kd 按曲线渐变。
• 用 transition.data 配置行为私有参数。
• 在 YAML 中定义 profile。
• 用 inline transition 覆盖单次切换。

第 5 课：从零写一个 UDP 自定义遥控器驱动

页面：手把手 5：从零写一个 UDP 自定义遥控器驱动

你会写 C++：

• 设计 raw source。
• 增加 UdpConfig。
• 新建 udp_input_driver.hpp/cpp。
• 用 UDP 文本包更新 InputMapper。
• 加入 factory。
• 修改 CMake。
• 用 nc -u 手动发包测试。
• 正确处理 Ctrl+C、failsafe 和心跳。

第 6 课：把示例升级到工程上限

页面：手把手 6：把示例升级到工程上限

你会把前面的内容组合起来：

• 一个状态支持多种入口。
• 一个事件同时支持键盘、手柄、UDP driver。
• 三档开关用 enum。
• 高危动作需要双确认。
• 动作状态有自定义过渡。
• 状态机导出图。
• 发布保护删除内部状态。

读完后应该达到的能力

你应该能独立完成：

新增一个动作状态
  -> 给它绑定任意遥控器
  -> 配状态机转换
  -> 配进入/退出过渡
  -> 写自定义过渡行为
  -> 接入新遥控器协议
  -> 调试状态机信息
  -> 发布时删除高危动作

如果你已经会写代码，只想查字段，看 YAML 字段完整参考。