Hands On Series

手把手系列总览

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

SinWaveState

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

• YAML 参数。
• 键盘和手柄绑定。
• remote_events。
• on_bind(ctx) 中创建状态自己的订阅。
• get_cmd_vel(ctx) 读取速度输入，process_cmd_vel(ctx, cmd_vel) 做状态私有处理。
• 自动返回。
• action 暂停。
• 第一帧。
• 自定义过渡行为。
• 双状态运行混合过渡。
• 自定义遥控器 driver。
• 复杂组合键。
• 发布保护。
• IsaacLab 模型 sim2real。

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

学习路径

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

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

你会写代码：

• 直接在 robot_states.py 里写 SinWaveState。
• 不新建状态子包，不改 setup.py。
• 先不接遥控器，直接把 initial_state 临时改成 sin_wave 验证状态代码。
• 加 params。
• 按需实现 EntryFrameProvider 和 RunningFrameProvider。
• 用 on_bind(ctx) 创建状态自己的订阅。
• 加 action。
• 加安全退出。

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

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

你会写工程代码：

• 把 .npz / .onnx 放进 data/。
• 在 BxiExample.load_models() 中用 model_file() 声明模型路径并实例化 policy。
• 直接在 robot_states.py 里写 WaveMotionState。
• 实现模型预热、进入帧、运行采样、速度输入、播放结束和暂停 action。
• 把 model_keys 写进发布保护。

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

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

你会写配置：

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

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

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

你会写代码：

• 理解 transition 生命周期。
• 在顶层 transitions/ 增加一个自动发现的插件类文件。
• 让位置从当前姿态插值到目标进入帧。
• 让 kp/kd 按曲线渐变。
• 用 ConfigReader 声明并验证插件参数。
• 在 YAML 中定义 profile。
• 用 inline transition 覆盖单次切换。

第 5 课：从零使用双状态运行混合过渡

页面：手把手 5：从零使用双状态运行混合过渡

你会写配置和少量状态代码：

• 使用 running_blend 插件 profile。
• 让旧状态和新状态在过渡期间同时生成电机目标。
• 配置 curve、sample_from/to 和 advance_from/to。
• 理解 RunningFrameProvider.sample_running_frame()。
• 保证 advance=False 时不推进运行状态。

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

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

你会写 C++：

• 设计 raw source。
• 新建 src/drivers/udp_input_driver.cpp。
• 用 InputDriverBase 把 UDP 文本包更新成 raw signal。
• 加入 factory，并配置候选设备优先级。
• 修改 CMake。
• 用 nc -u 手动发包测试。
• 正确处理 Ctrl+C、is_available()、is_ready() 和安全切换。

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

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

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

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

第 8 课：IsaacLab 模型从仿真到真机

页面：手把手 8：IsaacLab 模型从仿真到真机

你会按真实上机顺序走完整流程：

• 在 BxiExample.load_models() 里新增类似 self.withoutarm 的 IsaacLab 推理器。
• 在 robot_states.py 里写一个状态调用这个推理器。
• 在 elf3_state_machine.yaml 里注册新状态、事件和速度配置。
• 在 xbox_default.yaml 里绑定测试按键。
• 先用 example_demo.launch.py 仿真验证。
• 再用 example_demo_hw.launch.py 真机低风险验证。
• 补发布保护。

读完后应该达到的能力

你应该能独立完成：

新增一个动作状态
  -> 给它绑定任意遥控器
  -> 配状态机转换
  -> 配进入/退出过渡
  -> 写自定义过渡行为
  -> 使用双状态运行混合过渡
  -> 接入新遥控器协议
  -> 完成 IsaacLab 模型 sim2real 验证
  -> 调试状态机信息
  -> 发布时删除高危动作

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