Rosbag2

Rosbag2 — the tool for recording and playback of communications in ROS 2 systems.

This is the ROS 2 successor of https://wiki.ros.org/rosbag.

A “rosbag” is simply a file full of timestamped messages. The first goal of the tool is efficient recording, to support complex systems in real time. Its second goal is efficent playback, to allow for viewing and using recorded data.

For historical context, see the original design article that kicked off the project.

This README has a lot of information. You may want to jump directly to:

• Installation
• Usage
• Tips and Tricks

Installation

Debian packages

Rosbag2 packages are available via debian packages, and will already be included with any -ros-base installation (which is included within -desktop)

$ export ROS_DISTRO=humble
$ sudo apt-get install ros-$ROS_DISTRO-rosbag2

Other binaries

You can follow the instructions at http://docs.ros.org/en/humble/Installation/Alternatives/Ubuntu-Install-Binary.html (or for your chosen distro), and Rosbag2 will be included in that installation.

Build from source

To build from source, follow the instructions in DEVELOPING.md

Using rosbag2

Rosbag2 is part of the ROS 2 command line interface as ros2 bag. These verbs are available for ros2 bag:

• ros2 bag burst
• ros2 bag convert
• ros2 bag info
• ros2 bag list
• ros2 bag play
• ros2 bag record
• ros2 bag reindex

For up-to-date information on the available options for each, use ros2 bag <verb> --help.

Moreover, rosbag2_transport::Player and rosbag2_transport::Recorder components can be instantiated in rclcpp component containers, which makes possible to use intra-process communication for greater efficiency. See composition section for details.

Recording data

In order to record all topics currently available in the system:

$ ros2 bag record -a

The command above will record all available topics and discovers new topics as they appear while recording. This auto-discovery of new topics can be disabled by given the command line argument --no-discovery.

To record a set of predefined topics, one can specify them on the command line explicitly.

$ ros2 bag record <topic1> <topic2> … <topicN>

The specified topics don’t necessarily have to be present at start time. The discovery function will automatically recognize if one of the specified topics appeared. In the same fashion, this auto discovery can be disabled with --no-discovery.

If not further specified, ros2 bag record will create a new folder named to the current time stamp and stores all data within this folder. A user defined name can be given with -o, --output.

Simulation time

In ROS 2, “simulation time” refers to publishing a clock value on the /clock topic, instead of using the system clock to tell time. By passing --use-sim-time argument to ros2 bag record, we turn on this option for the recording node. Messages written to the bag will use the latest received value of /clock for the timestamp of the recorded message.

Note: Until the first /clock message is received, the recorder will not write any messages. Before that message is received, the time is 0, which leads to a significant time jump once simulation time begins, making the bag essentially unplayable if messages are written first with time 0 and then time N from /clock.

Splitting files during recording

Rosbag2 offers the capability to split bag files when they reach a maximum size or after a specified duration. By default Rosbag2 will record all data into a single bag file, but this can be changed using the CLI options.

Splitting by size: ros2 bag record -a -b 100000 will split the bag files when they become greater than 100 kilobytes. Note: the batch size’s units are in bytes and must be greater than 86016. This option defaults to 0, which means data is written to a single file.

Splitting by time: ros2 bag record -a -d 9000 will split the bag files after a duration of 9000 seconds. This option defaults to 0, which means data is written to a single file.

If both splitting by size and duration are enabled, the bag will split at whichever threshold is reached first.

Recording with compression

File truncated at 100 lines see the full file

Any contribution that you make to this repository will be under the Apache 2 License, as dictated by that license:

5. Submission of Contributions. Unless You explicitly state otherwise,
   any Contribution intentionally submitted for inclusion in the Work
   by You to the Licensor shall be under the terms and conditions of
   this License, without any additional terms or conditions.
   Notwithstanding the above, nothing herein shall supersede or modify
   the terms of any separate license agreement you may have executed
   with Licensor regarding such Contributions.

Contributors must sign-off each commit by adding a Signed-off-by: ... line to commit messages to certify that they have the right to submit the code they are contributing to the project according to the Developer Certificate of Origin (DCO).