Skip to main content

​
Transport Modes

The Cerulion Visualization bridge supports different transport modes, allowing you to visualize topics from local IPC (iox2) or network transport (zenoh). Understanding these modes helps you choose the right configuration for your use case.

​
Overview

Transport modes determine how the bridge connects to your Cerulion topics:

Iox2 Mode

Local inter-process communication via iceoryx2

Zenoh Mode

Network transport via zenoh

Both Mode

Both transports simultaneously (future)
You can only use one transport mode at a time when running the bridge. Choose the mode that matches how your topics are published.

​
Iox2 Mode

Iox2 mode connects to topics published via iceoryx2, which provides efficient local inter-process communication on a single machine.

​
What It Does

Iox2 mode:
  • Discovers topics from iceoryx2’s service registry
  • Subscribes to topics using local IPC
  • Forwards messages to WebSocket clients
  • Works entirely on the local machine
Iox2 is ideal for local development, single-machine deployments, and scenarios where all your Cerulion nodes run on the same system.

​
When to Use Iox2 Mode

Use iox2 mode when:
  • All your Cerulion nodes run on the same machine
  • You’re doing local development or testing
  • You want the lowest latency for local visualization
  • You don’t need network access to topics

​
How Topic Discovery Works

The bridge discovers iox2 topics by:
  1. Querying iceoryx2’s service registry
  2. Listing all available publish-subscribe services
  3. Making these topics available to WebSocket clients
Iox2 topic discovery is automatic - you don’t need to configure topic names manually. The bridge finds all available topics when it starts.

​
Running with Iox2 Mode

Start the bridge with iox2 transport: 
cargo run --bin cerulion --features bridge -- bridge --port 9090 --transport iox2
You should see output like: 
Bridge server started on ws://0.0.0.0:9090
Transport mode: iox2
Discovering topics...
Found 5 topics via iox2

​
Configuration Example

For iox2 mode, you typically don’t need additional configuration. The bridge automatically:
  • Connects to the local iceoryx2 service registry
  • Discovers available topics
  • Subscribes when clients request them
If you see topics discovered in the logs, iox2 mode is working correctly!

​
Zenoh Mode

Zenoh mode connects to topics published over the zenoh network, enabling visualization of distributed Cerulion systems.

​
What It Does

Zenoh mode:
  • Connects to the zenoh network
  • Discovers topics available over the network
  • Subscribes to topics via zenoh
  • Forwards messages to WebSocket clients
Zenoh is ideal for distributed systems, remote visualization, and scenarios where Cerulion nodes run on different machines.

​
When to Use Zenoh Mode

Use zenoh mode when:
  • Your Cerulion nodes are distributed across multiple machines
  • You need to visualize topics from remote systems
  • You’re working with network-based deployments
  • You want to visualize topics from different network locations

​
How Topic Discovery Works

Zenoh topic discovery:
  • Uses zenoh’s query mechanism to discover available topics
  • Maintains a topic registry of discovered topics
  • Leverages zenoh’s built-in discovery features
Zenoh topic discovery is currently a placeholder in the implementation. In production, you would use zenoh’s query mechanism. For now, you may need to manually subscribe to known zenoh topics in Lichtblick.

​
Running with Zenoh Mode

Start the bridge with zenoh transport: 
cargo run --bin cerulion --features bridge -- bridge --port 9090 --transport zenoh
You should see output like: 
Bridge server started on ws://0.0.0.0:9090
Transport mode: zenoh
Connecting to zenoh network...
Ensure zenoh is properly configured and running before starting the bridge in zenoh mode. The bridge needs to connect to the zenoh network.

​
Configuration Example

For zenoh mode, you may need to:
  • Configure zenoh session parameters
  • Set up network connectivity
  • Ensure zenoh routers are accessible
The bridge can use an optional shared zenoh session if provided in the configuration.

​
Current Limitations

Zenoh mode has some current limitations:
  • Topic discovery is a placeholder (not fully implemented)
  • You may need to manually specify topics
  • Some zenoh features may not be fully supported
These limitations are expected to be addressed in future releases as zenoh support matures.

​
Both Mode

Both mode is designed to support both iox2 and zenoh transports simultaneously, though this is currently for future use.

​
What It Does

Both mode (when fully implemented) will:
  • Connect to both iox2 and zenoh transports
  • Discover topics from both sources
  • Merge topic lists from both transports
  • Allow clients to subscribe to topics from either transport

​
When to Use Both Mode

Both mode will be useful when:
  • You have topics published via both transports
  • You want a unified view of all available topics
  • You’re transitioning between transport modes
  • You need to visualize mixed local and network topics
Both mode is planned for future releases. For now, use iox2 or zenoh mode depending on your primary transport.

​
Choosing a Transport Mode

Here’s guidance on which mode to use:

Use Iox2 If...

  • All nodes run on one machine
  • You’re doing local development
  • You want lowest latency
  • Network isn’t needed

Use Zenoh If...

  • Nodes are distributed
  • You need remote visualization
  • You’re using network transport
  • Topics span multiple machines

​
Decision Flow

  1. Are all your Cerulion nodes on the same machine?
    • Yes → Use iox2 mode
    • No → Use zenoh mode
  2. Do you need to visualize topics from remote systems?
    • Yes → Use zenoh mode
    • No → Use iox2 mode
  3. Are you doing local development?
    • Yes → Use iox2 mode (simpler, faster)
    • No → Consider your network setup
When in doubt, start with iox2 mode for local development. You can always switch to zenoh mode if you need network access later.

​
Switching Between Modes

You can switch transport modes by restarting the bridge with a different --transport option: 
# Stop the current bridge (Ctrl+C)

# Start with different transport
cargo run --bin cerulion --features bridge -- bridge --transport zenoh
Switching modes requires restarting the bridge. Active WebSocket connections will be lost, so clients will need to reconnect.

​
Transport-Specific Considerations

​
Iox2 Considerations

  • Requires iceoryx2 to be running
  • Only works on the local machine
  • Very low latency
  • No network configuration needed

​
Zenoh Considerations

  • Requires zenoh network to be accessible
  • May need network/firewall configuration
  • Supports distributed systems
  • Network latency applies

​
Message Conversion

Regardless of transport mode, message conversion works the same way:
  • With Schema: Messages are converted to JSON using Cerulion schemas
  • Without Schema: Messages are returned as hex-encoded data
The transport mode only affects how topics are discovered and subscribed to. Message conversion is independent of the transport mode.

​
Troubleshooting Transport Issues

​
Iox2 Issues

If iox2 mode isn’t working:
  • Verify iceoryx2 is running
  • Check that topics are actually published via iox2
  • Ensure the bridge can access the iceoryx2 service registry

​
Zenoh Issues

If zenoh mode isn’t working:
  • Verify zenoh network connectivity
  • Check zenoh configuration
  • Ensure zenoh routers are accessible
  • Verify network/firewall settings
For more troubleshooting help, see the Troubleshooting Guide.

​
Next Steps

Now that you understand transport modes: