Forks

comma does not validate custom forks for safety. Install them at your own risk.

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

Known Bad Forks

⚠️ These are bad forks that do not document that they will get you banned. Don't install them as your device will permanently never be able to upload to comma connect online services again. This list and reasons are not exhaustive.

• neokii/npilot - dm disabling
• Spacepilot - lots of unsafe code, just everywhere.

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)	Vitality Signs	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	FrogPilot is my personal openpilot fork based around my 2019 Lexus ES. Use at your own discretion. FrogPilot offers a wide range of customizable features that can be easily toggled on or off to suit your preferences. Whether you want a completely stock openpilot experience or want to add some fun and personal touches, FrogPilot has you covered!
@martinl / mlp		README	Subaru (In progress PR supporting both Global and Pre-Global models).
OPKR		README	Primary focus on HKG and Comma 2 support. This fork is specifically focused on Hyundai, Kia, and Genesis Vehicles, and is the ideal choice for enthusiasts seeking extreme customization and comprehensive control over the openpilot environment.
OPGM		README	Primary focus on adding support and qol improvements for GM vehicles.
sunnypilot		README	Hyundai/Kia/Genesis (HKG), Honda, Subaru, Toyota, and GM cars. Equipped with community-loved Modified Assistive Driving Safety (MADS) Mode for supported cars. Optimized and enhanced openpilot driving experience with rich features.
@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)	Vitality Signs	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.
@ShaneSmiskol		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.

Fork Management

How do I pull branches from multiple forks since GitHub only allows one fork per origin repo?

Instead of forking multiple fork repositories based on commaai/openpilot, you can choose specific branches you want to bring over to your own repository from other fork maintainers.

There's an easy way to do this which only involves using the GitHub website, and a more involved way which requires a local clone of your own fork as well as executing a few Git commands.

• The Easy Way

  This way takes advantage of GitHub's edit & PR (pull request) functionality.

  • Find the branch you want to bring to your own fork from another user.
  • Click on a file that isn't important to openpilot, such as the README.md file (click to use as an example). Or you can edit a file you want to change in the first place.
  • Then find the edit button above the file and click it. Make a small change and click the green "Propose changes" button.
  • The name outlined in red is the new name of the branch on your repo you copied over:

  

  • Exit the pull request page and you can now go into your branches to rename it.

• The Git Way

  Use this method if you know a bit of Git already and would like more control over pulling branches from other users. Prerequisites: You've cloned your fork locally and have Git set up to push and pull from your fork.

  Variables defined:

  • USERNAME: The GitHub username of the fork maintainer you would like to copy a branch from.
  • THEIR_BRANCH: The branch on USERNAME's fork you want to copy over to yours.
  • ANY_NAME_FOR_BRANCH: Can be identical to THEIR_BRANCH (as long as it doesn't already exist on your fork!), or a new name you want their branch to be called once uploaded (pushed) to your fork on GitHub.

  Now let's get started:

  • git remote add USERNAME https://github.com/USERNAME/openpilot - This adds a Git remote pointing to USERNAME's repository on GitHub to your local repository so you can pull from it.
  • git fetch USERNAME - This fetches all of the fork maintainer's branches and tags. Re-run this every time you want to pull a new branch from this fork.
  • git checkout -b ANY_NAME_FOR_BRANCH USERNAME/THEIR_BRANCH - Checks out a local branch called ANY_NAME_FOR_BRANCH that tracks branch THEIR_BRANCH from USERNAME.

  To push to your fork:

  • git push -u origin - This will push the fork's branch you just pulled and checked out to your own fork with the name ANY_NAME_FOR_BRANCH by default.