Home

bxi_rl_controller_ros2_example Wiki

本 Wiki 对应当前 dev 架构。自 0f90a49c539e0efcec0d6fbc481f634890742c78 之后，机器人状态侧已经从“中央 Python 状态文件 + 中央状态图 YAML”迁移为可发现、可依赖、可热重载的 Mod 系统。

快速入口

第一次接触项目，建议按以下顺序阅读：

1. 架构总览
2. Mod 系统
3. 状态机基础配置
4. 从低地板到高天花板实战
5. 手把手系列
6. 调试、验证与常见问题

从旧版本迁移，请直接阅读 从 0f90a49 迁移。

手把手课程

1. 同一个状态从 PoseState 升级到自定义 Driver
2. 从零写一个自定义状态 Mod
3. 把模型动作封装成 Mod
4. 绑定按键并接入 Mod 路由
5. 写一个 Mod 内自定义过渡
6. 使用双状态运行混合
7. 写一个 UDP 自定义输入驱动
8. 工程化组合示例
9. IsaacLab 模型 Sim2Real

参考手册

• Mod 系统：目录、清单、依赖、命名空间、资源和校验规则。
• 状态机基础配置：系统 YAML 与 Mod 清单如何合成。
• YAML 字段参考：遥控器、系统配置和 mod.yaml 字段。
• 自定义状态：生命周期、工厂、参数和状态能力。
• 自定义过渡：插件生命周期和 Mod 内注册方式。
• 模型、资源与 launch：惰性模型资源、资产目录和预热。
• 热重载：监控范围、原子切换和失败回滚。
• 发布保护：按完整 Mod 删除保护动作。
• 遥控器 YAML 与 自定义输入驱动。
• 框架底层运行原理 与 高级配置范式。

当前内置 Mod

Mod	内容	发布属性
com.bxi.basic_actions	走路、零力矩、初始姿态、零位、跳舞、起身、跑步、鼓掌、挥手、躺下	public
com.bxi.back_flip	后空翻	protected
com.bxi.forward_flip	前空翻	public
com.bxi.ballet	芭蕾舞	protected

内置 Mod 安装到包的 share/bxi_example_py_elf3/mods/。客户 Mod 可通过系统配置里的 mod_paths 从额外目录发现。

核心原则

• 一个可独立安装、删除或保护的功能放在一个 Mod 目录中。
• 状态、事件、资源和 profile 使用 mod-id/local-name 全局命名。
• 系统 YAML 只保存系统级选项；状态、事件、速度和边放在 mod.yaml。
• 简单状态只需 mod.yaml + state.py；需要资源或扩展注册时再增加 plugin.py。
• PoseState -> ProceduralState -> PolicyState -> RobotControlState 是同一运行时上的渐进 API，不是四套框架。
• 模型资源通过 ResourceHandle 惰性加载。
• 遥控器仍统一走 sources -> controls -> outputs -> MotionCommands。
• Mod 的 events 把 MotionCommands 槽位映射成事件；routes 决定当前状态如何响应。
• 高危功能通过 visibility: protected 保护整个 Mod，不再对单个类和模型文件做文本删除。