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

4. 命令行工具：用 ros2 命令调试节点、话题、服务与参数

ROS2 将机器人系统拆分为松耦合的节点，节点之间通过话题、服务、动作和参数进行通信。当系统运行异常时，我们无法直接“看到”数据流，必须借助命令行工具进行观测与干预。本章围绕 ros2 node、ros2 topic、ros2 service、ros2 action、ros2 param 五组命令，讲解如何定位节点状态、检查消息流、调用服务、监控动作目标以及动态调整参数。这些命令是 ROS2 调试的基础，也是理解系统运行逻辑的入口。

4.1 核心原理：从“进程”到“图”的观测视角

ROS2 运行时是一个分布式计算图。每个节点是独立进程，通过 DDS（数据分发服务）进行通信。命令行工具的本质是：以用户身份与计算图交互，查询节点注册信息、订阅/发布关系、消息类型、服务接口等。与 ROS1 不同，ROS2 命令统一以 ros2 开头，后接子命令，且支持 Tab 补全和 --help 查看用法。

调试时最常用的逻辑顺序是：先看节点是否存活，再看话题是否连通，然后检查消息内容，最后通过服务或参数进行动态干预。下图展示了这一调试路径中各类命令的定位关系。

上图展示了调试时的推荐路径：先确认节点存在，再检查话题数据是否流动，若需要触发一次性操作则调用服务，若涉及长时间任务则监控动作，最后通过参数微调节点行为。实际调试中不必严格按此顺序，但该路径能帮助初学者快速建立排查框架。

4.2 方法流程：五组命令的典型用法

4.2.1 节点查询：ros2 node

节点是计算图的基本单元。调试的第一步通常是确认目标节点是否已启动、是否与预期节点建立连接。

# 列出所有活动节点
ros2 node list

# 查看某个节点的详细信息（订阅、发布、服务、动作）
ros2 node info /turtlesim

ros2 node info 输出中会列出该节点的订阅者、发布者、服务服务器、服务客户端、动作服务器、动作客户端。若发现某个话题的发布者或订阅者缺失，说明节点之间的连接可能未建立，需检查话题名称或消息类型是否匹配。

4.2.2 话题调试：ros2 topic

话题是 ROS2 中最常用的通信方式，适合持续性的数据流（如传感器数据、速度指令）。调试话题的核心是“看数据是否在流动、内容是否正确”。

# 列出所有话题及其消息类型
ros2 topic list -t

# 打印话题实时数据（Ctrl+C 停止）
ros2 topic echo /turtle1/cmd_vel

# 查看话题发布频率
ros2 topic hz /turtle1/pose

# 查看话题带宽
ros2 topic bw /turtle1/pose

# 手动发布一条消息（用于测试订阅端）
ros2 topic pub /turtle1/cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 2.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 1.8}}" --once

ros2 topic echo 是最常用的调试命令。若 echo 无输出，可能原因包括：话题名称拼写错误、消息类型不匹配、发布者未运行、或 DDS 网络隔离导致无法发现。此时应结合 ros2 topic info 查看发布者与订阅者数量。

4.2.3 服务调用：ros2 service

服务适合请求-响应模式，如“拍照”“获取地图”“重置位置”。服务调用是同步的，客户端发送请求后阻塞等待响应。

# 列出所有服务
ros2 service list

# 查看服务类型
ros2 service type /clear

# 调用服务（需提供完整参数）
ros2 service call /spawn turtlesim/srv/Spawn \
  "{x: 2.0, y: 2.0, theta: 0.2, name: 'turtle2'}"

调用服务时若提示参数错误，可使用 ros2 interface show <服务类型> 查看接口定义，确保字段名和类型正确。

4.2.4 动作监控：ros2 action

动作适用于长时间任务，如“导航到目标点”“执行轨迹”。动作与服务的区别在于：动作支持进度反馈和取消，适合需要持续监控的任务。

# 列出所有动作
ros2 action list

# 查看动作类型
ros2 action list -t

# 发送动作目标并等待结果
ros2 action send_goal /turtle1/rotate_absolute \
  turtlesim/action/RotateAbsolute "{theta: 3.14}" --feedback

加上 --feedback 参数后，终端会实时显示动作反馈（如当前旋转角度）。若动作执行超时或卡住，可使用 Ctrl+C 中断，但注意这不会自动取消动作目标，需另行处理。

4.2.5 参数动态配置：ros2 param

参数是节点的全局配置项，可在运行时读取和修改，无需重启节点。调试时经常需要临时调整 PID 系数、速度上限、日志级别等。

# 列出节点所有参数
ros2 param list /turtlesim

# 获取某个参数值
ros2 param get /turtlesim background_r

# 设置参数（立即生效）
ros2 param set /turtlesim background_r 150

# 将参数保存到文件（便于复现）
ros2 param dump /turtlesim

注意：并非所有参数都支持运行时修改。若节点未声明参数为“可动态设置”，ros2 param set 会返回错误。此时需修改节点的 declare_parameter 回调逻辑。

4.3 案例场景：用 turtlesim 模拟器完整调试一次

下面通过一个综合案例，演示如何用命令行工具排查“乌龟不动了”的问题。假设我们启动 turtlesim 后，发布速度指令但乌龟没有反应。

排查步骤：

检查节点是否存活：ros2 node list，确认 /turtlesim 存在。
查看话题连接：ros2 topic info /turtle1/cmd_vel，若显示 Publisher count: 0，说明没有节点在发布速度指令。
手动发布测试：执行 ros2 topic pub --once 命令，若乌龟开始移动，说明订阅端正常，问题出在发布端。
检查服务可用性：调用 ros2 service call /reset std_srvs/srv/Empty "{}"，若乌龟回到原点，说明服务通信正常。
调整参数观察效果：用 ros2 param set /turtlesim background_b 0 改变背景色，若颜色变化，说明参数通道畅通。

通过上述步骤，我们可以将问题定位到“发布端未运行”或“话题名称不匹配”，而不是盲目重启节点。

4.4 误区与复盘：常见调试陷阱

误区	现象	正确做法
只 echo 不查类型	echo 报错 “type mismatch”	先用 `ros2 topic list -t` 确认类型
忽略命名空间	节点列表有节点，但 topic 找不到	使用 `ros2 node info` 查看完整话题路径
服务调用参数格式错误	YAML 解析失败	用 `ros2 interface show` 查看字段定义
动作目标未取消	Ctrl+C 后节点仍执行动作	使用 `ros2 action send_goal` 时记录 goal_id，必要时调用取消接口
param set 不生效	参数值未变化	检查节点是否声明了 `set_callback` 或参数为 const

重要提醒：在真实机器人上调试时，ros2 topic pub 和 ros2 service call 可能触发实际运动或执行机构动作。务必在安全环境下测试，并确保急停开关可用。另外，ros2 param set 修改的参数在节点重启后会恢复默认值，若需持久化应使用 ros2 param dump 保存。

复盘一次典型故障：某次调试中，ros2 topic echo /scan 无输出，但 ros2 node info 显示激光雷达节点存在。最终发现是激光雷达驱动节点运行在另一台机器上，且未配置相同的 ROS_DOMAIN_ID，导致 DDS 无法跨主机发现。这提醒我们：ROS2 的调试不仅限于单机，还需关注环境变量和网络配置。