Debugging

调试、验证与常见问题

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

1. 编译

常用编译：

colcon build --packages-select remote_controller bxi_example_py_elf3

加载环境：

source install/setup.bash

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

如果正在调试热重载，不建议使用 --symlink-install。普通 build 会在代码修改完成后更新 install/ 目录并触发一次热重载；--symlink-install 可能因为编辑器自动保存而频繁触发热重载。

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 里，或者已被 robot_states.py 导入。
• YAML 里的 behavior 是否和类名完全一致。

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

检查：

• on_update() 是否调用 ctx.set_motor_target()。
• timer_callback() 中是否有 motor_target。
• 状态是否处于 transition 中。普通过渡期间不会调用当前状态 on_update()；dual_running_blend 会调用状态的 get_transition_frame()，再混合后发给电机。
• 是否刚进入状态就被安全逻辑切到其他状态。

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

检查：

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

9. dual_running_blend 没有运行混合效果

检查：

• 状态是否实现了 get_motor_frame() 或 get_transition_frame()。
• get_motor_frame() 是否只返回 (qpos, kp, kd)，没有直接调用 ctx.set_motor_target()。
• transition.data.run_from / run_to 是否为 true。
• 某一侧采样不到时，是否被 from_fallback / to_fallback 退化成了 last_motor 或 first_frame。

10. publish_on_change 下机器人突然停

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

排查：

• BxiExample 是否保持上一次收到的原始速度到 raw_cmd_vel / current_raw_cmd_vel。
• 当前状态是否调用了 self.get_cmd_vel(ctx)；基类会把处理后的速度写入 current_cmd_vel。
• 当前状态是否配置了 speed_profile；没有 profile 时默认返回零速度。
• driver 是否错误触发了 failsafe。
• timeout_ms 是否过小。
• driver 在设备连接但值不变时是否调用了 touch_runtime_sources_with_prefix()。

11. 摇杆不动触发 failsafe

这是 driver 心跳问题。

正确逻辑：

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

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

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

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

检查：

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

13. 多个输出写同一个 btn

检查：

outputs:
  conflict_policy: first_wins

可选值：

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

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

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

检查：

• release_protection.yaml 的 protected_states.<state> 是否和状态名一致。
• behavior 是否包含所有需要删除的类。
• 要删除的模型文件是否都显式写在 files 中。
• model_keys 是否和 self.<model_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

15. 热重载没有生效或有明显延迟

先确认热重载是否开启：

• 仿真 example_demo.launch.py 默认 "/hot_reload": True。
• 硬件 example_demo_hw.launch.py 支持热重载，但默认 "/hot_reload": False。
• 真机上临时开启前先在仿真验证，并确认机器人处于安全姿态。

检查改动位置：

• 换模型路径：改 bxi_example_demo.py 的 load_models()。
• 覆盖模型文件：确认 .onnx / .npz 是当前 load_models() 正在引用的文件。
• 改状态类：改 robot_states.py。
• 改状态机结构：改 elf3_state_machine.yaml。
• 改遥控器映射：改 remote_controller/config/xbox_default.yaml。
• 改 launch 参数：需要重启 launch，不能靠热重载。

推荐触发方式：

• 不使用 --symlink-install。
• 修改 src/ 下代码或模型。
• 修改完成后执行对应 package 的 colcon build --packages-select ...。
• build 更新 install/ 目录后，运行中的 demo 节点或 remote_controller 会看到文件变化并触发热重载。

如果使用了 --symlink-install：

• 编辑器自动保存可能导致还没改完就触发热重载。
• 保存多次会触发多次重载。
• 真机上尤其不建议这样调试。

如果看到 actuator delay：

• 模型加载已放到后台线程，正常情况下控制循环只做最终替换。
• robot_states.py 和 elf3_state_machine.yaml 的结构热重载仍是同步提交，真机上不要在高风险动作中修改。
• 新模型很大时可能仍有 CPU/内存带宽竞争，先在仿真观察日志和控制周期。

更多说明看 热重载。

16. 最小验证 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 配置。