Wiki

綜合工程與系統排錯

更新於 2023-12-30約 4 分鐘閱讀

本文由簡體中文內容確定性轉換，並受版本化術語表保護。

本節把已有文件、運行方式和排錯順序整理在一起。運行環境發生變化時，用這張地圖逐段確認。

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 --once

4.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 總覽 · 上一篇：完整機械人與進階實例