Mod Public API

Mod 公共 API

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

最常用入口

from bxi_example_py_elf3.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 类。状态只面向这份能力契约编程，因此控制节点可以继续重构而不迫使客户 Mod 跟着修改。

能力	主要成员
本周期观测	current_q、current_dq、current_quat_xyzw/wxyz、current_omega
速度命令	current_raw_cmd_vel、current_cmd_vel、speed_profiles
控制默认值	joint_nominal_pos、joint_kp、joint_kd、dof_num
最近输出	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 中供已有状态兼容，但普通控制逻辑不需要绕过当前周期快照。

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

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

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

Transition 能力

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

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

导入边界

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

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