> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cerulion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bridge a ROS 2 system

> Discover an existing ROS 2 robot's DDS topics with cerulion ros attach, generate a bridge graph, and consume the topics in Cerulion.

`cerulion ros attach` points Cerulion at a robot that is already running ROS 2. It discovers the live DDS topics, generates a bridge graph for the ones whose types resolve, and runs it — so those topics become ordinary Cerulion topics you can echo, record, visualize, and consume from your own nodes.

Run it **on the robot**, or on a machine on the robot's DDS network.

## Look before you write

`--dry-run` prints the discovery report and stops: it writes nothing and runs nothing.

```bash theme={null}
cerulion ros attach --iface 192.168.123.18 --dry-run
```

| Flag             | Default  | Meaning                                                                                                                                                                             |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--iface IP`     | required | The robot-LAN interface to run DDS discovery on. Required, because restricting discovery to one interface is what keeps a multi-homed host from dropping fragmented discovery data. |
| `--domain N`     | `0`      | Must match the robot's `ROS_DOMAIN_ID`.                                                                                                                                             |
| `--timeout SECS` | `5`      | Discovery window. Must be greater than 0 and at most 3600.                                                                                                                          |

The report tells you which topics resolved to a known type and which did not. A topic whose type Cerulion cannot resolve is left out of the generated graph — add the message definition to your workspace and re-run if you need it.

## Generate and run the bridge

```bash theme={null}
cerulion ros attach --iface 192.168.123.18 --graph-name go2
```

It writes `graphs/go2.yaml` plus `graphs/go2.bridge.yaml`, asks you to confirm, and then runs the bridge. Use `--yes` for scripts and non-interactive shells.

| Flag                    | Meaning                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `--graph-name NAME`     | Names the generated files (default `attach`).                                                       |
| `--topic-prefix PREFIX` | Prepends a prefix to each generated Cerulion topic name. By default the ROS topic name is mirrored. |
| `--robot-name NAME`     | The namespace label written as the graph's `prefix:`.                                               |

<Note>
  `--robot-name` is not the network identity. The name that shows up in `cerulion topic list` and over mDNS comes from the machine's hostname, or from `CERULION_ROBOT_IDENTITY` if you set it.
</Note>

## See the data on your desk

The generated graph bridges the robot's topics and nothing else — no visualization node is staged on the robot, which keeps the robot's job to shipping raw frames. To look at the data, work from your own machine:

```bash theme={null}
cerulion topic list                  # the robot and its topics appear here
```

Then connect to the robot in Cerulion Studio and check the topics you want to watch. Your desk demands each topic, the frames are mirrored into desk-local shared memory, and decoding and rendering happen there — see [Visualize a running graph](/cerulion/guides/visualize-in-studio). See [Reach remote robots](/cerulion/guides/network-and-remote-robots).

## Consume a bridged topic from your own node

A bridged topic is a normal topic, so wire an input to it by absolute name:

```yaml theme={null}
nodes:
  - id: obstacle_monitor
    type: obstacle_monitor
    inputs:
      - name: cloud
        source: /go2/utlidar/cloud
```

An absolute source with no in-graph producer is an **external topic**: Cerulion does not own it, and other publishers attach to it freely.

## Record a bridged system

A bridge run records like any other run, and a recording of one plays back as a robot substitute when the robot is not available:

```bash theme={null}
cerulion bag record -a -o go2_session.mcap --duration 60
```

<Note>
  Use plain `bag play` for a bridge recording. A bridge node reads a live device rather than computing from its graph inputs, and `--resim all` re-executes **every** node in the bag — including the bridge, against DDS that is no longer there. See [Record and replay a run](/cerulion/guides/record-and-replay).
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Message types" icon="envelope" href="/cerulion/reference/message-types" color="#0080FF">
    The 254 built-in ROS 2 messages that resolve out of the box.
  </Card>

  <Card title="Record and replay a run" icon="circle-dot" href="/cerulion/guides/record-and-replay" color="#0080FF">
    Bag a bridged system and play it back without the robot.
  </Card>
</CardGroup>