openpilot Documentation

Technical Documentation: commaai/openpilot

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Using openpilot in a car Copy Chapter

To use openpilot in a car, you need four things:

1. Supported Device: a comma four, available at comma.ai/shop/comma-four.
2. Software: The setup procedure for the comma four allows users to enter a URL for custom software. Use the URL openpilot.comma.ai to install the release version.
3. Supported Car: Ensure that you have one of the 300+ supported cars.
4. Car Harness: You will also need a car harness to connect your comma four to your car.

We have detailed instructions for how to install the harness and device in a car. Note that it's possible to run openpilot on other hardware, although it's not plug-and-play.

Branches Copy Section

Running master and other branches directly is supported, but it's recommended to run one of the following prebuilt branches:

For chestnut, use the following installer URLs:

To start developing openpilot Copy Chapter

openpilot is developed by comma and by users like you. We welcome both pull requests and issues on GitHub.

• Join the community Discord
• Check out the contributing docs
• Check out the openpilot tools
• Code documentation lives at https://docs.comma.ai
• Information about running openpilot lives on the community wiki

Want to get paid to work on openpilot? comma is hiring and offers lots of bounties for external contributors.

Safety and Testing Copy Chapter

• openpilot observes ISO26262 guidelines, see SAFETY.md for more details.
• openpilot has software-in-the-loop tests that run on every commit.
• The code enforcing the safety model lives in panda and is written in C, see code rigor for more details.
• panda has software-in-the-loop safety tests.
• Internally, we have a hardware-in-the-loop Jenkins test suite that builds and unit tests the various processes.
• panda has additional hardware-in-the-loop tests.
• We run the latest openpilot in a testing closet containing 10 comma devices continuously replaying routes.

MIT Licensed

openpilot is released under the MIT license. Some parts of the software are released under other licenses as specified.

Any user of this software shall indemnify and hold harmless Comma.ai, Inc. and its directors, officers, employees, agents, stockholders, affiliates, subcontractors and customers from and against all allegations, claims, actions, suits, demands, damages, liabilities, obligations, losses, settlements, judgments, costs and expenses (including without limitation attorneys’ fees and costs) which arise out of, relate to or result from any use of this software by user.

THIS IS ALPHA QUALITY SOFTWARE FOR RESEARCH PURPOSES ONLY. THIS IS NOT A PRODUCT.
YOU ARE RESPONSIBLE FOR COMPLYING WITH LOCAL LAWS AND REGULATIONS.
NO WARRANTY EXPRESSED OR IMPLIED.

User Data and comma Account

By default, openpilot uploads driving data to our servers. You can also access your data through comma connect. We use your data to train better models and improve openpilot for everyone.

openpilot is open source software, and users can disable data collection if they wish.

openpilot logs the road-facing cameras, CAN, GPS, IMU, magnetometer, thermal sensors, crashes, and operating system logs.
The driver-facing camera and microphone are only logged if you explicitly opt-in in settings.

By using openpilot, you agree to our Privacy Policy. You understand that use of this software or its related services will generate certain types of user data, which may be logged and stored at the sole discretion of comma. By accepting this agreement, you grant an irrevocable, perpetual, worldwide right to comma for the use of this data.

Overview (`docs/README.md`) Copy Section

Docs development

The docs/ tree is the source for docs.comma.ai.
The site is updated on pushes to master by this workflow.

1. Build the site

op docs --build

2. Run the site locally (rebuilds on change)

op docs

Overview (`tools/README.md`) Copy Section

openpilot tools

System Requirements Copy Chapter

openpilot is developed and tested on Ubuntu 24.04, which is the primary development target aside from the supported embedded hardware.

Most of openpilot should work natively on macOS. On Windows you can use WSL for a nearly native Ubuntu experience. Running natively on any other system is not currently recommended and will likely require modifications.

Native setup on Ubuntu 24.04 and macOS Copy Chapter

Follow these instructions for a fully managed setup experience. If you'd like to manage the dependencies yourself, just read the setup scripts in this directory.

1. Clone openpilot

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

2. Run the setup script

cd openpilot
tools/op.sh setup

3. Activate a Python shell
Activate a shell with the Python dependencies installed:

source .venv/bin/activate

4. Build openpilot

scons -u

WSL on Windows Copy Chapter

Windows Subsystem for Linux (WSL) should provide a similar experience to native Ubuntu. WSL 2 specifically has been reported by several users to be a seamless experience.

Follow these instructions to setup the WSL and install the Ubuntu-24.04 distribution. Once your Ubuntu WSL environment is setup, follow the Linux setup instructions to finish setting up your environment. See these instructions for running GUI apps.

NOTE: If you are running WSL 2 and experiencing performance issues with the UI or simulator, you may need to explicitly enable hardware acceleration by setting GALLIUM_DRIVER=d3d12 before commands. Add export GALLIUM_DRIVER=d3d12 to your ~/.bashrc file to make it automatic for future sessions.

CTF Copy Chapter

Learn about the openpilot ecosystem and tools by playing our CTF.

Directory Structure Copy Chapter

├── car_porting/        # Tools for porting new cars
├── release/            # Scripts for building openpilot releases
└── scripts/            # Miscellaneous scripts

Development tools such as cabana, plotjuggler, and replay live in openpilot/tools/:

├── cabana/             # View and plot CAN messages from drives or in realtime
├── camerastream/       # Cameras stream over the network
├── joystick/           # Control your car with a joystick
├── lib/                # Libraries to support the tools and reading openpilot logs
├── plotjuggler/        # A tool to plot openpilot logs
├── replay/             # Replay drives and mock openpilot services
└── sim/                # Run openpilot in a simulator

Overview (`openpilot/cereal/README.md`) Copy Section

What is cereal?

cereal is the messaging system for openpilot. It uses msgq as a pub/sub backend, and Cap'n proto for serialization of the structs.

Messaging Spec Copy Chapter

You'll find the message types in log.capnp. It uses Cap'n proto and defines one struct called Event.

All Events have a logMonoTime and a valid. Then a big union defines the packet type.

Best Practices Copy Section

• All fields must describe quantities in SI units, unless otherwise specified in the field name.
• In the context of the message they are in, field names should be completely unambiguous.
• All values should be easy to plot and be human-readable with minimal parsing.

Maintaining backwards-compatibility Copy Section

When making changes to the messaging spec you want to maintain backwards-compatibility, such that old logs can
be parsed with a new version of cereal. Adding structs and adding members to structs is generally safe, most other
things are not. Read more details here.

Custom forks Copy Section

Forks of openpilot might want to add things to the messaging
spec, however this could conflict with future changes made in mainline openpilot's cereal spec. Rebasing against mainline openpilot
then means breaking backwards-compatibility with all old logs of your fork. So we added reserved events in
custom.capnp that we will leave empty in mainline openpilot's cereal spec. If you only modify those, you can ensure your
fork will remain backwards-compatible with all versions of mainline openpilot and your fork.

An example of compatible changes:

diff --git a/openpilot/cereal/custom.capnp b/openpilot/cereal/custom.capnp
index 3348e859e..3365c7b98 100644
--- a/openpilot/cereal/custom.capnp
+++ b/openpilot/cereal/custom.capnp
@@ -10,7 +10,11 @@ $Cxx.namespace("cereal");
 # DO rename the structs
 # DON'T change the identifier (e.g. @0x81c2f05a394cf4af)

-struct CustomReserved0 @0x81c2f05a394cf4af {
+struct SteeringInfo @0x81c2f05a394cf4af {
+  active @0 :Bool;
+  steeringAngleDeg @1 :Float32;
+  steeringRateDeg @2 :Float32;
+  steeringAccelDeg @3 :Float32;
 }

 struct CustomReserved1 @0xaedffd8f31e7b55d {
diff --git a/openpilot/cereal/log.capnp b/openpilot/cereal/log.capnp
index 1209f3fd9..b189f58b6 100644
--- a/openpilot/cereal/log.capnp
+++ b/openpilot/cereal/log.capnp
@@ -2558,14 +2558,14 @@ struct Event {

     # DO change the name of the field
     # DON'T change anything after the "@"
-    customReservedRawData0 @124 :Data;
+    rawCanData @124 :Data;
     customReservedRawData1 @125 :Data;
     customReservedRawData2 @126 :Data;

     # DO change the name of the field and struct
     # DON'T change the ID (e.g. @107)
     # DON'T change which struct it points to
-    customReserved0 @107 :Custom.CustomReserved0;
+    steeringInfo @107 :Custom.SteeringInfo;
     customReserved1 @108 :Custom.CustomReserved1;
     customReserved2 @109 :Custom.CustomReserved2;
     customReserved3 @110 :Custom.CustomReserved3;

Example Copy Chapter

import openpilot.cereal.messaging as messaging

# in subscriber
sm = messaging.SubMaster(['sensorEvents'])
while 1:
  sm.update()
  print(sm['sensorEvents'])

# in publisher
pm = messaging.PubMaster(['sensorEvents'])
dat = messaging.new_message('sensorEvents', size=1)
dat.sensorEvents[0] = {"gyro": {"v": [0.1, -0.1, 0.1]}}
pm.send('sensorEvents', dat)

Overview (`tools/car_porting/README.md`) Copy Section

tools/car_porting

Check out this blog post for a high-level overview of porting a car.

Useful car porting utilities Copy Chapter

Testing car ports in your car is very time-consuming. Check out these utilities to do basic checks on your work before running it in your car.

[Cabana](/openpilot/tools/cabana/README.md) Copy Section

View your car's CAN signals through DBC files, which openpilot uses to parse and create messages that talk to the car.

Example:

> openpilot/tools/cabana/cabana '1bbe6bf2d62f58a8|2022-07-14--17-11-43'

[tools/car_porting/auto_fingerprint.py](/tools/car_porting/auto_fingerprint.py) Copy Section

Given a route and platform, automatically inserts FW fingerprints from the platform into the correct place in fingerprints.py

Example:

> python3 tools/car_porting/auto_fingerprint.py '1bbe6bf2d62f58a8|2022-07-14--17-11-43' 'OUTBACK'
Attempting to add fw version for:  OUTBACK

[openpilot/selfdrive/car/tests/test_car_interfaces.py](/openpilot/selfdrive/car/tests/test_car_interfaces.py) Copy Section

Finds common bugs for car interfaces, without even requiring a route.

Example: Typo in signal name

> tools/test_runner.py openpilot/selfdrive/car/tests/test_car_interfaces.py -k subaru  # replace with the brand you are working on

=====================================================================
FAILED openpilot/selfdrive/car/tests/test_car_interfaces.py::TestCarInterfaces::test_car_interfaces_165_SUBARU_LEGACY_7TH_GEN - KeyError: 'CruiseControlOOPS'

[tools/car_porting/test_car_model.py](/tools/car_porting/test_car_model.py) Copy Section

Given a route, runs most of the car interface to check for common errors like missing signals, blocked panda messages, and safety mismatches.

Example: panda safety mismatch for gasPressed

> python3 tools/car_porting/test_car_model.py '4822a427b188122a|2023-08-14--16-22-21'

=====================================================================
FAIL: test_panda_safety_carstate (__main__.CarModelTestCase.test_panda_safety_carstate)
Assert that panda safety matches openpilot's carState
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/batman/openpilot/opendbc_repo/opendbc/car/tests/test_models.py", line 440, in test_panda_safety_carstate
    self.assertFalse(failed_checks, f"panda safety doesn't agree with CarState: {failed_checks}")
AssertionError: {'gasPressed': 116} is not false : panda safety doesn't agree with CarState: {'gasPressed': 116}

Jupyter notebooks Copy Chapter

To use these notebooks, install Jupyter within your openpilot virtual environment.

uv pip install jupyter ipykernel

Launching:

jupyter notebook

[examples/subaru_steer_temp_fault.ipynb](/tools/car_porting/examples/subaru_steer_temp_fault.ipynb) Copy Section

An example of searching through a database of segments for a specific condition, and plotting the results.

a plot of the steer_warning vs steering angle, where we can see it is clearly caused by a large steering angle change

[examples/subaru_long_accel.ipynb](/tools/car_porting/examples/subaru_long_accel.ipynb) Copy Section

An example of plotting the response of an actuator when it is active.

a plot of the brake_pressure vs acceleration, where we can see it is a fairly linear response.

[examples/ford_vin_fingerprint.ipynb](/tools/car_porting/examples/ford_vin_fingerprint.ipynb) Copy Section

In this example, we use the public comma car segments database to check if vin fingerprinting is feasible for ford.

/* Detailed source-code truncated for AI context efficiency. */

[examples/find_segments_with_message.ipynb](/tools/car_porting/examples/find_segments_with_message.ipynb) Copy Section

Searches for segments where a set of given CAN message IDs are present. In the example, we search for all messages
used for CAN-based ignition detection.

Match found: 46b21f1c5f7aa885/2024-01-23--15-19-34/20/s    JEEP GRAND CHEROKEE V6 2018            ['VW CAN Ign']
Match found: a63a23c3e628f288/2023-11-05--18-36-20/8/s     JEEP GRAND CHEROKEE V6 2018            ['VW CAN Ign']
Match found: ce31b7a998781ba8/2024-01-19--07-05-29/23/s    JEEP GRAND CHEROKEE 2019               ['VW CAN Ign']
Match found: e1dfba62a4e33f7b/2023-12-25--19-31-00/4/s     JEEP GRAND CHEROKEE 2019               ['VW CAN Ign']
Match found: e1dfba62a4e33f7b/2024-01-10--14-33-57/2/s     JEEP GRAND CHEROKEE 2019               ['VW CAN Ign']
Match found: ae679616266f4096/2023-12-05--15-43-46/4/s     RAM HD 5TH GEN                         ['Tesla 3/Y CAN Ign']
Match found: ae679616266f4096/2023-11-18--17-49-42/3/s     RAM HD 5TH GEN                         ['Tesla 3/Y CAN Ign']
Match found: ae679616266f4096/2024-01-03--21-57-09/25/s    RAM HD 5TH GEN                         ['Tesla 3/Y CAN Ign']
Match found: 6dae2984cc53cd7f/2023-12-10--11-53-15/17/s    FORD BRONCO SPORT 1ST GEN              ['Rivian CAN Ign']
Match found: 6dae2984cc53cd7f/2023-12-03--17-31-17/29/s    FORD BRONCO SPORT 1ST GEN              ['Rivian CAN Ign']
Match found: 6dae2984cc53cd7f/2023-11-27--23-29-07/1/s     FORD BRONCO SPORT 1ST GEN              ['Rivian CAN Ign']

Overview (`tools/release/README.md`) Copy Section

openpilot releases

## release checklist

### Go to staging
- [ ] make a GitHub issue to track release with this checklist
- [ ] create release master branch
  - [ ] create a branch from upstream master named `zerotentwo` for release `v0.10.2`
  - [ ] revert risky commits (double check with autonomy team)
  - [ ] push the new branch
- [ ] push to staging:
  - [ ] make sure you are on the newly created release master branch (`zerotentwo`)
  - [ ] run `BRANCH=devel-staging tools/release/build_stripped.sh`. Jenkins will then automatically build staging on device, run `test_onroad` and update the staging branch
- [ ] bump version on master: `openpilot/common/version.h` and `RELEASES.md`
- [ ] post on Discord, tag `@release crew`

### Go to release
- [ ] before going to release, test the following:
  - [ ] update from previous release -> new release
  - [ ] update from new release -> previous release
  - [ ] fresh install with `openpilot-test.comma.ai`
  - [ ] drive on fresh install
  - [ ] no submodules; only the Chestnut big driving model uses LFS
  - [ ] check MTBF, etc.
  - [ ] stress test passes in production
- [ ] publish the blog post
- [ ] `git reset --hard origin/release-mici-staging`
- [ ] tag the release: `git tag v0.X.X <commit-hash> && git push origin v0.X.X`
- [ ] create GitHub release
- [ ] final test install on `openpilot.comma.ai`
- [ ] update factory provisioning
- [ ] close out milestone and issue
- [ ] post on Discord, X, etc.

Overview (`openpilot/common/transformations/README.md`) Copy Section

Reference Frames Copy Chapter

Many reference frames are used throughout. This
folder contains all helper functions needed to
transform between them. Generally this is done
by generating a rotation matrix and multiplying.

Orientation Conventions Copy Chapter

Quaternions, rotation matrices and euler angles are three
equivalent representations of orientation and all three are
used throughout the code base.

For euler angles the preferred convention is [roll, pitch, yaw]
which corresponds to rotations around the [x, y, z] axes. All
euler angles should always be in radians or radians/s unless
for plotting or display purposes. For quaternions the hamilton
notations is preferred which is [q_w, q_x, q_y, q_z]. All quaternions
should always be normalized with a strictly positive q_w. These
quaternions are a unique representation of orientation whereas euler angles
or rotation matrices are not.

To rotate from one frame into another with euler angles the
convention is to rotate around roll, then pitch and then yaw,
while rotating around the rotated axes, not the original axes.

Car frame Copy Chapter

Device frame is aligned with the road-facing camera used by openpilot. However, when controlling the vehicle it is helpful to think in a reference frame aligned with the vehicle. These two reference frames can be different.

The orientation of car frame is defined to be aligned with the car's direction of travel and the road plane when the vehicle is driving on a flat road and not turning. The origin of car frame is defined to be directly below device frame (in car frame), such that it is on the road plane. The position and orientation of this frame is not necessarily always aligned with the direction of travel or the road plane due to suspension movements and other effects.

Calibrated frame Copy Chapter

It is helpful for openpilot's driving model to take in images that look similar when mounted differently in different cars. To achieve this we "calibrate" the images by transforming it into calibrated frame. Calibrated frame is defined to be aligned with car frame in pitch and yaw, and aligned with device frame in roll. It also has the same origin as device frame.

Example Copy Chapter

To transform global Mesh3D positions and orientations (positions_ecef, quats_ecef) into the local frame described by the
first position and orientation from Mesh3D one would do:

ecef_from_local = rot_from_quat(quats_ecef[0])
local_from_ecef = ecef_from_local.T
positions_local = np.einsum('ij,kj->ki', local_from_ecef, postions_ecef - positions_ecef[0])
rotations_global = rot_from_quat(quats_ecef)
rotations_local = np.einsum('ij,kjl->kil', local_from_ecef, rotations_global)
eulers_local = euler_from_rot(rotations_local)

Overview (`openpilot/system/ui/README.md`) Copy Section

ui

The user interfaces here are built with raylib.

Quick start:

• set BIG=1 to run the comma 3X UI (comma four UI runs by default)
• set SHOW_FPS=1 to show the FPS
• set STRICT_MODE=1 to kill the app if it drops too much below 60fps
• set SCALE=1.5 to scale the entire UI by 1.5x
• set BURN_IN=1 to get a burn-in heatmap version of the UI
• set GRID=50 to show a 50-pixel alignment grid overlay
• set MAGIC_DEBUG=1 to show every dropped frames (only on device)
• set RECORD=1 to record the screen, output defaults to output.mp4 but can be set with RECORD_OUTPUT
• set PRIME_TYPE to preview pairing/Prime status: -1 unpaired, 0 paired without Prime, 2 Prime Lite, 1 Prime Full
• set PAIRING_PROVIDER to preview the different states based on connect auth providers google, github or apple
• https://www.raylib.com/cheatsheet/cheatsheet.html
• https://electronstudio.github.io/raylib-python-cffi/README.html#quickstart

Style guide:

• All graphical elements should subclass Widget.
  • Prefer a stateful widget over a function for easy migration from QT
• All internal class variables and functions should be prefixed with _

Overview (`openpilot/tools/cabana/README.md`) Copy Section

Cabana

Cabana is a tool developed to view raw CAN data. One use for this is creating and editing CAN Dictionaries (DBC files), and the tool provides direct integration with commaai/opendbc (a collection of DBC files), allowing you to load the DBC files direct from source, and save to your fork. In addition, you can load routes from comma connect.

Usage Instructions Copy Chapter

$ ./cabana -h
Usage: ./cabana [options] [route]

  route                     the drive to replay. find your drives at connect.comma.ai

Options:
  --help                    show this help
  --demo                    use a demo route instead of providing your own
  --auto                    Auto load the route from the best available source (no video):
                            internal, openpilotci, comma_api, car_segments, testing_closet
  --qcam                    load qcamera
  --wide-road               load wide road camera (alias: --ecam)
  --cabin                   load cabin camera (alias: --dcam)
  --msgq                    read can messages from the msgq
  --panda                   read can messages from panda
  --panda-serial <serial>   read can messages from panda with given serial
  --socketcan <device>      read can messages from given SocketCAN device
  --zmq <ip-address>        read can messages from zmq at the specified ip-address
  --data_dir <dir>          local directory with routes
  --no-vipc                 do not output video
  --no-cache                turn off the local route file cache
  --dbc <file>              dbc file to open

Examples Copy Chapter

Running Cabana in Demo Mode Copy Section

To run Cabana using a built-in demo route, use the following command:

cabana --demo

Loading a Specific Route Copy Section

To load a specific route for replay, provide the route as an argument:

cabana "5beb9b58bd12b691/0000010a--a51155e496"

Replace "5beb9b58bd12b691/0000010a--a51155e496" with your desired route identifier.

Running Cabana with multiple cameras Copy Section

To run Cabana with multiple cameras, use the following command:

cabana "5beb9b58bd12b691/0000010a--a51155e496" --cabin --wide-road

Streaming CAN Messages from a comma Device Copy Section

SSH into your device and start the bridge with the following command:

cd /data/openpilot
./openpilot/cereal/messaging/bridge &

Then Run Cabana with the device's IP address:

cabana --zmq <ipaddress>

Replace <ipaddress> with your comma device's IP address.

While streaming from the device, Cabana will log the CAN messages to a local directory. By default, this directory is ~/cabana_live_stream/. You can change the log directory in Cabana by navigating to menu -> tools -> settings.

After disconnecting from the device, you can replay the logged CAN messages from the stream selector dialog -> browse local route.

Streaming CAN Messages from Panda Copy Section

To read CAN messages from a connected Panda, use the following command:

cabana --panda

Using the Stream Selector Dialog Copy Section

If you run Cabana without any arguments, a stream selector dialog will pop up, allowing you to choose the stream.

cabana

Additional Information Copy Chapter

For more information, see the openpilot wiki

Overview (`openpilot/tools/camerastream/README.md`) Copy Section

Camera stream

compressed_vipc.py connects to a remote device running openpilot, decodes the video streams, and republishes them over VisionIPC.

Usage Copy Chapter

On the device Copy Section

SSH into the device and run following in separate terminals:

cd /data/openpilot && ./openpilot/cereal/messaging/bridge

cd /data/openpilot/system/loggerd && ./encoderd

cd /data/openpilot/system/camerad && ./camerad

Note that both the device and your PC must be on the same openpilot commit.

Alternatively paste this as a single command:

(
  cd /data/openpilot
  ./openpilot/cereal/messaging/bridge &

  cd /data/openpilot/system/camerad/
  ./camerad &

  cd /data/openpilot/system/loggerd/
  ./encoderd &

  wait
) ; trap 'kill $(jobs -p)' SIGINT

Ctrl+C will stop all three processes.

On the PC Copy Section

Decode the stream with compressed_vipc.py:

cd ~/openpilot/tools/camerastream && ./compressed_vipc.py <ip>

To actually display the stream, run watch3 in separate terminal:

cd ~/openpilot/selfdrive/ui/ && ./watch3.py

compressed_vipc.py usage Copy Chapter

$ python3 compressed_vipc.py -h
usage: compressed_vipc.py [-h] [--cams CAMS] [--server SERVER] [--silent] addr

Decode video streams and broadcast on VisionIPC

positional arguments:
  addr             Address of comma three

options:
  -h, --help       show this help message and exit
  --cams CAMS      Cameras to decode
  --server SERVER  choose vipc server name
  --silent         Suppress debug output

Example: Copy Chapter

cd ~/openpilot/tools/camerastream && ./compressed_vipc.py comma-ffffffff --cams 0
cd ~/openpilot/selfdrive/ui/ && ./watch3.py

Overview (`openpilot/tools/joystick/README.md`) Copy Section

Joystick

Hardware needed: device running openpilot, laptop, joystick (optional)

With joystick_control, you can connect your laptop to your comma device over the network and debug controls using a joystick or keyboard.
joystick_control uses inputs which supports many common gamepads and joysticks.

Usage Copy Chapter

The car must be off, and openpilot must be offroad before starting joystick_control.

Using a keyboard Copy Section

SSH into your comma device and start joystick_control with the following command:

openpilot/tools/joystick/joystick_control.py --keyboard

The available buttons and axes will print showing their key mappings. In general, the WASD keys control gas and brakes and steering torque in 5% increments.

Joystick on your comma three Copy Section

Plug the joystick into your comma three aux USB-C port. Then, SSH into the device and start joystick_control.py.

Joystick on your laptop Copy Section

In order to use a joystick over the network, we need to run joystick_control locally from your laptop and have it send testJoystick packets over the network to the comma device.

1. Connect a joystick to your PC.
2. Connect your laptop to your comma device's hotspot and open a new SSH shell. Since joystick_control is being run on your laptop, we need to write a parameter to let controlsd know to start in joystick debug mode:
   shell Copy

   # on your comma device
   echo -n "1" > /data/params/d/JoystickDebugMode

3. Run bridge with your laptop's IP address. This republishes the testJoystick packets sent from your laptop so that openpilot can receive them:
   shell Copy

   # on your comma device
   openpilot/cereal/messaging/bridge {LAPTOP_IP} testJoystick

4. Start joystick_control on your laptop in ZMQ mode.
   shell Copy

   # on your laptop
   export ZMQ=1
   openpilot/tools/joystick/joystick_control.py

Now start your car and openpilot should go into joystick mode with an alert on startup! The status of the axes will display on the alert, while button statuses print in the shell.

Make sure the conditions are met in the panda to allow controls (e.g. cruise control engaged). You can also make a modification to the panda code to always allow controls.

Overview (`openpilot/tools/lateral_maneuvers/README.md`) Copy Section

Lateral Maneuvers Testing Tool

[!WARNING]
Use caution when using this tool.

Test your vehicle's lateral control tuning with this tool. The tool will test the vehicle's ability to follow a few lateral maneuvers and includes a tool to generate a report from the route.

Instructions Copy Chapter

1. Check out a development branch such as master on your comma device.

2. The full maneuver suite runs at 20 and 30 mph.

3. Enable "Lateral Maneuver Mode" in Settings > Developer on the device while offroad. Alternatively, set the parameter manually:

   sh Copy

   echo -n 1 > /data/params/d/LateralManeuverMode

4. Turn your vehicle back on. You will see "Lateral Maneuver Mode".

5. Ensure the area ahead is clear, as openpilot will command lateral acceleration steps in this mode. Once you are ready, set ACC manually to the target speed shown on screen and let openpilot stabilize lateral. After 1 seconds of steady straight driving, the maneuver will begin automatically. openpilot lateral control stays engaged between maneuvers normally while waiting for the next maneuver's readiness conditions. The maneuver will be aborted and repeated if speed is out of range, steering is touched or openpilot disengages.

6. When the testing is complete, you'll see an alert that says "Maneuvers Finished." Complete the route by pulling over and turning off the vehicle.

7. Visit https://connect.comma.ai and locate the route(s). They will stand out with lots of orange intervals in their timeline. Ensure "All logs" show as "uploaded."

8. Gather the route ID and then run the report generator. The file will be exported to the same directory:

   sh Copy

   $ python openpilot/tools/lateral_maneuvers/generate_report.py 98395b7c5b27882e/000001cc--5a73bde686
   
   processing report for KIA_EV6
   plotting maneuver: step right 20mph, runs: 3
   plotting maneuver: step left 20mph, runs: 3
   plotting maneuver: sine 0.5Hz 20mph, runs: 3
   plotting maneuver: step right 30mph, runs: 3
   
   Opening report: /home/batman/openpilot/tools/lateral_maneuvers/lateral_reports/KIA_EV6_98395b7c5b27882e_000001cc--5a73bde686.html

You can reach out on Discord if you have any questions about these instructions or the tool itself.

Overview (`openpilot/tools/lib/README.md`) Copy Section

LogReader Copy Chapter

Route is a class for conveniently accessing all the logs from your routes. The LogReader class reads the non-video logs, i.e. rlog.bz2 and qlog.bz2. There's also a matching FrameReader class for reading the videos.

from openpilot.tools.lib.route import Route
from openpilot.tools.lib.logreader import LogReader

r = Route("a2a0ccea32023010|2023-07-27--13-01-19")

# get a list of paths for the route's rlog files
print(r.log_paths())

# and road camera (fcamera.hevc) files
print(r.camera_paths())

# setup a LogReader to read the route's first rlog
lr = LogReader(r.log_paths()[0])

# print out all the messages in the log
import codecs
codecs.register_error("strict", codecs.backslashreplace_errors)
for msg in lr:
  print(msg)

# setup a LogReader for the route's second qlog
lr = LogReader(r.log_paths()[1])

# print all the steering angles values from the log
for msg in lr:
  if msg.which() == "carState":
    print(msg.carState.steeringAngleDeg)

Segment Ranges Copy Section

We also support a new format called a "segment range":

344c5c15b34f2d8a   /   2024-01-03--09-37-12   /     2:6    /       q
[   dongle id     ] [       timestamp        ] [ selector ]  [ query type]

you can specify which segments from a route to load

lr = LogReader("a2a0ccea32023010|2023-07-27--13-01-19/4")   # 4th segment
lr = LogReader("a2a0ccea32023010|2023-07-27--13-01-19/4:6") # 4th and 5th segment
lr = LogReader("a2a0ccea32023010|2023-07-27--13-01-19/-1")  # last segment
lr = LogReader("a2a0ccea32023010|2023-07-27--13-01-19/:5")  # first 5 segments
lr = LogReader("a2a0ccea32023010|2023-07-27--13-01-19/1:")  # all except first segment

and can select which type of logs to grab

lr = LogReader("a2a0ccea32023010|2023-07-27--13-01-19/4/q") # get qlogs
lr = LogReader("a2a0ccea32023010|2023-07-27--13-01-19/4/r") # get rlogs (default)

Overview (`openpilot/tools/longitudinal_maneuvers/README.md`) Copy Section

Longitudinal Maneuvers Testing Tool

Test your vehicle's longitudinal control tuning with this tool. The tool will test the vehicle's ability to follow a few longitudinal maneuvers and includes a tool to generate a report from the route.

Sample snapshot of a report.

Instructions Copy Chapter

1. Check out a development branch such as master on your comma device.

2. Locate either a large empty parking lot or road devoid of any car or foot traffic. Flat, straight road is preferred. The full maneuver suite can take 1 mile or more if left running, however it is recommended to disengage openpilot between maneuvers and turn around if there is not enough space.

3. Turn off the vehicle and set this parameter which will signal to openpilot to start the longitudinal maneuver daemon:

   sh Copy

   echo -n 1 > /data/params/d/LongitudinalManeuverMode

4. Turn your vehicle back on. You will see the "Longitudinal Maneuver Mode" alert:

5. Ensure the road ahead is clear, as openpilot will not brake for any obstructions in this mode. Once you are ready, press "Set" on your steering wheel to start the tests. The tests will run for about 4 minutes. If you need to pause the tests, press "Cancel" on your steering wheel. You can resume the tests by pressing "Resume" on your steering wheel.

   Note: For GM cars, it is recommended to hold down the resume button for all low-speed tests (starting, stopping and creep) to avoid the car entering standstill.

6. When the testing is complete, you'll see an alert that says "Maneuvers Finished." Complete the route by pulling over and turning off the vehicle.

7. Visit https://connect.comma.ai and locate the route(s). They will stand out with lots of orange intervals in their timeline. Ensure "All logs" show as "uploaded."

8. Gather the route ID and then run the report generator. The file will be exported to the same directory:

   sh Copy

   $ python openpilot/tools/longitudinal_maneuvers/generate_report.py 57048cfce01d9625/0000010e--5b26bc3be7 'pcm accel compensation'
   
   processing report for LEXUS_ES_TSS2
   plotting maneuver: start from stop, runs: 4
   plotting maneuver: creep: alternate between +1m/s^2 and -1m/s^2, runs: 2
   plotting maneuver: gas step response: +1m/s^2 from 20mph, runs: 2
   
   Report written to /home/batman/openpilot/tools/longitudinal_maneuvers/longitudinal_reports/LEXUS_ES_TSS2_57048cfce01d9625_0000010e--5b26bc3be7.html

You can reach out on Discord if you have any questions about these instructions or the tool itself.

Overview (`openpilot/tools/plotjuggler/README.md`) Copy Section

PlotJuggler

PlotJuggler is a tool to quickly visualize time series data, and we've written plugins to parse openpilot logs. Check out our plugins: https://github.com/commaai/PlotJuggler.

Installation Copy Chapter

Once you've set up the openpilot environment, this command will download PlotJuggler and install our plugins:

cd openpilot/tools/plotjuggler && ./juggle.py --install

Usage Copy Chapter

$ ./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) (default: None)

optional arguments:
  -h, --help            show this help message and exit
  --demo                Use the demo route instead of providing one (default: False)
  --can                 Parse CAN data (default: False)
  --stream              Start PlotJuggler in streaming mode (default: False)
  --layout [LAYOUT]     Run PlotJuggler with a pre-defined layout (default: None)
  --install             Install or update PlotJuggler + plugins (default: False)
  --dbc DBC             Set the DBC name to load for parsing CAN data. If not set, the DBC will be automatically
                        inferred from the logs. (default: None)

Example using route name:

./juggle.py "5beb9b58bd12b691/0000010a--a51155e496"

Examples using segment:

./juggle.py "5beb9b58bd12b691/0000010a--a51155e496/1"

./juggle.py "5beb9b58bd12b691/0000010a--a51155e496/1/q" # use qlogs

Example using segment range:

./juggle.py "5beb9b58bd12b691/0000010a--a51155e496/0:1"

Streaming Copy Chapter

Explore live data from your car! Follow these steps to stream from your comma device to your laptop:

• Enable wifi tethering on your comma device
• SSH into your device and run cd /data/openpilot && ./openpilot/cereal/messaging/bridge
• On your laptop, connect to the device's wifi hotspot
• Start PlotJuggler with ZMQ=1 ./juggle.py --stream, find the Cereal Subscriber plugin in the dropdown under Streaming, and click Start.

If streaming to PlotJuggler from a replay on your PC, simply run: ./juggle.py --stream and start the cereal subscriber.

Demo Copy Chapter

For a quick demo, go through the installation step and run this command:

./juggle.py --demo --layout=layouts/tuning.xml

Layouts Copy Chapter

If you create a layout that's useful for others, consider upstreaming it.

Tuning Copy Section

Use this layout to improve your car's tuning and generate plots for tuning PRs. Also see the tuning wiki and tuning PR template.

--layout layouts/tuning.xml

Overview (`openpilot/tools/replay/README.md`) Copy Section

Replay

replay allows you to simulate a driving session by replaying all messages logged during the use of openpilot. This provides a way to analyze and visualize system behavior as if it were live.

Setup Copy Chapter

Before starting a replay, you need to authenticate with your comma account using auth.py. This will allow you to access your routes from the server.

# Authenticate to access routes from your comma account:
python3 openpilot/tools/lib/auth.py

Replay a Remote Route Copy Chapter

You can replay a route from your comma account by specifying the route name.

# Start a replay with a specific route:
openpilot/tools/replay/replay <route-name>

# Example:
openpilot/tools/replay/replay '5beb9b58bd12b691/0000010a--a51155e496'

# Replay the default demo route:
openpilot/tools/replay/replay --demo

Replay a Local Route Copy Chapter

To replay a route stored locally on your machine, specify the route name and provide the path to the directory where the route files are stored.

# Replay a local route
openpilot/tools/replay/replay <route-name> --data_dir="/path_to/route"

# Example:
# If you have a local route stored at /path_to_routes with segments like:
# 5beb9b58bd12b691/0000010a--a51155e496--0
# 5beb9b58bd12b691/0000010a--a51155e496--1
# You can replay it like this:
openpilot/tools/replay/replay "5beb9b58bd12b691/0000010a--a51155e496" --data_dir="/path_to_routes"

Send Messages via ZMQ Copy Chapter

By default, replay sends messages via MSGQ. To switch to ZMQ, set the ZMQ environment variable.

# Start replay and send messages via ZMQ:
ZMQ=1 openpilot/tools/replay/replay <route-name>

Usage Copy Chapter

For more information on available options and arguments, use the help command:

$ openpilot/tools/replay/replay -h
Usage: openpilot/tools/replay/replay [options] route
Mock openpilot components by publishing logged messages.

Options:
  -h, --help             Displays this help.
  -a, --allow <allow>    whitelist of services to send (comma-separated)
  -b, --block <block>    blacklist of services to send (comma-separated)
  -c, --cache <n>        cache <n> segments in memory. default is 5
  -s, --start <seconds>  start from <seconds>
  -x <speed>             playback <speed>. between 0.2 - 3
  --demo                 use a demo route instead of providing your own
  --auto                 Auto load the route from the best available source (no video):
                         internal, openpilotci, comma_api, car_segments, testing_closet
  --data_dir <data_dir>  local directory with routes
  --prefix <prefix>      set OPENPILOT_PREFIX
  --cabin                  load cabin camera
  --wide-road                 load wide road camera
  --no-loop              stop at the end of the route
  --no-cache             turn off local cache
  --qcam                 load qcamera
  --no-hw-decoder        disable HW video decoding
  --no-vipc              do not output video
  --all                  do output all messages including uiDebug, userBookmark.
                         this may causes issues when used along with UI

Arguments:
  route                  the drive to replay. find your drives at
                         connect.comma.ai

Visualize the Replay in the openpilot UI Copy Chapter

To visualize the replay within the openpilot UI, run the following commands:

openpilot/tools/replay/replay <route-name>
cd openpilot/selfdrive/ui && ./ui.py

Work with plotjuggler Copy Chapter

If you want to use replay with plotjuggler, you can stream messages by running:

openpilot/tools/replay/replay <route-name>
openpilot/tools/plotjuggler/juggle.py --stream

watch3 Copy Chapter

watch all three cameras simultaneously from your comma three routes with watch3

simply replay a route using the --cabin and --wide-road flags:

# start a replay
cd openpilot/tools/replay && ./replay --demo --cabin --wide-road

# then start watch3
cd openpilot/selfdrive/ui && ./watch3.py

Stream CAN messages to your device Copy Chapter

Replay CAN messages as they were recorded using a panda jungle. The jungle has 6x OBD-C ports for connecting all your comma devices. Check out the jungle repo for more info.

In order to run your device as if it was in a car:

• connect a panda jungle to your PC
• connect a comma device or panda to the jungle via OBD-C
• run can_replay.py

batman:replay$ ./can_replay.py -h
usage: can_replay.py [-h] [route_or_segment_name]

Replay CAN messages from a route to all connected pandas and jungles
in a loop.

positional arguments:
  route_or_segment_name
                        The route or segment name to replay. If not
                        specified, a default public route will be
                        used. (default: None)

optional arguments:
  -h, --help            show this help message and exit

Overview (`openpilot/tools/sim/README.md`) Copy Section

openpilot in simulator

openpilot implements a bridge that allows it to run in the MetaDrive simulator.

Launching openpilot Copy Chapter

First, start openpilot.

# Run locally
./openpilot/tools/sim/launch_openpilot.sh

Bridge usage Copy Chapter

$ ./run_bridge.py -h
usage: run_bridge.py [-h] [--joystick] [--high_quality] [--dual_camera]
Bridge between the simulator and openpilot.

options:
  -h, --help            show this help message and exit
  --joystick
  --high_quality
  --dual_camera

Bridge Controls:

• To engage openpilot press 2, then press 1 to increase the speed and 2 to decrease.
• To disengage, press "S" (simulates a user brake)

All inputs:

| key  |   functionality       |
|------|-----------------------|
|  1   | Cruise Resume / Accel |
|  2   | Cruise Set    / Decel |
|  3   | Cruise Cancel         |
|  r   | Reset Simulation      |
|  i   | Toggle Ignition       |
|  q   | Exit all              |
| wasd | Control manually      |

MetaDrive Copy Chapter

Launching Metadrive Copy Section

Start bridge processes located in openpilot/tools/sim:

./run_bridge.py

Overview (`openpilot/selfdrive/modeld/models/README.md`) Copy Section

Neural networks in openpilot Copy Chapter

To view the architecture of the ONNX networks, you can use netron

Overview (`openpilot/selfdrive/test/process_replay/README.md`) Copy Section

Process replay

Process replay is a regression test designed to identify any changes in the output of a process. This test replays a segment through individual processes and compares the output to a known good replay. Each make is represented in the test with a segment.

If the test fails, make sure that you didn't unintentionally change anything. If there are intentional changes, the reference logs will be updated.

Use test_processes.py to run the test locally.
Log files are cached by default. Use DISABLE_FILEREADER_CACHE='1' test_processes.py to disable caching.

Currently the following processes are tested:

• controlsd
• radard
• plannerd
• calibrationd
• dmonitoringd
• locationd
• paramsd
• ubloxd
• torqued

Usage Copy Section

Usage: test_processes.py [-h] [--whitelist-procs PROCS] [--whitelist-cars CARS] [--blacklist-procs PROCS]
                         [--blacklist-cars CARS] [--ignore-fields FIELDS] [--ignore-msgs MSGS] [--update-refs]
Regression test to identify changes in a process's output
optional arguments:
  -h, --help            show this help message and exit
  --whitelist-procs PROCS               Whitelist given processes from the test (e.g. controlsd)
  --whitelist-cars WHITELIST_CARS       Whitelist given cars from the test (e.g. HONDA)
  --blacklist-procs BLACKLIST_PROCS     Blacklist given processes from the test (e.g. controlsd)
  --blacklist-cars BLACKLIST_CARS       Blacklist given cars from the test (e.g. HONDA)
  --ignore-fields IGNORE_FIELDS         Extra fields or msgs to ignore (e.g. driverMonitoringState.events)
  --ignore-msgs IGNORE_MSGS             Msgs to ignore (e.g. onroadEvents)
  --update-refs                         Updates reference logs using current commit

Forks Copy Chapter

openpilot forks can use this test with their own reference logs, by default test_proccesses.py saves logs locally.

To generate new logs:

./test_processes.py

Then, check in the new logs using git-lfs. Make sure to also update the ref_commit file to the current commit.

API Copy Chapter

Process replay test suite exposes programmatic APIs for simultaneously running processes or groups of processes on provided logs.

def replay_process_with_name(name: Union[str, Iterable[str]], lr: LogIterable, *args, **kwargs) -> List[capnp._DynamicStructReader]:

def replay_process(
  cfg: Union[ProcessConfig, Iterable[ProcessConfig]], lr: LogIterable, frs: Optional[Dict[str, Any]] = None,
  fingerprint: Optional[str] = None, return_all_logs: bool = False, custom_params: Optional[Dict[str, Any]] = None, disable_progress: bool = False
) -> List[capnp._DynamicStructReader]:

Example usage:

from openpilot.selfdrive.test.process_replay import replay_process_with_name
from openpilot.tools.lib.logreader import LogReader

lr = LogReader(...)

# provide a name of the process to replay
output_logs = replay_process_with_name('locationd', lr)

# or list of names
output_logs = replay_process_with_name(['ubloxd', 'locationd'], lr)

Supported processes:

• controlsd
• radard
• plannerd
• calibrationd
• dmonitoringd
• locationd
• paramsd
• ubloxd
• torqued
• modeld
• dmonitoringmodeld

Certain processes may require an initial state, which is usually supplied within Params and persists from segment to segment (for example CalibrationParams or the learner cache keys like LiveParametersV2). The custom_params is a dictionary used to prepopulate Params with arbitrary values. The get_custom_params_from_lr helper is provided to fetch meaningful values from log files.

from openpilot.selfdrive.test.process_replay import get_custom_params_from_lr

previous_segment_lr = LogReader(...)
current_segment_lr = LogReader(...)

custom_params = get_custom_params_from_lr(previous_segment_lr, 'last')

output_logs = replay_process_with_name('calibrationd', lr, custom_params=custom_params)

Replaying processes that use VisionIPC (e.g. modeld, dmonitoringmodeld) require additional frs dictionary with camera states as keys and FrameReader objects as values.

from openpilot.tools.lib.framereader import FrameReader

frs = {
  'narrowRoadCameraState': FrameReader(...),
  'wideRoadCameraState': FrameReader(...),
  'cabinCameraState': FrameReader(...),
}

output_logs = replay_process_with_name(['modeld', 'dmonitoringmodeld'], lr, frs=frs)

To capture stdout/stderr of the replayed process, captured_output_store can be provided.

output_store = dict()
# pass dictionary by reference, it will be filled with standard outputs - even if process replay fails
output_logs = replay_process_with_name(['radard', 'plannerd'], lr, captured_output_store=output_store)

# entries with captured output in format { 'out': '...', 'err': '...' } will be added to provided dictionary for each replayed process
print(output_store['radard']['out']) # radard stdout
print(output_store['radard']['err']) # radard stderr

Overview (`openpilot/system/camerad/webcam/README.md`) Copy Section

Run openpilot with webcam on PC

Setup openpilot Copy Chapter

• Follow this readme to install and build the requirements

Connect the hardware Copy Chapter

• Connect the camera first
• Connect your computer to panda

GO Copy Chapter

USE_WEBCAM=1 openpilot/system/manager/manager.py

• Start the car, then the UI should show the road webcam's view
• Adjust and secure the webcam
• Finish calibration and engage!

Specify Cameras Copy Chapter

Use the ROAD_CAM (default 0) and optional DRIVER_CAM, WIDE_CAM environment variables to specify which camera is which (ie. ROAD_CAM=1 uses /dev/video1, on Ubuntu, for the road camera):

USE_WEBCAM=1 ROAD_CAM=1 openpilot/system/manager/manager.py

Index (`docs/index.md`) Copy Section

What is openpilot?

openpilot is an open source driver assistance system. Currently, openpilot performs the functions of Adaptive Cruise Control (ACC), Automated Lane Centering (ALC), Forward Collision Warning (FCW), and Lane Departure Warning (LDW) for a growing variety of supported car makes, models, and model years. In addition, while openpilot is engaged, a camera-based Driver Monitoring (DM) feature alerts distracted and asleep drivers. See more about the vehicle integration and limitations.

How do I use it? Copy Chapter

openpilot is designed to be used on the comma four.

How does it work? Copy Chapter

In short, openpilot uses the car's existing APIs for the built-in ADAS system and simply provides better acceleration, braking, and steering inputs than the stock system.

CARS (`docs/CARS.md`) Copy Section

Supported Cars

A supported vehicle is one that just works when you install a comma device. All supported cars provide a better experience than any stock system. Supported vehicles reference the US market unless otherwise specified.

335 Supported Cars

Footnotes Copy Section

¹openpilot Longitudinal Control (Alpha) is available behind a toggle; the toggle is only available in non-release branches such as nightly-dev.
²Refers only to the Focus Mk4 (C519) available in Europe/China/Taiwan/Australasia, not the Focus Mk3 (C346) in North and South America/Southeast Asia.
³See more setup details for GM.
⁴2019 Honda Civic 1.6L Diesel Sedan does not have ALC below 12mph.
⁵Enabling longitudinal control (alpha) will disable all CMBS functionality, including AEB and FCW.
⁶See more setup details for Nissan.
⁷In the non-US market, openpilot requires the car to come equipped with EyeSight with Lane Keep Assistance.
⁸Enabling longitudinal control (alpha) will disable all EyeSight functionality, including AEB, LDW, and RAB.
⁹Model years 2023 and 2024 can have either hardware type, depending on build date and factory. To check which hardware type your vehicle has, look for Autopilot computer under Software -> Additional Vehicle Information on your vehicle's touchscreen. See this page for more information.
¹⁰See more setup details for Tesla.
¹¹openpilot operates above 28mph for Camry 4CYL L, 4CYL LE and 4CYL SE which don't have Full-Speed Range Dynamic Radar Cruise Control.
¹²The J533 harness plugs in at the CAN gateway under the dashboard, just above the steering column. More information can be found at this guide.
¹³Not including the China market Kamiq, which is based on the (currently) unsupported PQ34 platform.
¹⁴Refers only to the MQB-based European B8 Passat, not the NMS Passat in the USA/China/Mideast markets.
¹⁵Some Škoda vehicles are equipped with heated windshields, which are known to block GPS signal needed for some comma four functionality.
¹⁶Only available for vehicles using a gateway (J533) harness. At this time, vehicles using a camera harness are limited to using stock ACC.
¹⁷Model-years 2022 and beyond may have a combined CAN gateway and BCM, which is supported by openpilot in software, but doesn't yet have a harness available from the comma store.

Community Maintained Cars Copy Chapter

Although they're not upstream, the community has openpilot running on other makes and models. See the 'Community Supported Models' section of each make on our wiki.

Don't see your car here?

openpilot can support many more cars than it currently does. There are a few reasons your car may not be supported.
If your car doesn't fit into any of the incompatibility criteria here, then there's a good chance it can be supported! We're adding support for new cars all the time. We don't have a roadmap for car support, and in fact, most car support comes from users like you!

Which cars are able to be supported? Copy Section

openpilot uses the existing steering, gas, and brake interfaces in your car. If your car lacks any one of these interfaces, openpilot will not be able to control the car. If your car has ACC and any form of LKAS/LCA, then it almost certainly has these interfaces. These features generally started shipping on cars around 2016. Note that manufacturers will often make their own marketing terms for these features, such as Hyundai's "Smart Cruise Control" branding of Adaptive Cruise Control.

If your car has the following packages or features, then it's a good candidate for support.

FlexRay Copy Section

All the cars that openpilot supports use a CAN bus for communication between all the car's computers, however a CAN bus isn't the only way that the computers in your car can communicate. Most, if not all, vehicles from the following manufacturers use FlexRay instead of a CAN bus: BMW, Mercedes, Audi, Land Rover, and some Volvo. These cars may one day be supported, but we have no immediate plans to support FlexRay.

Toyota Security Copy Section

openpilot does not yet support these Toyota models due to a new message authentication method.
Vote if you'd like to see openpilot support on these models.

• Toyota RAV4 Prime 2021+
• Toyota Sienna 2021+
• Toyota Venza 2021+
• Toyota Sequoia 2023+
• Toyota Tundra 2022+
• Toyota Highlander 2024+
• Toyota Corolla Cross 2022+ (only US model)
• Toyota Camry 2025+
• Lexus NX 2022+
• Toyota bZ4x 2023+
• Subaru Solterra 2023+

CONTRIBUTING (`docs/CONTRIBUTING.md`) Copy Section

How to contribute

Our software is open source so you can solve your own problems without needing help from others. And if you solve a problem and are so kind, you can upstream it for the rest of the world to use. Check out our post about externalization.

Development is coordinated through Discord and GitHub.

Getting Started Copy Section

• Set up your development environment
• Join our Discord
• Docs are at https://docs.comma.ai and https://blog.comma.ai

What contributions are we looking for? Copy Chapter

openpilot's priorities are safety, stability, quality, and features, in that order.
openpilot is part of comma's mission to solve self-driving cars while delivering shippable intermediaries, and all development is towards that goal.

What gets merged? Copy Section

The probability of a pull request being merged is a function of its value to the project and the effort it will take us to get it merged.
If a PR offers some value but will take lots of time to get merged, it will be closed.
Simple, well-tested bug fixes are the easiest to merge, and new features are the hardest to get merged.

All of these are examples of good PRs:

• typo fix: https://github.com/commaai/openpilot/pull/30678
• removing unused code: https://github.com/commaai/openpilot/pull/30573
• simple car model port: https://github.com/commaai/openpilot/pull/30245
• car brand port: https://github.com/commaai/openpilot/pull/23331

What doesn't get merged? Copy Section

• style changes: code is art, and it's up to the author to make it beautiful
• 500+ line PRs: clean it up, break it up into smaller PRs, or both
• PRs without a clear goal: every PR must have a singular and clear goal
• UI design: we do not have a good review process for this yet
• New features: We believe openpilot is mostly feature-complete, and the rest is a matter of refinement and fixing bugs. As a result of this, most feature PRs will be immediately closed, however the beauty of open source is that forks can and do offer features that upstream openpilot doesn't.
• Negative expected value: This is a class of PRs that makes an improvement, but the risk or validation costs more than the improvement. The risk can be mitigated by first getting a failing test merged.

First contribution Copy Section

Projects / openpilot bounties is the best place to get started and goes in-depth on what's expected when working on a bounty.
There are a lot of bounties that don't require a comma four or a car.

Pull Requests Copy Chapter

Pull requests should be against the master branch.

A good pull request has all of the following:

• a clearly stated purpose
• every line changed directly contributes to the stated purpose
• verification, i.e. how did you test your PR?
• justification
  • if you've optimized something, post benchmarks to prove it's better
  • if you've improved your car's tuning, post before and after plots
• passes the CI tests

Contributing without Code Copy Chapter

• Report bugs in GitHub issues.
• Report driving issues in the #driving-feedback Discord channel.
• Consider opting into cabin camera uploads to improve the driver monitoring model.
• Connect your device to Wi-Fi regularly, so that we can pull data for training better driving models.
• Run the nightly branch and report issues. This branch is like master but it's built just like a release.
• Annotate images in the comma10k dataset.

Contributing Training Data Copy Chapter

A guide for forks Copy Section

In order for your fork's data to be eligible for the training set:

• Your cereal messaging structs must be compatible
• The definitions of all the stock messaging structs must not change: Do not change how any of the fields are set, including everything from selfdriveState.enabled to carState.steeringAngleDeg. Instead, create your own structs and set them however you'd like.
• Do not include cars that are not supported in upstream platforms: Instead, create new opendbc platforms for cars that you'd like to support outside of upstream, even if it's just a trim-level difference.

DEBUGGING SAFETY (`docs/DEBUGGING_SAFETY.md`) Copy Section

Debugging Panda Safety with Replay Drive + LLDB

1. Start the debugger in VS Code Copy Chapter

• Select Replay drive + Safety LLDB.
• Enter the route or segment when prompted.
  

2. Attach LLDB Copy Chapter

• When prompted, pick the running replay_drive process.
• ⚠️ Attach quickly, or replay_drive will start consuming messages.

[!TIP]
Add a Python breakpoint at the start of replay_drive.py to pause execution and give yourself time to attach LLDB.

3. Set breakpoints in VS Code Copy Chapter

Breakpoints can be set directly in modes/xxx.h (or any C file).
No extra LLDB commands are required — just place breakpoints in the editor.

4. Resume execution Copy Chapter

Once attached, you can step through both Python (on the replay) and C safety code as CAN logs are replayed.

[!NOTE]

• Use short routes for quicker iteration.
• Pause replay_drive early to avoid wasting log messages.

Video Copy Chapter

View a demo of this workflow on the PR that added it: https://github.com/commaai/openpilot/pull/36055#issue-3352911578

INTEGRATION (`docs/INTEGRATION.md`) Copy Section

Integration with Stock Features

In all supported cars:

• Stock Lane Keep Assist (LKA) and stock ALC are replaced by openpilot ALC, which only functions when openpilot is engaged by the user.
• Stock LDW is replaced by openpilot LDW.

Additionally, on specific supported cars (see ACC column in supported cars):

• Stock ACC is replaced by openpilot ACC.
• openpilot FCW operates in addition to stock FCW.

openpilot should preserve all other vehicle's stock features, including, but not limited to: FCW, Automatic Emergency Braking (AEB), auto high-beam, blind spot warning, and side collision warning.

LIMITATIONS (`docs/LIMITATIONS.md`) Copy Section

Limitations

Limitations of openpilot ALC and LDW Copy Chapter

openpilot ALC and openpilot LDW do not automatically drive the vehicle or reduce the amount of attention that must be paid to operate your vehicle. The driver must always keep control of the steering wheel and be ready to correct the openpilot ALC action at all times.

While changing lanes, openpilot is not capable of looking next to you or checking your blind spot. Only nudge the wheel to initiate a lane change after you have confirmed it's safe to do so.

Many factors can impact the performance of openpilot ALC and openpilot LDW, causing them to be unable to function as intended. These include, but are not limited to:

• Poor visibility (heavy rain, snow, fog, etc.) or weather conditions that may interfere with sensor operation.
• The road facing camera is obstructed, covered or damaged by mud, ice, snow, etc.
• Obstruction caused by applying excessive paint or adhesive products (such as wraps, stickers, rubber coating, etc.) onto the vehicle.
• The device is mounted incorrectly.
• When in sharp curves, like on-off ramps, intersections etc...; openpilot is designed to be limited in the amount of steering torque it can produce.
• In the presence of restricted lanes or construction zones.
• When driving on highly banked roads or in presence of strong cross-wind.
• Extremely hot or cold temperatures.
• Bright light (due to oncoming headlights, direct sunlight, etc.).
• Driving on hills, narrow, or winding roads.

The list above does not represent an exhaustive list of situations that may interfere with proper operation of openpilot components. It is the driver's responsibility to be in control of the vehicle at all times.

Limitations of openpilot ACC and FCW Copy Chapter

openpilot ACC and openpilot FCW are not systems that allow careless or inattentive driving. It is still necessary for the driver to pay close attention to the vehicle’s surroundings and to be ready to re-take control of the gas and the brake at all times.

Many factors can impact the performance of openpilot ACC and openpilot FCW, causing them to be unable to function as intended. These include, but are not limited to:

• Poor visibility (heavy rain, snow, fog, etc.) or weather conditions that may interfere with sensor operation.
• The road facing camera or radar are obstructed, covered, or damaged by mud, ice, snow, etc.
• Obstruction caused by applying excessive paint or adhesive products (such as wraps, stickers, rubber coating, etc.) onto the vehicle.
• The device is mounted incorrectly.
• Approaching a toll booth, a bridge or a large metal plate.
• When driving on roads with pedestrians, cyclists, etc...
• In presence of traffic signs or stop lights, which are not detected by openpilot at this time.
• When the posted speed limit is below the user selected set speed. openpilot does not detect speed limits at this time.
• In presence of vehicles in the same lane that are not moving.
• When abrupt braking maneuvers are required. openpilot is designed to be limited in the amount of deceleration and acceleration that it can produce.
• When surrounding vehicles perform close cut-ins from neighbor lanes.
• Driving on hills, narrow, or winding roads.
• Extremely hot or cold temperatures.
• Bright light (due to oncoming headlights, direct sunlight, etc.).
• Interference from other equipment that generates radar waves.

The list above does not represent an exhaustive list of situations that may interfere with proper operation of openpilot components. It is the driver's responsibility to be in control of the vehicle at all times.

Limitations of openpilot DM Copy Chapter

openpilot DM should not be considered an exact measurement of the alertness of the driver.

Many factors can impact the performance of openpilot DM, causing it to be unable to function as intended. These include, but are not limited to:

• Low light conditions, such as driving at night or in dark tunnels.
• Bright light (due to oncoming headlights, direct sunlight, etc.).
• The driver's face is partially or completely outside field of view of the cabin camera.
• The cabin camera is obstructed, covered, or damaged.

The list above does not represent an exhaustive list of situations that may interfere with proper operation of openpilot components. A driver should not rely on openpilot DM to assess their level of attention.

SAFETY (`docs/SAFETY.md`) Copy Section

Safety

openpilot is an Adaptive Cruise Control (ACC) and Automated Lane Centering (ALC) system.
Like other ACC and ALC systems, openpilot is a failsafe passive system and it requires the
driver to be alert and to pay attention at all times.

To assist the driver in maintaining alertness, openpilot includes a driver monitoring feature
that alerts when it detects driver distraction.

However, even with an attentive driver, we must make further efforts for the system to be
safe. We repeat, driver alertness is necessary, but not sufficient, for openpilot to be
used safely and openpilot is provided with no warranty of fitness for any purpose.

openpilot is developed in good faith to be compliant with FMVSS requirements and to follow
industry standards of safety for Level 2 Driver Assistance Systems. In particular, we observe
ISO26262 guidelines, including those from pertinent documents
released by NHTSA. In addition, we impose strict coding guidelines (like MISRA C : 2012)
on parts of openpilot that are safety relevant. We also perform software-in-the-loop,
hardware-in-the-loop, and in-vehicle tests before each software release.

Following Hazard and Risk Analysis and FMEA, at a very high level, we have designed openpilot
ensuring two main safety requirements.

1. The driver must always be capable to immediately retake manual control of the vehicle,
   by stepping on the brake pedal or by pressing the cancel button.
2. The vehicle must not alter its trajectory too quickly for the driver to safely
   react. This means that while the system is engaged, the actuators are constrained
   to operate within reasonable limits[^1].

For additional safety implementation details, refer to panda safety model. For vehicle specific implementation of the safety concept, refer to opendbc/safety/safety.

[^1]: For these actuator limits we observe ISO11270 and ISO15622. Lateral limits described there translate to 0.9 seconds of maximum actuation to achieve a 1m lateral deviation.

Forks of openpilot Copy Section

• Do not disable or nerf driver monitoring
• Do not disable or nerf excessive actuation checks
• If your fork modifies any of the code in opendbc/safety/:
  • your fork cannot use the openpilot trademark
  • your fork must preserve the full safety test suite and all tests must pass, including any new coverage required by the fork's changes