# 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

| Component | Description |
|---|---|
| **comma 3X** or **comma four** | The compute device that runs openpilot (Qualcomm Snapdragon SoC, AGNOS Linux) |
| **Panda** | CAN-bus interface that connects the device to your vehicle's OBD-II port |
| **Harness** | Vehicle-specific wiring harness for your car model |
| **Supported vehicle** | See the full list at [comma.ai/vehicles](https://comma.ai/vehicles) |

### 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)

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

#### macOS

```bash
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:

```powershell
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:

```bash
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:

```bash
# 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:

| Variable | Value | Purpose |
|---|---|---|
| `OMP_NUM_THREADS` | `1` | Prevent OpenMP thread oversubscription |
| `MKL_NUM_THREADS` | `1` | Prevent MKL thread oversubscription |

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

| Variable | Default | Description |
|---|---|---|
| `NOBOARD` | *(unset)* | Run without Panda hardware — useful for PC development |
| `USE_WEBCAM` | *(unset)* | Use a PC webcam instead of comma device cameras |
| `SIMULATION` | `0` | Enable simulation mode |
| `API_HOST` | `https://api.commadotai.com` | comma.ai API endpoint |
| `ATHENA_HOST` | `wss://athena.comma.ai` | Athena websocket connection for remote access |
| `BLOCK` | *(unset)* | Comma-separated list of process names to prevent from starting |

#### UI Variables

| Variable | Default | Description |
|---|---|---|
| `FPS` | *(system default)* | Override UI frame rate |
| `BIG` | `0` | Large UI mode |
| `SCALE` | `1.0` | UI scaling factor |
| `SHOW_FPS` | *(unset)* | Display FPS counter overlay |
| `SHOW_TOUCHES` | *(unset)* | Display touch point indicators |
| `RECORD` | *(unset)* | Record UI screen |

#### Development Example

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

```bash
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:

| Panel | What It Controls |
|---|---|
| **Device** | Device name, Wi-Fi, serial number, reset options |
| **Toggles** | Driver monitoring sensitivity, lane change behavior, metric/imperial units |
| **Developer** | SSH access, upload toggles, debug information |
| **Software** | Current version, update channel, update status |
| **Firehose** | Data sharing preferences for comma.ai's training pipeline |

### Language / Localization

openpilot supports 13 languages:

| Language | Code |
|---|---|
| German | `de` |
| English | `en` |
| Spanish | `es` |
| French | `fr` |
| Japanese | `ja` |
| Korean | `ko` |
| Portuguese (Brazil) | `pt-BR` |
| Thai | `th` |
| Turkish | `tr` |
| Ukrainian | `uk` |
| Chinese (Simplified) | `zh-CHS` |
| Chinese (Traditional) | `zh-CHT` |

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

| Feature | Description |
|---|---|
| **Adaptive Cruise Control (ACC)** | Maintains set speed and follows the car ahead at a safe distance |
| **Lane Centering** | Keeps the vehicle centered in the lane using camera-based lane detection |
| **Driver Monitoring** | Infrared camera tracks driver attention — alerts if eyes leave the road |
| **Automatic Lane Changes** | Signal and openpilot assists with the lane change (on supported vehicles) |

### 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:

| Process | Function |
|---|---|
| `modeld` | Neural network for path prediction and lane detection |
| `controlsd` | Sends steering and acceleration commands to the vehicle |
| `selfdrived` | High-level driving state machine |
| `card` | Vehicle CAN communication interface |
| `radard` | Radar processing for lead vehicle detection |
| `plannerd` | Path planning and longitudinal planning |
| `locationd` | GPS + IMU sensor fusion for positioning |
| `calibrationd` | Camera and device calibration |
| `torqued` | Steering torque controller tuning |
| `dmonitoringd` | Driver attention monitoring |
| `camerad` | Camera capture |
| `loggerd` | Drive logging and recording |

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

```bash
# 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

```bash
python tools/joystick/joystick_control.py --keyboard
```

### Drive Replay

#### Replay a Previous Drive

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
python selfdrive/debug/can_table.py
```

### Cereal Message Debugging

#### Dump Cereal Messages

```bash
# 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

```bash
python selfdrive/debug/check_freq.py
```

### System Monitoring

#### CPU Usage

```bash
python selfdrive/debug/cpu_usage_stat.py
```

#### Live CPU and Temperature

```bash
python selfdrive/debug/live_cpu_and_temp.py
```

#### Filter Log Messages

```bash
python selfdrive/debug/filter_log_message.py
```

### Car Fingerprinting

#### Get Your Car's Fingerprint

```bash
python selfdrive/debug/get_fingerprint.py
```

#### Read Firmware Versions

```bash
python selfdrive/debug/fw_versions.py
```

### Car Porting

#### Auto-Fingerprint a New Car

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

#### Measure Steering Accuracy

```bash
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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
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

| | |
|---|---|
| **Error** | "Device temperature too high. System cooling down before starting." |
| **Cause** | The comma device has exceeded its thermal limits, typically from direct sunlight on the windshield or high ambient temperature |
| **Solution** | Park in shade, use a windshield sunshade, or run the car's AC with the device powered on. Wait for the temperature to drop below the threshold |
| **Prevention** | Use a sunshade when parked. Consider window tinting. The comma device has thermal throttling built in, but sustained heat will trigger this alert |
| **Related** | GitHub issue #37707 (comma four high temperature warning) |

#### Internet Connection Required

| | |
|---|---|
| **Error** | "Immediately connect to the internet to check for updates." |
| **Cause** | The device has been offline too long and needs to verify it is running a current software version |
| **Solution** | Connect to Wi-Fi. The device will check for updates and clear the alert |
| **Prevention** | Ensure the device connects to Wi-Fi regularly (e.g., home garage Wi-Fi) |

#### Update Download Required

| | |
|---|---|
| **Error** | "Connect to internet to check for updates. openpilot won't automatically start..." |
| **Cause** | A mandatory update is pending and openpilot will not engage until it is installed |
| **Solution** | Connect to Wi-Fi, wait for the update to download and install, then restart |
| **Prevention** | Keep the device connected to Wi-Fi overnight for automatic updates |

#### Unable to Download Updates

| | |
|---|---|
| **Error** | "Unable to download updates" |
| **Cause** | Network connectivity issue, DNS resolution failure, or comma update servers temporarily unavailable |
| **Solution** | Verify Wi-Fi connection, try a different network, or wait and retry. Check that your network does not block the comma.ai domain |
| **Prevention** | Use a reliable Wi-Fi network with consistent internet access |

#### Registration Failed

| | |
|---|---|
| **Error** | "Failed to register with comma.ai backend." |
| **Cause** | The device could not complete registration with comma.ai servers during initial setup or after a reset |
| **Solution** | Verify internet connectivity. Restart the device. If persistent, factory reset and re-register |
| **Prevention** | Ensure stable internet during initial device setup |

#### Car Not Recognized

| | |
|---|---|
| **Error** | "openpilot was unable to identify your car." |
| **Cause** | The vehicle's CAN fingerprint does not match any known supported car. This can happen with new model years, regional variants, or aftermarket ECU modifications |
| **Solution** | Verify your vehicle is in the supported cars list. Check harness connections. If your car should be supported, use `selfdrive/debug/get_fingerprint.py` to capture and report the fingerprint |
| **Prevention** | Confirm vehicle compatibility before purchasing comma hardware |

#### Mounting Position Changed

| | |
|---|---|
| **Error** | "openpilot detected a change in the device's mounting position." |
| **Cause** | The device has moved relative to its calibrated position — the mount shifted, device was removed and reattached, or windshield was replaced |
| **Solution** | Ensure the mount is secure. openpilot will recalibrate automatically during the next drive. If the alert persists, reset calibration in Settings |
| **Prevention** | Use a firm mount. Avoid removing the device frequently |

#### Driver Monitoring Visibility

| | |
|---|---|
| **Error** | "Poor visibility detected for driver monitoring." |
| **Cause** | The infrared driver monitoring camera cannot see the driver's face clearly — sunglasses, face coverings, extreme head angles, or a dirty camera lens |
| **Solution** | Clean the DM camera lens. Remove reflective sunglasses. Adjust seating position so your face is visible to the camera |
| **Prevention** | Keep the DM camera lens clean. Use non-reflective sunglasses compatible with IR cameras |
| **Related** | GitHub issue #37135 (DM icon calibration) |

#### Excessive Actuation

| | |
|---|---|
| **Error** | "Excessive actuation detected on your last drive." |
| **Cause** | openpilot applied unusually high steering torque or acceleration commands during the previous drive, indicating potential tuning issues or unusual driving conditions |
| **Solution** | This is informational. If it occurs repeatedly, check for mounting issues, calibration problems, or report the behavior with your route log |
| **Prevention** | Ensure proper device mounting and calibration |

### Engagement Issues

#### openpilot Will Not Engage

| | |
|---|---|
| **Error** | Pressing cruise control stalk does nothing or shows a red alert |
| **Cause** | Multiple possible causes: car not in drive, seatbelt unbuckled, door open, device not calibrated, offroad alert blocking engagement |
| **Solution** | Clear all offroad alerts first. Ensure the car is in drive with seatbelt on and doors closed. Check the device screen for specific blocking alerts |
| **Prevention** | Address offroad alerts before driving |

#### Calibration Not Complete

| | |
|---|---|
| **Error** | "Calibration in progress" or openpilot refuses to engage |
| **Cause** | The device has not completed its initial calibration drive |
| **Solution** | Drive in a straight line at moderate speed for several minutes. The calibration percentage shows in the UI |
| **Prevention** | Complete calibration on a straight highway or well-marked road |

### comma four Specific Issues

#### Splash Screen Hang and Audio Delay

| | |
|---|---|
| **Error** | Device stuck on splash screen after boot; audio delayed after restart |
| **Cause** | Known issue on comma four hardware |
| **Solution** | Wait for the splash screen to clear (may take longer than expected). If stuck beyond 5 minutes, hold the power button for a hard reboot |
| **Related** | GitHub issue #37845 |

#### No Engage/Disengage Sound

| | |
|---|---|
| **Error** | No audible chime when openpilot engages or disengages |
| **Cause** | Audio subsystem issue on comma four |
| **Solution** | Restart the device. If persistent, check Settings > Device for audio settings |
| **Related** | GitHub issue #37384 |

#### Low FPS While Engaged

| | |
|---|---|
| **Error** | UI frame rate drops below 60 FPS while actively driving with openpilot engaged |
| **Cause** | GPU/CPU thermal throttling or resource contention on comma four |
| **Solution** | Ensure adequate device cooling. Reduce UI complexity if possible |
| **Related** | GitHub issue #37610 |

#### Camera View UI Glitch

| | |
|---|---|
| **Error** | Visual artifacts or glitches in the camera view |
| **Cause** | GPU rendering issue on comma four |
| **Solution** | Restart the device to clear the graphics state |
| **Related** | GitHub issue #36887 |

#### Green Screen Effect

| | |
|---|---|
| **Error** | Camera view shows a green tint or fully green screen |
| **Cause** | Camera pipeline initialization issue (resolved in recent updates) |
| **Solution** | Update to the latest openpilot version. Restart the device |
| **Related** | GitHub issue #37774 (closed/fixed) |

#### Stale Frame on Start

| | |
|---|---|
| **Error** | "Start car to use openpilot" text not centered; old camera frame displayed |
| **Cause** | UI caching a previous camera frame |
| **Solution** | The display corrects once the car is started and cameras activate |
| **Related** | GitHub issue #37440 |

### paramsd Active in Reverse

| | |
|---|---|
| **Error** | paramsd (parameter estimation daemon) continues updating while driving in reverse |
| **Cause** | Known behavior — paramsd does not gate on forward gear |
| **Solution** | No action needed; this does not affect driving safety. The issue is tracked |
| **Related** | GitHub issue #37458 |

### PC Development Issues

#### Build Fails with SCons

| | |
|---|---|
| **Error** | `scons -u -j$(nproc)` fails with compilation errors |
| **Cause** | Missing system dependencies or incompatible toolchain |
| **Solution** | Re-run `tools/op.sh setup` to install all dependencies. Ensure you are on Ubuntu 24.04 |
| **Prevention** | Always run setup before building |

#### WSL Graphics Not Working

| | |
|---|---|
| **Error** | UI or simulation tools fail to render on Windows WSL |
| **Cause** | Missing GPU driver passthrough configuration |
| **Solution** | Set `GALLIUM_DRIVER=d3d12` before launching graphical tools |
| **Prevention** | Add `export GALLIUM_DRIVER=d3d12` to your WSL `.bashrc` |

#### Virtual Environment Not Found

| | |
|---|---|
| **Error** | Python packages missing or `ModuleNotFoundError` |
| **Cause** | Virtual environment not activated |
| **Solution** | Run `source .venv/bin/activate` from the openpilot root directory |
| **Prevention** | Always activate the venv before running any openpilot Python tool |

#### Webcam Not Detected

| | |
|---|---|
| **Error** | `USE_WEBCAM=1` set but camera feed is black or missing |
| **Cause** | Webcam not accessible, wrong device index, or permissions issue |
| **Solution** | Verify the webcam works with other applications. On Linux, check `/dev/video*` permissions |

### Network / Remote Access

#### Athena Connection Failed

| | |
|---|---|
| **Error** | Device not reachable via comma connect / Athena |
| **Cause** | WebSocket connection to `wss://athena.comma.ai` blocked or device offline |
| **Solution** | Verify internet connectivity. Check that your network does not block WebSocket connections. Restart `manage_athenad` |

#### SSH Connection Refused

| | |
|---|---|
| **Error** | Cannot SSH into the device |
| **Cause** | SSH not enabled in Settings > Developer, or wrong IP address |
| **Solution** | Enable SSH in Settings > Developer. Find the device IP in Settings > Device or via your router's DHCP table |

---

## 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](https://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](https://github.com/commaai/openpilot/blob/master/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](https://github.com/orgs/commaai/projects/26/views/1) for specifically requested contributions.

**Q: Where can I get community help?**
A: Join the [comma.ai Discord](https://discord.comma.ai) for community support. Official documentation is at [docs.comma.ai](https://docs.comma.ai). For bugs, file issues on the [GitHub repository](https://github.com/commaai/openpilot).

**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](/commaai/openpilot/admin-guide/).

---

_Generated May 2026 from commaai/openpilot at 695a2d7. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._