Debugging

调试、验证与常见问题

本页按症状排查遥控器、状态机、过渡、driver 和发布保护问题。

1. 编译

常用编译：

colcon build --symlink-install --packages-select remote_controller bxi_example_py_elf3

加载环境：

source install/setup.bash

如果只改 wiki，不需要编译。

2. 单独看遥控器输出

手柄：

ros2 launch remote_controller remote_controller.launch.py

键盘：

ros2 launch remote_controller remote_controller_keyboard.launch.py

观察：

ros2 topic echo /motion_commands

publish_on_change: true 时，只有 payload 变化才会发布。调试时可以临时改：

outputs:
  publish_on_change: false

3. 看状态机信息

ros2 topic echo /simulation/state_machine_info

会看到：

• 当前状态名和 id。
• 是否正在 transition。
• transition 的 from / to / progress。
• pending transition。
• 本周期收到的 events。
• 当前速度命令。
• 状态图快照。

如果用了不同 topic_prefix，话题是：

<topic_prefix>state_machine_info

4. 看状态图

默认配置会导出：

/tmp/elf3_state_machine.dot
/tmp/elf3_state_machine.mmd

Mermaid 文件可以贴到支持 Mermaid 的 Markdown 查看器。

5. 按键没反应

按顺序查：

1. sources.*.signals 是否声明 source。
2. controls 是否引用这个 source。
3. outputs.edge / outputs.level 的 when 是否引用 control 名。
4. /motion_commands 中对应 btn_N 是否变化。
5. elf3_state_machine.yaml 的 remote_events 是否匹配 slot/value。
6. 当前状态的 transitions.on_event 是否监听该 event。
7. /simulation/state_machine_info 的 events 是否出现目标 event。

6. 状态类找不到

检查：

• 类是否继承 RobotControlState。
• 类所在文件是否被 robot_states.py 导入。
• 如果新建了子包，setup.py 的 packages 是否加入该子包。
• YAML 里的 behavior 是否和类名完全一致。

7. 状态切换了但动作没执行

检查：

• on_update() 是否调用 ctx.set_motor_target()。
• timer_callback() 中是否有 motor_target。
• 状态是否处于 transition 中，transition 期间不会调用当前状态 on_update()。
• 是否刚进入状态就被安全逻辑切到其他状态。

8. 切换时机器人突然软掉

检查：

• transition 是否使用了合适的 enter_behavior。
• 目标状态是否实现 get_first_frame()。
• first_frame_ramp_kp 的 data.kp_start 是否是你期望的值。
• kp/kd 数组 shape 是否和 dof 数一致。

9. publish_on_change 下机器人突然停

正常设计里，publish_on_change: true 只是减少重复发布，不应该导致机器人因为输入没变而停下。

排查：

• BxiExample 是否保持上一次收到的速度。
• driver 是否错误触发了 failsafe。
• timeout_ms 是否过小。
• driver 在设备连接但值不变时是否调用了 touch_runtime_sources_with_prefix()。

10. 摇杆不动触发 failsafe

这是 driver 心跳问题。

正确逻辑：

设备连接正常，只是值没变
  -> touch_runtime_sources_with_prefix("js.") 或 "crsf."

设备断开或长期没有有效帧
  -> 不 touch，让 timeout_ms/failsafe 生效

11. Ctrl+C 无法退出遥控器节点

driver 不能永久阻塞在 read()。

检查：

• fd 是否非阻塞。
• 是否用 select() / poll() 带超时等待。
• 循环里是否定期检查 stop_flag_。
• stop() 是否能关闭 fd 或打断阻塞。

12. 多个输出写同一个 btn

检查：

outputs:
  conflict_policy: first_wins

可选值：

• first_wins：先匹配的生效。
• last_wins：后匹配的生效。
• error：冲突时报错。

调试阶段可以用 error 尽早发现配置冲突。

13. release 脚本删多了或没删干净

检查：

• release_protection.yaml 的 protected_states.<state> 是否和状态名一致。
• behavior 是否包含所有需要删除的类。
• events 是否包含状态机事件。
• model_keys 是否和 self.<model_key> 以及 launch 字典 key 一致。
• files 相对路径是否按 manifest 所在目录解析。

运行：

python3 tools/sanitize_release.py \
  --manifest src/bxi_example_py_elf3/config/release_protection.yaml \
  --out dist/public_release \
  --self-check

手动扫残留：

rg "BackFlipState|ForwardFlipState|back_flip|forward_flip" dist/public_release

14. 最小验证 checklist

新增状态后：

1. colcon build 通过。
2. /motion_commands 能看到目标 btn_N/value。
3. /simulation/state_machine_info 的 events 出现目标 event。
4. current.name 切到新状态。
5. transition 信息符合预期。
6. 新状态 on_update 输出电机目标。

新增 driver 后：

1. remote_controller 能以 --driver <name> 启动。
2. 设备断开能重连或输出明确日志。
3. Ctrl+C 能退出。
4. 输入不变不会误触发 failsafe。
5. 设备断联会触发 failsafe。
6. /motion_commands 输出符合 YAML 配置。