Forks - commaai/openpilot GitHub Wiki

comma does not validate custom forks for safety. Install them at your own risk. This page is managed by the community. There is no guarantee from anybody that even the safe forks here are safe or even the bad forks are unsafe.

Unsafe forks will get your device banned from comma connect server services permanently.

openpilot forks are used for various purposes, often for use on a certain vehicle or for the development and testing of new features. Sometimes these features or changes make it back to comma's openpilot, sometimes they don't. Point is, those are changes not in comma's openpilot for one reason or another.

Forks are not apps. They can change the OS, device, and/or more permanently.

If you are starting out and a beginner, please do not use forks. This is a statement even from those who heavily vouch for fork usage. Start with comma's openpilot until you gather enough openpilot expertise like after a month to evaluate and discuss forks. You can re-install comma's openpilot with openpilot.comma.ai as the Custom Software URL.

Certain forks may make changes that are unsafe. These changes may get your device banned from uploading diagnostics and camera data to comma connect servers. This is a serious issue if you're looking to get help from the community or comma as developers from comma or the community will be unable and even unwilling to diagnose any issues on that device via comma servers. Comma will under no circumstances unban your device if it is banned for running an unsafe fork, even if the device is sold to a new owner. If you don't care, you don't care, but that's a choice with permanent consequences.

If you can't make sure or aren't sure a fork's code won't ban you from comma servers, you should evaluate the creator of your fork's presence/reputation in the comma.ai Discord. If they aren't there, it's a huge hint they may not be following safety guidelines and your device may be banned from comma's online services if it runs their fork.

Custom forks are discussed in the comma.ai Discord in the #custom-forks channel. Join the comma.ai Discord, and that #custom-forks channel link will work. In addition, forks themselves may have their own Discord communities; Please check their READMEs for details.

comma as a policy does not use or debug data from forks! Fork changes may be unclear or have non-straightforward changes. They will only debug or train on data from the https://github.com/commaai/openpilot repository. Please keep this in mind if you're reporting issues in the comma.ai Discord.

Comma Hardware is not fully backwards compatible

If the fork does not make this information clear, that should be considered a demerit.

Incomplete list of hardware compatibility:

Late-model 3, 3X must use codebases that are based on 0.9.4 or newer.

Fork Installation

Fork installation options from a subjective easiest to harder:

URL Installers

These include Shane's Fork Installer at https://smiskol.com/fork/ and comma.ai's Fork Installer at https://installer.comma.ai.

URL installers dynamically generate an executable binary that is downloaded at the Custom Software URL installation step that installs a fork configured by you inside the URL.

Quick Usage: "Uninstall openpilot" in ⚙️ Settings and enter a custom URL of a URL Installer to install.
- Example
  - Target Fork Repository: https://github.com/some_fork_maintainer_username/openpilot / Target Branch: some_git_branch_name
  - Shane's Fork Installer: At installation where you choose "Custom Software (Advanced)", instead of https://openpilot.comma.ai enter https://smiskol.com/fork/some_fork_maintainer_username/some_git_branch_name for the installer link. Do you see where some_fork_maintainer_username and some_git_branch_name come from in making that installer link?
  - comma.ai's Fork Installer: At installation where you choose "Custom Software (Advanced)", instead of https://openpilot.comma.ai enter https://installer.comma.ai/some_fork_maintainer_username/some_git_branch_name for the installer link. Do you see where some_fork_maintainer_username and some_git_branch_name come from in making that installer link?
These assume the repository name is openpilot on GitHub but some forks have setup GitHub redirects to work around this hardcoded assumption.
No SSH, no terminal, no software, and no computer is needed.
Takes a long time to recompile non-precompiled forks or branches when switching from pre-compiled branches such as comma's release3 branch that is installed with openpilot.comma.ai.
Uninstalling as part of the installation wipes settings and data. The upside is you can look at this as always starting with a clean slate with this method.
Because "Uninstalling" wipes all data, make sure you've uploaded all data you wanted from your device to comma connect you wish to share before "Uninstalling". Otherwise, it will be lost.
Unbootable fork? See https://youtu.be/0MPv_hSH3hk?t=218 and do a factory reset from recovery for C2 and https://www.youtube.com/watch?v=gNnRmEyVSVQ 's 1st part for C3's factory reset.
Black screen? See the Addendums to C3 C3X Flashing wiki page.
If you're a developer, you should look at the other options below.

@spektor56's openpilotToolkit

You get a nice GUI and more to walk you through setting up SSH and so on.
Currently only runs on Windows and Android

Fork manager at emu-sh/.oh-my-comma see: demo

Requires SSH-ing and setup.
Requires some knowledge of Linux shell behavior.

JFrux's guide for installing forks.

Old and neglected. JFrux has been MIA from the comma.ai and openpilot communities for a long time.
Stuff is broken like SSH now requiring GitHub accounts and keys and Workbench being broken.
Currently broken but still ranks really highly on search engines beating this page down. That's not a good thing. But you're here. That's good.
Still a reference for those wishing to run bare Git commands.

If you just want something to help you SSH into your device, check out Utilities for Developers

Fork Directory

Bad/Unsafe Forks

⚠️ These are the features that do not meet comma safety guidelines. The features may get you banned if your device logs are uploaded to the comma server. Fork maintainers may modify their code at any time, so you should always confirm changes while using forks.

When put on your brake, lateral/longitudinal control must be disengaged.
Disabling DM(Driver Monitoring) is not allowed.
Modifying the values of steering limit in Panda code is prohibited.

※ It's free to use any fork, and the device ban is fully up to the person who using it. Fork owners are not enemies of each other. They are collaborative relationships that advances openpilot.

Forks

While there is a short description here, READ their READMEs.

These forks may have their own communities and support channels. You should join them if interested.

The order in this list is purely alphabetical.

Name or Owner(s)	README	Description
@AlexandreSato	README	Primary focus on Toyota/Lexus.
dragonpilot	README	Heavily modified fork of openpilot with many different customizations accessible via UI.
@ErichMoraga	README	Firmware Backports, Toyota / ZSS
FrogPilot	README	Fully customizable fork focused on fine-tuning the driving experience. Aimed at more experienced openpilot users.
@martinl / mlp	README	Subaru (In progress PR supporting both Global and Pre-Global models).
OPGM	README	Primary focus on adding support and qol improvements for GM vehicles.
sunnypilot	README	sunnypilot offers a unique driving experience for over 260 supported car makes and models with modified behaviors of driving assist engagements. sunnypilot complies with comma.ai's safety rules as accurately as possible. Optimized and enhanced openpilot driving experience with rich features such as Modified Assistive Driving Safety (MADS), Enhanced Speed Control, Dynamic Experimental Control (DEC), and more.
@twilsonco	README	(C3X and some newer C3 units not supported!) GM (spec. Chevy Volt) fork with improved controls and many other features. Notable for being the NNFF-initiative testbed-development that some other forks are starting to integrate and explicit comma.ai interest in a possible NNFF approach.

"You should use something else" Forks

If it doesn't belong here, move it back up. Likewise, if it doesn't belong "there", move it down.

Abandoned / Obsolete / Unmaintained
- Generally > 6 months without a commit.
Extremely "Personal Workshop" - This isn't exactly a bad thing, but you should know what you're getting into especially if there isn't a "community" around a fork specifically.
- Only consider if you're in contact with the fork maintainer.

Name or Owner(s)	README Link	Description
@afa	README	Signs of abandonment. Original Description: Honda fork for Chinese users who like customization
@bugsy924	README	Redirect. Original Descrkiption: Subaru (Recommended to use mlp's fork which contains Bugsy's work).
@kegman	README	Signs of abandonment. Original Description: Largely supports Honda. Has many various customization options.
@jyoung8607	README	Personal Workshop. Original Description: Skoda, Volkswagen, Seat, Audi
@PaulLee	README	Signs of abandonment. Original Description: Korean version
@pfeiferj	README	Personal Workshop. A collection of patch sets of common unsupported/unofficial community features. This repo is primarily intended for developers.
@Ponzu	README	Signs of abandonment. Original Description: Japanese?
@spektor56	README	Based on ancient openpilot for C2; Will not work on current comma devices. Original Description: For Honda/Toyota and a small subset of Hyundai vehicles only. Replicates the behaviour of Honda Safety Sense. Supports Bosch, Nidec, and pedal.
Shane's Fork	README	Shane works at comma.ai now and his current work is in comma openpilot. Original Description: Close to stock, has an implementation of following distance profiles similar to the stock Toyota cruise control system. Supports Prius w/ ZSS
@xx979xx	README	Signs of abandonment. Original Description: Hyundai / Kia / Genesis
@zorrobyte	README	Personal Workshop / More focused on "retropilot" than "openpilot" interests. Original Description: Close to stock, automatically learns your curvature factor for better curve handling. Also supports the highly-accurate Zorro Steering Sensor (ZSS).

Not a Fork you can install on your comma device

Flowpilot
- Heavily modified and cut up port of openpilot to non-comma Device platforms.

Development

Helpful tips for creating and maintaining a successful openpilot fork.

comma.ai suggests familiarizing yourself with functional safety before starting development on a custom fork.
Here's where some of the commonly modified openpilot files are:
- longcontrol.py: Controls gas and brakes from an input desired speed, using a PI controller
- lane_planner.py: Calculates dPoly (the path openpilot tries to drive) from input lane line and path polys from the model
- planner.py: Has longitudinal acceleration limits. Picks the slowest longitudinal solution to use for cruise control (between set speed and the two longitudinal MPCs)
- interface.py (path: selfdrive/car/YOUR MAKE/interface.py): Houses the tuning values for each car. Specifies custom alerts/events for that make. Inherits from interfaces.py
From @Torq_boi: A lot of people seem to be changing the CAMERA_OFFSET parameter. So I just want to make clear that that just modifies the laneline positions, not the predicted path. If you want the car to consistently drive more left or right you should change the path too. Since OP sometimes relies on lanelines sometimes on path, having them mismatched can cause weirdness.

Custom Fork Do's and Don'ts

Forks can change many of the fundamental pieces of openpilot software. Because of this, custom forks are expected to maintain certain safety procedures in order to access comma.ai's server infrastructure.

Do's

Mess with the UI, there's tons of information in openpilot begging to be displayed. We have so much data that isn't shown.
Change the tuning of your car to be good. Most of the stock tunings are actually quite bad.
Experiment with new control algorithms. Right now it's using simple algorithms that don't accurately model the actuators on the car.
Add advanced features like traffic lights and navigation!
Overview of the safety of openpilot (SAFETY.MD)

Don'ts

By and large, comma.ai recommends developers to not touch any of the panda safety code to add new features or modify existing behavior. One exception is unsafe_mode defined in safety_declarations.h, near the bottom. Some definitions of what each mode does can also be found in that file.
- If you would like to propose a change in panda safety, consider opening a pull request.
The integrity of the time variables in the driver_monitor.py file must remain consistent with what's been predefined by comma.
Don't use the car's Parking Assist parameters to drive at highway speed. Don't promote to other users. See medium article for more details: https://medium.com/@comma_ai/safer-control-of-steering-362f3526c9ab

NOTE: To fork maintainers. Disabling or nerfing safety features may get you and your users banned from our servers. comma.ai strongly discourages the use of openpilot forks with safety code either missing or not fully meeting the requirements defined in SAFETY.md.