openpilot User Guide

openpilot is an open-source advanced driver-assistance system (ADAS) developed by comma.ai. It provides automated lane centering, adaptive cruise control, and driver monitoring for over 300 supported vehicle models across major automotive brands. openpilot runs on dedicated comma hardware devices installed in your vehicle, turning your car into a semi-autonomous driving machine.

Important

openpilot is a Level 2 driver-assistance system. You must keep your hands on the wheel and your eyes on the road at all times. The driver monitoring camera actively enforces attentiveness. openpilot assists with driving; it does not replace the driver.

1. Quick Start

What You Need

5-Minute Setup

1. Mount the device on your windshield behind the rearview mirror using the provided mount
2. Connect the harness to your vehicle's OBD-II port and camera connector
3. Plug the Panda into the device and connect it to the harness
4. Power on the device — it boots AGNOS Linux and launches openpilot automatically
5. Connect to Wi-Fi during initial setup for registration and updates
6. Drive — openpilot engages when you activate your car's cruise control stalk

Supported Brands

Toyota, Honda, Hyundai, Kia, Genesis, GM (Chevrolet/GMC/Cadillac), Volkswagen, Chrysler, Jeep, Ram, Ford, Subaru, Mazda, Nissan, and Infiniti. Each brand has specific models and years supported — check the comma.ai compatibility list for your exact vehicle.

Tip

The best-supported vehicles are Toyota and Honda models with Toyota Safety Sense or Honda Sensing. These provide the smoothest lateral and longitudinal control.

2. Installation

On-Device (Production Use)

The comma 3X and comma four come with AGNOS (version 17.2) pre-installed. openpilot is managed through the device UI:

1. Power on the device
2. Connect to your Wi-Fi network
3. The device downloads and installs the latest openpilot release automatically
4. Registration with comma.ai backend completes over the network

Software updates happen automatically when the device is connected to Wi-Fi and the car is off. The updated process runs offroad to check for and apply updates.

On PC (Development Use)

openpilot can run on a standard PC for development, replay, simulation, and tooling. Ubuntu 24.04 is the primary supported platform.

Linux (Ubuntu 24.04)

git clone https://github.com/commaai/openpilot.git
cd openpilot
tools/op.sh setup
source .venv/bin/activate
scons -u -j$(nproc)

macOS

git clone https://github.com/commaai/openpilot.git
cd openpilot
tools/op.sh setup
source .venv/bin/activate
scons -u -j$(nproc)

Windows (via WSL)

1. Install the Ubuntu-24.04 WSL distribution:

wsl --install -d Ubuntu-24.04

2. Inside the WSL shell, follow the Linux instructions above

3. For GPU acceleration, set the environment variable before running graphical tools:

export GALLIUM_DRIVER=d3d12

Note

The PC installation is for development and simulation only. Running openpilot in a real vehicle requires comma hardware (comma 3X or comma four) with a Panda CAN interface.

Build System

openpilot uses SCons as its build system. After initial setup:

# Full build (all targets)
scons -u -j$(nproc)

# The -j flag sets parallel jobs — $(nproc) uses all CPU cores

The device launch sequence is: launch_openpilot.sh calls launch_chffrplus.sh, which triggers an SCons build and then starts system/manager/manager.py — the process manager that orchestrates all openpilot daemons.

Launch Environment

The launch environment (launch_env.sh) configures performance-critical settings:

These are set automatically on device. For PC development, source the environment manually if needed.

3. Configuration

Environment Variables

openpilot is configured primarily through environment variables. These are especially useful for development and simulation workflows.

Core System Variables

UI Variables

Development Example

To run openpilot on a PC without hardware, using a webcam:

export NOBOARD=1
export USE_WEBCAM=1
export SIMULATION=0
cd openpilot && source .venv/bin/activate
python system/manager/manager.py

Warning

Environment variables like NOBOARD and SIMULATION are for development only. Never use these on a device installed in a real vehicle — they bypass safety-critical hardware checks.

Settings UI

On the device, tap the gear icon to access Settings. The Settings screen has five panels:

Language / Localization

openpilot supports 13 languages:

Language is selectable in the device Settings UI.

4. Core Usage

Engaging openpilot

openpilot activates through your vehicle's existing cruise control interface:

1. Start your car with the comma device powered on
2. Wait for calibration — the device needs a short initial drive to calibrate the camera and IMU
3. Press SET or RES on your steering wheel cruise control stalk
4. openpilot engages — the UI shows the driving visualization with path prediction

What openpilot Controls

Disengaging

• Brake pedal — always disengages immediately
• Cancel button — on the cruise control stalk
• Gas pedal — behavior varies by vehicle; some models allow gas override without full disengage
• Steering override — applying significant steering torque overrides lateral control

The UI While Driving

The onroad UI displays:

• Driving path — the predicted trajectory shown as a colored lane overlay
• Lead vehicle — detected car ahead with distance indicator
• Speed — current speed and set cruise speed
• Driver monitoring icon — shows DM camera status and attention state
• Alerts — system messages, warnings, and errors appear as banners

Process Architecture (What Runs Under the Hood)

The manager process starts approximately 40 daemons. Key processes that run while driving:

Processes that always run (on and offroad): pandad, ui, logmessaged, hardwared, uploader, deleter, statsd, manage_athenad.

The updated process runs only when offroad to handle software updates.

For a deep dive into the process architecture, inter-process communication via cereal messaging, and the full daemon lifecycle, see the Admin Guide.

5. Common Tasks

Simulation

Run in MetaDrive Simulator

# Start the simulation bridge
python tools/sim/run_bridge.py

# With joystick control
python tools/sim/run_bridge.py --joystick

# High-quality rendering
python tools/sim/run_bridge.py --high_quality

# Dual camera mode
python tools/sim/run_bridge.py --dual_camera

Run with Keyboard Control

python tools/joystick/joystick_control.py --keyboard

Drive Replay

Replay a Previous Drive

# Replay a route (use route name from comma connect)
python tools/replay/can_replay.py <route_or_segment_name>

# Replay with UI visualization
python tools/replay/ui.py <ip_address>

# Replay with custom frame address
python tools/replay/ui.py <ip_address> --frame-address <addr>

Data Visualization

Plot Drive Logs with PlotJuggler

# Launch with demo data
python tools/plotjuggler/juggle.py --demo

# Plot a specific route
python tools/plotjuggler/juggle.py <route>

# Stream live data
python tools/plotjuggler/juggle.py --stream

# Load a specific layout
python tools/plotjuggler/juggle.py --layout <layout_file>

# Plot CAN messages with DBC
python tools/plotjuggler/juggle.py --can --dbc <dbc_file> <route>

View CAN Messages with Cabana

Cabana is a CAN message viewer and plotter. Launch it to inspect raw vehicle bus traffic, decode messages with DBC files, and plot signals over time.

Video Clips

Create Clips from Recorded Drives

# Create a clip from a route
python tools/clip/run.py <route> -s <start_seconds> -e <end_seconds>

# Custom output path
python tools/clip/run.py <route> -s 10 -e 30 -o my_clip.mp4

# Use demo route
python tools/clip/run.py --demo

# Big camera clip
python tools/clip/run.py <route> --big -s 0 -e 15

# Quick camera (lower resolution, faster)
python tools/clip/run.py <route> --qcam -s 0 -e 60

CAN Bus Debugging

Print CAN Messages

# Print all CAN messages
python selfdrive/debug/can_printer.py

# Filter by bus
python selfdrive/debug/can_printer.py --bus 0

# Limit number of unique message IDs shown
python selfdrive/debug/can_printer.py --max_msg 20

# ASCII representation
python selfdrive/debug/can_printer.py --ascii

# Filter by address
python selfdrive/debug/can_printer.py --addr 0x180

CAN Table View

python selfdrive/debug/can_table.py

Cereal Message Debugging

Dump Cereal Messages

# Dump a specific socket
python selfdrive/debug/dump.py <socket_name>

# Pipe mode for chaining with other tools
python selfdrive/debug/dump.py --pipe <socket_name>

# Raw output
python selfdrive/debug/dump.py --raw <socket_name>

# JSON format
python selfdrive/debug/dump.py --json <socket_name>

# Dump to JSON file
python selfdrive/debug/dump.py --dump-json <socket_name>

# Connect to specific address
python selfdrive/debug/dump.py --addr <address> <socket_name>

# Show values only
python selfdrive/debug/dump.py --values <socket_name>

Check Message Frequency

python selfdrive/debug/check_freq.py

System Monitoring

CPU Usage

python selfdrive/debug/cpu_usage_stat.py

Live CPU and Temperature

python selfdrive/debug/live_cpu_and_temp.py

Filter Log Messages

python selfdrive/debug/filter_log_message.py

Car Fingerprinting

Get Your Car's Fingerprint

python selfdrive/debug/get_fingerprint.py

Read Firmware Versions

python selfdrive/debug/fw_versions.py

Car Porting

Auto-Fingerprint a New Car

python tools/car_porting/auto_fingerprint.py <route> <platform>

Measure Steering Accuracy

python tools/car_porting/measure_steering_accuracy.py --route <route>

# Group measurements
python tools/car_porting/measure_steering_accuracy.py --route <route> --group

Model Testing

Run the Driving Model

# Run modeld with demo data
python selfdrive/modeld/modeld.py --demo

Camera Streaming

Stream Cameras Over Network

Use tools/camerastream to stream the device cameras to a remote viewer for debugging or demonstration.

eSIM Management

Manage the Device eSIM

# Switch eSIM profile
python system/hardware/esim.py --switch

# Delete an eSIM profile
python system/hardware/esim.py --delete

# Download a new eSIM profile
python system/hardware/esim.py --download

# Set eSIM nickname
python system/hardware/esim.py --nickname <name>

Body Teleoperation

Use tools/bodyteleop to remotely control a comma body robot from a web interface.

Blocking Specific Processes

To prevent specific processes from starting, use the BLOCK environment variable:

# Block uploader and loggerd
export BLOCK="uploader,loggerd"

Tip

Blocking uploader is useful during development to prevent drive logs from being uploaded to comma servers. Blocking loggerd saves disk space during extended testing sessions.

SSH Access

Enable SSH in Settings > Developer on the device. Once enabled, connect over your local network:

ssh comma@<device-ip>

The default user is comma. SSH is also accessible over Tailscale or comma's Athena remote access service.

Updating openpilot

Updates are handled automatically by the updated process when the device is offroad and connected to Wi-Fi. To check update status:

• Go to Settings > Software on the device
• Current version, target branch, and download progress are displayed

Caution

Do not interrupt a software update in progress. If the device loses power during an update, it may require a factory reset via USB flash.

6. Troubleshooting

Offroad Alerts

These alerts appear on the device screen when the car is off or openpilot cannot engage.

Device Temperature Too High

Internet Connection Required

Update Download Required

Unable to Download Updates

Registration Failed

Car Not Recognized

Mounting Position Changed

Driver Monitoring Visibility

Excessive Actuation

Engagement Issues

openpilot Will Not Engage

Calibration Not Complete

comma four Specific Issues

Splash Screen Hang and Audio Delay

No Engage/Disengage Sound

Low FPS While Engaged

Camera View UI Glitch

Green Screen Effect

Stale Frame on Start

paramsd Active in Reverse

PC Development Issues

Build Fails with SCons

WSL Graphics Not Working

Virtual Environment Not Found

Webcam Not Detected

Network / Remote Access

Athena Connection Failed

SSH Connection Refused

7. FAQ

Q: Which cars does openpilot support? A: openpilot supports vehicles from Toyota, Honda, Hyundai, Kia, Genesis, GM, Volkswagen, Chrysler, Jeep, Ram, Ford, Subaru, Mazda, Nissan, and Infiniti. The specific models and years vary — check comma.ai/vehicles for the definitive compatibility list. Car-specific logic is maintained per brand within the openpilot codebase.

Q: What is the difference between comma 3X and comma four? A: Both are Qualcomm Snapdragon-based compute devices running AGNOS Linux. The comma four is the newer generation with hardware improvements. Both run the same openpilot software. Some known issues (audio delay, FPS drops, green screen) have been specific to the comma four's early firmware.

Q: Can I run openpilot on my own hardware instead of buying a comma device? A: openpilot is designed for comma hardware. You can run it on a PC for development, simulation, and tool usage, but driving a real vehicle requires the comma 3X or comma four with a Panda CAN interface. The device provides the cameras, driver monitoring, and real-time compute that cannot be replicated with consumer hardware.

Q: What is AGNOS? A: AGNOS is comma.ai's custom Linux distribution (currently version 17.2) that runs on comma devices. It provides the operating system layer, hardware drivers, and system services that openpilot depends on. Updates to AGNOS are delivered alongside openpilot updates.

Q: Can I use openpilot without an internet connection? A: openpilot can drive without an active internet connection. However, the device needs periodic internet access to check for mandatory updates. If it goes too long without connecting, it will display an alert and may refuse to engage until updates are verified.

Q: How do I know if openpilot is engaged? A: The onroad UI clearly shows the engagement state. When engaged, you see the driving path visualization (colored lane overlay) and the set speed. When disengaged, the path disappears and the UI shows a different state indicator. Audible chimes sound on engage and disengage.

Q: What happens if I need to take over immediately? A: Press the brake pedal — this immediately disengages openpilot. You can also apply firm steering input to override lateral control, or press the cancel button on your cruise control stalk. openpilot is designed for instant human override.

Q: How does driver monitoring work? A: An infrared camera pointed at the driver tracks eye gaze and head position. If you look away from the road for too long or close your eyes, openpilot issues escalating warnings. Persistent inattention will disengage the system. This is a critical safety feature that cannot be disabled.

Q: Can I contribute a new car port? A: Yes. Car model ports are explicitly listed as welcome contributions. Use tools/car_porting/auto_fingerprint.py to capture your vehicle's CAN fingerprint and selfdrive/debug/get_fingerprint.py for initial identification. Submit a pull request against the master branch. See CONTRIBUTING.md for guidelines.

Q: What types of pull requests does comma.ai accept? A: In priority order, comma.ai values: safety, stability, quality, then features. Good PRs include typo fixes, removing unused code, and car model ports. PRs that are unlikely to be merged: style-only changes, PRs over 500 lines, unclear goal PRs, UI design changes, and most new feature proposals. Check the bounty board for specifically requested contributions.

Q: Where can I get community help? A: Join the comma.ai Discord for community support. Official documentation is at docs.comma.ai. For bugs, file issues on the GitHub repository.

Q: How do I view my drive logs? A: Drives are automatically uploaded to comma connect when the device has internet access. For local analysis, use tools/plotjuggler/juggle.py to plot logged data, tools/replay/can_replay.py to replay drives, or tools/clip/run.py to create video clips from recorded routes.

Q: Can I run openpilot in a simulator? A: Yes. Use tools/sim/run_bridge.py to connect openpilot to the MetaDrive simulator. Add --joystick for manual control input or --high_quality for better rendering. This is useful for testing without a vehicle.

Q: How do I debug CAN bus communication? A: Use the debug tools: selfdrive/debug/can_printer.py shows raw CAN messages in real time, selfdrive/debug/can_table.py displays a structured table view, and selfdrive/debug/dump.py can dump any cereal message socket in various formats (raw, JSON, piped).

Q: What is the Panda? A: The Panda is comma.ai's CAN-bus interface device. It connects between the comma device and your vehicle's OBD-II port, translating CAN messages between the car's internal network and openpilot. It handles safety-critical message filtering in firmware.

Q: How do I check message frequencies? A: Run selfdrive/debug/check_freq.py to verify that cereal messages are being published at their expected rates. Frequency drops can indicate process crashes, CPU throttling, or communication issues.

Q: Can I block specific processes from running? A: Yes. Set the BLOCK environment variable to a comma-separated list of process names. For example, BLOCK="uploader,loggerd" prevents those two daemons from starting. This is useful for development and debugging.

Q: What does "calibration" mean in openpilot? A: Calibration is the process of determining the exact position and orientation of the device's cameras relative to the road surface. The calibrationd process runs during driving to compute and refine these parameters. A well-calibrated device produces more accurate lane detection and path prediction.

Q: How do I factory reset my comma device? A: Factory reset options are available in Settings > Device on the device UI. For a complete reset, you can reflash AGNOS via USB. After a reset, you will need to reconnect to Wi-Fi, re-register with comma.ai, and recalibrate the device.

Q: What data does openpilot upload? A: Drive logs (camera footage, CAN data, sensor data, model outputs) are uploaded to comma.ai servers by the uploader process. This data is used for model training and improvement. You can manage data sharing preferences in Settings > Firehose. The deleter process manages local storage by removing old logs after upload.

Q: How do I read my car's firmware versions? A: Run selfdrive/debug/fw_versions.py with the device connected to your car. This queries the vehicle's ECUs for firmware version strings, which are used in car identification and compatibility checking.

Q: What is cereal? A: cereal is openpilot's inter-process communication framework. It uses a publish/subscribe model over shared memory for high-performance, low-latency messaging between the ~40 daemons that make up openpilot. Tools like dump.py and check_freq.py let you inspect cereal messages for debugging.

Q: How do I monitor system performance on the device? A: Use selfdrive/debug/cpu_usage_stat.py for per-process CPU usage and selfdrive/debug/live_cpu_and_temp.py for real-time CPU utilization and thermal monitoring. These help diagnose performance issues like frame drops or thermal throttling.

Q: Can I use openpilot on a right-hand drive vehicle? A: Support depends on the specific vehicle model. Some right-hand drive variants of supported vehicles work with openpilot, but not all. Check the compatibility list for your specific market variant.

Note

For architecture details, deployment configuration, security analysis, and system internals, see the openpilot Admin Guide.