Home

bxi_rl_controller_ros2_example Wiki

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

快速入口

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

1. 架构总览
2. Mod 系统
3. 状态机基础配置
4. 手把手系列
5. 调试、验证与常见问题

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

手把手课程

1. 从零写一个自定义状态 Mod
2. 把模型动作封装成 Mod
3. 绑定按键并接入 Mod 路由
4. 写一个 Mod 内自定义过渡
5. 使用双状态运行混合
6. 写一个 UDP 自定义输入驱动
7. 工程化组合示例
8. 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。
• Python 插件只声明资源和状态工厂；模型资源通过 ResourceHandle 惰性加载。
• 遥控器仍统一走 sources -> controls -> outputs -> MotionCommands。
• Mod 的 events 把 MotionCommands 槽位映射成事件；routes 决定当前状态如何响应。
• 高危功能通过 visibility: protected 保护整个 Mod，不再对单个类和模型文件做文本删除。