ROS 2

Record with MCAP

ROS 2 supports recording directly to MCAP using the rosbag2 MCAP storage plugin. To get started, install the plugin:

$ sudo apt-get install ros-$ROS_DISTRO-rosbag2-storage-mcap

Set your storage ID to mcap when recording:

$ ros2 bag record -s mcap --all

You can also customize MCAP writer options such as compression and chunk size using storage options:

$ cat << EOF > my_storage_config.yaml
compression: "Lz4"
compressionLevel: "Fastest"
EOF
$ ros2 bag record -s mcap --all --storage-config-file my_storage_config.yaml

Convert to MCAP

Using ros2 bag convert

To convert your existing ROS 2 .db3 files into MCAP files, you can use ros2 bag convert from within your ROS 2 workspace.

$ cat << EOF > convert.yaml
output_bags:
  - uri: ros2_output
    storage_id: mcap
    storage_config_uri: my_storage_config.yaml
    all: true
EOF
$ cat << EOF > my_storage_config.yaml
compression: Zstd
EOF
$ ros2 bag convert -i ros2_input.db3 -o convert.yaml

If you want to use compression when converting, specify a storage config file. Specifying compression_mode and compression_format directly in the convert.yaml file will result in an unplayable rosbag2 (https://github.com/ros2/rosbag2/issues/1920).

Using the mcap CLI tool

The mcap CLI tool also supports converting ROS 2 .db3 files into MCAP files directly.

$ mcap convert multiple_files_1.db3 demo.mcap

mcap convert reads the message definitions embedded in the .db3 file. ROS 2 Iron and later embed message definitions when recording, so these bags convert directly without a sourced workspace. Converting may still produce different results from recording the bag directly in MCAP using the rosbag2 MCAP storage plugin.

Bags recorded before ROS 2 Iron do not contain embedded message definitions and cannot be converted directly by the CLI. To convert them, use the ros2 bag convert method described above with the original ROS 2 workspace sourced.

You can also use the mcap CLI tool to inspect MCAP files, validate them, and even echo their messages to stdout. For a full list of possible commands, check out the mcap CLI documentation.

Read and write MCAP

If you're starting from scratch, you can write code that allows you to write your ROS 2 data to MCAP files and subsequently read your ROS 2 data from your MCAP files.

Guides

• Python

Examples

• Python - reader and writer

Inspect MCAP

Use the mcap CLI tool to inspect MCAP files, validate their contents, and even echo their messages to stdout.

For an exhaustive list of ways to interact with your MCAP data, check out the mcap CLI documentation.

Visualize MCAP

Foxglove supports playing back local and remote ROS 2 db3 files, as well as local and remote MCAP files containing ROS 2 data.

With that said, we recommend MCAP files over ROS 2 db3 files, as the latter are not completely self-contained.