Define a node

A node is a Rust crate with a #[cerulion_node] struct and a tick() method. This guide takes you from cerulion node create to a node that reads inputs, writes outputs, and is ready to stage into a graph. For the full attribute and policy grammar, see the node macro reference and trigger policies reference.

Run these commands from inside a workspace (a directory with a [workspace] Cargo.toml and a graphs/ folder). Create one with cerulion workspace create <name>.

Create the node type

cerulion node create <node_type> scaffolds nodes/<node_type>/ with a Cargo.toml (cdylib) and a src/lib.rs macro template. The type name becomes the folder name and, PascalCased, the struct name. It must be non-empty, alphanumeric or underscore, and must not start with a digit. Add ports while creating the node:

Flag	Value names	Meaning
`-o` / `--output`	`SCHEMA NAME`	Add one output port.
`-i` / `--input`	`SCHEMA NAME`	Add one regular input port.
`-T` / `--trigger-input`	`SCHEMA NAME`	Add one trigger input (fires the node on data arrival).
`--policy`	`SPEC`	Set the trigger policy (see below).

Each of -o, -i, and -T takes two values (a schema and a name), and you may pass at most one of each per create call. Add more ports later with node modify. Schemas accept both sensor_msgs/Image and sensor_msgs::Image; both canonicalize to the slash form.

Pick a trigger policy

The trigger policy decides when the node fires. Pass it with --policy SPEC:

`--policy` SPEC	Fires when…
`period_ms=N`	Every N milliseconds (N > 0).
`sync_window_ms=N`	All trigger inputs have a message within an N-ms window.
`external`	The node fires itself off a non-Cerulion signal (a device fd or a blocking SDK call).
`data_trigger=NAME`	The named trigger input receives data.

Conceptual close-up of a robot joint sensor and its signal indicator.

How the policy defaults when you omit --policy depends on the node’s inputs:

0 inputs (no -i, no -T): a source-only node must declare a non-data policy. cerulion node create errors otherwise.
1+ inputs via -i only: no node-level policy is written; the runtime fires on any input arrival and emits a graph-build warning.
-T set: the policy becomes data_trigger for that trigger input.

A source-only node (zero inputs) has nothing to fire it, so you must give it an explicit non-data policy with --policy period_ms=N or --policy external. Combining a non-data --policy with -T is a conflict and errors.

Create a periodic source node

A camera with no inputs needs a period:

cerulion node create camera -o sensor_msgs/Image image --policy period_ms=33

Created node type 'camera'

Create a data-triggered consumer

A detector that fires whenever an image arrives:

cerulion node create detector -T sensor_msgs/Image image -o geometry_msgs/PoseStamped detection

Created node type 'detector'

Write the tick()

Open nodes/<node_type>/src/lib.rs. The template pairs two macros:

#[cerulion_node(...)] on the struct declares the node and its trigger policy, and generates the glue that lets cerulion graph run load it.
#[cerulion_node_impl] on the adjacent impl block lets tick() use plain field access for ports — reads and writes go directly to shared memory, zero-copy. It takes no arguments, and the struct must appear before the impl block.

Import everything from the prelude, and import the message types you use:

use cerulion_core::prelude::*;
use native_ros2_messages::geometry_msgs::Vector3;
use native_ros2_messages::sensor_msgs::LaserScan;

#[cerulion_node(period_ms = 10)]      // period-driven; reads the latest scan each tick
#[derive(Default)]
struct SafetyController {
    #[input(depth = 1)]               // regular input (use `trigger` for data-triggered)
    scan: LaserScan,

    #[output]                         // Vector3 = fixed-only schema (pub x/y/z: f64)
    linear_velocity: Vector3,
}

#[cerulion_node_impl]
impl SafetyController {
    fn tick(&mut self) -> Result<(), NodeError> {
        // Variable field read via typed accessor:
        let obstacle_close = self.scan.ranges().iter().any(|&r| r < 0.5);
        // Fixed field write; goes straight to shared memory:
        self.linear_velocity.x = if obstacle_close { 0.0 } else { 0.3 };
        Ok(())
    }
}

Fixed vs variable fields

How you write an output field depends on whether it is fixed-size or variable-length:

Fixed primitive fields (for example x, y, z, height, width) are written directly: self.linear_velocity.x = 0.3;. The write goes straight to shared memory.
Variable-length fields (string, T[]) are also written with plain assignment, but they are read through an accessor — self.scan.ranges() — because their length is only known at runtime.

#[output] is the only form you need, for every schema:

use cerulion_core::prelude::*;
use native_ros2_messages::sensor_msgs::Image;

#[cerulion_node(period_ms = 33)]
#[derive(Default)]
struct Camera {
    #[output]
    image: Image,
}

#[cerulion_node_impl]
impl Camera {
    fn tick(&mut self) -> Result<(), NodeError> {
        self.image.height = 480;                    // fixed field, direct write
        self.image.width = 640;                     // fixed field, direct write
        self.image.encoding = "rgb8";               // variable field, plain assignment
        self.image.header.frame_id = "camera";      // nested field, same
        Ok(())
    }
}

Earlier versions required you to list variable fields in the attribute (#[output(data, encoding)]) and to wrap nested ones in complex(...). Both forms are gone — write #[output] and assign the fields.

Only the outputs you actually touch during a tick are published, so a node can hold a channel silent by leaving it alone. A tick that returns Err publishes nothing at all.

Zero-copy write for large payloads: plain = assignment copies your buffer once. For camera drivers or codecs that can write directly into a destination buffer, use fill_from instead — your producer receives the destination buffer itself, skipping the copy:

self.image.data.fill_from(|buf: &mut [u8]| {
    let n = driver.read_frame_into(buf)?;
    Ok(n)
})?;

FillFrom and SliceSource are re-exported from cerulion_core::prelude. See the node macro reference for details.

Build the node

cerulion node build <node_type> compiles the crate into a cdylib. Add --release for an optimized build.

node build shells out to cargo, so cargo must be on your PATH. A missing toolchain is reported as such and names what to install: Rust 1.93 or later from rustup, plus a C linker — build-essential on Ubuntu and Debian, the Xcode Command Line Tools on macOS.

cerulion node build camera
cerulion node build detector

Built 'camera'

A successful build prints Built '<node_type>'. On failure the CLI prints Error: with the cargo output, and no cdylib is produced.

Inspect and adjust

Use these commands to review and edit node types after creation.

List node types

cerulion node list prints a table of types with input/output counts and a short policy label.

cerulion node list

TYPE       INPUTS  OUTPUTS  POLICY
camera     0       1        period 33ms
detector   1       1        trigger:image

Show one node's details

cerulion node info <node_type> prints the type, policy, and each port with its schema. Metadata is parsed from src/lib.rs; there is no sidecar file.

cerulion node info detector

Add ports later

cerulion node modify <node_type> mutates src/lib.rs in place, preserving the tick body and comments. It takes the same -i, -T, -o, and --policy flags (at most one of each per call).

cerulion node modify detector -i sensor_msgs/Imu imu

Added input 'imu' to 'detector'

Adding a trigger input with -T also sets the data_trigger policy. To make a node externally triggered, use --policy external.

Delete a node type

cerulion node delete <node_type> removes the node crate and its workspace member entry.

cerulion node delete detector

Deleted node type 'detector'

Next steps

Wire and run a graph

Stage these node types into a graph and run it.

Trigger policies

The full --policy grammar and defaulting matrix.

Backpressure and deadlines

Queue policies, rate caps, and reacting to late data in code.

Get started

Concepts

Guides

Studio and Hindsight

Reference

Community

Create the node type

Pick a trigger policy

Write the tick()

Fixed vs variable fields

Build the node

Inspect and adjust

Next steps

Wire and run a graph

Trigger policies

Backpressure and deadlines

​Create the node type

​Pick a trigger policy

​Write the tick()

​Fixed vs variable fields

​Build the node

​Inspect and adjust

​Next steps

Wire and run a graph

Trigger policies

Backpressure and deadlines

Create the node type

Pick a trigger policy

Write the tick()

Fixed vs variable fields

Build the node

Inspect and adjust

Next steps