万俟淋曦

ROS Topic 相关API接口与命令行介绍

- 一、Topic
- - 1.1 常用函数接口
  - - ros::Publisher类
    - ros::Subscriber类
  - 1.2 常用命令行工具
  - - rostopic相关
    - - 1.2.1 rostopic bw
      - 1.2.2 rostopic delay
      - 1.2.3 rostopic echo
      - rostopic echo --offset
        
        rostopic echo --filter
        
        rostopic echo -c
        
        rostopic echo -b
        
        rostopic echo -p
        
        rostopic echo -w
        
        rostopic echo -n
      - 1.2.4 rostopic find
      - 1.2.5 rostopic hz
      - rostopic hz -w
        
        rostopic hz --filter
      - 1.2.6 rostopic info
      - 1.2.7 rostopic list
      - rostopic list <名空间>
        
        rostopic list -b
        
        rostopic list -p
        
        rostopic list -s
        
        rostopic list -v
        
        rostopic list --host
      - 1.2.8 rostopic pub
      - rostopic pub -l/--latch
        
        rostopic pub -r RATE
        
        rostopic pub -1/--once
        
        rostopic pub -f FILE
      - 1.2.9 rostopic type
    - rosmsg 相关
    - - 1.2.10 rosmsg show
      - 1.2.11 rosmsg list
      - 1.2.12 rosmsg package
      - 1.2.13 rosmsg packages
      - 1.2.14 rosmsg md5

一、Topic

1.1 常用函数接口

ros::Publisher类

// 两个重载函数模板，用于发布topic消息
template 
void publish(const boost::shared_ptr& message) const

template 
void publish(const M& message) const

// 关闭与此发布者关联的广播
void shutdown()

// 还不知道怎么用，mark一下，有知道的欢迎评论区留言
boost::function getLastMessageCallback()

// 获取与此发布者关联的订阅者的数量
uint32_t getNumSubscribers() const

// 获取此发布者发布的topic
std::string getTopic() const

// 此发布者是否为锁存模式
// 锁存模式：记录发布的最后一条消息，每有订阅者连接发布一次最后一条消息
// 通过advertise函数设置
bool isLatched() const

ros::Subscriber类

// 获取与此订阅者关联的发布者的数量
uint32_t getNumPublishers() const

// 获取此订阅者订阅的topic
std::string getTopic() const

// 关闭与此订阅者关联的广播
void shutdown ()

1.2 常用命令行工具

rostopic相关

rostopic bw    显示主题使用的带宽
rostopic delay 显示带header的topic的网络延迟
rostopic echo  将消息打印到屏幕
rostopic find  按类型查找主题
rostopic hz    显示主题的发布率
rostopic info  打印关于活动主题的信息
rostopic list  打印有关活动主题的信息
rostopic pub   将数据发布到主题
rostopic type  打印主题类型

1.2.1 rostopic bw

rostopic bw <topic-name>
rostopic bw /rosout

显示topic使用的带宽，显示的带宽是subscriber端的带宽，由于rostopic是用python实现的，所以实际速度可能会低于c++实现的ros节点。

比如topic为/rosout ，发布默认消息

则subscribe端的带宽为

其中，

average：带宽。

mean：从开始通信到现在，每次通信的平均数据量。

min：从开始通信到现在，最小的一次通信数据量。

max：从开始通信到现在，最大的一次通信数据量。

window：应该是从开始通信到现在接收数据的次数，但到100就不再增加了。作者代码里使用队列存储时间戳记录通信，通过获取队列大小得到通信次数，为限制内存开销，作者将队列大小限制为100，将队首元素pop，并将新时间戳加入队列，但pop后作者没有对记录通信次数的变量加1，所以window到100就不再增加了。

1.2.2 rostopic delay

rostopic delay 
rostopic delay /rosout

显示带header的topic的网络延迟(因为header会记录msg发出时的时间戳)，即msg从advertiser发出到subscriber接收经过的时间。

自己写一个测试topic /log 代码如下，

#!/usr/bin/python3
#-*- coding:utf-8 -*-

import rospy
from rosgraph_msgs.msg import Log

if __name__ == '__main__':

    rospy.init_node('log')

    log = rospy.Publisher('/log', Log, queue_size=10)

    rate = rospy.Rate(10)

    while not rospy.is_shutdown():
        log_msg = Log()
        log_msg.header.stamp = rospy.get_rostime()

        log.publish(log_msg)
        rospy.loginfo("Publish log message %s", log_msg)
 
        rate.sleep()

则该topic的网络延迟为

其中，

average delay ：从开始通信到现在，所有通信的平均延迟时间，单位：s

min：从开始通信到现在，所有通信中延迟时间最小的一次

max：从开始通信到现在，所有通信中延迟时间最大的一次

std dev：从开始通信到现在，所有通信延迟数据的标准差，表征延迟数据的波动大小，标准差越小表示延迟数据波动越小。

window：和 rostopic bw 的window 一样，不过它的队列大小限制为50000。

1.2.3 rostopic echo

rostopic echo <topic-name>
rostopic echo /rosout

将消息内容打印到屏幕

rostopic echo 有自己的参数选项，如下，

rostopic echo --offset	
rostopic echo --filter
rostopic echo -c
rostopic echo -b
rostopic echo -p
rostopic echo -p --nostr
rostopic echo -p --noarr
rostopic echo -w
rostopic echo -n

rostopic echo --offset

在打印的消息中显示advertiser发布时间与subscriber接收时间的偏移量，和delay一样，topic要有header，否则打印中没有时间戳。

rostopic echo --offset /topic_name

测试程序如下：

自定义msg：

# HeaderString.msg
# 自定义msg
std_msgs/Header header
string data

offset节点源文件：

package名称为mbot_communication，自建包需相应修改

#include "ros/ros.h"
#include "mbot_communication/HeaderString.h"

int main(int argc, char **argv)
{
    ros::init(argc, argv, "offset");

    ros::NodeHandle n;
    ros::Publisher chatter_pub = n.advertise("/offset", 1000);

    ros::Rate loop_rate(5);

    int count = 0;

    while (ros::ok())
    {
        mbot_communication::HeaderString msg;
        msg.header.stamp = ros::Time::now();
        std::stringstream ss;
        ss << "hello world " << count;
        msg.data = ss.str();

        chatter_pub.publish(msg);

        ROS_INFO("sec: %d, nsec: %d, data: %s", msg.header.stamp.sec, msg.header.stamp.nsec, msg.data.c_str());

        ros::spinOnce();

        loop_rate.sleep();
        ++count;
    }

    return 0;
}

启动offset节点后，执行以下命令会有相应打印：

其中，

stamp是时间戳，这里是advertiser发布时间与subscriber接收时间的偏移量，stamp = advertiser发布时间戳 - subscriber接收时间戳，secs是秒，nsecs是纳秒，1秒= $1*10^{-9}$ 纳秒，上图第一个消息的偏移量就是 $1+998923014*10^{-9} = -0.001076986(s)$ 。

rostopic echo --filter

显示与指定python语法的逻辑表达式匹配的消息

rostopic echo --filter "逻辑表达式"  /topic_name
rostopic echo --filter "m.data=='foo'"  /topic_name

可以对消息内容做逻辑匹配，比如上述自定义 /offset topic，只显示seq为偶数的消息，

默认消息变量为 m，使用.表示字段包含关系，只支持匹配数字和字符串，

支持python的所有内置运算符和内置函数，比如对于数字，支持 +、-、*、**、/、//、% 等数学运算，&、|、~、^、<<、>> 等位运算，pow()、abs()、round()、max() 等内置函数，对于字符串，支持 split()、upper()、find()、len() 等内置函数，就是那种使用时不需要另外import包的函数在这里都支持。

对于逻辑运算支持 ==、!=、>、<、>=、<=、and、or 等。

另外，如果和字符或字符串进行比较，需要用 '' 括起来。

再给两个例子，其他自己探索吧：

rostopic echo -c

打印每条消息前清除屏幕，不能与 -p 一起使用。

rostopic echo -c /topic_name

rostopic echo -b

显示bag文件中录制的topic

rostopic echo -b log_file.bag /topic_name

录制了一段/offset的消息，使用该命令打印如下：

.bag有特定的编码格式，不能直接打开，如果想直接查看bag记录的内容而不想每次播放bag，可以使用这个命令将bag内容重定向，offset.txt文件就可以随时打开查看了。

和 rostopic echo -b 一起用的还有一个 -a 参数选项，用来显示 bag 文件中记录的所有消息，也就是 rostopic echo -b log_file.bag 后面如果接 topic 名字，就显示对应 topic 的消息内容，如果接 -a 就显示所有消息。

显示所有消息时，是按照记录时的时间顺序打印每条消息的。

rostopic echo -p

以 matlab/octave 友好的格式显示消息。不能与 -c 一起使用。

rostopic echo -p /topic_name

其中，以%开头的第一行是标题，按顺序对应每行以 , 隔开的变量名。

rostopic echo -p 还有两个参数选项，--nostr 和 --noarr ，分别代表 忽略字符串 和 忽略数组

使用 --nostr 参数选项后，忽略掉了字符串类型的 frame_id 和 data 。

rostopic echo -w

以固定宽度 NUM_WIDTH 打印所有数值，如果 NUM_WIDTH 小于实际宽度，则以实际宽度打印。

rostopic echo -w NUM_WIDTH /topic_name

每个数字的宽度为13，实际宽度不足13的，在数字前面补空格。

符合python的 % 占位符规则，具体可查询 python % 占位符 。

rostopic echo -n

打印接收到的 COUNT 条消息并退出。

rostopic echo -n COUNT /topic_name

1.2.4 rostopic find

rostopic find <msg-type>
rostopic find rosgraph_msgs/Log

按照 topic 的消息类型查找运行的 topic。

1.2.5 rostopic hz

rostopic hz 
rostopic hz /rosout

显示主题的发布率。默认情况下，报告的速率是 rostopic 运行期间的平均速率。

和 rostopic delay 的打印类似，其中，

average rate ：从开始通信到现在，所有通信的平均发布率，单位：Hz

min：从开始通信到现在，所有通信中发布周期最小的一次

max：从开始通信到现在，所有通信中发布周期最大的一次

std dev：从开始通信到现在，所有通信发布周期的标准差，表征发布周期的波动大小，标准差越小表示波动越小。

window：从开始通信到现在接收数据的次数，队列限制大小50000。

rostopic hz 的参数选项如下：

rostopic hz -w 
rostopic hz --filter

rostopic hz -w

使用窗口大小（样本数）报告速率，以对速率进行时间局部估计。

如不使用 -w 选项，报告的平均速率时从开始通信以来所有通信的平均速率，如使用 -w 则为最近 WINDOW_SIZE 次通信的平均速率。

 rostopic hz -w WINDOW_SIZE /topic_name

rostopic hz --filter

仅报告指定python语法的逻辑表达式匹配的消息的速率。

逻辑表达式的使用规则同 rostopic echo --filter

此选项对性能有很大影响，不应用于高速率主题。

rostopic hz --filter FILTER_EXPR /topic_name

1.2.6 rostopic info

rostopic info <topic-name>
rostopic info /rosout

打印 topic 的信息

其中，

Type：是 topic 的消息类型

Publishers：是该 topic 的发布者节点名，如果是通过 rostopic 指令发布，则节点名称就是 /rostopic_7739_1651069588197 的命名形式，其中 7739 是节点的 PID（线程ID），

1651069588197 是什么不知道（如果你知道欢迎评论区留言）

Subscribers：是该 topic 的订阅者节点名。

http://Yogo:40683/ 是该节点的网络地址，

1.2.7 rostopic list

列出当前运行的topic

rostopic的参数选项如下：

rostopic list <namespace>    # 列出指定命名空间中的topic
rostopic list -b <bag_file>  # 列出bag文件中的topic
rostopic list -p  # 只列出发布者
rostopic list -s  # 只列出订阅者
rostopic list -v  # 详细模式
rostopic list --host  # 按主机名分组列表

rostopic list <名空间>

列出指定命名空间中的topic，关于ROS的命名空间，见 ROS WiKi/Names/Graph Resource Names

rostopic list /up

rostopic list -b

列出bag文件中的topic

rostopic list -b all.bag

rostopic list -p

只列出有发布者的topic

rostopic list -p

rostopic list -s

只列出有订阅者的topic

rostopic list -s

rostopic list -v

列出所有topic的详细信息

rostopic list -v

其中包括topic的属性(发布者/订阅者)、topic名、topic消息类型(方括号里的)、该topic发布者/订阅者的数量。

rostopic list --host

按主机名分组列表

rostopic list --host

其中，方括号里是主机名。

1.2.8 rostopic pub

将数据发布到主题

rostopic pub <topic-name> <topic-type> [data...]
rostopic pub /topic_name std_msgs/String "hello"

关于topic发布的三种模式：

latching mode
- 记录发布的最后一条消息，每有订阅者连接，发布一次最后一条消息
- 默认为这个模式
once mode
- 保持latching模式3秒，然后退出。
rate mode
- 可以自定义消息的发布频率

关于topic发布消息的数据源：

命令行参数（最常用的方法）

rostopic pub /topic_name std_msgs/String "hello"

管道输入
```
rostopic echo /chatter | rostopic pub /bar std_msgs/String
```
这个没发现有什么好用的场景，就是把/chatter的消息内容转发给/bar了。
通过YAML文件输入

首先要有一个存有msg的文件，可以重定向topic内容：
```
rostopic echo /chatter > chatter.bagy
```
然后使用-f参数选项将文件内容输入到topic
```
rostopic pub -f chatter.bagy /bar std_msgs/String
```

关于YAML格式在ROS中的使用，见 YAML on the ROS command line

参数选项：

rostopic pub -l <topic-name> <topic-type> [data...]
rostopic pub --latch <topic-name> <topic-type> [data...]
rostopic pub -r RATE <topic-name> <topic-type> [data...]
rostopic pub -1 <topic-name> <topic-type> [data...]
rostopic pub --once <topic-name> <topic-type> [data...]
rostopic pub -f FILE <topic-name> <topic-type> [data...]

rostopic pub -l/–latch

-l和--latch是一样的，代表latching mode

发布者发布一次消息，并将最后一条消息保存等待，直到有新的订阅者连接，把保存的消息发给新的订阅者（每个新订阅者收到的都是这条保存的消息）

rostopic pub -r RATE

rate mode，RATE的单位是Hz。

发布者按10Hz的频率不停发布消息，订阅者一直接收消息。

rostopic pub -1/–once

-1(注意是数字1) 和 --once 是一样的，代表once mode

rostopic pub -f FILE

通过YAML文件输入

1.2.9 rostopic type

显示topic的消息类型

rostopic type <topic-name>
rostopic type /topic_name

rosmsg 相关

rosmsg show 显示消息格式内容
rosmsg list 显示消息列表
rosmsg package 显示指定包中的所有消息列表
rosmsg packages 显示所有带有消息的包的列表
rosmsg md5 显示指定消息类型的 md5 总和

1.2.10 rosmsg show

rosmsg show <message type>
rosmsg show std_msgs/String

显示 ROS 消息类型中的字段。

如果不知道包名称，也可以只写消息类型，该命令会在所有包中匹配：

-r 选项

显示消息原始文件中的所有内容，包括注释。

rosmsg show -r <message-type>

1.2.11 rosmsg list

显示所有消息列表

rosmsg list

1.2.12 rosmsg package

显示指定包中的所有消息列表

rosmsg package <package-name> 
rosmsg package mbot_communication

-r选项

将消息列表显示在一行

rosmsg package mbot_communication -s

1.2.13 rosmsg packages

显示所有带有消息的包的列表。

rosmsg packages