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.

The tools/ directory in the openpilot repository contains the full set of developer utilities for working with CAN data, replaying drives, visualizing logs, running the simulator, and debugging car controls. These tools are designed to run on your development machine rather than on the comma device itself, and they give you a local environment that closely mirrors what openpilot sees while driving.

​
System requirements

openpilot is developed and tested on Ubuntu 24.04, which is the primary supported platform for the developer tools. Most tools also work on macOS. Windows users can use WSL 2 with the Ubuntu-24.04 distribution for a near-native experience.
If you are running WSL 2 and see performance issues with UI or simulator graphics, set GALLIUM_DRIVER=d3d12 before running GUI commands, or add export GALLIUM_DRIVER=d3d12 to your ~/.bashrc.

​
Setting up your development environment

1

Clone the repository

git clone https://github.com/commaai/openpilot.git
2

Run the setup script

cd openpilot
tools/op.sh setup
3

Activate the Python virtual environment

source .venv/bin/activate
4

Build openpilot

scons -u

​
Directory structure

tools/
├── cabana/             # View and plot CAN messages from drives or in realtime
├── camerastream/       # Stream cameras over the network
├── joystick/           # Control your car with a joystick or keyboard
├── lib/                # Libraries for reading openpilot logs
├── plotjuggler/        # Plot openpilot logs with PlotJuggler
├── replay/             # Replay drives and mock openpilot services
├── scripts/            # Miscellaneous utility scripts
├── serial/             # Tools for using the comma serial
├── sim/                # Run openpilot in the MetaDrive simulator
└── webcam/             # Run openpilot on a PC with webcams

​
Major tools

Cabana

View, decode, and plot raw CAN bus messages from recorded drives or live from a connected comma device or panda. Integrates with the opendbc DBC library for signal decoding.

PlotJuggler

Visualize openpilot log time series data. Includes custom plugins for parsing openpilot log formats and pre-built layouts for common tuning workflows.

Replay

Replay any recorded drive and mock all openpilot services, letting you run and test openpilot code against real data without hardware.

Simulator

Run openpilot in the MetaDrive simulator via the bridge in tools/sim/. Supports joystick input and dual camera mode.

​
All tools at a glance

ToolLocationPurpose
Cabanatools/cabana/CAN message viewer and DBC editor
PlotJugglertools/plotjuggler/Time series log visualization
Replaytools/replay/Drive replay and service mocking
Simulatortools/sim/Run openpilot in MetaDrive
Joysticktools/joystick/Debug controls with a joystick or keyboard
Camerastreamtools/camerastream/Stream cameras over the network
Webcamtools/webcam/Run openpilot on a PC with standard webcams
Scriptstools/scripts/Miscellaneous developer utility scripts

​
Learning the tools with the CTF

The openpilot CTF is the fastest way to get hands-on with the developer tools. All flags are hidden in the route 0c7f0c7f0c7f0c7f|2021-10-13--13-00-00. Start with replay and the UI, then work through the tools in tools/ and selfdrive/debug/. See tools/CTF.md for the full instructions.
# Start the CTF route replay
cd tools/replay
./replay '0c7f0c7f0c7f0c7f|2021-10-13--13-00-00' --dcam --ecam

# Start the UI in another terminal
selfdrive/ui/ui

Build docs developers (and LLMs) love

Get started for freeTalk to us