This Python package wraps and documents functionality for reading data from bag files generated by ROS2. Bag files (or "bags") are the standard via which ROS2 stores data to disk. For an introduction to bag files, please see the ROS2 documentation that explains recording and playing back data.

The purpose of this package is to facilitate direct reading of data from bag files that have been recorded by ROS.¹ The ROS 2 bag design document explains the motivation and approach to data storage, and the rosbag2 package provides an official implementation (C++ and Python). However, documentation of the rosbag2 API is currently both scattered and limited, as are recommended best practices for working with bags. This package is intended to aggregate documentation about existing ROS2 functionality and to illustrate its usage. This package is intended only to fill a temporary gap, and it is expected that later versions of ROS2 (Jazzy and beyond) will make it obsolete.

The rosbag2 package must be installed. This does not necessarily require that ROS2 must be installed.

With the rosbag2 package installed, no further steps are required, as long as the package is available on the Python path (e.g., via PYTHONPATH).

A setup.cfg file has been provided, to facilitate package installation via setuptools. Package installation can be accomplished via the command:

pip install path/to/nml_bag

Basic usage of the package follows this pattern:

1. Initialize a ROS2 command prompt by sourcing the ROS2 environment.
2. Import the package:

   import nml_bag

3. Initialize a Reader object:

   reader = nml_bag.Reader('path/to/bag.mcap', topics=['topic_a', '/topic_b'])

4. Iterate through message records:

   for message_record in reader: print(message_record)
   

5. Alternatively, the records property will return all available message records:

   records = reader.records
   

A usage example is included in this package as example.py. The example initializes a bag directory and a MCAP file bag_test_0.mcap. The bag file contains a single topic test, on which two string-type messages are recorded.

Roughly following the quickstart outline, the code for reading the bag is:

from pprint import pprint
import nml_bag
reader = nml_bag.Reader('path/to/bag_test_0.mcap')
pprint(reader.records)

And the output is similar to:

[{'data': 'Hello World!',
  'time_ns': 1654207659885697659,
  'topic': 'test',
  'type': 'example_interfaces/msg/String'},
 {'data': 'Goodybye World!',
  'time_ns': 1654207659885798001,
  'topic': 'test',
  'type': 'example_interfaces/msg/String'}]

By default, ROS2 messages are serialized using the Common Data Representation (CDR) standard and stored using MCAP (since Iron) -- "an open source container file format for multimodal log data". Formerly, data were stored using sqlite 3.

Note: Although the sqlite3 package is part of the standard distribution of Python 3 -- and it can be used to interpret bag files -- it is recommended that the ROS2 API be used for decoding bag files wherever possible.