YAML Reference

YAML 字段参考

项目存在三类 YAML：遥控器映射、状态机系统配置和 Mod 清单。

1. 遥控器 YAML

主文件：

src/remote_controller/config/xbox_default.yaml

顶层结构：

inputs:
  selection: {}
sources: {}
curves: {}
controls: {}
outputs: {}
system: {}
system_mutexes: {}
system_reset_motion_after: []

inputs.selection

字段	含义
scan_interval_ms	扫描候选设备的周期
promote_stable_ms	高优先级设备持续可用多久后允许抢占

sources

每个 source group 声明一个候选设备：

sources:
  gamepad:
    type: joystick
    device: /dev/input/jsBattleDragon
    priority: 50
    ready_timeout_ms: 1000
    loss_timeout_ms: 300
    cooldown_ms: 1000
    signals:
      gamepad.left_y: {from: js.axis.3}

内置 type 包含 joystick、keyboard 和 crsf。自定义类型需注册输入驱动工厂。

通用字段：type、priority、ready_timeout_ms、loss_timeout_ms、cooldown_ms、signals。设备专有字段由对应 driver 解析。

curves

curves:
  stick:
    type: expo
    deadzone: 0.03
    expo: 0.0
    limit: [-1.0, 1.0]
    calibration:
      input: [-1.0, 0.0, 1.0]
      output: [-1.0, 0.0, 1.0]

controls

支持 analog、bool 和 enum。control 把多个设备输入统一成业务控制量，输入规则可带 source、direction、curve、when、value 等字段。条件支持 pressed、released、equals、范围以及 all/any 组合。

完整语法和实例见 遥控器 YAML 配置。

outputs

outputs:
  conflict_policy: first_wins
  publish_on_change: true
  analog:
    vx: move.vx
  edge:
    - output: btn_10=8
      when:
        any:
          - [keyboard.wave_event]
          - [gamepad.a_event]

conflict_policy 可为 first_wins、last_wins 或 error。publish_on_change 控制是否仅在消息变化时发布。analog 连续写值，level 保持条件结果，edge 只在进入条件时产生脉冲；最终字段写入 MotionCommands。

2. 状态机系统 YAML

主文件：

src/bxi_example_py_elf3/config/elf3_state_machine.yaml

字段	必需	含义
initial_state	是	完整初始状态名
mod_paths	否	额外 Mod 搜索根列表
graph.validate	否	是否验证状态图
graph.export.dot	否	DOT 导出路径
graph.export.mermaid	否	Mermaid 导出路径
default_transition	否	未指定边的默认过渡
transition_profiles	否	系统共享过渡 profile

states、remote_events 和 speed_profiles 由 Mod 合成，不应写入此文件。

内置过渡类型

Transition 是源状态与目标状态之间的切换策略，决定切换期间怎样生成电机 qpos/kp/kd。它的主要作用是处理两边输出不连续的问题，避免直接换帧造成突跳；instant 表示明确选择不做中间处理。

• instant
• hold
• entry_gain_ramp
• running_blend
• sequence

各字段见 自定义过渡 和 双状态运行混合。

3. mod.yaml

顶层字段

字段	必需	含义
schema	否	当前固定为 1，省略时默认为 1
id	是	全局唯一、带命名空间的 Mod id
version	是	数字点版本，如 1.0.0
api	否	当前固定为 1，省略时默认为 1
enable	否	是否启用此 Mod；省略时默认为 true
entrypoint	否	高级插件的 module:function；存在 plugin.py 时默认 plugin:create_mod
visibility	否	public（默认）或发布工具识别的 protected
requires	否	Mod 依赖及版本约束
python_exports	否	暂时导出的顶层 Python 包
events	否	遥控槽位到事件的映射
speed_profiles	否	Mod 私有速度 profile
transition_profiles	否	Mod 私有过渡 profile
states	否	本地状态声明；资源 Mod 可省略或使用 {}
routes	否	状态图边和 action

requires

requires:
  - com.example.shared
  - id: com.bxi.basic_actions
    version: ">=1,<2"

python_exports

python_exports:
  - customer_common

Mod 根目录必须存在 customer_common/__init__.py。导出名必须是合法且全局唯一的 Python 包名。

events

events:
  activate: {slot: btn_10, value: 8}
  any_change: {slot: btn_9}

slot 必须是合法标识符，value 若存在必须是整数。事件必须至少被一条 route 使用。

states

states:
  wave:
    factory: state:WaveState
    id: 12345
    label: 示例
    index: 20
    group: Customer
    icon: waves
    confirm: true
    confirm_message: 请确认安全
    speed_profile: walk
    params:
      amplitude: 0.4

factory: module:Class 用于没有 entrypoint 的约定加载。状态 id 是可选 int32；index 是 manifest.index 的简写和非负 UI 序号。label/index/group/icon/confirm/confirm_message 均可直接写，也可继续放在 manifest 中，但不能同时给出冲突值。重复 index 会自动重分配并告警。params 的类型和允许字段由类的 dataclass Params 或显式插件工厂决定。

routes

routes:
  - from: com.bxi.basic_actions/normal
    event: activate
    to: wave
    transition: soft_switch

  - from: wave
    event: toggle_pause
    action: toggle_pause

  - from: wave
    event: stop
    to: com.bxi.basic_actions/zero_torque
    transition: {profile: safe_exit, duration: 0.5}
    delay: 0.2

字段：from、event、to、action、transition、delay。to/action 至少存在一个。

speed_profiles

speed_profiles:
  walk:
    vx_scale: 1.0
    vx_min: -1.0
    vx_max: 1.0
    vy_scale: 0.5
    yaw_scale: 1.5

transition_profiles

与系统 profile 结构相同，但运行时自动命名为 mod-id/local-name。

4. 名称限定规则

• 不含 / 的 state、event、speed profile 和 Mod transition profile 名称属于当前 Mod。
• 包含 / 的值视为完整名称。
• 资源键始终必须显式写完整命名空间。
• 跨 Mod 引用应同时出现在 requires 中。

完整加载和校验行为见 Mod 系统。