YAML Reference

YAML 字段完整参考

本页是字段手册。教程页讲“怎么一步步做”，本页讲“每个字段是什么、能怎么写、默认行为是什么”。

涉及文件：

src/remote_controller/config/xbox_default.yaml
src/bxi_example_py_elf3/config/elf3_state_machine.yaml
src/bxi_example_py_elf3/config/release_protection.yaml

1. remote_controller YAML 顶层字段

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

字段：

• inputs：候选设备扫描与抢占策略。可选。
• sources：候选设备和输入来源声明。必须有。
• curves：曲线、死区、校准。可选。
• controls：统一控制量。必须有。
• outputs：输出到 MotionCommands 或 system.*。必须有。
• system：系统命令表。可选。
• system_mutexes：系统命令互斥关系。可选。
• system_reset_motion_after：执行某些 system action 后清零运动输入。可选。

未知顶层字段会产生 warning。

2. sources

通用结构：

sources:
  <group>:
    type: <driver_type>
    priority: <integer>
    signals:
      <semantic_source>:
        from: <raw_source>

2.1 group 字段

• type：输入组类型。内置支持 joystick / gamepad / keyboard。其他类型会按通用 source 解析，但需要对应编译内置 driver 才能运行；缺失 driver 只会记录 warning 并跳过该候选项。
• priority：候选设备优先级，值越大越优先，默认 0。
• ready_timeout_ms：启动后等待 driver is_ready() 的最长时间，默认 1000，必须大于 0。
• loss_timeout_ms：driver is_available() 连续失败多久后判定断连，默认 300，必须大于等于 0。
• cooldown_ms：断连或就绪超时后的冷却时间，默认 1000，必须大于等于 0。
• signals：本组 source 声明。必须是 map。

2.0 inputs.selection

inputs:
  selection:
    scan_interval_ms: 100
    promote_stable_ms: 500

• scan_interval_ms：调用所有候选 driver is_available() 的周期，默认 100，必须大于 0。
• promote_stable_ms：高优先级候选设备连续可用多久后才允许抢占，默认 500，必须大于等于 0。

候选设备严格独占。切换时会清除旧设备输入并发布一次零运动命令；新设备必须先通过 is_ready()，edge 输出才会重新启用。

2.2 joystick / gamepad group 字段

sources:
  gamepad:
    type: joystick
    device: /dev/input/js0
    signals: {}

字段：

• device：Linux joystick 设备路径。
• js：device 的旧别名。推荐写 device。

raw source：

• js.axis.N：第 N 个轴，归一化到 [-1, 1]。
• js.button.N：第 N 个按钮，松开 0.0，按下 1.0。

2.3 keyboard group 字段

sources:
  keyboard:
    type: keyboard
    poll_timeout_us: 20000
    hold_ms: 200
    stop: space
    signals: {}

字段：

• poll_timeout_us：终端轮询超时，单位微秒，必须大于等于 0。
• hold_ms：键盘 source 默认保持时间，单位毫秒，必须大于等于 0。
• stop：清零运动轴的键名，默认 space。

支持键名：

space
tab
esc
escape
单字符，例如 1、q、w

2.4 generic signal 字段

适用于 joystick、gamepad、自定义 driver：

gamepad.left_y:
  from: js.axis.3
  timeout_ms: 1000
  failsafe: 0.0

字段：

• from：raw source 名。必须有。
• timeout_ms：runtime source 超时时间。0 或不写表示关闭 timeout。
• failsafe：timeout 后写入 raw source 的值。

timeout_ms 是 单个 raw signal 的过期保护：超过时间后写入 failsafe，但不会判定设备断连或切换候选设备。设备级断连统一由 driver 的 is_available() 和 group 的 loss_timeout_ms 负责。

• joystick 默认不要设置 timeout_ms，因为静止时没有新事件是正常的。
• CRSF 应按最近一次 CRC 正确完整帧实现 is_available()。
• UDP/TCP 可在字段独立停更时使用 timeout_ms 作为额外保护。

2.5 keyboard.axis signal 字段

keyboard.vx:
  from: keyboard.axis
  negative: s
  positive: w
  hold_ms: 200

字段：

• from: keyboard.axis：声明键盘模拟轴。
• negative：按下时输出 -1.0 的键。
• positive：按下时输出 1.0 的键。
• hold_ms：覆盖该 source 的保持时间。

键盘 axis source 名必须以 vx、vy 或 yaw 结尾，框架用尾名绑定内部键盘运动轴。

2.6 keyboard.key signal 字段

keyboard.normal:
  from: keyboard.key
  key: "1"
  hold_ms: 200

字段：

• from: keyboard.key：声明普通键。
• key：触发该 source 的键。
• hold_ms：覆盖该 source 的保持时间。

3. curves

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

字段：

• type：expo 或 piecewise。
• deadzone：死区，必须大于等于 0。
• expo：指数曲线强度，范围 [0, 1]。
• limit: [min, max]：输出限幅。
• min / max：输出限幅，等价于 limit。
• calibration：三点校准。
• points：分段线性曲线点。

3.1 calibration

数组写法：

calibration:
  input: [-1.0, 0.0, 1.0]
  output: [-1.0, 0.0, 1.0]
  clamp: true

展开写法：

calibration:
  input_min: -1.0
  input_center: 0.0
  input_max: 1.0
  output_min: -1.0
  output_center: 0.0
  output_max: 1.0
  clamp: true

字段：

• input：输入三点 [min, center, max]。
• output：输出三点 [min, center, max]。
• input_min / input_center / input_max：输入三点展开写法。
• output_min / output_center / output_max：输出三点展开写法。
• clamp：是否把输入限制在输入范围，默认 true。

3.2 piecewise points

curves:
  throttle_curve:
    type: piecewise
    points:
      - [-1.0, -0.2]
      - [0.0, 0.0]
      - [1.0, 1.0]

字段：

• points 每项必须是 [input, output]。
• input 必须从小到大排序。
• type: piecewise 时至少两个点。

4. controls

每个 control 都只有一个 inputs: 规则列表。旧的顶层 source、sources、expr 已删除，写入即为配置错误。

controls:
  move.yaw:
    type: analog
    mix: max_abs
    inputs:
      - source: gamepad.yaw
        direction: -1
        curve: stick
      - name: dpad_left
        priority: 100
        when: [crsf.button_group_b=dpad_left]
        value: 1.0
      - name: dpad_right
        priority: 100
        when: [crsf.button_group_b=dpad_right]
        value: -1.0
    min: -1.0
    max: 1.0

4.1 input 规则

inputs 中的规则只能是以下三种之一：

• raw 输入：source: <raw source>，可附加 direction、scale、offset、deadzone、expo、curve。
• 条件常量：when: <condition> 加 value: <number|bool|string>。
• 无条件常量：仅 value: ...，始终作为一个激活输入。

每条规则可有 name（DEBUG 日志使用）和整数 priority。每次只选择已激活规则中最高 priority 的整组；同组规则再按 control 的 mix 合并。因此高优先级条件天然严格抢占低优先级摇杆。

raw source 的激活条件是变换后非零；when 规则由条件为真激活，即使其 value: 0 也能明确覆盖低优先级输入。

4.2 类型与 mix

• analog：max_abs、sum、first_active。sum 允许正负值抵消；结果再经过 control 的 invert/curve/expo/deadzone 并限制在 min/max。
• bool：any、all、first_active。raw source 用 threshold/hysteresis 转为 bool；使用 all 时，选中 priority 组内值为零的 raw source 也会作为 false 参与判断。
• enum：仅 first_active。default 必须为非空字符串；若含 raw source，还必须定义 positions。

analog 的 alpha 默认 1.0（立即响应）；明确设置后才低通平滑。

4.3 enum 与条件值

switch.mode:
  type: enum
  default: middle
  hysteresis: 0.03
  inputs:
    - source: crsf.mode
  positions:
    low: [-1.0, -0.35]
    middle: [-0.34, 0.34]
    high: [0.35, 1.0]

command.enable:
  type: bool
  inputs:
    - when:
        all: [switch.mode=high, button.west]
      value: true

条件可递归组合 all、any、not，叶子条件为 pressed、released、equals、range。 也可判断 raw 数值闭区间：

- when:
    raw_range: {source: udp.mode, min: 0.6, max: 1.0}
  value: sport

条件依赖会在加载时检查未知 control、未知 raw source 和循环引用。

5. binding condition

outputs.level、outputs.edge 和 controls.*.inputs[].when 都使用同一套条件语法。

5.1 pressed 简写

when: [button.west]

等价于：

when:
  - pressed: button.west

5.2 released

when:
  - button.west
  - released: shoulder.left

5.3 equals 简写

when:
  - switch.mode=high

等价于：

when:
  - equals:
      control: switch.mode
      value: high

5.4 range

when:
  - range:
      control: throttle
      min: 0.2
      max: 1.0

5.5 all / any

默认一个列表就是 all：

when: [shoulder.right, button.west]

显式 all：

when:
  all:
    - shoulder.right
    - button.west

任意一组：

when:
  any:
    - [shoulder.right, button.west]
    - [keyboard.normal]

6. outputs

outputs:
  conflict_policy: first_wins
  publish_on_change: true
  analog: {}
  level: []
  edge: []

字段：

• conflict_policy：first_wins、last_wins、error。
• publish_on_change：是否只在 payload 变化时发布。
• analog：连续字段输出。
• level：电平 binding。
• edge：上升沿 binding。

未知 outputs.* 字段会报错。

6.1 outputs.analog

标量写法：

analog:
  vel_des.x: move.vx

对象写法：

analog:
  vel_des.x:
    controls: [move.vx, autonomous.vx]
    mix: first_active
    scale: 1.0
    offset: 0.0
    limit: [-1.0, 1.0]

字段：

• key：MotionCommands 字段路径或简写。
• control：单个 control。
• controls：多个 control。
• mix：max_abs、sum、first_active。
• scale：输出缩放。
• offset：输出偏移。
• limit：[min, max]。
• min / max：输出限幅。

支持字段：

vel_des.x
vel_des.y
vel_des.z
yawdot_des
height_des

简写：

vx -> vel_des.x
vy -> vel_des.y
vz -> vel_des.z
yaw -> yawdot_des
height -> height_des

6.2 outputs.level / outputs.edge

level:
  - output: btn_1=1
    when: [keyboard.normal]

edge:
  - output: btn_10=5
    when: [keyboard.sin_wave]

字段：

• output：输出目标。
• when：条件。

output 支持：

• btn_N=value：写 MotionCommands.btn_N。
• btn_N：等价于 btn_N=1。
• system.<name>：只允许放在 edge。

限制：

• btn_N 中 N 范围是 1 到 10。
• system.* 必须在 system 中声明。
• system.* 不能放在 level。

7. system

system:
  start:
    - "<prepare_log_or_environment_command>"
    - "<start_robot_stack_command>"

字段：

• key 是 action 名。
• value 是命令字符串数组。
• outputs.edge.output: system.<name> 触发对应命令。

8. system_mutexes

system_mutexes:
  launch:
    acquire: start
    release: stop

字段：

• key 是互斥锁名字。
• acquire：执行哪个 system action 后锁定。
• release：执行哪个 system action 后释放。

9. system_reset_motion_after

system_reset_motion_after:
  - stop

字段：

• 数组项是 system action 名。
• action 执行后调用 InputMapper::reset_motion()。

10. state machine YAML 顶层字段

initial_state: zero_torque
default_transition: instant
graph: {}
remote_events: {}
transition_profiles: {}
speed_profiles: {}
states: {}

字段：

• initial_state：初始状态。
• default_transition：默认过渡 profile，必须引用 transition_profiles。
• graph：状态图自检和导出。
• remote_events：MotionCommands 到 event 的映射。
• transition_profiles：过渡 profile。
• speed_profiles：速度缩放 profile。
• states：状态定义。

11. graph

graph:
  validate: true
  export:
    dot: /tmp/elf3_state_machine.dot
    mermaid: /tmp/elf3_state_machine.mmd

字段：

• validate：是否自检。
• export：导出配置 map。
• export.dot：dot 文件路径。
• export.mermaid：mermaid 文件路径。

12. remote_events

完整写法：

normal:
  slot: btn_1
  value: 1

简写：

any_change_event: btn_1

字段：

• slot：MotionCommands 字段名。
• value：期望值。不写时，slot 任意变化都会触发 event。

13. transition_profiles

instant:
  type: instant

soft_switch:
  type: hold
  duration: 0.02

first_frame_switch:
  type: sequence
  steps:
    - type: hold
      duration: 0.02
    - type: entry_gain_ramp
      duration: 1.0
      kp_from: zero
      kd_from: target

dual_running_blend:
  type: running_blend
  duration: 0.3
  curve: smoothstep
  sample_from: true
  sample_to: true
  advance_from: false
  advance_to: false

所有 profile 必须声明 type。状态机核心不识别具体 type；插件从 bxi_example_py_elf3/transitions/ 自动发现。

type	字段
instant	无其他字段，时长为 0
hold	duration >= 0
entry_gain_ramp	duration、kp_from、kd_from
running_blend	duration、curve、sample_from、sample_to、advance_from、advance_to
sequence	非空 steps，每项为完整过渡配置

kp_from / kd_from 支持 current、zero、target。curve 支持 linear、smoothstep、smootherstep。未知字段会被拒绝。

14. speed_profiles

normal_run:
  vx_scale: 2.0
  vx_min: -1.0
  vx_max: 2.0
  vy_scale: 0.5
  yaw_scale: 1.0

speed_profiles 由 RobotControlState.get_cmd_vel(ctx) 使用。状态 YAML 通过 speed_profile 选择一个 profile：

states:
  normal:
    behavior: NormalState
    speed_profile: normal_run

支持字段：

• vx_scale：vel_des.x 缩放，默认 1.0。
• vy_scale：vel_des.y 缩放，默认 1.0。
• yaw_scale：yawdot_des 缩放，默认 1.0。
• vx_min / vx_max：前后速度限幅，默认不限。
• vy_min / vy_max：左右速度限幅，默认不限。
• yaw_min / yaw_max：转向速度限幅，默认不限。

运行规则：

• 状态调用 self.get_cmd_vel(ctx) 时才会应用。
• 状态重写 process_cmd_vel(ctx, cmd_vel) 时，可以在 profile 之后继续做滤波、限速或屏蔽方向。
• 状态没有 speed_profile 时返回 [0, 0, 0]。
• 状态引用不存在的 profile 时 warning 一次，并返回 [0, 0, 0]。
• 处理后的速度会写入 ctx.current_cmd_vel，同时出现在 state_machine_info.cmd_vel。

15. states

sin_wave:
  id: 20
  manifest:
    label: 正弦测试
    index: 20
    group: Debug
    icon: waves
    confirm: false
    confirm_message: ""
  behavior: SinWaveState
  params: {}
  speed_profile: normal
  transitions:
    on_event: {}
    after: []

字段：

• state 名由 map key 决定。
• id：可选。通常不写，自动分配。
• manifest：可选展示元数据，会透传到 state_machine_info.graph.states。
• behavior：Python 类名。
• params：传给状态类构造函数。
• speed_profile：引用 speed_profiles；状态调用 self.get_cmd_vel(ctx) 时生效。
• transitions：状态转移定义。

manifest 支持常用展示字段：

• label：展示名称。
• index：排序。
• group：分组。
• icon：图标名。
• confirm：外部控制界面是否应二次确认。
• confirm_message：确认提示。

状态机核心逻辑不会读取这些展示字段。

16. transitions.on_event

简写：

zero_torque: zero_torque

完整写法：

recover:
  to: recover
  delay: 0.2
  action: null
  transition: soft_switch

字段：

• key 是 event 名。
• to：目标状态。
• delay：延迟多少秒后切换。
• action：执行 action。不写 to 时只执行 action。
• transition：过渡 profile 名或 inline transition。

17. transitions.after

after:
  - seconds: 3.0
    to: normal
    action: null
    transition: soft_switch

字段：

• seconds：进入状态多少秒后触发。
• after：seconds 的等价字段。
• to：目标状态。
• action：到时间后执行 action。
• transition：过渡 profile 名或 inline transition。

18. inline transition

transition:
  profile: dual_running_blend
  duration: 1.0
  curve: linear

profile 复制已有 profile，其他字段覆盖它。也可以直接写插件配置：

transition:
  type: hold
  duration: 0.1

不支持其他 profile 引用别名。

19. release_protection.yaml

protected_states:
  <state_name>:
    behavior:
      - <StateClassName>
    model_keys: [<model_member_name>]
    files:
      - ../data/<model_or_motion_file>

字段：

• protected_states：受保护状态表。
• protected_states.<state>：状态名。
• behavior：要删除的 class，字符串或数组。
• behaviors：behavior 的等价复数字段。
• 状态机 event 不需要在清单里声明；脚本会从状态机转移关系自动推导。
• model_keys：要从 demo node 初始化中删除的模型成员名。
• files：额外删除文件。
• paths：覆盖脚本推导路径。

paths 字段：

paths:
  state_machine: elf3_state_machine.yaml
  robot_states: ../bxi_example_py_elf3/robot_states.py
  demo_node: ../bxi_example_py_elf3/bxi_example_demo.py

更多发布保护细节看 发布保护与公开版同步。