Home

bxi_rl_controller_ros2_example Wiki

这个 wiki 按工程任务拆分。建议先读架构总览，再根据要做的事进入对应页面。

手把手课程

如果读者是第一次接触这套框架，优先按这个顺序读。每一篇都用一个具体例子从零开始写代码，然后逐步加功能。

1. 手把手系列总览
2. 手把手 1：从零写一个自定义状态
3. 手把手 2：从零添加模型动作状态
4. 手把手 3：从零绑定按键并接入状态机
5. 手把手 4：从零写一个自定义过渡行为
6. 手把手 5：从零使用双状态运行混合过渡
7. 手把手 6：从零写一个 UDP 自定义遥控器驱动
8. 手把手 7：把示例升级到工程上限
9. 手把手 8：IsaacLab 模型从仿真到真机

参考手册

这些页面用于查字段、查原理、查设计边界。

1. 架构总览
2. 遥控器 YAML 配置
3. 状态机 YAML 配置
4. YAML 字段完整参考
5. 自定义状态参考
6. 自定义过渡行为参考
7. 自定义遥控器驱动参考
8. 模型、动作数据与 launch 工程参考
9. 框架底层运行原理
10. 高级配置范式
11. 发布保护与公开版同步
12. 热重载
13. 调试、验证与常见问题

按任务查找

只想绑定一个新按键：

• 看 遥控器 YAML 配置 的 sources -> controls -> outputs。
• 如果这个按键要切状态，再看 状态机 YAML 配置 的 remote_events 和 states.*.transitions。
• 不确定字段含义时，看 YAML 字段完整参考。

想写一个新动作状态：

• 从 手把手 1：从零写一个自定义状态 开始。
• 如果这个动作依赖 .npz / .onnx，继续看 手把手 2：从零添加模型动作状态。
• 如果目标是 IsaacLab 模型上真机，直接看 手把手 8：IsaacLab 模型从仿真到真机。
• 需要更复杂的进入、退出动作时，看 自定义过渡行为。
• 想让两个状态在过渡中同时运行并混合输出时，看 手把手 5：从零使用双状态运行混合过渡。

想接入新的遥控器或协议：

• 先看 遥控器 YAML 配置，确认是否只改 YAML 就够。
• 多个设备需要自动优先级选择、抢占和断连回退时，看该页的 inputs / sources 章节。
• 如果需要读串口、CRSF、SBUS、UDP、自定义 HID，再看 手把手 6：从零写一个 UDP 自定义遥控器驱动。
• 想理解 failsafe、edge、level、publish_on_change 的底层细节，看 框架底层运行原理。

想把配置写到更高上限：

• 看 高级配置范式。

想运行时替换模型、状态代码或状态机配置：

• 看 热重载。

想发布公开版并删除高危动作：

• 看 发布保护与公开版同步。

遇到按键不触发、状态不切换、failsafe 误触发、Ctrl+C 退不出：

• 看 调试、验证与常见问题。

核心原则

• 不修改底层 communication/msg/MotionCommands 来适配业务状态。
• 遥控器输入统一走 sources -> controls -> outputs。
• 状态机只判断当前 state 和 event，不在业务代码里散落按键判断。
• 每个具体状态是一个类，状态私有变量放在状态对象内部。
• 状态自己的 ROS 订阅、client、timer 放在 on_bind(ctx)。
• 状态需要速度输入时调用 self.get_cmd_vel(ctx)，并通过 YAML 的 speed_profile 声明能力。
• utils/state_machine.py 保持通用；机器人相关逻辑放到 utils/robot_state_base.py 和具体状态类。
• 新遥控器 driver 只生产 raw source，不写业务状态名。
• 发布保护以配置驱动，公开版只发布脱敏后的目录。