ros2 CLI 指令大全
- ros2
- cli
- cheatsheet
問題定義
前面幾節陸續用到不少 ros2 指令，但都是穿插在範例裡零散出現。這一節把日常開發最常用的指令集中整理成速查表——目標不是背下每個指令的完整參數，而是知道「遇到什麼情境該用哪個指令」，需要細節時再回來查。
核心概念說明：ros2 指令的分類邏輯
ros2 CLI 的子指令基本上是照 ROS2 的核心概念分類的：node、topic、service、action、param 分別對應前面幾節介紹過的五種通訊機制，每一類底下都有類似的操作模式：list（列出目前有哪些）、info（看詳細資訊）、echo／call（實際互動）。掌握這個分類邏輯之後，遇到新的子指令也能很快猜到它大概在做什麼。
速查表
| 指令 | 分類 | 用途 |
|---|---|---|
ros2 node list | node | 列出所有執行中的節點 |
ros2 node info <node> | node | 看某節點的主題、服務、動作清單 |
ros2 topic list | topic | 列出所有主題 |
ros2 topic echo <topic> | topic | 即時印出主題收到的訊息 |
ros2 topic hz <topic> | topic | 量測主題的實際發布頻率 |
ros2 topic bw <topic> | topic | 量測主題的頻寬使用量 |
ros2 topic pub <topic> <type> <data> | topic | 手動發布一則訊息 |
ros2 topic info -v <topic> | topic | 看發布/訂閱端的數量與 QoS 設定 |
ros2 service list | service | 列出所有服務 |
ros2 service type <service> | service | 看服務使用的介面型別 |
ros2 service call <service> <type> <data> | service | 手動呼叫一次服務 |
ros2 action list | action | 列出所有動作 |
ros2 action info <action> | action | 看動作的 client/server 數量 |
ros2 action send_goal <action> <type> <data> | action | 手動送出一個 goal |
ros2 param list | param | 列出節點目前所有參數名稱 |
ros2 param get <node> <param> | param | 查詢單一參數目前的值 |
ros2 param set <node> <param> <value> | param | 動態修改單一參數 |
ros2 param dump <node> | param | 匯出節點目前所有參數為 yaml |
ros2 interface show <type> | interface | 看某個 msg/srv/action 的欄位定義 |
ros2 doctor | system | 健檢目前環境與系統狀態 |
常用指令詳解與輸出範例
以下沿用前幾節已經寫好的 talker／listener／add_server 節點（分別執行在各自的終端機），示範每個指令實際會看到的輸出。
節點相關
ros2 node list
/talker
/listener
/add_server
ros2 node info /talker
/talker
Subscribers:
Publishers:
/chatter: std_msgs/msg/String
/parameter_events: rcl_interfaces/msg/ParameterEvent
/rosout: rcl_interfaces/msg/Log
Service Servers:
/talker/describe_parameters: rcl_interfaces/srv/DescribeParameters
/talker/get_parameters: rcl_interfaces/srv/GetParameters
...
Action Servers:
Action Clients:
留意這裡列出的 describe_parameters、get_parameters 這類服務並不是你自己寫的——每個 ROS2 節點預設都會自動附帶一組參數相關的服務，這是 CLI 工具（例如 ros2 param get）底層實際呼叫的介面。
主題相關
ros2 topic hz /chatter
average rate: 2.001
min: 0.498s max: 0.502s std dev: 0.00145s window: 12
ros2 topic pub --once /ping std_msgs/msg/String "data: 'manual test'"
publisher: beginning loop
publishing #1: std_msgs.msg.String(data='manual test')
服務相關
ros2 service type /add_two_ints
my_package_msgs/srv/AddTwoInts
ros2 service call /add_two_ints my_package_msgs/srv/AddTwoInts "{a: 4, b: 6}"
waiting for service to become available...
requester: making request: my_package_msgs.srv.AddTwoInts_Request(a=4, b=6)
response:
my_package_msgs.srv.AddTwoInts_Response(sum=10)
參數相關
ros2 param list /talker
qos_overrides./parameter_events.publisher.depth
qos_overrides./parameter_events.publisher.durability
qos_overrides./parameter_events.publisher.history
use_sim_time
注意這裡出現的 qos_overrides.* 也是自動產生的系統參數，不是使用者自訂的——每個節點的內建 /parameter_events publisher，其 QoS 設定本身也被暴露成可調整的參數。
介面查詢
ros2 interface show my_package_msgs/action/Countdown
# Goal
int32 target_count
---
# Result
int32 total_elapsed_sec
---
# Feedback
int32 current_count
常見錯誤與除錯技巧
錯誤一：ros2 topic pub 打完指令後卡住不動，什麼都沒發生
publisher: beginning loop
原因：沒加 --once 旗標時，ros2 topic pub 預設會持續發布（通常是 1Hz），不會自動結束。這不是錯誤，而是預期行為，只是新手常常以為指令卡住了。
排除方式：需要單次發布用 --once；需要持續發布測試（例如模擬感測器資料流）才不加，並在確認完成後用 Ctrl+C 手動中斷。
錯誤二：ros2 service call 出現 Waiting for service... 卡住不結束
waiting for service to become available...
原因：目標服務的 Server 節點還沒啟動、名稱打錯，或是不同 ROS_DOMAIN_ID 導致互相看不到。CLI 工具會無限等待，不會自動逾時退出。
排除方式：先用 ros2 service list 確認服務名稱與是否存在，再確認執行 CLI 的終端機環境變數與目標節點一致：
ros2 service list | grep add_two_ints
echo $ROS_DOMAIN_ID
小結
ros2 CLI 的子指令分類跟 ROS2 的核心通訊概念一一對應，日常除錯多數情況下只會用到 list（看有什麼）、info -v（看細節與 QoS）、echo／call（手動互動）這幾種操作模式的組合。把這張速查表當字典查，比死背指令參數更實際。下一節會介紹另一個對除錯與重現問題很關鍵的工具：rosbag2，讓你能把整段資料流錄下來，事後重播分析。
延伸閱讀
常見問題
- 這些指令可以寫進 shell script 裡自動化嗎？
- 可以，多數 ros2 CLI 指令都支援 --no-daemon 或搭配 timeout 使用，也能用 ros2 topic echo --once 這類單次執行的旗標避免腳本卡住。但如果需要更結構化的自動化流程（多節點啟動、參數注入），通常會改用 launch 檔案，這在下一節會介紹。
- 為什麼 ros2 topic hz 顯示的頻率跟我 timer 設定的不一樣？
- ros2 topic hz 量測的是「實際收到訊息」的頻率，會反映真實的排程延遲、網路狀況等因素，本來就可能跟 timer 理論頻率有些微差距。如果差距很大（例如設定 10Hz 但實際只有 2Hz），才需要進一步排查是不是 callback 執行時間過長、或 executor 被其他工作佔用。
- ros2 topic echo 收不到任何輸出，但主題確實在 list 裡，為什麼？
- 常見原因是 QoS 不相容（本站第 2.2 節有詳細說明），或是主題確實存在但目前沒有任何 Publisher 真的在發布資料（只是曾經有節點宣告過這個主題）。用 ros2 topic info -v 檢查 Publisher count 是否為 0 可以快速排除後者。