◄ Home

Table of Contents

• Git Branches
• Why Would a User Switch Branches?
• How to Switch to master-ci (Non-Developers)
• How to Checkout a Specific Release
• For Developers
  • 1. SSH into your comma2/EON
  • 2. Checkout your desired branch
  • 3. (Optional) Monitor build process after reboot
  • Developer Notes

Overview

Updating openpilot for most users is intended to be an automatic process, when it comes to official releases (i.e. versions that are listed here: https://github.com/commaai/openpilot/releases).

By switching away from the default release2 branch of openpilot, you will lose the benefit of Comma's rigorous test and review process. All other branches can and likely do have bugs, some of which may cause undesirable behavior, you switch branches at your own risk.

Git Branches

See the Pro Git Book and specifically the chapter on Git Branches for an explanation of what a branch is. See the openpilot Development Flow discussion on George's Medium post on Externalization for an explanation of the various openpilot branches.

Why Would a User Switch Branches?

Switching branches is primarily the realm of developers. However, there are two reasons why a general user may want to switch to the master-ci branch of openpilot:

• Gaining access to a bug fix
• Gaining access to newly fingerprinted vehicles

How to Switch to master-ci (Non-Developers)

Comma's URL Installer is easier but SSH may be a fallback if that doesn't work.

Comma URL Installer

1. Ensure you can "Factory Reset" the device.

• See https://www.youtube.com/watch?v=gNnRmEyVSVQ 's 1st part for Comma 3's factory reset. Mind the YouTube comments re: newer OSes on Comma 3.

2. Factory Reset the device.
3. In place of the "openpilot.comma.ai" URL for Custom Software during installation, use "installer.comma.ai/commaai/master-ci".

• The startup time for master-ci can be slower.

Factory Reset can also be done through "Uninstall openpilot" in Settings but master-ci is definitely not perfect, contains bleeding edge software, and the UI is more likely to break including access to the "Uninstall openpilot" button. The preferred instructions above ensure the reader has visited Recovery in case the new software does not boot.

Additionally, you may encounter a "No Panda" Error. Please see the "Panda Flashing" page for details on addressing that.

SSH

1. You will first need to gain access to your device using SSH, see the SSH instructions.
2. Then you need to run the following command:

This command will replace whatever version of openpilot you are currently running with the master-ci branch. Caution: this command will blow away the openpilot directory, so if you are a developer who has made changes to openpilot, this command is not for you.

For comma2/EON:

cd /data && rm -rf openpilot && git clone -b commatwo_master https://github.com/commaai/openpilot && reboot

For comma3:

cd /data && rm -rf openpilot && git clone -b master-ci https://github.com/commaai/openpilot && sudo reboot

When switching between branches, if the version of cereal or some other submodule has changed between the branches, you may encounter errors including the "communication between processes" issue. To reinitialize the submodules after you checkout a new branch run the following commands:

git submodule deinit --all -f
git submodule init
git submodule update

Alternatively, switching to another branch can be done without pulling the entire repository, while retaining the necessary submodules, and with one less reboot.

For comma2/EON:

cd /data; rm -rf ./openpilot; git clone -b commatwo_master --depth 1 --single-branch --recurse-submodules --shallow-submodules https://github.com/commaai/openpilot.git openpilot; cd openpilot; pkill -f thermald; rm -f prebuilt && reboot

For comma3:

cd /data; rm -rf ./openpilot; git clone -b master-ci --depth 1 --single-branch --recurse-submodules --shallow-submodules https://github.com/commaai/openpilot.git openpilot; cd openpilot; pkill -f thermald; rm -f prebuilt && sudo reboot

How to Checkout a Specific Release

1. You will first need to gain access to your device using SSH, see the SSH instructions.
2. Then you need to run the following command:

This command will replace whatever version of openpilot you are currently running with version v0.7.6. Caution: this command will blow away the openpilot directory, so if you are a developer who has made changes to openpilot, this command is not for you.

For comma2/EON:

cd /data && rm -rf openpilot && git clone -b v0.7.6 https://github.com/commaai/openpilot && reboot

For comma3:

cd /data && rm -rf openpilot && git clone -b v0.7.6 https://github.com/commaai/openpilot && sudo reboot

When switching between branches, if the version of cereal or some other submodule has changed between the branches, you may encounter errors including the "communication between processes" issue. To reinitialize the submodules after you checkout a new branch run the following commands:

git submodule deinit --all -f
git submodule init
git submodule update

For Developers

However, if you want to test out newer, unreleased version like 0.8.0, the easiest way is to git clone openpilot directly onto your CommaTwo/EON and git checkout the master branch (could potentially be unstable since changes are made daily). The steps below show how to ensure you are on the git branch that has the latest code changes.

The latest openpilot revisions come from the main repository: https://github.com/commaai/openpilot .
If you want to test out your own modified code, create a fork of the main repo and clone that one (branches should still be the same)

1. SSH into your comma2/EON

cd /data/
mv openpilot/ openpilot.backup
git clone https://github.com/commaai/openpilot.git
cd openpilot

2. Checkout your desired branch

• release2 - latest official release with compiled binary. Does not need to be built on the device
  • git checkout release2
• master - latest openpilot changes. The master branch has submodules, which need to be updated/initialized, otherwise once you reboot your build will fail. Needs to be built on the device.
  • git checkout master
  • git submodule update --init --recursive
  • reboot to start build
• master-ci - latest openpilot changes, with submodules already integrated. Needs to be built on the device.
  • git checkout master-ci
  • reboot to start build
• devel
• devel-staging
• <version_number> - release version (tag) (e.g. v0.8.7, v0.7.3). Use this to downgrade to an older release version, should not need to be built on the device
  • git checkout v0.8.7
    • If the checkout aborts due to overwrites, first deinitialize the modules then run checkout
    • git submodule deinit --all -f
  • reboot needed if <version_number> uses older version of OS (will prompt for OS update on device after reboot)

3. (Optional) Monitor build process after reboot

For branches that need to be built, you can monitoring the building process by SSH'ing into your comma right after reboot and typing tmux a

Developer Notes

When switching between branches, if the version of cereal or some other submodule has changed between the branches, you may encounter errors including the "communication between processes" issue. To reinitialize the submodules after you checkout a new branch run the following commands:

git submodule deinit --all -f
git submodule init
git submodule update