This site’s top bar has promoted a small USB logic analyzer alongside PlotJuggler for a while, without ever explaining why the two belong in the same sentence. This post is that explanation. The short version: robot logs tell you what the software believed happened, and a logic analyzer tells you what the hardware actually did — and the interesting bugs live in the gap between those two stories. Correlating a captured digital signal with plotted telemetry from the same moment is how you find out which story is wrong.

Two views of the same event

Consider a familiar failure: a motor, actuator or peripheral intermittently does nothing, and the logs look clean. The software issued the command — that is in the log, timestamped, plotted, undeniable. What the log cannot show is whether the signal ever left the board: whether the line toggled, whether a chip-select asserted, whether the bus carried the frame or sat idle while the driver reported success. A logic analyzer answers exactly those questions by recording the digital signals themselves. Neither view is “the truth” alone. The log is the intended behaviour; the capture is the physical behaviour; debugging is comparing them at the same moment in time.

The correlation workflow

1. Capture both sides of the event. Run the system with the logic analyzer attached to the signals under suspicion, and record the robot’s normal logs or stream for the same run. Note one unmistakable shared event — a button press, a mode change, a distinctive command — that appears in both records.
2. Review the telemetry in PlotJuggler first. Load the recording, find the failure window, and establish exactly what the software did and when, relative to that shared event. If the data is live rather than recorded, the same session can take a stream — see streaming data into PlotJuggler over WebSocket and MQTT.
3. Read the capture against the same reference point. In the analyzer’s software, locate the shared event and measure from it to the signals in question: did the line change, when, and in what order relative to the logged command?
4. Align the two timelines mentally with time offset discipline. The habit from time-offset alignment in PlotJuggler applies here in spirit: until the shared event lines up in both views, apparent delays may be clock differences rather than behaviour.
5. Draw the conclusion the evidence supports. Signal present and correct, but the log shows no response: the problem is upstream of the pin — sensing, wiring back, or software interpretation. Signal absent while the log claims action: the problem is between the software and the pin. Either way, a vague intermittent fault just became a located one.

Where derived signals help on the software side

Correlation is easier when the telemetry side shows intent crisply. If the log records a state or a flag rather than the command itself, build the comparison view in PlotJuggler: plot the command path, the reported state, and any feedback signal together, and use a Lua custom function where the quantity that matters is a combination — for example a derived “commanded but not acknowledged” condition over time. On PlotJuggler 4, Python transforms serve the same purpose. The sharper the software-side picture, the smaller the window you need to search in the hardware capture, and logic captures reward small windows.

When this workflow is worth the extra instrument

• Intermittent faults that logs alone have repeatedly failed to explain.
• Suspected wiring, level or timing problems between boards, where software evidence has already been exhausted.
• Bring-up of a new peripheral or bus, when “the driver sent it” and “the device received it” both need proving independently.
• Disagreements between teams — firmware pointing at hardware, hardware pointing at firmware — where a capture both sides can read settles the question.

And when it is not: purely algorithmic problems, planning and logic bugs, and anything fully reproducible in the recorded data alone. A logic analyzer earns its bench space on the boundary between software and hardware, which is a specific — and for robot builders, frequently visited — place.

Logs describe intentions, captures describe physics, and most hard robotics bugs are disagreements between the two. Put the records side by side, align them on an event both witnessed, and the disagreement will usually point at its own cause.

You are a test engineer. A subsystem test finished an hour ago, the results sit in files — a CSV export here, a ULog there, an MCAP recording from the rig — and someone needs a verdict before the next test slot. The usual detour is Python: load each file, remember each format’s quirks, write plotting code, and only then start thinking. PlotJuggler exists to remove that detour for the review step. It is a free desktop application (MPL-2.0, no account) that loads the file formats test rigs actually produce, plots them by dragging signals onto charts, and lets you derive and compare values in the window — so the first plot is minutes away, and the thinking starts sooner.

What PlotJuggler loads directly

The same application also handles rosbag recordings and, on the PlotJuggler 4 line, Parquet files, plus live streams (MQTT, WebSocket, ZeroMQ, UDP and others) when the rig can send data while a test runs. For a review workflow, though, the file loaders above are the working set.

The review workflow, under time pressure

1. Load everything for this test into one session. PlotJuggler 4 can hold several recordings at once, so the CSV from the bench instrument and the MCAP from the rig can be reviewed together rather than in separate tools.
2. Align before you judge. If two files describe the same test, their clocks may differ. Use time offsets to line up a shared event first — our time offset guide shows the per-curve version — otherwise you will chase timing differences that are really recording differences.
3. Plot the acceptance signals first. Whatever the test was supposed to prove, plot those series before exploring. Limits, setpoints and measured values on one chart answer the pass/fail question fastest.
4. Derive, don’t export. Need a difference, a rate, or a scaled value? Built-in transforms (derivative, integral, moving average, scale) and Lua custom functions — Python as well on PlotJuggler 4 — produce it in place, without round-tripping the data through a script.
5. Save the layout. The same subsystem will be tested again. A saved layout turns the next review into: load file, open layout, read verdict.

“But I already have Python scripts”

Keep them — for automation, batch processing and reports, scripting is the right tool, and nothing here replaces it. The claim is narrower: for the interactive review in the middle of a test day, opening a file and dragging signals is faster than editing and rerunning a script each time a new question occurs to you, and each follow-up question (“what was the other channel doing at that moment?”) costs seconds instead of another code cycle. Many engineers end up using both: PlotJuggler to find the moment and the cause, a script afterwards to check every historical file for the same pattern.

Setup burden, honestly

The scepticism is reasonable, so the facts: PlotJuggler is a single desktop application for Windows and Linux, distributed from its project releases, free and open source under MPL-2.0, with no account, no licence server and no cloud upload — your test data stays on your machine, which for many test organisations is not a preference but a requirement. There is no official macOS binary in the current line, which is a real limitation if your bench machine is a Mac. Very large recordings can also need the practical handling in our large-file guide. Within those limits, the setup burden is: install one application, open your file.

The detour through a general-purpose script is sometimes necessary. For the everyday review of CSV, ULog and MCAP results, it usually is not — and the hour between a test finishing and its verdict is exactly where that difference is worth most.

“Did the firmware change make the robot better or worse?” is one of the most common questions in robotics — and one of the worst answered, because the before and after runs usually live in different files, recorded at different times, and get eyeballed in different tools. PlotJuggler 4 was built with this comparison in mind: it can load several recordings at once, align their timelines, and overlay their signals, with a per-dataset time offset for each recording. That mechanism — not a new chart type, not an export to a spreadsheet — is what turns run-to-run comparison from an impression into evidence. This guide sets out the workflow.

Why before/after comparisons go wrong

• The runs start at different moments. One log begins at power-on, the other at motion start, so the same event sits at different timestamps and the overlay looks “shifted” even when behaviour is identical.
• The views differ. Different signals, different zoom, different scaling — the comparison quietly becomes a comparison of screenshots.
• Only the interesting run gets examined. The after run is scrutinised; the before run is remembered. Memory is not a baseline.

Each of these is a workflow problem, and each has a direct fix in the loading and alignment steps below. If you have not yet worked with several recordings in one view, start with the basics in comparing multiple bag files in PlotJuggler, then apply the stricter discipline here.

Step 1: Load both recordings into one session

Load the before and after recordings into the same PlotJuggler session — PlotJuggler 4’s multi-recording support is the core mechanism of this whole method. Use recordings of the same task, driven the same way, wherever you can: a comparison is only as fair as the runs themselves. If the two runs were recorded by different versions of your logging setup, expect topic names or content to differ slightly, and verify that the signals you plan to compare exist, under the same names, in both datasets before drawing any conclusion.

Step 2: Align the timelines with per-dataset offsets

This is the step that decides whether the comparison means anything. PlotJuggler 4 lets you set a time offset per dataset, so you can shift one entire recording until a shared, unmistakable event — motion start, a mode change, a distinctive manoeuvre — lines up in both. Align on an event that the change under test could not itself have moved; aligning on the very behaviour you are testing would erase the difference you are looking for. Once aligned, events that genuinely moved stand out immediately, because everything that should coincide, does. The per-curve version of the same idea is covered in our time offset guide.

Step 3: Compare the same signals, in the same layout

Build one view and use it for both datasets: the same signals, the same arrangements, the same derived series. Where a judgement depends on a quantity neither log records directly — an error, a rate, a settling behaviour — build it once as a Lua or Python custom transform and apply it to both datasets identically. Then read the overlay question by question:

Step 4: Save the comparison so it can be repeated

Save the finished view as a layout. PlotJuggler 4’s layout format (schema v4) saves the viewport and the per-dataset offsets alongside the plot arrangement, which means next week’s run can be dropped into exactly the comparison you built today — the foundation of a genuine regression habit rather than a one-off investigation. For what changed in the new line overall, see What’s New in PlotJuggler 4; if your team is still on the previous line, the PlotJuggler 3 to 4 migration guide covers moving over, and it is worth doing for this workflow alone: several recordings with per-dataset alignment is a PlotJuggler 4 capability.

The honest limits

Two cautions. First, an overlay shows difference, not cause: a changed run proves the change coincided with different behaviour, and narrowing which input or subsystem explains it is the debugging workflow, not the comparison. Second, two runs are a sample of two. For a change you intend to ship, run the comparison across several before and after recordings of the same task; the per-dataset-offset workflow makes that practical, because each new recording is minutes of alignment rather than a new analysis. Teams that adopt that habit catch regressions while they are still a diff under review — which is the cheapest moment to catch them.

Most robot bugs are not found by staring at code. They are found by watching what the robot actually did — which means a recording, a timeline, and a disciplined way of moving from “it behaved strangely” to the minute, then the second, then the signal where behaviour diverged. This workflow uses PlotJuggler as the investigation desk: record the run, load the recording, align the signals in time, derive the quantities that are not logged directly, and save the whole view as a layout you can reuse on the next run and hand to a colleague.

Step 1: Record with debugging in mind

A debugging session starts before PlotJuggler opens. Record the run in the format your stack already produces — a ROS bag or an MCAP recording are the common cases — and record the topics you would want if something went wrong, not only the topics for the feature you are testing. Note the wall-clock time of anything you observe in the room: a bump, a pause, a missed grasp. That single note is often the difference between a ten-minute investigation and an afternoon of scrubbing. Our guide to reading rosbag and MCAP files in PlotJuggler covers loading both formats, including what to check when a recording does not open as expected.

Step 2: Load, orient, and narrow the window

Load the recording and first read it at the widest level: when did the robot start moving, when did the task end, and where does the observed problem sit? Plot a small set of high-level signals — commanded versus actual motion is the classic pair — and zoom into the window around your noted timestamp. Resist adding more series until the window is right. Debugging fails by drowning: fifty plotted topics will always contain something that looks odd, somewhere.

Step 3: Align signals with time offset

Signals recorded by different parts of a system rarely share a perfect clock, and a cause can appear to follow its effect if two series are offset. PlotJuggler’s per-curve time offset exists for exactly this: shift one series until events that happened together line up together, then judge the relationship. The dedicated walkthrough is PlotJuggler time offset: aligning signals that do not line up. Alignment is also the step that makes sensor-versus-command comparisons honest — a “lag” that disappears after a small offset was never a control problem; it was a timestamp problem, which is a different bug and a different fix.

Step 4: Derive what was not logged

The signal that proves a root cause is often not in the recording at all — it is a combination of signals that are. PlotJuggler’s transform tools cover the common cases two ways. Built-in transforms give you derivatives, integrals, moving averages and scaling without code. For anything bespoke, custom functions do the job: Lua has been the scripting route on the established line, and PlotJuggler 4 adds Python alongside it, as our PlotJuggler 4 Python scripting guide explains. Typical derived series in a debugging session include an error signal (command minus actual), a rate (the derivative of a position), and a combined condition that only matters when two states coincide. Build the derived series, plot it in the narrowed window, and the question usually answers itself.

Step 5: Save the investigation as a layout

When the view finally shows the problem clearly, save it as a layout before you touch anything else. A saved layout preserves which series are plotted, where, and — on PlotJuggler 4’s layout format — the viewport and offsets as well, so the same investigation can be reopened on tomorrow’s recording in one step. The how-to is saving and sharing PlotJuggler layouts. Treat good layouts like good tests: one per recurring question (“why did navigation pause?”, “why did the arm overshoot?”), named for the question, and shared with the team so root-cause analysis stops depending on who holds the mouse.

The workflow in one pass

1. Record generously, and note the wall-clock time of anything you see go wrong.
2. Load the bag or MCAP file and narrow to the window around that note.
3. Align series with time offset before judging cause and effect.
4. Derive the missing quantity with a built-in transform or a Lua/Python custom function.
5. Confirm the pattern in the window, then check whether it appears elsewhere in the run.
6. Save the layout, named for the question it answers, and reuse it on the next recording.

Followed in order, that sequence turns debugging from folklore into a repeatable method — and each step leaves an artefact (the recording, the offsets, the derived series, the layout) that someone else can check.

After a PX4 flight, the fastest honest route from “something felt wrong” to a cause is a repeatable post-flight workflow in PlotJuggler: load the ULog file, plot the signals that describe that kind of problem, derive the quantities the raw log does not show directly, and save the view so the next flight is reviewed the same way. This is not a workflow we invented for this page. The official PX4 documentation itself carries a full “Log Analysis using PlotJuggler” guide — covering installation, the ULog workflow, and a Lua custom series that converts quaternions into roll, pitch and yaw — and this guide follows that same structure, adding the review discipline around it.

Step 1: Load the ULog and orient yourself

Open the flight’s ULog file in PlotJuggler using its ULog loader. Before judging anything, establish the basic shape of the flight: when it armed, when it took off, which flight phases are present, and where the moment you care about sits on the timeline. Zoom to that window first. Most post-flight mistakes come from reading a signal across the whole log when the question is really about ten seconds of it. If the file is very large or the machine struggles while scrubbing, work through the fixes in PlotJuggler Is Slow with Large Files before you start interpreting plots — a lagging view makes normal behaviour look like spikes.

Step 2: Plot by question, not by topic list

A ULog contains far more series than any one review needs. Work question by question, adding only the signals that answer it:

Step 3: Derive attitude with the Lua quaternion series

Quaternions are compact for machines and unreadable for people. The PX4 guide’s answer — and the pattern worth copying — is a Lua custom function that takes the quaternion components as inputs and outputs roll, pitch and yaw as separate, plottable series. Once built, those derived series behave like any other signal: you can overlay them with commands, events and vibration views, and save the function with your layout so you never rebuild it. If custom functions are new to you, our Lua custom functions tutorial explains the editor, multi-input functions and the built-in transforms (derivative, integral, moving average, scale) that pair with them. PlotJuggler 4 also adds Python as an alternative scripting language for derived series, but the PX4-documented workflow is Lua, and it works on the established line as well.

Step 4: Check the event window, then the whole flight

1. Return to the moment that prompted the review and read it with the derived series in place.
2. Widen the view: does the same pattern appear earlier in the flight, or on previous flights? A pattern that repeats is a configuration or tuning question; a pattern that appears once is an event question.
3. Note the exact timestamps of anything abnormal. Precise timestamps are what make a forum post, an issue report or a question to a colleague answerable.
4. Save the layout once the review view is useful. The next flight then opens into the same charts, in the same order, which is what turns log review from archaeology into routine.

Where this workflow fits among the other ULog tools

PX4 Flight Review, the project’s online analyser, is the quick first look: upload a log and receive plots, including PID and vibration analysis, by link. PlotJuggler is the in-depth step the PX4 documentation points to when the quick look is not enough — local and private, with every logged topic available and your own transforms on top. Our roundup of the best drone flight log analysis tools sets out where each option fits, and the CSV import guide covers the companion case where supporting data arrives as a spreadsheet-style export rather than a ULog. Whichever tool you start with, keep the discipline the same: question first, signals second, conclusions last.

This is an independent, unofficial resource site, not affiliated with the PlotJuggler or PX4 projects. PlotJuggler is free and open source under the MPL-2.0 licence.