Skip to main content
Conceptual humanoid vision sensor observing a test object in a robotics lab.
When a robot misbehaves, the first question is what it is actually publishing. These commands answer it from any terminal, for this machine or for a robot on your network. While a graph runs, every wired port becomes a topic you can observe. This guide covers listing and watching live topics — local or on a robot across the network — and the interactive dashboard.
The topic commands use iceoryx2 service discovery, so they work from any directory, no workspace required. Run them in a second terminal while a graph is running.

List and inspect live topics

cerulion topic list prints this machine’s shared-memory topics first, then the robots on your account and their topics, on one LAN or across networks.
If nothing is publishing, it prints No active local topics. cerulion topic info <topic> prints one topic’s schema and its last sequence number and timestamp:
topic info, echo, and hz each accept a remote robot’s topic too: a name that is not local is found on a robot on your account, demanded for the life of the command, and released when it exits. --local or CERULION_NETWORK=off keeps them local-only.

Watch messages with echo

cerulion topic echo <topic> subscribes and prints each message until you press Ctrl+C.
Echo prints one YAML document per message: a # seq=.. ts=..ns schema=0x.. size=.. comment, a # <type> comment, the fields, then ---. An array longer than --truncate-length (default 128) ends in !truncated <n>, the number of elements left out. Every type prints its fields this way, sensor_msgs/Image included. A frame no known schema names prints # comment lines that say why, with a hex preview of its first 64 payload bytes.

Measure publish rate

cerulion topic hz <topic> measures how often a topic publishes, until Ctrl+C.
For the periodic camera created with --policy period_ms=33, topic hz should report roughly 30 Hz.

Find topics by type, and measure bandwidth

cerulion topic type <topic> prints a topic’s message type, and cerulion topic find <type> lists every topic that carries one:
cerulion topic bw <topic> measures how many bytes a topic carries per second, over its newest 100 messages by default (--window N changes that):

Publish a test message

cerulion topic pub <topic> <type> <message> publishes one message given as JSON or YAML. --times N and --rate HZ publish several:
A message you publish reaches every subscriber of that topic, a robot’s controller included. Publish on a topic nothing acts on, such as a status topic of your own, and never into a topic a running graph already publishes: topics are single-writer.

Save a camera frame

cerulion topic snapshot <topic> -o <file> saves the newest frame of a sensor_msgs/Image or sensor_msgs/CompressedImage topic as a JPEG:

Open the interactive dashboard

cerulion tui launches an interactive terminal dashboard. Logging is suppressed while the TUI is open.

Keep a record instead of watching

echo and hz answer questions about now. To keep the data, record the run to an MCAP bag and inspect it afterwards; see Record and replay a run.

Clean up stale services

iceoryx2 keeps on-disk bookkeeping for each node. When a graph’s topology changes between runs, stale entries from dead nodes can cause discovery errors. cerulion clean removes the bookkeeping dead Cerulion processes left behind; live nodes are left alone. It needs no account and reaches no network. It prints cleanup counts and per-cause remediation, and names every node it could not reclaim together with the reason. A graph that stops normally already runs a short cleanup pass of its own as it exits, so reach for this command mainly after a run that was killed, or when you want everything cleared at once. cerulion clean --report-only deletes nothing: it lists what a plain cerulion clean would remove and ends with Report only: nothing was removed.
Run cerulion clean if you rewire a graph and then see stale-service errors on the next graph run. It will not disturb a graph that is currently running.

Next steps

Wire and run a graph

Produce the topics you inspect here.

Messages and schemas

Understand the message shapes that echo prints.

Reach remote robots

Discovery, same-account access, and pulling a robot’s topics to your desk.