Mod Public API

Mod 公共 API

Mod 代码只应依赖 bxi_example_py_elf3.framework.mod_api。该包是面向客户的稳定扩展边界；bxi_example_py_elf3.framework.runtime 是控制器内部实现，不保证跨版本兼容。

最常用入口

from bxi_example_py_elf3.framework.mod_api import (
    ModDefinition,
    ModLoadContext,
    MotorFrame,
    PoseState,
    ProceduralState,
    PolicyState,
    ResourceHandle,
    ResourceKey,
    RobotControlState,
)

模块	用途
mod_api.state	StateBehavior、RobotControlState
mod_api.states	Pose、Procedural、Policy、MotionReplay 等渐进式基类
mod_api.frame	MotorFrame 和电机帧数组类型
mod_api.resource	Resource key、handle 和加载上下文
mod_api.mod	Mod 定义、加载上下文和状态构建参数
mod_api.transition	状态帧能力、Transition 配置和插件接口
mod_api.context	状态与 Transition 使用的控制器 Protocol
mod_api.geometry	四元数和重力方向等通用计算

控制上下文

公开生命周期使用 RobotControlContext，不再依赖具体的 BxiExample 类。当前由 RobotControlFramework 实现这份能力契约；状态只面向契约编程，因此 ROS/硬件适配层可以改变而不迫使客户 Mod 跟着修改。

能力	主要成员
本周期观测	current_q、current_dq、current_quat_xyzw/wxyz、current_omega
速度命令	current_raw_cmd_vel、current_cmd_vel、speed_profiles
机器人结构	control_layout、dof_num、current_joints
最近输出	pos_last、kp_last、kd_last 和对应的 *_last_state
输出与切换	set_motor_target()、request_state()
模型与安全	preheat_model()、is_orientation_unsafe()
运行信息	生命周期参数 dt，以及上下文中的 loop_count
日志和 ROS	get_logger()、ros_node

新状态优先读取 current_* 快照。qpos、quat_xyzw 等传感器缓存仍在 Protocol 中供已有状态兼容，但普通控制逻辑不需要绕过当前周期快照。

目标姿态和 kp/kd 属于状态输出语义，不属于控制上下文。状态应通过自己的参数、Resource、模型或常量构造完整 MotorFrame；需要保持连续时，可以明确选择 pos_last/kp_last/kd_last，但必须考虑来源状态是否为零力矩。

需要创建自定义 ROS subscription、service 或 timer 时，使用高级出口：

def on_bind(self, ctx):
    node = ctx.ros_node
    self.subscription = node.create_subscription(...)

在 on_unbind() 中销毁自己创建的 ROS 实体。

这是显式的平台扩展点：使用它的 Mod 会依赖 ROS，而只使用观测、事件、Resource 和 MotorFrame 的 Mod 不会与 BxiExample 或具体硬件绑定。

Transition 能力

from bxi_example_py_elf3.framework.mod_api.transition import (
    EntryFrameProvider,
    RunningFrameProvider,
)

EntryFrameProvider 提供目标状态的稳定进入帧，供 first_frame_switch 一类过渡使用；RunningFrameProvider 允许过渡采样两端的实时电机帧，供双状态混合使用。普通状态不需要主动实现无关能力。

导入边界

旧版 bxi_example_py_elf3.utils.* 扩展入口已经移除。Mod 必须从 bxi_example_py_elf3.framework.mod_api 导入公共类型；这样使用了框架内部实现的代码会立即失败，而不会形成难以维护的隐式依赖。

mod_api 导入本身不会创建 ROS 节点、加载 ONNX Runtime 或扫描 Mod，因此可以单独用于 IDE 补全、静态检查和离线单元测试。

Resource 加载策略

资源注册支持代码侧加载策略：

context.register_resource(POLICY, load_policy, loading="eager")
context.register_resource(CLIP, load_clip, loading="lazy")

eager 在所有 Mod 注册完成后、控制循环启动前创建资源；lazy 在首次 ResourceHandle.get() 时创建。默认值是 lazy，未知值会在 Mod 加载时直接 报错。策略属于资源工厂的运行语义，因此不写入 mod.yaml。

相关文档

• Mod 系统
• Mod 状态开发进阶指南
• 自定义状态参考
• 自定义过渡参考
• 模型、资源与 launch