Skip to main content

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.

A graph is a .yaml file that wires node instances together by their ports. This guide takes you from an empty graph to a running one, and covers the difference between validating and running. The perception graph you build below wires a camera instance to a detector instance: the detector’s image input reads the camera’s image output, which you set up with -I. Figure: The example topology. -I image [camera,image] wires the detector’s image input to the camera’s image output.
Run these commands from inside a workspace. You need built node types first — see Define a node.

​
Create a graph

cerulion graph create <name> writes graphs/<name>.yaml. Pass -n/--prefix to set a topic prefix; if you omit it, the prefix line is left out and resolves to the machine’s hostname at load time. 
cerulion graph create perception

Created graph 'perception'
Graph files are YAML with a .yaml extension and carry topology only — they do not contain a policy: block. Trigger policies live on the node macro.

​
Stage node instances

cerulion node stage <node_type> appends a node instance to a graph and auto-derives its outputs from the node’s source metadata.
FlagValue namesMeaning
-i / --idIDInstance ID (defaults to the node type).
-g / --graphGRAPHTarget graph. Omit to auto-select (see below).
-INAME SOURCEWire input NAME to SOURCE. Repeatable.
The -I source accepts either node/port or the [node,port] form; both resolve to node/port.
When you omit -g, the CLI auto-selects the workspace’s sole graph. If there are zero graphs or more than one, it errors and asks you to name one.
node stage also parses a -p/--prefix flag, but the handler currently ignores it — staging does not change topic prefix resolution. Set the prefix on the graph with graph create -n instead.

Stage the source node

cerulion node stage camera -g perception

Staged 'camera' into graph 'perception'

Stage the consumer and wire its input

Wire the detector’s image input to the camera’s image output:
cerulion node stage detector -g perception -I image [camera,image]

Staged 'detector' into graph 'perception'
Each node stage validates the resulting graph and rejects duplicate instance IDs.

​
Validate vs run

These two commands treat failures differently:
  • cerulion graph validate <name> runs the full validation report (topology, node crates exist, ports parse, cdylibs exist, input bindings and schemas match) and exits non-zero if any check fails.
  • cerulion graph run <name> only warns on validation problems and continues. Use validate as a gate in scripts or CI.
cerulion graph validate perception
graph validate prints a report and exits 0 when every check passes. A non-zero exit means at least one check failed — read the report to see which.

​
Run the graph

cerulion graph run <name> loads the compiled cdylibs, builds the runtime, and steps a simulated clock until you stop it with Ctrl+C or a node requests shutdown. 
cerulion graph run perception
graph run loads compiled cdylibs and needs cargo available, so build your nodes first. It runs an iceoryx2 dead-node cleanup at start.

​
Real-time and validation flags

FlagDefaultEffect
--real-time[=BOOL]trueDrive the sim clock from wall time with ~1 ms pacing. Bare --real-time means --real-time true.
--no-real-timeoffRun full-speed with no pacing — for benches and replay.
--no-validateoffSkip the pre-run validation check entirely.
Real-time pacing is on by default. To opt out, pass --no-real-time or --real-time false: 
cerulion graph run perception --no-real-time
If you pass both --real-time and --no-real-time, --no-real-time wins — the run goes full-speed.
Press Ctrl+C to stop a running graph.

​
Smoke-test a single node

cerulion node run <node_type> runs one node in a hidden temporary graph (not real-time, validation skipped) and deletes that temp graph on exit. It is a quick way to check that a node loads and ticks without wiring a full graph. 
cerulion node run camera
Press Ctrl+C to stop it.
If you change a graph’s topology between runs (add, remove, or rewire nodes) and hit stale iceoryx2 service errors, run cerulion clean to clear bookkeeping for dead nodes, then run again.

​
Next steps

Inspect topics

Watch the running graph with topic echo, hz, and the TUI.

Define a node

Add or adjust the node types you stage here.