Home

BXI 机器人运控框架文档

本 Wiki 对应当前 dev 分支，覆盖机器人平台适配、控制调度、状态机与 Mod、模型推理、 输入系统、Sim2Real 和框架维护。Mod 是动作与业务能力的主要扩展机制，但不是整个框架 的边界。

先选择你的入口

你的目标	从这里开始	接下来阅读
新增姿态、轨迹或动作状态	创建第一个自定义状态 Mod	Mod 状态开发进阶指南
接入 ONNX、NPZ 或感知策略	把模型动作封装成 Mod	推理框架架构
接入自己的机器人消息、SDK 或硬件	机器人平台适配指南	Sim2Real
修改状态机、调度器或框架内部	架构总览	框架底层运行原理
当前程序加载或运行失败	调试、验证与常见问题	根据故障层进入对应参考手册

推荐阅读路线

不需要从头通读 Wiki。根据自己的工作选择一条路线即可。

路线 A：开发一个动作 Mod

1. 创建第一个自定义状态 Mod：完成最小的 mod.yaml + state.py。
2. Mod 状态开发进阶指南：选择 Pose、公式轨迹、模型 或完整状态 API。
3. 绑定按键并接入路由：从键盘、手柄或 CRSF 触发状态。
4. 工程化组合示例：加入资源、依赖、启动校验和发布边界。

路线 B：部署一个推理策略

1. 把模型动作封装成 Mod：管理模型资产和生命周期。
2. 推理框架架构：选择 ONNX Runtime、OpenVINO、RKNN，理解 历史帧和性能约束。
3. 深度感知行走 Mod 开发实录：参考多输入感知策略的完整 工程实现。
4. Sim2Real：核对 observation、action、控制频率和真机安全。

路线 C：接入自己的机器人程序

1. 架构总览：理解平台适配层与运控内核的边界。
2. 机器人平台适配指南：实现状态快照、关节映射和硬件输出。
3. 框架控制调度：配置周期、deadline、绑核和实时优先级。
4. Sim2Real：按断使能、吊架和落地阶段验证。

路线 D：扩展或维护框架

1. 架构总览：先确认修改属于平台、Runtime、Mod、输入还是推理层。
2. 框架底层运行原理：按启动、加载和每周期路径定位实现。
3. Mod 公共 API：不要把 framework.runtime 内部接口泄漏给客户 Mod。
4. 高级配置范式和版本迁移指南：处理复杂组合 与已有项目升级。

所有按步骤操作的课程集中在专题教程索引。

按任务查文档

我想完成的工作	直接阅读
新增固定姿态或公式轨迹	自定义状态参考
合并模型、话题、IK或轨迹关节命令	多来源关节命令合成
理解29/31/N关节输入输出映射	关节布局与映射
管理模型资产和 eager/lazy 资源	模型、资源与 launch
新增状态之间的切换方式	自定义过渡教程
配置双状态实时混合	双状态运行混合
修改按键、组合键或摇杆映射	遥控器输入映射配置
接入 UDP、串口或新输入协议	自定义输入 Driver 教程
为 Mod 启动相机、感知或通信 ROS 节点	Mod 子节点声明与运行
查询某个 YAML 字段	YAML 字段参考
组织多个 Mod、启动校验和发布	工程化组合示例
生成公开发布树	发布保护与公开版同步

文档类型

类型	用法	例子
手把手教程	按顺序完成一个具体目标	专题教程索引
开发指南	解释选择、边界和完整工程方法	状态开发指南、平台适配指南
参考手册	已经知道要做什么时查询字段或接口	YAML 字段参考、Mod 公共 API
架构文档	修改框架或排查底层问题时阅读	架构总览、框架底层原理

核心边界

1. bxi_example_demo.py 是 ELF3 的 ROS/硬件适配层，不是运控框架本体。
2. RobotControlRuntime 管理控制调度和生命周期，RobotControlFramework 管理 Mod、 状态机、Transition 和每周期控制计算。
3. 客户 Mod 只依赖 bxi_example_py_elf3.framework.mod_api，不依赖 framework.runtime。
4. 新动作从 Mod 开始；新机器人从平台适配器开始；新推理设备从 inference backend 开始。
5. Input Driver 只产生原始输入，业务状态切换由 Mod event 和 route 决定。