Home

BXI 机器人运控框架文档

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

框架能力一览

能力	当前提供的特性	深入阅读
模块化动作系统	动作、模型、状态、事件、路由和资产封装为独立 Mod；支持版本约束、依赖、冲突、启停、外置部署和发布可见性	Mod 系统
分层状态开发 API	以 RobotControlState 为核心，同时提供固定姿态、公式轨迹、在线策略和动作回放便捷基类；支持强类型 YAML 参数和完整生命周期	状态开发指南
安全状态切换	内置保持、增益渐变、序列过渡和双状态实时混合；支持进入帧、运行帧、取消准备及业务自定义 Transition	状态机配置、自定义过渡
具名关节与命令合成	按关节名处理 29/31/N 关节布局，支持局部模型输出、跨布局解析，以及模型、ROS、IK、轨迹等多来源命令的所有权校验与合成	关节布局与映射、多来源命令合成
模型推理与资源管理	支持 ONNX Runtime、OpenVINO、RKNN 后端选择和回退；模型可在启动期准备或首次请求时异步加载，并统一预热、缓存和关闭	推理框架架构、模型与资源
仿真与真机统一接入	平台适配层隔离机器人消息和硬件 SDK；MuJoCo 与真机可使用一致的相机逻辑名和 ROS 话题契约，仅切换 simulation/hardware 前缀	平台适配指南、Sim2Real
深度感知策略	独立相机进程发布 Image + CameraInfo，策略根据真实内参裁剪 FOV、缩放和旋转；支持相机新鲜度检查与失联安全退出	深度感知行走
多设备输入映射	键盘、Xbox/兼容手柄和 CRSF 统一映射到业务 control；支持组合键、互斥 released 条件、曲线、优先级和自定义 UDP/串口 Driver	输入映射、自定义 Input Driver
受管辅助进程	Mod 可声明 Python、原生可执行文件、ROS 包节点和普通命令；支持按状态启停、依赖顺序、CPU 角色、环境隔离、异常重启和分阶段关闭	Mod 子节点
实时控制与工程交付	提供周期预算、deadline 统计、CPU 亲和性和实时调度；启动期完成状态图、输入冲突和依赖校验，并支持分级日志、公开版裁剪与自检	控制调度、调试、发布保护

先选择你的入口

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

推荐阅读路线

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

路线 A：开发一个动作 Mod

1. 用 Mod API 4.0 开发第一个动作：完成最小的 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关节输入输出映射	关节布局与映射
管理模型资产和 startup/on-demand 资源	模型、资源与 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 的控制集成依赖 framework.mod_api，策略实现可依赖 framework.inference；两者都不依赖 framework.runtime。
4. 新动作从 Mod 开始；新机器人从平台适配器开始；新推理设备从 inference backend 开始。
5. Input Driver 只产生原始输入，业务状态切换由 Mod event 和 route 决定。