Forks

◄ Home

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

Unsafe forks will get you banned from comma servers and their associated services.

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

openpilot forks are used for various purposes, often for use on a certain vehicle or for the development and testing of new features.

If you are starting out and are a beginner, do not use forks. Start with stock openpilot until you gather enough expertise to evaluate and discuss forks. You can install stock openpilot with openpilot.comma.ai as the Custom Software URL.

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.

comma as a policy does not use or debug data from forks! Fork changes may be unclear or non-straightforward to them. They will only debug or train on data from their repositories.

Fork installation options from a subjective easiest to harder:

URL Installers at Installation Screen

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

• Quick Usage: "Uninstall openpilot" in ⚙️ Settings and enter a custom URL of a URL Installer to install.
  • Example
    • Target 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?
• Assumes the repository name is openpilot on GitHub but some forks such as Dragonpilot have setup redirects to work around this hardcode.
• No SSH, no terminal, no software, and no computer is needed.
• Takes a long time to recompile non-precompiled forks or branches when switching.
• 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 before Uninstalling. Otherwise, it will be lost.
• Black screen or 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.
• If you're a developer, you should look at the other options below.

@spektor56's openpilotToolkit

• Maintained
• 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.
• Maintained

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

Owner(s)	Link	Description
@spektor56	spektor56	For Honda/Toyota and a small subset of Hyundai vehicles only. Replicates the behaviour of Honda Safety Sense. Supports Bosch, Nidec, and pedal.
@sunnyhaibin	sunnyhaibin	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.
@kegman	kegman	Largely supports Honda. Has many various customization options.
@zorrobyte	zorrobyte	Close to stock, automatically learns your curvature factor for better curve handling. Also supports the highly-accurate Zorro Steering Sensor (ZSS).
@ErichMoraga	ErichMoraga	Toyota / ZSS
@xx979xx	xx979xx	Hyundai / Kia / Genesis
@eFini	dragonpilot	Heavily modified fork of openpilot with many different customizations accessible via UI.
@jyoung8607	jyoung8607	Skoda, Volkswagen, Seat, Audi
@ShaneSmiskol	Stock Additions	Close to stock, has an implementation of following distance profiles similar to the stock Toyota cruise control system. Supports Prius w/ ZSS
@bugsy924	bugsy924	Subaru (Recommended to use use mlp's fork which contains Bugsy's work).
@mlp	martinl	Subaru (In progress PR supporting both Global and Pre-Global models).
@twilsonco	twilsonco	GM (spec. Chevy Volt) fork with improved controls and many other features. Also includes a fork of SunnyPilot with improved GM controls while we work on upstreaming the improvements
@afa	Afa	Honda fork for Chinese users who like customization
@Ponzu	Ponzu07	Japanese?
@PaulLee	cebu13	Korean version

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 never be able to use comma online services again. For obvious reasons, this list and reasons are not exhaustive.

• neokii/npilot - dm disabling
• OPKR - dm disabling is an option
• Spacepilot - lots of unsafe code.

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.