跳至主要内容

CLI 基礎操作

ros2 命令列工具可以讓你在不閱讀原始碼的情況下，探索、檢查並操作一個正在執行中的 ROS 2 系統。本頁會介紹如何正確載入 ROS 2 環境，以及日常最常使用的探索與檢查指令。

概述​

每一個需要操作 ROS 2 的 Terminal，都必須先 source 對應的 setup script，讓正確的執行檔、函式庫與環境變數（例如 ROS_DISTRO、AMENT_PREFIX_PATH、PYTHONPATH 等）加入目前的 Shell 環境。

忘記執行這個步驟，是 ros2 指令無法使用，或找不到任何 Node / Topic 時最常見的原因之一。

為什麼重要​

幾乎每一次 ROS 2 Troubleshooting 都可能從同一個問題開始：

「我已經啟動 Node 了，但為什麼哪裡都看不到？」

在懷疑程式碼或網路問題之前，應先確認 ROS 2 環境已正確載入，並使用 ros2 CLI 查看系統目前實際執行的狀態。

這些指令也會反覆出現在 Publisher/Subscriber、Service 與 Action 以及 Troubleshooting 中。

核心概念​

載入 ROS 2 環境​

一般 ROS 2 安裝會針對各個 Distribution 提供 setup script。每次開啟新的 Shell 時，可以手動載入：

# Underlay（ROS 2 Distribution 本身）— 路徑與 Distribution 名稱依安裝環境而異
source /opt/ros/<distro>/setup.bash

# Overlay（使用 colcon 編譯的自訂 Workspace）— 必須在 Underlay 之後載入
source ~/ros2_ws/install/setup.bash

順序很重要：先載入 Underlay，再載入任何 Overlay Workspace。

載入 Overlay 後，該 Workspace 中已編譯的 Package 會加入目前環境，並建立在原本 ROS 2 Distribution 的 Package 之上，而不是取代它們。

確認環境是否已正確載入：

printenv ROS_DISTRO
printenv ROS_DOMAIN_ID    # 未設定或為空值時，等同使用 0
which ros2

ros2 指令家族​

ros2 是單一 CLI 入口，下面再依不同概念提供 Sub-command：

ros2 node ...       # nodes
ros2 topic ...       # topics
ros2 service ...     # services
ros2 action ...      # actions
ros2 param ...        # parameters
ros2 interface ...    # message/service/action definitions
ros2 pkg ...           # packages
ros2 run ...            # run a single node
ros2 launch ...          # run a launch file (possibly many nodes)
ros2 bag ...              # record/replay data — see Rosbag
ros2 doctor               # basic environment/network sanity checks

每個 Sub-command 都支援 --help，這通常是確認可用參數與 Flag 最快的方法：

ros2 topic --help
ros2 topic echo --help

實作步驟​

先啟動 Demo Talker，讓 ROS 2 Graph 中有可以檢查的內容。這需要 demo_nodes_cpp 或 demo_nodes_py Package；在 Desktop ROS 2 安裝中通常會預先安裝。

ros2 run demo_nodes_cpp talker

接著在第二個已經 source ROS 2 環境的 Terminal 中，依序執行以下指令：

# 1. Nodes
ros2 node list
ros2 node info /talker

# 2. Topics
ros2 topic list
ros2 topic list -t                 # 同時顯示 Message Type
ros2 topic echo /chatter           # 顯示即時 Message（Ctrl+C 停止）
ros2 topic hz /chatter             # 測量 Publish Rate
ros2 topic bw /chatter             # 測量 Bandwidth
ros2 topic info /chatter -v        # 查看 Publisher、Subscriber 與 QoS

# 3. Interfaces
ros2 interface show std_msgs/msg/String
ros2 topic type /chatter

# 4. Packages and executables
ros2 pkg list | grep demo_nodes
ros2 pkg executables demo_nodes_cpp

預期成果​

ros2 node list 應該會顯示 /talker。

ros2 topic echo /chatter 會大約每秒顯示一筆新的 String Message。

ros2 topic info /chatter -v 則會顯示一個 Publisher，以及該 Publisher 的 QoS Profile。

完成後，使用 Ctrl+C 停止 Talker。

常用指令​

# 快速檢查 ROS 2 環境與 Graph
ros2 doctor
ros2 doctor --report          # 顯示更完整的報告

# 查看目前正在執行的 ROS 2 Entity
ros2 node list
ros2 topic list -t
ros2 service list -t
ros2 action list -t

# 檢查特定項目
ros2 node info <node_name>
ros2 topic info <topic_name> -v
ros2 service type <service_name>
ros2 action info <action_name>

# Interface（定義），不是目前正在執行的 Instance
ros2 interface list
ros2 interface show <package>/msg/<Type>
ros2 interface show <package>/srv/<Type>
ros2 interface show <package>/action/<Type>

常見問題​

  • ros2: command not found — 目前這個 Shell 尚未載入 ROS 2 環境。先 source 對應 Distribution 的 setup script，再使用 which ros2 確認。
  • ros2 node list 沒有顯示任何內容，但 Node 明明正在執行 — 確認執行 Node 的 Terminal 與執行 CLI 的 Terminal 使用相同的 ROS_DOMAIN_ID。可參考 ROS 2 Domain ID 與 Troubleshooting。
  • Topic 出現在 ros2 topic list 中，但 echo 沒有任何輸出 — Topic 可能目前沒有 Active Publisher，或 Publisher / Subscriber 的 QoS 不相容。使用 ros2 topic info -v 檢查 QoS 詳細資訊，並參考 Troubleshooting。
  • Workspace 已經編譯完成，但找不到 Overlay 中的 Package — 可能是目前這個 Terminal 尚未 source Overlay，或是在 Build 完成前就已經 source。每次 colcon build 完成後，重新執行 source install/setup.bash。

重點整理​

  • 每次開啟新的 Terminal，都應先 source Underlay，再 source 任何 Overlay Workspace。
  • ros2 <noun> list 用來查看目前有哪些項目；ros2 <noun> info 用來查看其中一個特定項目的詳細資訊。
  • ros2 interface show 顯示的是 Type 的定義；ros2 topic echo 顯示的是正在傳輸的即時資料。
  • 當 ROS 2 環境看起來有問題時，ros2 doctor 是很適合優先執行的快速檢查工具。

下一步​

接著前往 Workspace 與 Package，開始建立自己的 ROS 2 Package，而不只是檢查既有的 ROS 2 系統。