Wiki
綜合工程與系統排錯
約 4 分鐘閱讀
本文由簡體中文內容確定性轉換，並受版本化術語表保護。
整理最終文件與運行入口，按從配置到設備反饋的順序排查問題。
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.運行方式
| 後端 | 入口 | 前提 |
|---|---|---|
| 自編模擬硬件 | 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 總覽 · 上一篇：完整機械人與進階實例