The service API¶

Everything else in this project (the CLI, the Python library, the browser UI) is a client of these services. A node that speaks ROS needs nothing else.

The names below are relative to the recorder node, so with the default name ~/pause is /rosbag2_dynamic_recorder/pause.

Topic management¶

Service	Type	Purpose
`~/subscribe_topics`	`SubscribeTopics`	Add topics. Types discovered from the graph if not given.
`~/unsubscribe_topics`	`UnsubscribeTopics`	Drop topics. Recorded messages are kept.
`~/set_topics`	`SetTopics`	Replace the whole set.
`~/get_subscribed_topics`	`GetSubscribedTopics`	The current set.
`~/set_profile`	`SetProfile`	Apply a named topic set.
`~/get_profiles`	`GetProfiles`	List the configured profiles.

The guarantee that matters: on set_topics and set_profile, topics present in both the old and the new set are never torn down. They keep recording without a gap, which is what makes a mode switch mid-recording safe. Measured, the largest gap on such a topic across two changes is 0.05s, one publish interval.

return_code is 0 on success and 1 when nothing was actioned or on error. An empty set_topics is a valid request that unsubscribes everything, and is reported as success. The reused rosbag2_interfaces services under Recording control keep their own return codes instead.

Selecting by pattern¶

subscribe_topics, unsubscribe_topics and set_topics all take regex and exclude_regex.

The semantics are stock ros2 bag record -e’s: an ECMAScript search, not a full match, so camera finds /robot/camera/image without anchors. Anchor it yourself (^/robot/) when you mean a prefix. exclude_regex is applied to the combined selection, after names and matches are merged, so “everything under /robot except the depth camera” takes one call rather than two.

Three rules:

A pattern never matches the recorder’s own topics. Its event channels are already written into the bag directly, so subscribing to them would record every event twice. Hidden topics are excluded too, as stock rosbag2 does.
unsubscribe_topics matches what is being recorded, not the graph. Only a recorded topic can be dropped, and matching the graph would silently do nothing for one that has since left it.
An invalid expression is refused with the reason. Quietly matching nothing would be indistinguishable from a pattern that legitimately found nothing, and the likely cause is a typo.

Naming a type explicitly¶

topic_types lines up with topics by index. An empty entry requests discovery from the graph, which succeeds only when the topic currently offers exactly one type, and cannot work before the publisher exists. Naming the type is how you record a topic whose publisher has not started yet.

A pattern match has no index, so it cannot carry an explicit type; matched topics always take their type from the graph.

Recording control¶

These use the stock rosbag2_interfaces definitions, so a client written against standard rosbag2 drives this node unchanged.

That holds fully on Rolling, which is the rosbag2 (0.34) this project is written against. Jazzy and Kilted ship older definitions: Record, Resume and SplitBagfile without the scheduling fields (Kilted has no Record at all) and Stop without a return code. There the recorder offers those four under field-identical copies in rosbag2_dynamic_recorder_interfaces, with the same behaviour, so scheduling works on every distro; ros2 service type ~/resume tells you which is in use. pause, toggle_paused, is_paused and snapshot are the same on every distro and always stock. Python clients should take these types from dynrec.services, which resolves them the same way the recorder does; see Install.

Service	Type	Purpose
`~/pause` `~/resume` `~/toggle_paused` `~/is_paused`	`Pause`, `Resume`, …	Stop writing without tearing down subscriptions.
`~/split_bagfile`	`SplitBagfile`	Close the current file and open the next.
`~/snapshot`	`Snapshot`	Flush the in-memory buffer. Requires `snapshot_mode`.
`~/stop`	`Stop`	Close the bag.
`~/record`	`Record`	Open a new bag, restoring the previous topic selection.
`~/get_status`	`GetStatus`	Everything needed for a status line, in one round trip.

Stopping is not final: ~/record opens a fresh bag and re-subscribes whatever was being recorded at stop. Since rosbag2 will not open over an existing bag directory, the new one takes the next free suffix: mybag, then mybag(1).

Scheduled operations¶

resume, split_bagfile and record accept a future timestamp instead of acting immediately. A zero stamp means “now”, so an untouched request is already the immediate request.

Node time (mode: 0, and the only option for record) is driven by a timer, so it fires even if the robot has gone quiet.
Publish time (1) and receive time (2) are compared against arriving messages, on any recorded topic or on tracking_topic_name alone. They cannot fire while no messages are arriving, which is useful for “when data resumes” and a trap for “in five minutes”.

A mode outside 0-2, or a tracking_topic_name nobody is recording, is rejected: a schedule keyed to a topic that is not being recorded would wait forever.

Only the newest schedule of each operation is live, whichever clock either is on: a second resume replaces the first, a timer or a queued message-time check alike. There is no call to cancel one; scheduling the same operation again replaces it.

~/stop clears a queued resume or split_bagfile, so it cannot fire against the next bag. A queued record is not cleared and will still fire.

Whatever is queued, by any client, is listed in the status as schedules, until it fires or a stop clears it.

Simulation time¶

With use_sim_time:=true the recorder behaves as ros2 bag record --use-sim-time does, and then some, because everything it writes has to agree with itself:

Messages are stamped with the node clock, driven by /clock, instead of the middleware’s receive time, so the bag’s timeline is the simulation’s: ros2 bag info, playback and describe() all measure in simulated seconds, and a paused simulation produces a paused bag. The send stamp stays the middleware’s wall-clock one, as upstream leaves it. The recorder’s own events were always on the node clock, so the two timelines in one bag now match.
Nothing is opened or subscribed until /clock has been heard: a node clock reads zero until then, and a bag opened on it would begin in 1970. The recorder is up and answering in the meantime, ~/status says waiting_for_clock, and a call that needs an open bag, such as adding a topic or ~/record, is refused with a message that says why rather than left to time out.
Node-time schedules (resume, split_bagfile, record with a future stamp) run on the node clock too, so they keep to simulated time when the simulation runs slow or stops.

Status¶

~/get_status is the one-shot form; ~/status is the same message published periodically, on every change, and latched, so a client attaching mid-recording sees current state immediately rather than waiting for the next tick. A UI or a long-lived script should prefer the topic.

A few fields need reading carefully:

messages_missed: Detected by watching for gaps in each publisher’s sequence numbers. It does not depend on the transport raising an event, so it catches samples a publisher overwrote in its own history before the recorder ever saw them. Meaningful only when sequence_numbers_available is true; treat it as unknown, not zero, when that is false.
messages_lost_in_transport: What the transport reported as dropped before delivery. Observed reading 0 while roughly 3-4% of messages were absent from a bag. Treat it as a floor, not a total. A large messages_missed with this at 0 means the recorder was blocked long enough for publisher history to overflow. When this is the figure that climbs, the remedy is on the publisher’s side: its QoS, the network, or load.
messages_lost_in_recorder: Messages that did reach the recorder and were then dropped by the writer, because the cache filled while the disk could not keep up or because a storage write failed. Known with certainty, and the remedy is local: max_cache_size or max_cache_duration, a lighter storage_preset_profile, fewer or lighter topics, or faster storage. The name matches the same field in rosbag2’s own MessagesLostEvent, which ~/events/messages_lost also now fills correctly. Only Rolling’s writer reports these losses; on Jazzy and Kilted this reads 0 and means unknown, not zero.
messages_lost: The two above summed, for anything that only wants a total. Inherits the transport caveat.
topic_losses: The three figures above broken down by topic (TopicLoss), for every topic that has lost anything in this bag, sorted by name, and empty when nothing has been lost. Counted over the bag rather than the subscription: dropping a topic and adding it back keeps its figures, and ~/record starts them at zero. The per-topic messages_missed carries the same caveat as the total.
schedules: Resumes, splits and records queued for later and not yet fired (ScheduledAction), at most one of each, in that order, with the time, the clock it is compared against and the tracking topic. It lists schedules any client set, so a UI shows what a script queued.
bag_size_bytes: Bytes flushed to disk, not bytes captured. The writer caches, so this reads 0 early in a perfectly healthy recording. Use messages_written to answer “is it recording?”.
write_errors: Messages that reached the recorder but could not be written, for example when the disk filled. Any non-zero value means the bag is incomplete, and the recorder kept running deliberately, since stopping would lose the rest of the recording too.
free_space_bytes, total_space_bytes: Available and total bytes on the filesystem holding the bag, or 0 when either could not be determined. min_free_space / min_free_space_percent are compared against the first, so a UI can show how close the recorder is to stopping.
stopped_for_low_disk: True when the recorder stopped itself because free space fell below the configured minimum, rather than because of ~/stop. Cleared when ~/record opens a new bag.
max_bag_size, stopped_for_max_bag_size: The configured cap on the bag directory in bytes (0 when unset), and whether the recorder stopped itself for exceeding it. Compared against bag_size_bytes, so it inherits that field’s caveat. Cleared when ~/record opens a new bag.
use_sim_time, waiting_for_clock: Whether messages are stamped on the /clock-driven node clock, and whether the recorder is still waiting for that clock’s first message. While it waits no bag is open and every call that needs one is refused with a message saying so; see Simulation time.
stamp, recording_started, elapsed_seconds: When the status was built, when the bag started, and how long it has been recording, all on the node clock. Once stopped, recording_started and elapsed_seconds describe the last bag and stop advancing; stamp keeps going. A client that needs the recorder’s current time, to count down to a schedule or to turn +30s into a time, should use stamp.

The remaining fields are literal: recording, paused, snapshot_mode, subscribed_topics, bag_splits (times the file has rolled over; closing the bag at a stop is not counted) and messages_written (which counts the recorder’s own event messages too).

active_profile is derived from the live topic set on every publication, not remembered. Record one extra topic and it goes empty, because no profile is in effect any more. Land exactly on another profile’s set and it reports that one, whatever command got you there.

Events¶

Topic	Message
`~/events/subscription_change`	`SubscriptionChangeEvent`	also written into the bag
`~/events/pause`	`PauseEvent`	also written into the bag
`~/events/low_disk`	`LowDiskEvent`	also written into the bag
`~/events/bag_size_limit`	`BagSizeLimitEvent`	also written into the bag
`~/events/file_split`	`FileSplitEvent`	also written into the bag
`~/events/write_split`	`WriteSplitEvent`	stock; no stamp or cause
`~/events/messages_lost`	`MessagesLostEvent`	stock on Rolling, a field-identical copy on Jazzy and Kilted

Writing the first five into the bag is what makes a gap legible: a gap mid-bag is otherwise indistinguishable from a dropout, a crash or a network fault. The event records what changed, when and why, in-stream and timestamped, and it survives bag splitting.

The first four cover different shapes of gap, and you need all of them:

SubscriptionChangeEvent explains a channel that stops: one topic goes sparse while the others carry on. Disable with record_subscription_events:=false.
PauseEvent explains a bag that stops: a pause leaves a hole in every topic at once, which is what a crash or a network fault looks like too. The stock rosbag2_interfaces/srv/Pause has an empty request and response and so can carry no explanation. Disable with record_pause_events:=false.
LowDiskEvent explains a recording the recorder ended itself: when min_free_space or min_free_space_percent is set and free space falls below it, the recorder emits this, stops, and closes the bag. Without it the bag would simply end, indistinguishable from a crash or a power loss. Disable the in-bag copy with record_low_disk_events:=false.
BagSizeLimitEvent is the same explanation for the other guard: when max_bag_size is set and the bag directory grows past it, across every split, the recorder emits this, stops, and closes the bag. max_bagfile_size only rolls to a new file; this is the cap on the recording as a whole. Disable the in-bag copy with record_bag_size_limit_events:=false.

FileSplitEvent explains a file boundary rather than a gap: when the bag rolls over, by ~/split_bagfile, a schedule, or max_bagfile_size / max_bagfile_duration, it names the file that closed, the file recording continues in, and the cause. The stock WriteSplitEvent is still published for clients written against it, but it carries neither a stamp nor a cause, so it cannot be placed on a timeline. The in-bag copy goes into the new file; disable it with record_split_events:=false. Closing the bag at a stop emits none.

While paused no messages are written, but these events still are. An event suppressed by the pause it describes would leave the hole it exists to account for.

Warning

Bag readers return messages in timestamp order, so the recorded order of events is only as monotonic as the clock was. A backward clock step (NTP correcting, or a virtualised host, where ~120 ms steps have been measured) reshuffles the events inside it, and a PAUSED can then appear after its RESUMED. The recorder’s own transition sequence is always correct and no event is lost; only the recorded order follows the clock. If a sequence fails to alternate, suspect the clock before the recorder.

Profiles¶

A named topic set, switched in one call. The fleet case it exists for: a supervisor changes the robot’s operating mode and the recorded topic set follows, without interrupting the topics the two modes share.

rosbag2_dynamic_recorder:
  ros__parameters:
    profile_names: ["idle", "navigation", "inspection"]
    profiles:
      idle: ["/tf", "/odom", "/imu"]
      navigation: ["/tf", "/odom", "/imu", "/scan"]

A worked example using the TurtleBot 4 simulator’s topics ships at rosbag2_dynamic_recorder/config/profiles.example.yaml. Recording profiles covers declaring, switching and designing them in full.

Parameters¶

Parameter	Default	Meaning
`uri`	`dynamic_bag`	Output bag path.
`storage_id`	`mcap`	Storage plugin.
`serialization_format`	`cdr`	Message serialization format.
`topics`	`[]`	Topics to subscribe at startup.
`start_paused`	`false`	Start with recording paused.
`use_sim_time`	`false`	Stamp messages on the node clock driven by `/clock`, and open nothing until it has started. See Simulation time.
`snapshot_mode`	`false`	Buffer in memory, write only on `~/snapshot`.
`max_cache_size`	`104857600`	Writer cache in bytes. `snapshot_mode` needs this or `max_cache_duration` > 0.
`max_cache_duration`	`0`	Writer cache bound in seconds; `0` for none. Combines with `max_cache_size`. Rolling only: refused at startup elsewhere.
`max_bagfile_size`	`0`	Split when a file reaches this many bytes; `0` never.
`max_bagfile_duration`	`0`	Split every this many seconds; `0` never.
`storage_preset_profile`	(empty)	Storage plugin preset. mcap: `none`, `fastwrite`, `zstd_fast`, `zstd_small`.
`storage_config_uri`	(empty)	Storage plugin YAML, overlaid on the preset.
`record_subscription_events`	`true`	Write subscription changes into the bag.
`record_pause_events`	`true`	Write pauses and resumes into the bag.
`record_low_disk_events`	`true`	Write a low-disk stop into the bag.
`record_bag_size_limit_events`	`true`	Write a bag-size-limit stop into the bag.
`record_split_events`	`true`	Write each rollover to a new file into the bag.
`min_free_space`	`0`	Stop recording below this many bytes free on the bag filesystem; `0` disables.
`min_free_space_percent`	`0.0`	Same, as a percentage of the filesystem; `0.0` disables. The stricter applies.
`max_bag_size`	`0`	Stop recording once the bag directory, across every split, exceeds this many bytes; `0` disables.
`storage_check_period`	`1.0`	Seconds between free-space and bag-size checks when either limit is set.
`messages_lost_report_period`	`5.0`	Seconds between `MessagesLostEvent`. `0` disables.
`status_publish_period`	`1.0`	Seconds between `~/status` publications.
`profile_names`	`[]`	Names of the declared profiles.

The five storage settings after max_cache_size are rosbag2’s own StorageOptions, passed through untouched. They matter most on a small computer writing to an SD card. When messages_lost_in_recorder climbs, the disk is not keeping up: max_cache_duration bounds how much recording is at risk in terms an operator can reason about; storage_preset_profile:=fastwrite cuts the per-message CPU cost; the zstd_* presets spend CPU to reduce disk bandwidth, which on a slow card with a spare core is a net gain; and a size or duration split keeps any one file small enough to survive a crash. With max_cache_size and max_cache_duration both 0 every message is written synchronously from its callback, which is what makes publishers overwrite their own history unseen; the recorder warns once at startup if you do that.

These are node parameters. The launch files forward only some of them: uri, storage_id, serialization_format, topics, start_paused, use_sim_time, snapshot_mode, the six storage settings, record_subscription_events, messages_lost_report_period, min_free_space, min_free_space_percent and max_bag_size. Set record_pause_events, record_low_disk_events, record_bag_size_limit_events, record_split_events, storage_check_period, status_publish_period, profile_names and the profiles themselves through params_file (or -p name:=value when running the node directly). The full argument list is in Install.

Calling them by hand¶

ros2 run rosbag2_dynamic_recorder dynamic_recorder --ros-args \
  -p uri:=/tmp/mybag -p "topics:=['/scan','/odom']"

ros2 service call /rosbag2_dynamic_recorder/subscribe_topics \
  rosbag2_dynamic_recorder_interfaces/srv/SubscribeTopics "{topics: ['/diagnostics']}"

ros2 service call /rosbag2_dynamic_recorder/set_topics \
  rosbag2_dynamic_recorder_interfaces/srv/SetTopics "{topics: ['/scan','/odom','/tf']}"

The other clients exist so you do not have to call these by hand; ros2 dynrec is the simplest of them.