Wiki
综合工程与系统排错
About 4 min read
Existing English translations were reused. 16 current source blocks remain in Simplified Chinese, without triggering paid translation.
整理最终文件与运行入口，按从配置到设备反馈的顺序排查问题。
1.最终工程结构
~/ros2_control_jazzy_ws/
├── src/
│ ├── jazzy_control_hardware/
│ │ ├── package.xml
│ │ ├── CMakeLists.txt
│ │ ├── hardware_plugins.xml
│ │ ├── include/jazzy_control_hardware/two_joint_system.hpp
│ │ ├── src/two_joint_system.cpp
│ │ ├── src/serial_system.cpp
│ │ ├── config/controllers.yaml
│ │ ├── config/diff_controllers.yaml
│ │ ├── launch/two_joint.launch.py
│ │ ├── launch/sim.launch.py
│ │ └── urdf/
│ │ ├── two_joint.urdf
│ │ ├── two_joint_gz.urdf.xacro
│ │ ├── diff_gz.urdf.xacro
│ │ └── two_joint_serial.urdf
│ └── jazzy_position_controller/
│ ├── package.xml
│ ├── CMakeLists.txt
│ ├── controller_plugins.xml
│ └── src/position_hold.cpp
├── tools/virtual_mcu.py
├── build/
├── install/
└── log/目录随着章节逐步建立。完成虚拟串口与模拟下位机后，硬件包使用包含串口插件的最终构建和注册文件。
2.示例 1：检查安装空间
source /opt/ros/jazzy/setup.bash
cd ~/ros2_control_jazzy_ws
colcon build --symlink-install --packages-select jazzy_control_hardware jazzy_position_controller
source install/setup.bash
ros2 pkg prefix jazzy_control_hardware
ros2 pkg prefix jazzy_position_controller路径应来自当前学习工作区。源代码存在不代表正在运行的库就是这份代码，尤其要检查其它工作区是否覆盖了包。
3.Operation Mode
| 后端 | 入口 | 前提 |
|---|---|---|
| 自编模拟硬件 | two_joint.launch.py 默认模型 | 从零编写模拟硬件插件 |
| Harmonic 机械臂 | sim.launch.py 默认模型 | Harmonic机械臂物理仿真 |
| Harmonic 底盘 | sim.launch.py 指定模型、配置和控制器 | Harmonic差速底盘仿真 |
| 虚拟串口 | two_joint.launch.py 指定串口模型 | 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 --once节点存在、组件 active、接口 claimed、反馈变化分别证明不同层次。实际机器人还需要核对真实运动与停止结果。
5.排错表
| 现象 | 首先检查 |
|---|---|
| 包找不到 | 构建、安装路径和 source 顺序 |
| C++ 类型不存在 | 子包版本和实际头文件路径 |
| 共享库符号找不到 | 库与依赖是否来自一致版本环境 |
| 插件加载失败 | 导出宏、XML、CMake 注册、库依赖 |
| spawner 一直等待 | 模型解析和管理器启动日志 |
| 控制器配置失败 | --param-file、参数层级、接口组合 |
| 激活资源冲突 | claimed 接口与当前 active 控制器 |
| 底盘不接收目标 | TwistStamped、Topic、时间戳和 /clock |
| RViz 不动 | JointState、TF、Fixed Frame、QoS |
| 仿真模型生成失败 | 质量惯量、插件路径和转换日志 |
| 轮子转但车不走 | 碰撞、接触、摩擦和轴向 |
| 串口反馈过期 | 数据帧、通信线程与设备状态 |
6.保存自己的验收记录
记录模型、源码版本、参数、完整目标、组件与控制器状态、反馈和停止结果。使用自己的实验结果，不把示例输出当作固定时间的精确标准。
完成本套教程后，应能独立创建硬件插件与控制器，解释从 Topic 到设备再回到反馈的完整链路，并沿源码定位参数、接口、生命周期和通信问题。
返回 Jazzy 总览 · 上一篇：完整机器人与进阶实例