[Documentation] [TitleIndex] [WordIndex


grep for ROS bag files and live topics: read, filter, export.

Searches through ROS messages and matches any message field value by regular expression patterns or plain text, regardless of field type. Can also look for specific values in specific message fields only.

By default, matches are printed to console. Additionally, matches can be written to a bagfile or HTML/CSV/MCAP/Parquet/Postgres/SQL/SQLite, or published to live topics.

Supports both ROS1 and ROS2. ROS environment variables need to be set, at least ROS_VERSION.

In ROS1, messages can be grepped even if Python packages for message types are not installed. Using ROS1 live topics requires ROS master to be running.

Using ROS2 requires Python packages for message types to be available in path.

Supports loading custom plugins, mainly for additional output formats.

Usable as a Python library. Full API documentation available at https://suurjaak.github.io/grepros.


Example usage

Search for "my text" in all bags under current directory and subdirectories:

Print 30 lines of the first message from each live ROS topic:

Find first message containing "future" (case-sensitive) in my.bag:

Find 10 messages, from geometry_msgs package, in "map" frame, from bags in current directory, reindexing any unindexed bags:

Pipe all diagnostics messages with "CPU usage" from live ROS topics to my.bag:

Find messages with field "key" containing "0xA002", in topics ending with "diagnostics", in bags under "/tmp":

Find diagnostics_msgs messages in bags in current directory, containing "navigation" in fields "name" or "message", print only header stamp and values:

Print first message from each lidar topic on host, without highlight:

Export all bag messages to SQLite and Postgres, print only export progress:

Patterns use Python regular expression syntax, message matches if all match. '*' wildcards use simple globbing as zero or more characters, target matches if any value matches.

Note that some expressions may need to be quoted to avoid shell auto-unescaping or auto-expanding them, e.g. linear.x=2.?5 should be given as "linear.x=2\.?5".


Using pip

grepros is written in Python, supporting both Python 2 and Python 3.

Developed and tested under ROS1 Noetic and ROS2 Foxy, should also work in later ROS2 versions; may work in earlier ROS1 versions.

This will add the grepros command to path.

Requires ROS Python packages (ROS1: rospy, roslib, rosbag, genpy; ROS2: rclpy, rosidl_parser, rosidl_runtime_py, builtin_interfaces).

If you don't want to install the ROS1 stack, and are only interested in using bag files, not grepping from or publishing to live topics, minimal ROS1 Python packages can also be installed separately with:

Using apt

If ROS apt repository has been added to system:

This will add the grepros command to the global ROS1 / ROS2 environment.

Using catkin

In a ROS1 workspace, under the source directory:

This will add the grepros command to the local ROS1 workspace path.

Using colcon

In a ROS2 workspace, at the workspace root:

This will add the grepros command to the local ROS2 workspace path.


Documentation and more examples at github.com/suurjaak/grepros.

Use GitHub to report bugs or submit feature requests. [View active issues]

2024-07-20 13:21