机器人 / 系统课时
用接口命令核对消息字段
用接口命令核对消息字段
接入机器人底盘或激光雷达时,需要确认话题使用什么消息类型、消息包含哪些字段,以及运行时实际传输了什么值。本篇使用 ROS 2 Jazzy 的 ros2 interface、ros2 topic info 和 ros2 topic echo,分别检查速度指令 Twist 与激光扫描 LaserScan,并用独立演示话题完成验证。
学习目标
- 使用
ros2 interface show查看标准消息类型及嵌套字段。 - 正确识别 Twist 的速度分量与 LaserScan 的角度、距离数组和单位。
- 使用
ros2 topic info与ros2 topic echo交叉核对话题类型和实时数据。
确认 Jazzy 环境
以下命令适用于 Ubuntu 24.04 与 ROS 2 Jazzy。打开终端,先加载 ROS 环境,再检查发行版标识。已有自定义工作空间时,还需要在此基础上加载对应的 install/setup.bash,否则新生成的接口可能无法被发现。
# 加载 Jazzy 环境并确认当前发行版
source /opt/ros/jazzy/setup.bash
printf 'ROS_DISTRO=%s\n' "$ROS_DISTRO"预期输出:
ROS_DISTRO=jazzy本篇使用 geometry_msgs 与 sensor_msgs 中的标准消息类型,不需要连接真实机器人或启动 Gazebo。后续发布测试消息时使用 /inspect_cmd_vel 和 /inspect_scan,避免直接向真实底盘的 /cmd_vel 发送运动指令。
读取 Twist 的嵌套字段
geometry_msgs/msg/Twist 表示线速度与角速度,具有两个顶层字段:linear 和 angular。二者的类型都是 geometry_msgs/msg/Vector3,每个向量又包含三个 float64 分量。
执行下面的命令,分别查看 Twist 的成员以及 Vector3 的定义。这里使用 awk 过滤注释和重复展开的内容,便于核对字段名称。
# 先查 Twist 的成员,再查 Vector3 的数值字段
ros2 interface show geometry_msgs/msg/Twist | awk '$1 == "Vector3" {print $1, $2}'
ros2 interface show geometry_msgs/msg/Vector3 | awk '$1 == "float64" {print $1, $2}'预期输出:
Vector3 linear
Vector3 angular
float64 x
float64 y
float64 z去掉过滤管道,直接运行 ros2 interface show geometry_msgs/msg/Twist,还能看到展开后的子字段和接口注释。完整字段的含义如下。
| 字段路径 | 类型 | 常见用途 |
|---|---|---|
linear.x |
float64 | 前进或后退线速度,m/s |
linear.y |
float64 | 横向线速度,m/s |
linear.z |
float64 | 竖直线速度,m/s |
angular.x |
float64 | 绕 X 轴角速度,rad/s |
angular.y |
float64 | 绕 Y 轴角速度,rad/s |
angular.z |
float64 | 绕 Z 轴角速度,rad/s |
对于常见的平面双轮差速机器人,通常只使用 linear.x 和 angular.z:前者控制沿车体前方的移动,后者控制绕竖直轴旋转。其余分量通常设为 0,但这属于底盘运动约束,并不是 Twist 消息类型本身的限制。
例如,linear.x = 0.25 表示沿正 X 方向的线速度为 0.25 m/s,angular.z = 0.5 表示绕正 Z 轴的角速度为 0.5 rad/s。具体运动方向仍取决于接收节点采用的坐标约定。
读取 LaserScan 的数组字段
sensor_msgs/msg/LaserScan 表示一次平面激光扫描。它不仅包含距离值,还携带扫描角度、测距范围、采样时间及坐标系信息。先查看接口定义中的浮点字段。
# 提取 LaserScan 的 float32 标量和数组定义
ros2 interface show sensor_msgs/msg/LaserScan | awk '$1 ~ /^float32/ {print $1, $2}'预期输出:
float32 angle_min
float32 angle_max
float32 angle_increment
float32 time_increment
float32 scan_time
float32 range_min
float32 range_max
float32[] ranges
float32[] intensities接口还包含 std_msgs/Header header,其中的 stamp 表示首条激光射线的采集时间,frame_id 表示测量所使用的坐标系。
| 字段 | 含义与单位 |
|---|---|
angle_min、angle_max |
扫描起始和结束角度,rad |
angle_increment |
相邻采样射线的角度间隔,rad |
time_increment |
相邻测量的时间间隔,s |
scan_time |
相邻两次扫描的时间间隔,s |
range_min、range_max |
有效测距范围的下限和上限,m |
ranges |
各采样方向的距离数组,单位 m |
intensities |
各采样方向的反射强度数组,单位由设备定义 |
float32[] 中的方括号表示可变长度数组,不能把 ranges 当成单个浮点数。若传感器未提供强度数据,intensities 可以为空数组。
第 个距离样本对应的角度可按以下公式计算,数组下标从 0 开始:
例如,angle_min = -0.5、angle_increment = 0.5,且 ranges 有 3 个元素时,三个方向分别是 -0.5、0 和 0.5 rad,与 angle_max = 0.5 一致。超出 range_min 和 range_max 的距离值不应直接作为有效障碍物测量使用。

使用话题命令核对实时数据
ros2 interface show 读取的是消息类型的静态定义,即使没有节点运行也可以使用。ros2 topic info 查看当前话题的类型和通信端点数量,ros2 topic echo 则需要有实际发布的消息才能输出字段值。
为了验证这三种命令,分别创建两个持续发布的演示话题。打开三个终端,均执行 source /opt/ros/jazzy/setup.bash,然后按以下顺序操作。
发布速度测试消息
在终端 A 运行:
# 使用独立话题,避免影响真实机器人运动
ros2 topic pub -r 1 /inspect_cmd_vel geometry_msgs/msg/Twist '{linear: {x: 0.25}, angular: {z: 0.5}}'预期输出中会出现:
publisher: beginning loop随后终端会持续显示 publishing #1、publishing #2 等消息记录。-r 1 表示每秒发布一次;未显式填写的速度分量使用默认值 0。保持该终端运行。
发布激光扫描测试消息
在终端 B 运行以下命令。这里使用三个固定距离构造一帧扫描,不依赖真实激光雷达。
# 三个距离元素分别对应 -0.5、0、0.5 rad
ros2 topic pub -r 1 /inspect_scan sensor_msgs/msg/LaserScan '{header: {frame_id: laser}, angle_min: -0.5, angle_max: 0.5, angle_increment: 0.5, scan_time: 1.0, range_min: 0.25, range_max: 8.0, ranges: [1.0, 1.5, 2.0]}'预期输出中会出现:
publisher: beginning loop终端将每秒发布一次 LaserScan。未填写的 time_increment 默认为 0,intensities 默认为空数组,header.stamp 也保持默认零时间戳。因此,这组消息仅用于字段结构验收,不能代表具有真实时间信息的雷达采样。
查询话题类型与字段值
在终端 C 依次运行以下命令。info 检查通信类型和端点数量,echo --once 收到一条消息后自动退出,便于比较两个话题。
# 对同一个话题先查类型,再查消息内容
ros2 topic info /inspect_cmd_vel
ros2 topic echo /inspect_cmd_vel --once
ros2 topic info /inspect_scan
ros2 topic echo /inspect_scan --once预期输出的关键内容如下,已省略部分默认字段、输出分隔标记和重复内容:
Type: geometry_msgs/msg/Twist
Publisher count: 1
Subscription count: 0
linear:
x: 0.25
angular:
z: 0.5
Type: sensor_msgs/msg/LaserScan
Publisher count: 1
Subscription count: 0
header:
stamp:
sec: 0
nanosec: 0
frame_id: laser
angle_min: -0.5
angle_max: 0.5
angle_increment: 0.5
ranges:
- 1.0
- 1.5
- 2.0
intensities: []Publisher count 和 Subscription count 是查询瞬间的端点数量。如果还有其他节点接入,数值可能变化。这里的订阅数为 0,是因为执行 info 时后续的 echo 尚未启动。
完成检查后,应该能够确认以下对应关系:
/inspect_cmd_vel的类型为geometry_msgs/msg/Twist,其linear.x和angular.z与发送值一致。/inspect_scan的类型为sensor_msgs/msg/LaserScan,其ranges数组长度为 3,元素分别为 1.0、1.5、2.0 m。- LaserScan 的三个距离元素与
angle_min、angle_increment定义的三个角度一一对应。
无消息或字段不符时怎么排查
如果 ros2 interface show 可以显示接口,但 ros2 topic echo 一直没有结果,不要立即判断消息定义错误。应按环境、话题、发布者、通信 QoS 的顺序检查。
首先在终端 C 查看演示话题是否存在,以及当前声明的消息类型。
# 列出当前话题及其消息类型
ros2 topic list -t | grep '^/inspect_'两个发布终端正常运行时,预期输出为:
/inspect_cmd_vel [geometry_msgs/msg/Twist]
/inspect_scan [sensor_msgs/msg/LaserScan]若没有任何匹配结果,检查终端 A、B 是否仍在发布,并确认三个终端使用相同的 ROS_DOMAIN_ID 和网络发现环境。grep 本身不会等待话题出现,因此应在发布者启动后再执行检查。
常见问题及处理方法:
| 现象 | 排查与修正 |
|---|---|
interface show 找不到类型 |
检查 Jazzy 环境及 geometry_msgs、sensor_msgs 是否已安装;自定义接口还需构建并加载工作空间 |
topic info 显示发布者数量为 0 |
确认发布命令仍在运行,检查话题名称和 ROS Domain |
echo 持续等待 |
先确认发布者存在,再检查发布与订阅端的 QoS 是否兼容 |
ranges 没有预期的三个元素 |
检查发送的 YAML 数组内容和字段名,不能写成单个 range |
| 速度字段读取结果不符 | 核对 linear.x 与 angular.z,避免混淆线速度和角速度 |
对于真实雷达的 /scan 话题,如果发布端采用 Best Effort 可靠性策略,默认订阅设置不兼容时可以尝试显式指定可靠性。
# 适用于已启动且发布 LaserScan 的 /scan 话题
ros2 topic echo /scan --qos-reliability best_effort --once预期结果:在发布端 QoS 兼容且持续发送消息的情况下,终端显示一帧 LaserScan 的 header、角度参数及距离数组,然后退出。如果没有 /scan 发布者,该命令会等待消息,不会凭空生成扫描数据。
完成实验后,在终端 A、B 按 Ctrl+C 停止测试发布者。以后接入新设备时,按照话题类型、接口字段定义、实时字段值三个层次依次核对,就可以判断问题发生在类型声明、消息组织还是实际数据发布环节。