Wiki
综合工程与系统排错
About 4 min read
Existing English translations were reused. 21 current source blocks remain in Simplified Chinese, without triggering paid translation.
本节把已有文件、运行方式和排错顺序整理在一起。运行环境发生变化时，用这张地图逐段确认。
1.最终工程结构
~/ros2_control_humble_ws/
├── src/
│ ├── learn_control_hardware/
│ │ ├── package.xml
│ │ ├── CMakeLists.txt
│ │ ├── hardware_plugins.xml
│ │ ├── include/learn_control_hardware/mini_system.hpp
│ │ ├── src/mini_system.cpp
│ │ ├── src/serial_system.cpp
│ │ ├── config/controllers.yaml
│ │ ├── config/diff_controllers.yaml
│ │ ├── launch/mini.launch.py
│ │ ├── launch/sim.launch.py
│ │ └── urdf/
│ │ ├── mini.urdf
│ │ ├── mini_gz.urdf.xacro
│ │ ├── diff_gz.urdf.xacro
│ │ └── mini_serial.urdf
│ └── learn_position_controller/
│ ├── package.xml
│ ├── CMakeLists.txt
│ ├── controller_plugins.xml
│ └── src/hold_controller.cpp
├── tools/virtual_mcu.py
├── build/ colcon 生成
├── install/ colcon 生成
└── log/ colcon 生成前面的章节逐步创建这些文件，不需要一开始就建立全部内容。虚拟串口与模拟下位机完成后，硬件包的 CMakeLists 和插件 XML 使用包含串口插件的最终版本。
2.示例 1：从干净终端运行
source /opt/ros/humble/setup.bash
cd ~/ros2_control_humble_ws
colcon build --symlink-install --packages-select learn_control_hardware learn_position_controller
source install/setup.bash
ros2 pkg prefix learn_control_hardware
ros2 pkg prefix learn_position_controller确认两个路径都来自预期的学习工作区。若指向旧工作区，先解决 source 顺序，再排查 C++ 逻辑。
3.选择一个运行后端
一次只选择一个：
| 后端 | 入口 | 附加条件 |
|---|---|---|
| 自编模拟硬件 | mini.launch.py 默认模型 | 从零编写模拟硬件插件完成 |
| Fortress 机械臂 | sim.launch.py 默认模型 | 机械臂物理仿真完成 |
| Fortress 底盘 | sim.launch.py 指定 diff 模型与控制器 | 差速底盘物理仿真完成 |
| 虚拟串口双关节 | mini.launch.py 指定 mini_serial | socat 和模拟下位机先运行 |
| 真实硬件 | 设备专用模型与插件 | 按单执行器实物接入完成设备适配 |
4.示例 2：按顺序收集运行证据
ros2 node list
ros2 control list_hardware_components
ros2 control list_hardware_interfaces
ros2 control list_controllers
ros2 topic info /joint_states -v
ros2 topic echo /joint_states --once4.1.怎样解释这些证据
节点存在只表示进程或节点已出现；硬件 active 表示状态机通过；接口 claimed 表示命令资源已被借出；控制器 active 表示允许周期执行；反馈变化才说明数据链路产生了可观察结果。真实设备还要核对实际运动。
5.排错表
| 现象 | 优先检查 | 修复后怎样验证 |
|---|---|---|
| 找不到包 | 构建结果、source 和安装路径 | ros2 pkg prefix |
| 找不到插件 | 导出宏、XML、CMake 注册、库依赖 | 管理器成功加载硬件 |
| spawner 一直等待 | 管理器是否已收到有效模型 | list_controllers 服务可用 |
| 控制器配置失败 | 参数层级、关节名、接口组合 | inactive 状态 |
| 激活报资源冲突 | 已 claimed 的命令接口 | 原子切换后只剩一个写入者 |
| 发命令无反应 | Topic、类型、长度、时间戳、active 状态 | 目标与反馈一起观察 |
| RViz 不动 | JointState、TF、Fixed Frame、QoS | TF 与模型一致 |
| Gazebo 生成失败 | 惯量、模型转换、插件文件名 | 模型实际存在且管理器启动 |
| 仿真时间不走 | world 是否暂停、/clock 桥 | /clock 连续增加 |
| 轮子动但车不走 | 接触、摩擦、轴向、离地 | 世界位姿与里程计对照 |
| 串口状态过期 | 数据帧、线程错误、下位机是否运行 | 新有效反馈恢复且显式重启 |
6.示例 3：保存一次实验记录
记录以下内容：使用哪个模型与源码版本，当前参数，发送的完整目标，控制器与硬件状态，反馈采样，是否出现错误，以及停止后的状态。
对照总览中的学习验收表，记录当前实验的实际结果。示例输出用于帮助理解；实验记录应使用自己运行得到的状态、反馈和日志。
7.学完后应当能够做到
解释命令如何进入硬件接口；从头创建并运行硬件插件与控制器；区分 RViz 显示、程序模拟、物理仿真和实物；沿源码定位接口与生命周期问题；为具体设备设计反馈、超时与停机流程。
真实硬件接入的最后一步取决于实际设备协议与验证。仿真和虚拟串口通过，不应替代这一部分记录。
返回 Humble 总览 · 上一篇：完整机器人与进阶实例