Skip to main content

​
Usage

This guide shows you how to run the Cerulion Visualization bridge server and connect visualization tools like Lichtblick to visualize your Cerulion topics in real-time.

​
Prerequisites

Before running the bridge, ensure you have:

Built Binary

The bridge server built with --features bridge (see Installation Guide)

Running Topics

Cerulion topics actively publishing data via iox2 or zenoh

Lichtblick Installed

Lichtblick visualization tool installed and ready to use

Network Access

If using zenoh mode, ensure network connectivity is configured

​
Running the Bridge Server

The bridge server runs as a standalone process that connects to your Cerulion topics and provides a WebSocket endpoint for visualization clients.

​
Using the CLI

The bridge is accessed via the bridge subcommand of the cerulion binary:
1

Start the bridge for iox2 topics

For local IPC topics (iox2), run:
cargo run --bin cerulion --features bridge -- bridge --port 9090 --transport iox2
This command:
  • Starts the bridge server
  • Listens on port 9090 (default)
  • Connects to iox2 transport for topic discovery
  • Waits for WebSocket client connections
You can specify a different port with --port. The default is 9090, which matches the standard Rosbridge port.
2

Start the bridge for zenoh topics

For network topics (zenoh), run:
cargo run --bin cerulion --features bridge -- bridge --port 9090 --transport zenoh
This connects to zenoh transport instead of iox2.
3

Verify the server started

You should see output indicating the server is running:
Bridge server started on ws://0.0.0.0:9090
Transport mode: iox2
Discovering topics...
If you see this message, the bridge server is running and ready for connections!

​
Using the Example

You can also use the included example: 
cargo run --example lichtblick_bridge --features bridge
This example demonstrates a complete setup with default configuration.

​
Connecting Lichtblick

Once the bridge server is running, you can connect Lichtblick to visualize your topics.
1

Start the bridge server

First, ensure the bridge server is running (see above). Keep the terminal open - you’ll see connection logs here.
2

Open Lichtblick

Launch the Lichtblick application on your system.
3

Connect to the bridge

In Lichtblick, connect to the WebSocket endpoint:
ws://localhost:9090
If the bridge is running on a different machine, replace localhost with the server’s IP address or hostname.
4

Verify connection

In Lichtblick, you should see:
  • Connection status showing “Connected”
  • Available topics listed in the topic browser
  • Ability to subscribe to topics and view data
If topics appear in Lichtblick, the connection is successful and the bridge is working correctly!
5

Subscribe to topics

Click on topics in Lichtblick to subscribe and start visualizing the data stream.

​
Understanding the Bridge Output

The bridge provides diagnostic information to help you understand what’s happening:

​
Server Started

Bridge server started on ws://0.0.0.0:9090
This confirms the WebSocket server is listening for connections.

​
Topic Discovery

Discovering topics...
Found 5 topics via iox2
This shows how many topics were discovered from the selected transport.

​
Client Connections

Client connected from 127.0.0.1:54321
Client subscribed to topic: /sensor/camera/image
This indicates when clients connect and which topics they subscribe to.

​
Message Forwarding

Forwarding message from /sensor/camera/image (size: 921600 bytes)
This shows when messages are being forwarded to connected clients.
The bridge forwards messages in real-time as they arrive from Cerulion topics. There’s minimal buffering to keep latency low.

​
Common Usage Patterns

​
Local Development with Iox2

For local development where topics are published via iox2: 
# Terminal 1: Start your Cerulion nodes publishing topics
# Terminal 2: Start the bridge
cargo run --bin cerulion --features bridge -- bridge --transport iox2

# Terminal 3: Open Lichtblick and connect to ws://localhost:9090

​
Visualizing ROS Bags and ROS 2 Data

You can visualize existing ROS bags or live ROS 2 topics by combining Cerulion RCL Hooks with the visualization bridge:
1

Start RCL Hooks with ROS node or bag

First, run your ROS 2 node or play a ROS bag with RCL Hooks enabled to mirror messages to Cerulion:
# For a ROS 2 node:
LD_PRELOAD=/path/to/libcerulion_rcl_hooks.so ros2 run <package> <node>

# For ROS bag playback:
LD_PRELOAD=/path/to/libcerulion_rcl_hooks.so ros2 bag play <bag_directory>
The RCL Hooks will automatically capture ROS messages and mirror them to Cerulion topics via iox2.
See the RCL Hooks Usage Guide for detailed instructions on running ROS nodes with hooks enabled.
2

Start the visualization bridge

In a separate terminal, start the bridge to expose the mirrored topics:
cargo run --bin cerulion --features bridge -- bridge --port 9090 --transport iox2
The bridge will discover the topics that RCL Hooks mirrored to Cerulion.
3

Connect Lichtblick

Open Lichtblick and connect to ws://localhost:9090. You should see the ROS topics that were mirrored by RCL Hooks, now available for visualization.
This workflow lets you visualize ROS data in Lichtblick without modifying your ROS code or bags!
This is especially useful for analyzing ROS bag files or visualizing data from existing ROS 2 systems. The RCL Hooks handle the ROS-to-Cerulion conversion automatically, and the bridge handles the Cerulion-to-visualization conversion.

​
Network Visualization with Zenoh

For visualizing topics over a network: 
# On the server machine:
cargo run --bin cerulion --features bridge -- bridge --port 9090 --transport zenoh

# On your local machine:
# Connect Lichtblick to ws://server-ip:9090

​
Custom Port

If port 9090 is already in use: 
cargo run --bin cerulion --features bridge -- bridge --port 9091 --transport iox2
Then connect Lichtblick to ws://localhost:9091.

​
Verifying It’s Working

Here’s how to confirm the bridge is working correctly:
1

Check server is listening

Verify the server is listening on the expected port:
netstat -an | grep 9090
# or
lsof -i :9090
You should see the port is in LISTEN state.
2

Test WebSocket connection

You can test the WebSocket endpoint with a simple client:
# Using wscat (if installed)
wscat -c ws://localhost:9090
Or use any WebSocket client to verify the connection works.
3

Check topic discovery

Look at the bridge server logs to see if topics were discovered. You should see messages like:
Found 5 topics via iox2
4

Verify in Lichtblick

In Lichtblick, check that:
  • Connection status shows “Connected”
  • Topics appear in the topic list
  • You can subscribe and see data flowing
If all these checks pass, your bridge is working correctly!

​
Configuration Options

The bridge supports several configuration options:

​
Port Selection

--port 9090
Specify the WebSocket server port. Default is 9090.

​
Transport Mode

--transport iox2    # Local IPC
--transport zenoh   # Network transport
--transport both    # Both (future use)
Select which transport to use for topic discovery and subscription.

​
Topic Filtering

--topics topic1 topic2 topic3
(When implemented) Specify which topics to expose. By default, all discovered topics are available.
Most users will only need to specify --port and --transport. Other options are for advanced use cases.

​
Using Release Builds

For production use, use the optimized release build: 
target/release/cerulion bridge --port 9090 --transport iox2
The release build:
  • Handles more concurrent connections
  • Uses less memory
  • Has lower latency
  • Better suited for production deployments
Use debug builds for development and troubleshooting, and release builds for production deployments.

​
Troubleshooting

If something isn’t working, check the Troubleshooting Guide for common issues and solutions. Common issues include:
  • Port already in use
  • Topics not discovered
  • Connection refused errors
  • No data flowing to clients

​
Next Steps

Now that you’re running the bridge and visualizing topics, you might want to:
  • Learn about transport modes in detail
  • Check the troubleshooting guide for common issues
  • Explore advanced configuration options
  • Understand how message conversion works with schemas