Skip to content

Commit 2fb8a48

Browse files
committed
Add some introductory material to the README, and a Tips and Tricks section
Signed-off-by: Emerson Knapp <emerson.b.knapp@gmail.com>
1 parent 323ebbf commit 2fb8a48

1 file changed

Lines changed: 64 additions & 6 deletions

File tree

README.md

Lines changed: 64 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,18 @@
22
![License](https://img.shields.io/github/license/ros2/rosbag2)
33
[![GitHub Action Status](https://github.com/ros2/rosbag2/workflows/Test%20rosbag2/badge.svg)](https://github.com/ros2/rosbag2/actions)
44

5-
Repository for implementing rosbag2 as described in its corresponding [design article](https://github.com/ros2/design/blob/ros2bags/articles/rosbags.md).
5+
Rosbag2 - the tool for recording and playback of messages from ROS 2 topics.
6+
7+
This is the ROS 2 successor of https://wiki.ros.org/rosbag.
8+
9+
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.
10+
11+
For historical context, see the original [design article](https://github.com/ros2/design/blob/ros2bags/articles/rosbags.md) that kicked off the project.
12+
13+
This README has a lot of information. You may want to jump directly to:
14+
- [Installation](#installation)
15+
- [Usage](#using-rosbag2)
16+
- [Tips and Tricks](#tips-and-tricks)
617

718
## Installation
819

@@ -217,7 +228,7 @@ Topic information: Topic: /chatter | Type: std_msgs/String | Count: 9 | Serializ
217228
Topic: /my_chatter | Type: std_msgs/String | Count: 18 | Serialization Format: cdr
218229
```
219230

220-
### Converting bags
231+
### Converting bags (merge, split, etc.)
221232

222233
Rosbag2 provides a tool `ros2 bag convert` (or, `rosbag2_transport::bag_rewrite` in the C++ API).
223234
This allows the user to take one or more input bags, and write them out to one or more output bags with new settings.
@@ -403,7 +414,7 @@ def generate_launch_description():
403414
])
404415
```
405416

406-
## Using with composition
417+
### Using recorder and player as composable nodes
407418

408419
Play and record are fundamental tasks of `rosbag2`. However, playing or recording data at high rates may have limitations (e.g. spurious packet drops) due to one of the following:
409420
- low network bandwidth
@@ -487,7 +498,7 @@ player:
487498
node_prefix: ""
488499
rate: 1.0
489500
loop: false
490-
# Negative timestamps will make the playback to not stop.
501+
# Negative timestamps will make the playback to not stop.
491502
playback_duration:
492503
sec: -1
493504
nsec: 00000000
@@ -501,7 +512,9 @@ player:
501512

502513
For a full list of available parameters, you can refer to [`player`](rosbag2_transport/test/resources/player_node_params.yaml) and [`recorder`](rosbag2_transport/test/resources/recorder_node_params.yaml) configurations from the `test` folder of `rosbag2_transport`.
503514

504-
## Storage format plugin architecture
515+
## Plugin implementation
516+
517+
### Storage format plugin architecture
505518

506519
Looking at the output of the `ros2 bag info` command, we can see a field `Storage id:`.
507520
Rosbag2 was designed to support multiple storage formats to adapt to individual use cases.
@@ -521,7 +534,7 @@ Bag reading commands can detect the storage plugin automatically, but if for any
521534
To write your own Rosbag2 storage implementation, refer to [Storage Plugin Development](docs/storage_plugin_development.md)
522535

523536

524-
## Serialization format plugin architecture
537+
### Serialization format plugin architecture
525538

526539
Looking further at the output of `ros2 bag info`, we can see another field attached to each topic called `Serialization Format`.
527540
By design, ROS 2 is middleware agnostic and thus can leverage multiple communication frameworks.
@@ -538,3 +551,48 @@ By default, rosbag2 can convert from and to CDR as it's the default serializatio
538551

539552
[qos-override-tutorial]: https://docs.ros.org/en/rolling/Guides/Overriding-QoS-Policies-For-Recording-And-Playback.html
540553
[about-qos-settings]: https://docs.ros.org/en/rolling/Concepts/About-Quality-of-Service-Settings.html
554+
555+
## Tips and Tricks
556+
557+
### Record bags to a custom base directory
558+
559+
If you want to send bagfiles to a different directory than the current working directory, like so
560+
561+
```plaintext
562+
/my/bag/base_dir
563+
├── rosbag2_2025_02_21-15_35_35
564+
| ├── metadata.yaml
565+
│ └── rosbag2_2025_02_21-15_35_35_0.mcap
566+
└── rosbag2_2025_02_21-15_37_17
567+
├── metadata.yaml
568+
└── rosbag2_2025_02_21-15_37_17_0.mcap
569+
```
570+
571+
This can be accomplished without features in `rosbag2` itself.
572+
573+
In shell:
574+
575+
```bash
576+
pushd $MY_BASE_DIR && ros2 bag record ...
577+
```
578+
579+
In launch:
580+
581+
```python
582+
ExecuteProcess(
583+
cmd=['ros2', 'bag', 'record', ...],
584+
cwd=my_base_dir,
585+
),
586+
```
587+
588+
589+
### Custom name with timestamp for bag directory
590+
591+
You can fully customize the output bag name, without any `rosbag2` special features.
592+
593+
For example, you want a timestamp on the bag directory name, but want a custom prefix instead of `rosbag2_`.
594+
595+
```bash
596+
$ ros2 bag record -a -o mybag_"$(date +"%Y_%m_%d-%H_%M_%S")"
597+
... creates e.g. mybag_2025_02_21-15_35_35
598+
```

0 commit comments

Comments
 (0)