Skip to content

YAML Reference

Jump to bottom
konodoki edited this page Jul 20, 2026 · 26 revisions

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

通用结构：

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.action:
  type: bool
  expr:
    any:
      - [trigger.left, button.west]
      - [keyboard.action]

限制：

  • 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:
    - "<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
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
  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:
  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:
  <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

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

快速开始

Mod 与状态开发

模型、推理与真机

输入系统

平台接入与控制时序

配置与 API 参考

框架架构与维护

Clone this wiki locally