Best Visualisation and Debugging Tools for Robot Projects

For most robot projects the best combination is RViz 2 or Foxglove for what the robot sees, PlotJuggler for numbers over time, and recorded runs. Between them they answer what the robot believed and when that belief changed. That flips when the fault is timing, not content, because a viewer draws what arrived and never what was late, a question about ROS 2, HORUS and the layer beneath. The rest of this post is for someone on a ROS 2 robot who is tired of adding print statements to find one bug.

Your robot did something wrong and you cannot see why. The terminal is a wall of text from six programs at once, none of it timestamped in a way you can line up, and the one message you actually wanted scrolled past while you were reading the one before it.

So you add a print statement, then another, then a counter, and now the terminal is worse and the robot behaves slightly differently because you added the prints. The bug moved.

Meanwhile the parts you would most like to look at are the parts text cannot show. You want to see where the robot thought it was when it turned early. You want to see whether the obstacle it swerved around was ever really there. You want to know whether the arm command was wrong or the arm was fine and the estimate of the table was wrong, and no amount of numbers scrolling past a terminal is going to settle that. What you need is a picture, a graph, and a way to watch the same failure more than once.

What are the best tools for seeing what a robot is doing?

RViz 2 for spatial data, PlotJuggler for values over time, and recorded runs so the failure can be watched again. That trio covers most of what goes wrong on a robot with sensors, and all three are a short install away. RViz 2 draws the world as the robot understands it: the map, the laser returns, the camera cloud, the coordinate frames hanging off each joint. PlotJuggler draws a value against time, which is the right shape for a drifting estimate, an oscillating controller or a battery sagging under load. Recordings made with the ros2 bag tool turn a fault you saw once into a fault you can study, which changes debugging from hunting to reading. Foxglove substitutes for RViz 2 when you want the same picture in a browser, shareable with somebody who has no ROS 2 environment. Everything else is for a narrower job, and the trio tells you which one you have.

What does a robot visualisation tool actually do?

A robot visualisation tool draws the robot's own beliefs, not the world. That distinction is the single most useful thing to understand about the category. When RViz 2 shows a wall, it is not showing a wall; it is showing that the robot believes there is a wall there. When the picture shows the robot in the middle of the room and the robot is actually against the door, the tool is working perfectly and the robot is wrong. This is why a viewer is so effective on a whole class of faults. Many robot problems are disagreements between belief and reality, and the fastest way to find one is to put the belief on a screen beside the reality you can see. It is also why a viewer cannot help with faults where the belief is correct and something else went wrong, such as a command that arrived after the moment it was needed. What is a robot software stack, layer by layer shows where the viewer sits relative to everything else.

What are the actual options for looking inside a running robot?

There are six families, and a working robot project usually uses three of them. Spatial viewers such as RViz 2 and Foxglove draw the robot and its sensor data in three dimensions. Time-series plotters such as PlotJuggler draw a chosen value as it changes. Graph inspectors such as the rqt tools answer whether the programs are even connected to each other. Recorders such as ros2 bag capture a run so it can be replayed. General logging, meaning a timestamped line of text with a name and a value, remains the tool that finds the most bugs despite being the least impressive. Finally there is the layer under all of it, the messaging system itself, whether that is ROS 2 or a single-machine middleware such as HORUS, because some faults are not in your programs at all but in how messages travel between them. Choosing among the first five is about the shape of your data. Reaching for the sixth is about a fault the first five keep failing to explain.

How do the debugging tools compare?

The rows run from the most visual to the least, which is also roughly the order people try them.

Read the last two columns first. Most wasted evenings come from using a spatial viewer on a fault that was never spatial.

Which tools fit if you are one person on a hobby robot?

Timestamped logging and one recorder, and add a viewer only when your robot grows a sensor whose output is a shape. A solo builder is served badly by installing an ecosystem before there is a fault worth pointing it at, because every tool has its own setup, vocabulary and way of being misconfigured. Start with log lines that carry a timestamp, the name of the thing speaking and one value, written so that two programs' logs can be sorted together into one story. That single habit finds most early faults. Add recording next, because the moment a fault becomes rare you will want it back. The viewer becomes worth its setup when your robot has a camera, a laser or a map, at which point the picture beats any amount of reading. The order matters more than the choice: builders who install the visual tools first tend to stare at a beautiful picture of a robot that is not moving. Robotics projects for beginners that teach the software side suggests builds where each tool earns its place in turn.

What if your robot is a small board with no screen attached?

Then the tools split into what runs on the robot and what runs on your laptop, and that split is the whole design of your debugging setup. A small board can record and log, and both should happen on the robot itself where nothing is lost to a dropped connection. Drawing pictures should happen elsewhere, because rendering is work the board should not be doing while also driving your robot. The usual arrangement is recording on the robot, copying the file off afterwards, and opening it on a laptop where a viewer has room to breathe. Live viewing over the network works and is pleasant, and it introduces a second problem, since streaming everything to your laptop changes the load on the robot and can hide or create the fault you are hunting. Watch the disk too, because recordings fill a small card quickly and a full card produces failures that look like anything except a full card. Best robotics middleware for Raspberry Pi and Jetson robots covers what else changes on constrained hardware.

What should you install if the bug has to be found tonight?

Install nothing, and start recording. On a deadline, the highest-value move is capturing the fault while it happens, because a fault on disk is one you can work on tomorrow and a fault you merely watched is one you will argue about. Start the recorder, reproduce the problem as many times as you can, and only then start looking. When you do start looking, use whatever is already installed, because a tool you install tonight will consume the evening in setup. If the robot has ROS 2, the graph inspector will tell you within a minute whether the programs are connected, which eliminates a whole class of causes for free. Then read your own logs sorted by time, because ordering questions are the most common and the least visual. Reach for the picture only once you know the fault involves a shape, a frame or a place. Why does my robot behave differently every run covers the faults that most often produce a panicked evening.

What skill level do these tools assume?

The viewers assume ROS 2 vocabulary, and the logging assumes nothing, and that gap explains most of the frustration newcomers report. To get a useful picture out of RViz 2 you need to know what a topic is, what a coordinate frame is, and which frame your data is expressed in, because the most common newcomer experience is an empty window with an error about a missing transform. That is not a bug in the tool; it is the tool asking a question the robot has not answered. PlotJuggler is gentler, and the main skill is knowing what your own values look like when things are healthy, which you learn by watching them when nothing is wrong. Recording and replaying is the easiest habit to acquire and the one with the largest return. The honest sequence is logging in week one, recording in week two, plots when you have a number you distrust, and the spatial viewer when you have sensors whose output is a shape.

What do people try first, and why does printing stop working?

People print, and printing stops working the moment two programs are involved. The breakdown comes when the answer depends on the order of events across programs, because each program's output arrives in your terminal in an order that has more to do with buffering than with what actually happened. You end up with two lines that appear to prove the command came before the sensor reading, when in fact they arrived in the terminal that way and not on the robot. The second breakdown is that printing changes the thing it measures, since writing text takes time and a program printing on every cycle is a program doing something it did not do before. The escape is not a fancier tool. It is timestamps taken at the moment of the event rather than the moment of the print, one identifier per message so you can follow one item through the system, and recording rather than watching. Why is my robot dropping sensor data is the fault that most often teaches this lesson.

What do you give up by leaning on the heavy viewers?

You give up the ability to trust what you are measuring, in a specific and avoidable way. A full visual setup, streaming several sensor topics to a viewer on a laptop, adds work to the robot and traffic to the network, and both of those change how the system behaves. The classic version of this is a fault that disappears whenever you are watching, which sends teams on a long hunt for a phenomenon whose real name is the debugging setup. The second cost is time: a serious visual configuration is a project of its own, and it is easy to spend a day building a beautiful view of a problem your logs already held. The third cost is storage, because recordings of camera data become large quickly, and a machine that stops mid-experiment because a disk filled has taught nobody anything. None of this argues against the viewers, which are excellent. It argues for turning them on deliberately rather than leaving everything streaming all the time.

When is ROS 2 the better choice?

ROS 2 is the better choice whenever the tooling itself is a reason for your decision, and for debugging tooling it is not close. The visual ecosystem, the recording format, the replay tools, the graph inspectors and the years of accumulated advice about which panel to open when a transform is missing all live in the ROS 2 world, and nothing else offers the same depth. If you expect to spend real time looking at maps, frames and sensor data, that ecosystem is a serious argument on its own, quite apart from the packages. HORUS is not the answer to that question, because a shared-memory layer for a single machine gives you a way for programs to exchange data and does not give you a viewer, a bag format or a decade of forum answers about coordinate frames. The narrow case where the layer underneath becomes the right thing to examine is a single onboard computer running mixed-language code where the fault is when data arrives rather than what it contains.

Can a visualiser find a timing bug?

No, and here is why. A viewer draws the messages that arrived, in the order it received them, which means the picture of a robot that hesitated looks identical to the picture of a robot that did not. The information you need was destroyed before the drawing started. Timing faults show up as a robot that swerves late, an arm that begins its motion a fraction after the object has moved, or a machine that behaves correctly four times and oddly on the fifth, and in every one of those cases the viewer shows a perfectly reasonable sequence of events. What does find these faults is different in kind: timestamps recorded at the moment each message was created and again when it was used, so the delay between the two is visible; counters on messages so a gap in the sequence is obvious; and comparing two recorded runs of the same behaviour to see where they diverge. Latency, jitter and determinism explained simply is the vocabulary for describing what you find.

Do logs tell you what the robot was thinking?

Partly, but not the way you think. Logs tell you what a programmer decided to write down, which is a record of the thoughts somebody anticipated being interested in later. That is valuable and also biased, because the interesting failure is the one nobody expected, and the line that would have explained it was never written. This is why experienced teams log decisions rather than events: not that the planner ran, but what it chose and what it rejected and on what basis. A line saying an obstacle was ignored because it was judged too small is worth a hundred lines saying the obstacle detector completed. The other half of the answer is that the robot's real thinking often lives in data too large for a log line, such as the map or the image it was working from, and that is exactly what recordings are for. How to review robot code you did not write has more on reading a system through what it chose to record.

How do you decide which tool to reach for first?

Ask what shape the missing information has, and let the shape choose the tool. If the missing information is a place, a map or an orientation, the answer is a spatial viewer, because a shape written as numbers is unreadable to a human. If the missing information is a value that should have been steady and was not, the answer is a plot. If the missing information is whether a program is connected or running at all, the answer is the graph inspector, and it takes a minute. If the missing information is the order in which things happened, the answer is timestamped logs sorted together, and no picture will help. If the fault is rare, record first and choose the tool afterwards, because the recording is the only irreplaceable part. And if the fault survives all of that, appearing only when the machine is busy and vanishing when you watch, the question has moved below your code and into how messages travel, which is a different investigation with a different set of answers. Why your robot slows down as you add features is where that investigation usually starts.

Where that leaves you, in five lines:

• If you are one person with a small robot -> timestamped logs plus recording, because tools installed too early go unused.
• If your robot has cameras, lasers or a map -> RViz 2 or Foxglove, because a shape written as numbers cannot be read.
• If a number drifts, oscillates or sags -> PlotJuggler, because the fault is already in the right shape for a graph.
• If the fault is rare -> record now and analyse later, because a fault on disk is one you can work on.
• If the fault only appears when the machine is busy -> look below your code at the messaging layer, because the viewers cannot show what was late.

The HORUS Fit Framework applies the same reasoning to the layer under the tools, along five axes: ecosystem size, setup effort, team size fit, deployment target and licence. Debugging tooling is mostly an ecosystem size question, which is why teams who look inside their robot weight that axis heavily. For the same choices on a machine with legs, why humanoid demos look better than humanoid products follows the thread into harder hardware.

HORUS is open source under Apache-2.0 at github.com/softmata/horus. Star it so it is in your list when you start building.