Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/commaai/openpilot/llms.txt

Use this file to discover all available pages before exploring further.

PlotJuggler is the primary log visualization tool for openpilot development. It is a fast, interactive time series plotter, and the openpilot repository ships custom plugins that parse openpilot’s log formats so you can load any route or segment and immediately start plotting signals like lateral error, steering torque, speed, and hundreds of other fields. The helper script tools/plotjuggler/juggle.py handles installation, plugin setup, and launching PlotJuggler with the right arguments.

​
Installation

Once you have set up the openpilot environment, run the install command to download PlotJuggler and the openpilot plugins: 
cd tools/plotjuggler
./juggle.py --install
Run this command again whenever you want to update PlotJuggler or the plugins.

​
Launching with a route

Pass a route name, a segment, or a segment range directly to juggle.py. Cabana share URLs are also accepted. 
# Full route
./juggle.py "5beb9b58bd12b691/0000010a--a51155e496"

# A single segment
./juggle.py "5beb9b58bd12b691/0000010a--a51155e496/1"

# A segment using qlogs
./juggle.py "5beb9b58bd12b691/0000010a--a51155e496/1/q"

# A range of segments
./juggle.py "5beb9b58bd12b691/0000010a--a51155e496/0:1"

# Demo route (no account needed)
./juggle.py --demo

​
Full options reference

$ ./juggle.py -h
usage: juggle.py [-h] [--demo] [--can] [--stream] [--layout [LAYOUT]]
                 [--install] [--dbc DBC]
                 [route_or_segment_name]

A helper to run PlotJuggler on openpilot routes

positional arguments:
  route_or_segment_name
                        The route or segment name to plot (cabana share URL accepted)

optional arguments:
  -h, --help            show this help message and exit
  --demo                Use the demo route instead of providing one
  --can                 Parse CAN data
  --stream              Start PlotJuggler in streaming mode
  --layout [LAYOUT]     Run PlotJuggler with a pre-defined layout
  --install             Install or update PlotJuggler + plugins
  --dbc DBC             Set the DBC name to load for parsing CAN data

​
Layouts

PlotJuggler layouts save a pre-configured arrangement of plots so you can jump straight into a specific analysis view. Pass a layout file with --layout.

​
Tuning layout

The tuning layout provides a pre-built view for evaluating lateral and longitudinal controller performance. Use it when working on PID tuning or generating plots for a tuning pull request. 
./juggle.py --demo --layout=layouts/tuning.xml
See the openpilot tuning wiki for guidance on interpreting the tuning plots.
If you create a layout that is useful for other developers, consider submitting it upstream to tools/plotjuggler/layouts/.

​
Streaming live data

You can stream live openpilot log data from a comma device or from a local replay session into PlotJuggler.

​
Streaming from a comma device

1

Enable wifi tethering

Turn on the wifi hotspot on your comma device.
2

Start the bridge on the device

SSH into your device and start the cereal bridge:
cd /data/openpilot && ./cereal/messaging/bridge
3

Connect your laptop to the device's hotspot

Join the comma device’s wifi network on your laptop.
4

Launch PlotJuggler in streaming mode

ZMQ=1 ./juggle.py --stream
In the PlotJuggler UI, select the Cereal Subscriber plugin from the streaming dropdown and click Start.

​
Streaming from a local replay

If you have a replay running on your PC, stream directly from it without ZMQ: 
# Terminal 1: start a replay
tools/replay/replay <route-name>

# Terminal 2: start PlotJuggler in stream mode
tools/plotjuggler/juggle.py --stream
Then start the Cereal Subscriber plugin inside PlotJuggler.

​
Parsing CAN data

To plot decoded CAN signals alongside the standard openpilot log data, add the --can flag. You can optionally specify a DBC file by name; if you omit --dbc, the DBC is inferred automatically from the route. 
./juggle.py "5beb9b58bd12b691/0000010a--a51155e496" --can
./juggle.py "5beb9b58bd12b691/0000010a--a51155e496" --can --dbc toyota_nodsu_pt_generated
PlotJuggler loads openpilot’s standard rlog and qlog formats via the commaai PlotJuggler plugins. Raw video is not plotted — use Cabana if you need to view CAN data alongside the drive video.

Build docs developers (and LLMs) love

Get started for freeTalk to us