Forks - commaai/openpilot Wiki
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.
openpilot forks are used for various purposes, often for use on a certain vehicle or for the development and testing of new features.
Fork installation options from a subjective easiest to harder:
Shane's Fork Installer at https://smiskol.com/fork/
- Quick Usage: "Uninstall openpilot" in ⚙️ Settings and enter a custom URL of Shane's Fork Installer to install.
- Target Repository: https://github.com/some_fork_maintainer_username/openpilot / Target Branch: some_git_branch_name
- At installation where you choose "Custom Software (Advanced)", instead of
https://smiskol.com/fork/some_fork_maintainer_username/some_git_branch_namefor the installer link. Do you see where
some_git_branch_namecome from in making that installer link?
- Assumes the repository name is
openpiloton 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.
- 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.
Fork manager at emu-sh/.oh-my-comma see: demo
- Requires SSH-ing and setup.
- Requires some knowledge of Linux shell behavior.
- Kind of 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
|@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||Hyunida/Kia/Genesis (HKG) cars. Equipped with community-loved Modified Assistive Driving Safety (MADS) Mode for HKG 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.|
|@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).|
|@afa||Afa||Honda fork for Chinese users who like customization|
|@LexusRXopenpilotUG (org) -> @nelsonchen -> @sumedhekaru||LexusRXopenpilotUG||Un-upstreamable daily auto-generated patch of comma branches and some community forks for Lexus RX longitudinal users to allow lower highway RPMs, quieter rides, and higher mileage.|
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
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
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.
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!
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
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.
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.
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_BRANCHthat tracks branch
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