# ROS 2

Replay ROS 2 bags or stream live topics

- Category: Robotics
- Capabilities: Streams, History, Entities
- Runs on: Linux x64, Linux ARM64, macOS Apple silicon, macOS Intel, Windows x64

Bring a robot's ROS 2 data into Phloem. Replay a bag from disk, or stream live
topics over DDS or rosbridge. No ROS install is needed on this machine.

## Sources

Pick the **Source** first; only its settings show.

- **Bag** — replay a rosbag2 recording. Reads both `mcap` (the default since
  Iron) and `sqlite3` (the default before it), split bags, `metadata.yaml`,
  and zstd compression in file and message mode. Speed `0` loads as fast as
  the disk allows. **Loop** replays over and over, each pass timed from now.
- **DDS** — join the robot's ROS 2 graph like another node. Set the robot's
  `ROS_DOMAIN_ID` (0 unless the robot sets one), on a network that reaches the
  robot. Topics are found with their types. Each subscription matches its
  publisher, so a latched topic like `/tf_static` still arrives. Leave the
  topic list blank to take every topic. Nothing runs on the robot.
- **rosbridge** — subscribe to live topics on a robot running
  `rosbridge_server`. Each topic's type is looked up before subscribing.

## What you get

- **Joints** — `sensor_msgs/JointState` becomes one channel per joint, named
  by the robot: `/joint_states/position/left_hip_pitch`,
  `/joint_states/effort/left_hip_pitch`, with units (rad, rad/s, N·m). A limit
  can watch one joint; a chart can pick the joints it wants.
- **Diagnostics** — `diagnostic_msgs/DiagnosticArray` (`/diagnostics`) gives
  channels per component: `/diagnostics/left_wheel/level` as a word (`OK`,
  `WARN`, `ERROR`, `STALE`, a state strip in Replay), `/message`, and one
  channel per key/value pair (`/diagnostics/left_wheel/temperature`, numeric
  when the value is a number). Names stay stable when the list reorders.
- **Scene** — point clouds, laser scans, TF transforms, 3D detections and
  camera images draw in the 3D view, in the frame the message names.
- **Scene, the rest** — paths and polygons, poses and odometry, occupancy
  grids, camera models, GPS fixes (on the map), and every marker type (arrows,
  cubes, spheres, cylinders, lines, points, text, meshes) draw in the 3D view,
  each marker under its own name.
- **Everything else** — flattened to `topic/nested/field` channels. A type
  with no definition arrives as raw bytes, with a warning naming the fix.

## Setup

1. Pick the source. Browse to a bag, or set the DDS domain or rosbridge URL.
2. The table lists each topic, its type, its message count, and the channels
   it will create.
3. Tick the topics to bring in.

## Message definitions

MCAP bags, and sqlite3 bags from Iron or later, carry their own type
definitions. A **Humble-era sqlite3 bag carries only type names**. The
standard interfaces (`sensor_msgs`, `geometry_msgs`, `tf2_msgs`, `nav_msgs`,
`vision_msgs`, `std_msgs`, …) are built in, so those bags still decode.

For your own packages, point **Message definitions** at folders laid out as
ROS packages (`<dir>/<pkg>/msg/<Type>.msg`). Your copy wins over the built-in
one.

## Time

| **Time** | Places each sample at |
|---|---|
| `recorded` (default) | the bag's log time, or arrival time for a live topic |
| `header` | the message's `header.stamp`; a zero stamp falls back |

Choose `header` only when you trust the robot's clock. A simulator's clock
counts from zero.

## Missing data

- Over DDS, samples this machine missed show as a gap on the topic's channels.
- Messages `rosbridge_server` dropped before sending cannot be seen.

## Supports

- rosbag2 recordings: mcap and sqlite3 storage, split bags, zstd file/message compression
- Bags from ROS 2 Humble and earlier (no embedded definitions) — the common ROS 2 interfaces are built in; add your own packages under Message definitions
- Live ROS 2 topics straight from the DDS graph (ROS_DOMAIN_ID, topics discovered with their types, each writer's reliability and durability matched) — no ROS install on this machine
- Live ROS 1 / ROS 2 topics over rosbridge_server (ws://host:9090) — no ROS install on this machine

## Connection fields

| Field | Type | Required | Notes |
|---|---|---|---|
| Source | One of | Yes |  |
| Bag | Path | No |  |
| Your message packages | Folders | No | Only for message types outside the standard ROS 2 interfaces. |
| Time | One of | No |  |
| Speed | Number | No |  |
| Loop | On / off | No |  |
| ROS domain | Number | No |  |
| rosbridge URL | Text | No |  |
| Topics | Text | No |  |