State Machine Config

状态机基础配置

当前状态图由两部分合成：

1. config/elf3_state_machine.yaml：系统级配置。
2. 每个 Mod 的 mod.yaml：状态、事件、速度、私有过渡 profile、路由、action 和可选内置节点。

不要再把 states 或 remote_events 写进系统 YAML；加载器会用 Mod 贡献重新生成这些字段。

状态图中的 route 决定“什么事件把哪个状态切到哪个状态”，Transition 则决定“切换期间每个控制周期如何生成电机帧”。两个状态的 qpos/kp/kd 可能不连续，直接切换可能使机器人突然动作，因此系统提供保持、进入增益渐变和双状态运行混合等过渡；只有明确需要立即切换时，例如进入安全断力状态，才使用 instant。

系统 YAML

initial_state: com.bxi.basic_actions/zero_torque

mod_paths:
  - /opt/bxi/mods

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

default_transition: instant

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

initial_state 必须使用完整状态名。mod_paths 只追加搜索根；安装包内置 mods/ 始终扫描。

Mod 事件

events:
  activate: {slot: btn_10, value: 8}
  toggle_pause: {slot: btn_9, value: 1}

运行时名称分别为 mod-id/activate 和 mod-id/toggle_pause。value 省略时表示槽位任意变化；通常推荐明确 value。

Mod 状态

states:
  wave:
    id: 12345                 # 可选；默认由完整名称稳定计算
    manifest:
      label: 波浪动作
      priority: 100
      group: Customer
      icon: waves
      confirm: true
      confirm_message: 请确认周围安全
    speed_profile: walk
    params:
      amplitude: 0.4

manifest.priority 控制界面顺序：数值越大越靠前，默认 0；相同值按完整状态名升序排列。框架自动生成唯一 index，它与状态机 id 无关。只有必须固定绝对位置时才显式写非负 manifest.index，重复的显式 index 会阻止启动。params 必须由工厂的 StateBuildContext 完整消费。

速度 profile

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

状态写 speed_profile: walk 时会自动解析成当前 Mod 的 mod-id/walk。状态代码通过 self.get_cmd_vel(ctx) 获取处理后的速度。

路由

所有边放在 routes，不写进 states.*.transitions：

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

  - from: wave
    event: com.bxi.basic_actions/normal
    to: com.bxi.basic_actions/normal
    transition:
      profile: dual_running_blend
      duration: 0.8

  - from: wave
    event: stop
    to: com.bxi.basic_actions/zero_torque
    delay: 0.2

规则：

• 本地 from/event/to 自动限定到当前 Mod。
• 包含 / 的值视为完整名称。
• 一条 route 必须包含 to，不能包含 action。
• transition 可为 profile 名、内联对象或 {profile: ..., 覆盖字段...}。
• first_frame_switch 的共享默认 ramp 是 1.0s。需要更快切换的路由应使用 {profile: first_frame_switch, steps: [...]} 完整覆盖 steps；列表不会按下标深度合并。内置 normal_depth 进入路由把 ramp 显式覆盖为 0.02s。
• 同一源状态和同一事件只能有一条 route 或 action。

Action

不切换状态的事件处理单独放在 actions，不混入 routes：

actions:
  - from: wave
    event: toggle_pause
    action: toggle_pause
    manifest:
      label: 暂停/继续

from/event 的命名空间规则与 route 相同。每条 action 必须包含 action 和非空的 manifest.label，不能包含 to/transition/delay；触发后状态机调用当前状态的 action handler。

状态机信息会在 graph.actions[] 发布规范化后的 from/event/action 和展开的 manifest，消费端可直接读取 label 显示操作名称。

Mod 私有过渡 profile

transition_profiles:
  wave_entry:
    type: entry_gain_ramp
    duration: 0.6
    kp_from: zero
    kd_from: target

运行时名称是 mod-id/wave_entry。当前 Mod route 中写 transition: wave_entry 会自动解析；其他 Mod 使用时写完整名称并声明依赖。

图验证和导出

graph.validate: true 会在启动阶段验证目标、事件、过渡能力和图结构。导出文件可用于排查不可达状态或错误边：

sed -n '1,120p' /tmp/elf3_state_machine.mmd
dot -Tsvg /tmp/elf3_state_machine.dot -o /tmp/elf3_state_machine.svg

完整示例

当前最完整的生产示例是：

src/bxi_example_py_elf3/config/elf3_state_machine.yaml
src/bxi_example_py_elf3/mods/com.bxi.basic_actions/mod.yaml

字段全集见 YAML 字段参考，Mod 加载规则见 Mod 系统。