Quickstart - Cerulion Docs

Camera to display in 5 minutes. ~60 ns latency. Zero config.

Cerulion lion mascot wiring together a camera and display node in a robotics lab

From Scratch
From ROS2

You’ll build a two-node pipeline — a camera publisher sending images to a display subscriber via zero-copy shared memory.

Prerequisites

Cerulion installed — see the Installation guide if not

What You’ll Build

A simple two-node pipeline:

camera_pub — Publishes an Image every 100ms
display_sub — Receives images and renders them

Step 1: Create a Workspace

Create the workspace

cerulion workspace create my_robot_workspace
cd my_robot_workspace

This creates:

my_robot_workspace

graphs

nodes

Cargo.toml

Step 2: Create the Nodes

Create the camera publisher

cerulion node create camera_pub --period-ms 100

This creates a periodic node that runs every 100 milliseconds.

Create the display subscriber

cerulion node create display_sub --ext-trigger

This creates an event-triggered node that runs when it receives input.

Your workspace now looks like:

my_robot_workspace

graphs

nodes

camera_pub

Cargo.toml

camera_pub.rs

display_sub

Cargo.toml

display_sub.rs

Cargo.toml

Step 3: Write the Node Code

camera_pub.rs
display_sub.rs

Open nodes/camera_pub/camera_pub.rs and replace its contents:

nodes/camera_pub/camera_pub.rs

use cerulion_core_v2::prelude::*;

/// Publishes an Image every 100ms.
/// The #[out("image")] attribute names the output port.
#[node(period_ms = 100)]
pub fn camera_pub() -> (#[out("image")] Image) {
    // Image lives in shared memory — subscribers read it directly
    let mut img = Image::new();
    img.set_height(480);
    img.set_width(640);
    img.set_encoding("rgb8");

    // Capture pixels (simulated here)
    let data = capture_pixels();
    img.set_data(&data);

    (img)
}

/// Fill pixel data (simulated). Real: grab from camera driver.
fn capture_pixels() -> Vec<u8> {
    vec![0; 480 * 640 * 3]
}

Image is a built-in ROS2-compatible message type. See Wireformat Messages for the full list of included types.

Open nodes/display_sub/display_sub.rs and replace its contents:

nodes/display_sub/display_sub.rs

use cerulion_core_v2::prelude::*;

/// Receives Images and displays them.
/// The #[node(trigger = "image")] means this runs whenever
/// a new message arrives on the "image" input.
#[node(trigger = "image")]
pub fn display_sub(image: &Image) {
    // No deserialization needed — this is the publisher's original memory
    render_on_screen(image.data());

    println!(
        "Received {}x{} image ({} bytes)",
        image.width(),
        image.height(),
        image.data().len()
    );
}

/// Real: blit to GPU / display server.
fn render_on_screen(_data: &[u8]) {}

Step 4: Create the Graph

Create the graph definition

cerulion graph create launch

This creates graphs/launch.crln.

Wire the nodes together

Open graphs/launch.crln and replace its contents:

graphs/launch.crln

name: my_robot

nodes:
  - id: camera
    type: camera_pub

  - id: display
    type: display_sub
    inputs:
      - name: image
        source_node: camera
        source_output_name: image

This connects the image output of camera_pub to the image input of display_sub.

Step 5: Run It

Launch the graph

cerulion graph run launch

You’ll see:

Building nodes...
  ✓ camera_pub
  ✓ display_sub

Starting graph: my_robot
  ✓ camera (camera_pub)
  ✓ display (display_sub)

Graph running. Press Ctrl+C to stop.

Open the TUI

In a new terminal:

cerulion tui

The TUI shows your graph running in real-time with node status, topic flow, and message rates.

What Just Happened?

Zero-Copy Transport

Images flow through shared memory. No serialization, no copying — the subscriber reads directly from where the publisher wrote.

~60 ns Latency

The image message reaches the subscriber in ~60 ns via shared memory. That’s 100,000x faster than ROS2’s default DDS for local Image transport.

Automatic Scheduling

camera_pub runs every 100ms automatically. display_sub triggers only when new data arrives.

Type-Safe Messages

Image is validated at compile time. Schema mismatches are caught before you run.

How zero-copy works: Think of a whiteboard in a shared office — the publisher writes on the board, and the subscriber reads it in place. Nobody makes a photocopy.

Already have ROS2 nodes? Port them to Cerulion’s Rust API incrementally — same message types, same pub/sub patterns — and get zero-copy shared memory (~60 ns latency), deterministic scheduling, and zero-copy logging.

Prerequisites

Cerulion installed — see the Installation guide if not

Existing ROS2 workspace with pub/sub nodes

What Changes

Your ROS2 node code is reimplemented in Cerulion’s Rust API. Same message types, same pub/sub patterns — faster backend.

Dimension	Before (ROS2)	After (Cerulion)
🌐 Local transport	DDS (serialized)	iceoryx2 (zero-copy)
⚡ Image latency	~6 ms	~60 ns
📝 Logging impact	Slows the stack	Zero performance impact
🎯 Determinism	Non-deterministic	Deterministic execution

Step 1: Create a Cerulion Workspace

Initialize from your existing project

cd your-ros2-workspace
cerulion workspace init .

This adds Cerulion configuration alongside your existing code.

Step 2: Migrate a Node

Take an existing ROS2 publisher — for example, a camera node that publishes sensor_msgs/Image:

use cerulion_core_v2::prelude::*;

#[node(period_ms = 33)]
pub fn camera() -> (#[out("image")] Image) {
    let mut img = Image::new();
    img.set_height(480);
    img.set_width(640);
    img.set_encoding("rgb8");
    img.set_data(&vec![0u8; 480 * 640 * 3]);

    (img)
}

The same sensor_msgs/Image type — but now it flows through zero-copy shared memory. No serialization for local subscribers.

Step 3: Wire and Run

Build the node

cerulion node build camera

Create and wire the graph

cerulion graph create perception

Open graphs/perception.crln and replace its contents:

graphs/perception.crln

name: perception

nodes:
  - id: camera
    type: camera

This runs your ported camera node as a standalone publisher. Add more nodes under nodes: as you migrate them.

Run it

cerulion graph run perception

Verify the topic is publishing:

cerulion topic hz image

Subscribed to: image
Average rate: 30.02 Hz
  Min: 29.98 Hz
  Max: 30.05 Hz
  Std Dev: 0.02 Hz
Window: 100 messages

Your image data flows via shared memory with sub-microsecond latency. Subscribers read directly from where the publisher wrote — no copies, no serialization.

What You Get Immediately

Zero-Copy Transport

sensor_msgs/Image with its variable-size data array works with zero-copy shared memory. No type changes needed.

Zero-Copy Logging

Record bags without slowing down the stack. What you record is what happened.

Deterministic Execution

Replay logs and get the same behavior. Essential for debugging production failures.

Less Code

No class hierarchies, no manual lifecycle, no QoS tuning. A function with an attribute macro.

ROS2 compatibility currently supports standard pub/sub patterns. For details on specific pattern support, schedule a call with the team.

Troubleshooting

Graph fails to start

Check your launch.crln wiring:

source_node must match a node id in the same file
source_output_name must match an #[out("name")] in the source node
name must match a parameter name in the target node

Build fails with missing dependency

Ensure you have Rust installed and up to date:

rustup update stable

Then rebuild:

cerulion node build camera_pub

iceoryx2 shared memory fails to start

Shared memory requires proper permissions. On Linux:

# Check shared memory limits
cat /proc/sys/kernel/shmmax

# Increase if needed (requires root)
sudo sysctl -w kernel.shmmax=2147483648

On macOS, this usually works out of the box. If not, try restarting your terminal.

TUI doesn't show any topics

Make sure your graph is running in another terminal:

# Terminal 1
cerulion graph run launch

# Terminal 2
cerulion tui

Topics only appear when nodes are actively publishing.

Pipeline running? Next, wire more nodes together with Publisher & Subscriber — or explore the Architecture Overview to understand what just happened under the hood.

Cerulion

AI Tools

​Prerequisites

​What You’ll Build

​Step 1: Create a Workspace

​Step 2: Create the Nodes

​Step 3: Write the Node Code

​Step 4: Create the Graph

​Step 5: Run It

​What Just Happened?

Zero-Copy Transport

~60 ns Latency

Automatic Scheduling

Type-Safe Messages

​Prerequisites

​What Changes

​Step 1: Create a Cerulion Workspace

​Step 2: Migrate a Node

​Step 3: Wire and Run

​What You Get Immediately

Zero-Copy Transport

Zero-Copy Logging

Deterministic Execution

Less Code

​Troubleshooting

Prerequisites

What You’ll Build

Step 1: Create a Workspace

Step 2: Create the Nodes

Step 3: Write the Node Code

Step 4: Create the Graph

Step 5: Run It

What Just Happened?

Prerequisites

What Changes

Step 1: Create a Cerulion Workspace

Step 2: Migrate a Node

Step 3: Wire and Run

What You Get Immediately

Troubleshooting