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 顶层字段

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

字段：

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

未知顶层字段会产生 warning。

2. sources

通用结构：

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

2.1 group 字段

• type：输入组类型。内置支持 joystick / gamepad / keyboard。其他类型会按通用 source 解析，但需要对应 driver 才能运行。
• signals：本组 source 声明。必须是 map。

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 的语义是“设备连接心跳超时”，不是“输入值没变化”。

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

通用结构：

controls:
  <control_name>:
    type: analog
    source: gamepad.left_y

通用字段：

• type：analog、bool、enum。
• source：单个 source 或 source 配置。
• sources：多个 source 配置。
• expr：派生 bool control 的表达式。
• mix：多输入混合方式。
• curve：control 层曲线。
• default：默认字符串值，常用于 enum。
• deadzone：control 层死区。
• min / max：control 输出范围。
• alpha：低通滤波系数，范围 [0, 1]。
• threshold：bool 按下阈值。
• hysteresis：bool/enum 迟滞。
• expo：control 层指数曲线。
• invert：是否取反。
• positions：enum 的区间配置。

4.1 source 配置字段

标量写法：

source: gamepad.left_y

对象写法：

source:
  source: gamepad.left_y
  direction: -1
  scale: 1.0
  offset: 0.0
  deadzone: 0.03
  expo: 0.1
  curve: stick

字段：

• source：source 名。
• direction：方向，常用 -1 反向。
• scale：缩放。
• offset：偏移。
• deadzone：source 层死区。
• expo：source 层指数曲线。
• curve：引用 curves。

4.2 mix

mix: max_abs

可选：

• max_abs：取绝对值最大的输入。
• sum：求和后限制到 [-1, 1]。
• first_active：按顺序取第一个非零输入。

4.3 analog control

move.vx:
  type: analog
  mix: max_abs
  sources:
    - source: gamepad.left_y
      direction: -1
      curve: stick
    - source: keyboard.vx
  deadzone: 0.03
  min: -1.0
  max: 1.0
  alpha: 0.03

计算顺序：

读取 source
  -> source direction/scale/offset
  -> source curve/deadzone/expo
  -> mix
  -> control invert/curve/expo/deadzone
  -> min/max 映射
  -> alpha 低通

4.4 bool control

trigger.left:
  type: bool
  source: gamepad.trigger_left
  threshold: 0.85
  hysteresis: 0.05

阈值逻辑：

• 未按下时，raw >= threshold + hysteresis 变为按下。
• 已按下时，raw >= threshold - hysteresis 保持按下。

4.5 enum control

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

字段：

• positions.<value>: [min, max]。
• default 用于没有区间匹配时的值。
• hysteresis 会扩展当前值的保持区间。

4.6 expr 派生 bool control

command.flip:
  type: bool
  expr:
    any:
      - [trigger.left, button.west]
      - [keyboard.back_flip]

限制：

• expr 只支持 type: bool。
• expr 不能和 source / sources 同时使用。
• 表达式依赖不能成环。

5. binding condition

outputs.level、outputs.edge 和 controls.*.expr 都使用同一套条件语法。

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:
    - "mkdir -p /var/log/bxi_log"
    - "ros2 launch bxi_example_py_elf3 example_demo_hw.launch.py > /var/log/bxi_log/elf.log 2>&1 &"

字段：

• 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
graph: {}
remote_events: {}
transition_profiles: {}
speed_profiles: {}
states: {}

字段：

• initial_state：初始状态。
• 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，也可以是 true。
• 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

soft_switch:
  duration: 0.02
  exit_duration: 0.02
  enter_duration: 0.02
  exit_behavior: hold_last_motor
  enter_behavior: hold_last_motor
  data: {}

dual_running_blend:
  duration: 0.3
  exit_behavior: none
  enter_behavior: dual_running_blend
  data:
    curve: smoothstep
    run_from: true
    run_to: true
    from_fallback: last_motor
    to_fallback: first_frame

字段：

• profile 名由 map key 决定。
• duration：默认同时设置 exit 和 enter 时长。
• exit_duration：退出侧时长。
• enter_duration：进入侧时长。
• exit_behavior：退出侧行为名。
• enter_behavior：进入侧行为名。
• data：行为私有数据，必须是 map。

内置机器人过渡行为：

• none：不额外输出。
• hold_last_motor：保持上一帧电机目标。
• first_frame_ramp_kp：使用目标状态第一帧，按进入进度渐变 kp/kd。
• dual_running_blend：旧状态和新状态都继续生成电机目标，按进入进度混合两侧 (qpos, kp, kd)。

dual_running_blend.data：

• curve：linear、smoothstep、smootherstep，默认 linear。
• run_from：是否运行旧状态采样，默认 true。
• run_to：是否运行新状态采样，默认 true。
• from_fallback：旧状态采样不到时的退路，默认 last_motor。
• to_fallback：新状态采样不到时的退路，默认 first_frame。

fallback 支持 last_motor、hold_last_motor、first_frame、none。

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
  behavior: SinWaveState
  params: {}
  speed_profile: normal
  transitions:
    on_event: {}
    after: []

字段：

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

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:
  name: recover_long_entry
  base: first_frame_switch
  enter_duration: 1.0
  data:
    kp_start: current

字段：

• name：可选名称。
• base：继承的 profile。
• profile：base 等价字段。
• extends：base 等价字段。
• duration / exit_duration / enter_duration。
• exit_behavior / enter_behavior。
• data。

19. release_protection.yaml

protected_states:
  back_flip:
    behavior:
      - FlipState
      - BackFlipState
    events: [back_flip]
    model_keys: [back_flip]
    files:
      - ../data/back_flip.npz

字段：

• protected_states：受保护状态表。
• protected_states.<state>：状态名。
• behavior：要删除的 class，字符串或数组。
• behaviors：behavior 的等价复数字段。
• events：要删除的状态机 event。
• model_keys：要从 launch 字典和 demo node 初始化中删除的模型 key。
• 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
  launch_glob: ../launch/*.launch.py

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