Remote Config

遥控器 YAML 配置

遥控器配置文件：

src/remote_controller/config/xbox_default.yaml

推荐从上到下按这条线理解：

sources  ->  curves  ->  controls  ->  outputs  ->  system
输入声明      曲线校准     统一控制量      写 MotionCommands   执行系统命令

配置目标是：业务层不要关心具体是 Xbox、键盘、CRSF 还是其他遥控器。业务层只看统一后的 control 和状态机 event。

1. sources：声明输入来源

sources 负责把 driver 产生的 raw source 命名成业务可读 source。

通用结构：

sources:
  <group_name>:
    type: <driver_type>
    signals:
      <semantic.source.name>:
        from: <raw.source.name>

读法是从左到右：

semantic source 由 raw source 产生

例如：

gamepad.left_y: {from: js.axis.3}

表示：

gamepad.left_y 由 js.axis.3 产生

不要反过来写成 js.axis.3: gamepad.left_y，因为那会让人误解为 raw source 被业务含义反向定义。

2. joystick / gamepad source

示例：

sources:
  gamepad:
    type: joystick
    device: /dev/input/js0
    signals:
      gamepad.left_y: {from: js.axis.3, timeout_ms: 1000, failsafe: 0.0}
      gamepad.left_x: {from: js.axis.0, timeout_ms: 1000, failsafe: 0.0}
      gamepad.yaw: {from: js.axis.6, timeout_ms: 1000, failsafe: 0.0}
      gamepad.a: {from: js.button.0}
      gamepad.b: {from: js.button.1}

字段：

• type: joystick 或 type: gamepad：使用 Linux joystick driver。
• device：设备路径，例如 /dev/input/js0。
• signals：业务 source 声明。
• signals.<name>.from：raw source，例如 js.axis.3 或 js.button.0。
• timeout_ms：多久没有收到该 raw source 的连接心跳后触发 failsafe。
• failsafe：timeout 后写入的值，通常是 0.0。

driver 行为：

• js.axis.N 会归一化到 [-1, 1]。
• js.button.N 按下为 1.0，松开为 0.0。
• joystick driver 在设备连接但值不变时会 touch runtime source，避免摇杆不动被误判断联。

3. keyboard source

示例：

sources:
  keyboard:
    type: keyboard
    poll_timeout_us: 20000
    hold_ms: 200
    stop: space
    signals:
      keyboard.vx: {from: keyboard.axis, negative: s, positive: w}
      keyboard.vy: {from: keyboard.axis, negative: d, positive: a}
      keyboard.yaw: {from: keyboard.axis, negative: e, positive: q}
      keyboard.normal: {from: keyboard.key, key: "1", hold_ms: 200}

字段：

• type: keyboard：使用终端键盘 driver。
• poll_timeout_us：轮询终端输入的超时时间，单位微秒。
• hold_ms：键盘 source 触发后保持多久。键盘终端没有真实 release 事件，所以需要这个字段。
• stop：清零运动轴的按键，常用 space。
• from: keyboard.axis：声明键盘模拟轴。
• negative：按下后输出 -1.0 的键。
• positive：按下后输出 1.0 的键。
• from: keyboard.key：声明普通按键。
• key：触发普通按键 source 的键。
• signals.<name>.hold_ms：覆盖单个 source 的保持时间。

特殊键名：

space
tab
esc
escape

普通键写单字符：

keyboard.sin_wave: {from: keyboard.key, key: "0"}

4. 自定义 driver source

如果接 CRSF、SBUS、串口、UDP 或自定义 HID，source 仍然按同一套写：

sources:
  crsf:
    type: crsf
    signals:
      crsf.roll: {from: crsf.ch1, timeout_ms: 200, failsafe: 0.0}
      crsf.pitch: {from: crsf.ch2, timeout_ms: 200, failsafe: 0.0}
      crsf.throttle: {from: crsf.ch3, timeout_ms: 200, failsafe: 0.0}
      crsf.yaw: {from: crsf.ch4, timeout_ms: 200, failsafe: 0.0}
      crsf.mode: {from: crsf.ch5, timeout_ms: 200, failsafe: 0.0}

这里 crsf.ch1 等 raw source 由你的 CrsfInputDriver 产生。YAML 只负责解释这些 raw source。

如果新 driver 需要 device、baudrate 这类参数，需要在 C++ config 里加字段。具体看 手把手添加自定义遥控器驱动。

5. curves：曲线、死区和校准

curves 负责输入曲线处理。它可以在 control source 上引用。

expo 曲线：

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：指数曲线。
• deadzone：死区，小于等于该绝对值时输出 0。
• expo：指数强度，范围 [0, 1]。
• limit: [min, max]：输出限幅。
• min / max：等价的限幅字段。
• calibration.input：输入校准点 [min, center, max]。
• calibration.output：输出校准点 [min, center, max]。
• calibration.clamp：是否限制输入到校准范围内，默认 true。

分段曲线：

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

piecewise 适合非线性旋钮、三档开关的预处理。points 必须按 input 从小到大排序。

6. controls：统一控制量

controls 是配置里最重要的一层。后面的 outputs.when 应该判断 control，而不是直接判断 raw source。

6.1 analog control

controls:
  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

字段：

• type: analog：连续模拟量。
• source：单个 source。
• sources：多个 source。
• mix: max_abs：取绝对值最大的输入。
• mix: sum：求和后限幅到 [-1, 1]。
• mix: first_active：按顺序取第一个非零输入。
• direction：方向，-1 表示反向。
• scale：缩放。
• offset：偏移。
• curve：引用 curves 中的曲线。
• deadzone：control 层死区。
• min / max：输出范围。
• alpha：低通滤波系数，1.0 表示不滤波。
• expo：control 层指数曲线。
• invert：是否反向。

6.2 bool control

按钮：

controls:
  button.south: {type: bool, source: gamepad.a}

模拟轴当按钮：

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

字段：

• threshold：大于阈值时认为按下。
• hysteresis：迟滞，避免阈值附近抖动。
• invert：反向。

6.3 enum control

三档开关或多档模式推荐用 enum：

controls:
  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]

字段：

• default：没有匹配区间时使用的值。
• positions.<value>: [min, max]：枚举值对应的输入范围。
• hysteresis：当前枚举值保持范围扩展。

判断 enum：

when: [switch.mode=high]

或：

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

6.4 派生 bool control

复杂组合键可以先定义成 command.*：

controls:
  command.sin_wave:
    type: bool
    expr:
      any:
        - [trigger.right, button.west]
        - [keyboard.sin_wave]

再在 outputs 里复用：

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

默认配置可以保持简单。如果某个组合只用一次，也可以直接写在 outputs.when 里。

7. outputs：写入 MotionCommands

outputs 是最后一层。

outputs:
  conflict_policy: first_wins
  publish_on_change: true

  analog:
    vel_des.x: move.vx
    vel_des.y: move.vy
    yawdot_des: move.yaw

  edge:
    - output: system.start
      when: [system.start]

  level:
    - output: btn_1=1
      when:
        any:
          - [shoulder.right, button.west]
          - [keyboard.normal]

顶层字段：

• conflict_policy: first_wins：同一个 btn_N 被多个 binding 写入不同值时，保留先匹配的。
• conflict_policy: last_wins：后匹配的覆盖先匹配的。
• conflict_policy: error：冲突时报错。
• publish_on_change: true：只有 payload 变化时才发布 MotionCommands。
• publish_on_change: false：固定频率发布。

7.1 analog

analog 写连续字段，推荐直接写 MotionCommands 字段路径：

outputs:
  analog:
    vel_des.x: move.vx
    vel_des.y: move.vy
    vel_des.z: move.vz
    yawdot_des: move.yaw
    height_des: body.height

当前支持的简写：

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

高级写法：

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

7.2 level

level 是电平输出。条件满足时持续写值，条件不满足时自动回 0。

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

适合：

• 按住期间持续有效的按钮。
• 旧逻辑里需要保持 btn_N=1 的命令。

当前设计不需要 release_outputs。level 每次刷新都会重新计算所有 binding，组合键不满足时对应 btn_N 自然回 0。

7.3 edge

edge 是上升沿输出。条件从 false 变 true 时输出一帧。

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

适合：

• 状态切换。
• toggle / pause。
• system.start、system.stop。

对于 btn_N=value，下一帧自动回 0。对于 system.*，只执行一次命令。

8. when 条件语法

单个 control：

when: [keyboard.normal]

多个 control 同时满足：

when: [shoulder.right, button.west]

任意一组满足：

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

显式 pressed：

when:
  - pressed: button.west

显式 released：

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

枚举等于：

when:
  - switch.mode=high

范围判断：

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

9. system：执行系统命令

outputs.edge 可以触发 system.*：

outputs:
  edge:
    - output: system.start
      when: [system.start]

然后在 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 &"

  stop:
    - "pkill -f example_demo_hw.launch.py"

互斥锁：

system_mutexes:
  launch:
    acquire: start
    release: stop

清零运动输入：

system_reset_motion_after:
  - stop

10. 添加一个新按键的最小流程

目标：按键盘 0 触发 btn_10=5。

1. 在 sources.keyboard.signals 添加：

keyboard.sin_wave: {from: keyboard.key, key: "0"}

2. 在 controls 添加：

keyboard.sin_wave: {type: bool, source: keyboard.sin_wave}

3. 在 outputs.edge 添加：

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

4. 如果这是状态切换，去 elf3_state_machine.yaml 添加对应 remote_events 和 transitions。

下一步看 状态机 YAML 配置。