📚 课程目录第4章命令行工具

4. 命令行工具：使用 ros2 node、ros2 topic、ros2 service 等命令进行调试

ROS2 系统运行起来后，节点之间通过话题、服务、动作等机制进行通信。这些通信发生在系统内部，肉眼无法直接观察。当系统出现“节点没启动”“话题没数据”“服务调不通”等问题时，我们需要一套“透视镜”来观察系统内部状态。ROS2 命令行工具就是这套透视镜，它让我们能够以文本方式查看节点列表、话题列表、消息内容、服务调用情况，从而定位问题。

4.1 核心原理：命令行工具如何“看到”系统

ROS2 命令行工具本身并不直接连接各个节点，而是通过 DDS（数据分发服务） 的底层发现机制来获取系统信息。每个节点启动时，都会在 DDS 域（默认 domain ID 为 0）中广播自己的存在，并声明自己发布/订阅的话题、提供的服务等。命令行工具同样作为一个“临时节点”加入这个域，通过 DDS 的发现协议收集所有节点的元数据，再以表格或列表形式呈现给用户。

理解这一点很重要：命令行工具看到的是 DDS 层的逻辑视图，而不是进程视图。也就是说，即使一个节点进程崩溃了，只要它的 DDS 实体没有正确清理，工具可能仍会短暂显示它；反之，如果两个节点不在同一个 domain ID 或同一网段，工具就看不到它们。因此，排查通信问题时，第一步永远是确认“工具能否看到节点”，而不是直接怀疑代码逻辑。

核心命令速查：

ros2 node list —— 查看当前所有活跃节点
ros2 node info <node_name> —— 查看某节点的发布者、订阅者、服务客户端/服务端
ros2 topic list —— 查看所有话题
ros2 topic echo <topic_name> —— 实时打印话题消息内容
ros2 topic info <topic_name> —— 查看话题的消息类型、发布者/订阅者数量
ros2 service list —— 查看所有服务
ros2 service type <service_name> —— 查看服务接口类型
ros2 service call <service_name> <type> <arguments> —— 手动调用服务

4.2 方法流程：从“看不到”到“看得清”的调试路径

当系统出现通信异常时，建议按照以下流程逐层排查，而不是盲目修改代码。这个流程的核心思想是：先确认系统级可见性，再确认节点级连接，最后确认消息内容。

第一步：查看节点列表 —— 运行 ros2 node list，确认所有预期节点是否都已启动。如果缺少某个节点，检查该节点的启动命令、依赖库、配置文件。
第二步：查看节点详情 —— 对每个关键节点运行 ros2 node info <node_name>，检查其发布者、订阅者、服务端/客户端是否与设计一致。例如，发布节点应出现在“Publisher”列表，订阅节点应出现在“Subscription”列表。
第三步：查看话题列表与类型 —— 运行 ros2 topic list -t 查看所有话题及其消息类型。确认话题名称拼写一致、消息类型匹配。类型不匹配是常见错误，例如发布 std_msgs/msg/String 而订阅方使用 std_msgs/msg/Int32。
第四步：检查话题通信频率与内容 —— 运行 ros2 topic hz <topic_name> 查看发布频率，运行 ros2 topic echo <topic_name> 查看消息内容。如果频率为 0，说明发布方未发送；如果内容异常，检查数据生成逻辑。
第五步：服务排查 —— 运行 ros2 service list 查看服务是否注册，用 ros2 service type 确认接口类型，最后用 ros2 service call 手动调用服务，验证服务端逻辑是否正常。

实用技巧： 使用 ros2 topic echo --once 只打印一条消息就退出，适合在脚本中检查；使用 ros2 topic echo --field data 只打印某个字段，减少输出干扰。对于服务，ros2 service find <type_name> 可以反向查找提供某类型服务的所有服务端。

4.3 案例：用命令行定位“话题收不到数据”问题

假设我们运行了一个发布节点 /sensor_node 和一个订阅节点 /display_node，预期 /sensor_node 每 100ms 发布一次 sensor_msgs/msg/LaserScan 到 /scan 话题，但 /display_node 收不到任何数据。我们按流程排查：

# 1. 查看节点是否都在运行
$ ros2 node list
/display_node
/sensor_node

# 2. 查看发布节点详情
$ ros2 node info /sensor_node
Publishers:
  /scan: sensor_msgs/msg/LaserScan
Subscribers: (none)

# 3. 查看订阅节点详情
$ ros2 node info /display_node
Publishers: (none)
Subscribers:
  /scan: sensor_msgs/msg/LaserScan

# 4. 查看话题实时频率
$ ros2 topic hz /scan
average rate: 0.000
  min: 0.000s max: 0.000s std dev: 0.000s

# 5. 查看话题内容
$ ros2 topic echo /scan --once
# 没有任何输出，说明话题上确实没有消息流动

从第 4 步可以看出话题频率为 0，说明发布方没有实际发送数据。此时检查 /sensor_node 的代码，发现发布循环中使用了 rclcpp::sleep_for(100ms)，但发布逻辑被一个永远为 false 的条件包裹，导致从未执行发布。修复后再次运行 ros2 topic hz /scan，显示频率约为 10Hz，问题解决。

这个案例说明：命令行工具能快速缩小问题范围——节点都在、话题连接正确、类型匹配，问题就出在发布方的执行逻辑上。如果没有这些工具，我们可能需要在代码中加大量打印来定位，效率极低。

4.4 误区与复盘：常见使用陷阱

误区	现象	正确做法
只查 `topic list` 不查 `topic info`	话题存在但消息类型不匹配，订阅方静默丢弃	用 `ros2 topic info -v` 查看类型和连接数量
忽略 domain ID 不一致	两个节点在同一台机器却互相看不到	检查 `ROS_DOMAIN_ID` 环境变量是否一致
用 `Ctrl+C` 中断 `topic echo` 后误以为节点停止	echo 退出但发布节点仍在运行	echo 只是临时订阅者，不影响其他节点
服务调用时参数格式错误	报错 `Invalid service arguments`	先运行 `ros2 service type` 查看接口，再按 YAML 格式传参
在非 ROS2 环境下运行命令	提示 `command not found`	先 `source /opt/ros/<distro>/setup.bash`

重要提醒： 当使用 ros2 service call 手动调用服务时，参数必须使用 YAML 格式。例如调用 /talker_info（类型为 std_srvs/srv/Trigger），应写：

ros2 service call /talker_info std_srvs/srv/Trigger "{}"

如果服务有请求字段，例如 example_interfaces/srv/AddTwoInts，则写：

ros2 service call /add_two_ints example_interfaces/srv/AddTwoInts "{a: 3, b: 5}"

注意花括号内字段名必须与接口定义完全一致，否则会报参数解析错误。

4.5 复盘：命令行工具调试心法

通过以上案例和误区，我们可以总结出命令行工具调试的几条核心心法：

先看结构，再看数据 —— 先确认节点、话题、服务的存在性和连接关系，再深入查看消息内容。结构不对时，数据内容没有意义。
善用 -t、-v 等参数 —— ros2 topic list -t 同时显示类型，ros2 node info -v 显示更详细的 QoS 信息，这些细节往往能揭示隐藏问题。
QoS 策略不可忽视 —— 如果发布方和订阅方的 QoS 不兼容（如可靠性策略一个为 RELIABLE 一个为 BEST_EFFORT），命令行工具可能显示连接存在，但消息实际不流通。此时用 ros2 topic info -v 查看 QoS 配置。
日志与命令行结合 —— 命令行工具给出系统级视图，而节点自身的 rclcpp 日志给出进程内部状态。两者结合才能完整还原问题现场。

掌握这些命令和排查思路，你就能在 ROS2 开发中快速定位大部分通信问题。随着经验积累，你会发现命令行工具不仅是调试工具，更是理解 ROS2 运行时架构的最佳学习途径——通过观察节点、话题、服务的真实交互，你对“分布式通信”的理解会从抽象概念变成具体画面。