RobotGuide

Tools & simulation · topic G8 · 25 hours

Visualization & debugging toolchains

Most robot problems you cannot debug are, at heart, «invisible». Someone who can read the data localizes the fault in an hour; someone who cannot guesses for a week. This toolkit is an amplifier of judgment.

Engineering stage · Intermediate
Algorithm · Aware System software · Proficient Embedded & controls · Proficient Mechanical · Aware

Tools
Tools

What to learn

  • RViz2: the TF tree, Markers, PointCloud2, Image, the plugin mechanism (add your own display type without recompiling)
  • Foxglove Studio: offline bag viewing, multiple panels on one screen, shareable layouts, a web client; comparison views RViz cannot do
  • PlotJuggler: plot 20 topics from a bag in one figure and find the real «command-to-feedback» latency and jitter
  • rosbag2 / MCAP: what to record (recording every high-rate control topic will blow the disk), compression, chunking, `--use-sim-time` replay
  • The CLI trio: `ros2 topic hz` / `delay` / `echo --once`; `ros2 param dump`; `tf2_tools view_frames`
  • System level: cyclictest to measure jitter, perf to find hotspots, ftrace / LTTng / ros2_tracing to trace the full timeline of one callback
  • Logging: rclcpp log levels, /rosout aggregation, structured fields instead of concatenated strings

The lesson · plain words

The visualization and debugging toolchain (rviz2/PlotJuggler/rosbag/rqt) is the robot's «instrument panel»: where the problem happened, when it happened, and what every module was doing at that moment — this toolkit reconstructs the scene.

Replay: the robot's black-box reconstruction

Watch the animation: several topics, each with its own timestamp scale; as the playhead sweeps, every one of them aligns to the same instant. rosbag records every topic and the rviz playhead performs «time travel» — every millisecond of the incident scene can be replayed.

Replaying properly: record everything at capture time (while bandwidth allows), filter by topic during analysis. /tf is a must-record — a replay without tf leaves nothing in rviz lining up spatially.

Interactive figure · drag it and see

What this figure shows: three recorded topic timelines (/tf at 100 Hz, /camera at 30 Hz, /scan at 40 Hz) with a playback head sweeping across them; each stream snaps to the same query instant, and tf frames on both sides of the query time are interpolated. Takeaway: rosbag playback plus rviz is the black-box reconstruction of a robot incident — always record /tf, and align timestamps before comparing any streams.

rviz2: an amplifier of spatial intuition

rviz's value is turning abstract coordinate transforms into visible frames and lines. The standard trio for tf trouble: the TF display (see the tree structure), RViz's «Frame» selector (which reference frame), and the Axes display (each frame's orientation).

Advanced moves: use Time Travel mode to align timestamps during replay; use the Measure tool for point-to-point distance; screenshot anything that «looks wrong» and file it — rviz screenshots are the common language of robot incident reports.

PlotJuggler and rqt

PlotJuggler: a drag-and-drop curve viewer that reads rosbag/data streams directly — frequency jitter, latency spikes, and value jumps leap out at a glance. Over rqt_plot it wins on «multi-stream alignment» and «offline analysis».

The rqt family is ROS's Swiss army knife: rqt_graph for node connections (D5's animation is drawn with it), rqt_console for logs, rqt_publisher for hand-issued commands. The trio to open in the first minute of debugging.

How deep to go

Design a recording plan (what to record, at what rate, with what disk budget); localize a tf misalignment in rviz; pull «the moment of the latency spike» out of a rosbag with PlotJuggler. These three are the daily bread of robot debugging jobs.

Three questions — do you really get it?

1. On rosbag replay nothing in rviz lines up spatially — what did you most likely forget to record?

  • A/camera
  • B/diagnostics
  • C/tf
Show answer

C. tf is the skeleton of spatial relations. Without it, no data can be restored to its spatial position.

2. Which tool is the smoothest for multi-topic aligned analysis?

  • Arqt_graph
  • Becho
  • CPlotJuggler (multi-stream alignment + offline)
Show answer

C. It aligns multiple streams by timestamp and lets you zoom interactively offline — the main weapon against timing problems.

3. The correct move when rviz «looks wrong»?

  • ARecompile
  • BSwitch the Frame to check the reference frame + screenshot for the record
  • CReboot
Show answer

B. A wrong reference frame is the number-one cause of rviz «looking wrong». The screenshot is raw material for incident analysis.

Keep going deeper

Links without a marker stay on this site; the rest point to the Chinese edition until its translation batch lands.

How it fails in the field

  • Debugging a robot with printf: the logging drags down the real-time thread, and your own debugging method amplifies the problem
  • The point cloud is uniformly misaligned; you go fix the camera calibration when the real cause is a missing static_transform in the tf tree
  • Recorded the bag without `--use-sim-time`; on replay the timestamps jump and the whole system's behavior no longer matches

You have learned enough when

From a bag, use PlotJuggler to measure the median and P99 of the real «control command → joint feedback» latency and name the source of the jitter; use perf or cyclictest to prove whether a 1 kHz thread's jitter is caused by the kernel or by your code.

The Chinese edition carries the full topic page for Visualization & debugging toolchains, including the complete outline, depth requirements per career track, and further derivations: robotguide.dev/k/G8/.