Home

BXI Mod 开发文档

本 Wiki 对应当前 dev 分支的 Mod 架构，面向状态开发、模型接入、控制器配置和框架扩展。

第一次接触本项目？ 从 创建第一个自定义状态 Mod 开始。完成后，你会得到一个能够加载、校验和进入的两文件 Mod。

新用户阅读路径

只按下面四步阅读，不需要先通读全部架构文档。

顺序	阅读内容	完成后能够
1	创建第一个自定义状态 Mod	用 mod.yaml + state.py 新增一个动作
2	Mod 状态开发进阶指南	判断应该使用 Pose、轨迹、模型还是完整状态 API
3	绑定按键并接入路由	从键盘、手柄或 CRSF 触发自己的状态
4	深度感知行走 Mod 开发实录	看我们是如何开发一个新状态的

如果加载或切换失败，直接进入 调试、验证与常见问题。

按开发目标查找

我想完成的工作	直接阅读
新增固定姿态或公式轨迹	自定义状态参考
接入 ONNX、NPZ 或动作回放	模型动作教程
为策略选择 ONNX Runtime、OpenVINO 或 RKNN	推理框架架构
用外部 ROS 图像驱动多输入策略	深度感知行走 Mod 开发实录
管理模型资产和 eager/lazy 资源	模型、资源与 launch
修改按键、组合键或摇杆映射	遥控器 YAML 配置
新增状态之间的切换方式	自定义过渡教程
配置双状态实时混合	双状态运行混合
接入 UDP、串口或新输入协议	自定义输入 Driver 教程
把仿真模型部署到真机	Sim2Real 教程
组织多个 Mod、启动校验和发布	工程化组合示例

所有专题教程集中在 专题教程索引。

查配置和 API

参考手册	适合查询的问题
Mod 公共 API	客户代码允许导入哪些稳定类和 Protocol
Mod 系统	Mod 目录、依赖、命名空间、factory、Resource
YAML 字段参考	某个 YAML 字段允许写什么
状态机基础配置	initial_state、mod_paths 和共享 transition profile
Mod 子节点声明与运行	mod.yaml 的 nodes 如何启动 Python、Mod 原生程序和已安装 ROS 节点
自定义状态	生命周期、参数、MotorFrame 和状态能力
自定义过渡	Transition API、配置读取和能力校验
自定义输入 Driver	InputDriver 接口、注册和断连契约

理解框架

• 想先知道各组件如何连接：阅读 架构总览。
• 需要调试启动加载、每帧执行或状态切换：阅读 框架底层运行原理。
• 需要理解 50 Hz 时间轴、deadline 和调度统计：阅读 框架控制调度。
• 需要扩展推理后端或分析性能：阅读 推理框架架构。
• 从旧提交 0f90a49 升级：阅读 版本迁移指南。

四条开发原则

1. RobotControlState 是状态系统的核心基类；PoseState、ProceduralState 和 PolicyState 是建立在它之上的入门封装。
2. 简单状态从 mod.yaml + state.py 开始，需要资源或注册扩展时再增加 plugin.py。
3. Mod ID、状态名和 routes 是稳定契约；升级实现不要求修改这些名称。
4. 新输入 Driver 只产生 raw signal，不直接引用状态名。