Skip to content

Toolchain Setup

Software Banner


The following section is intended for advanced users who intend to dabble with the source code directly.

Toolchain Setup (Advanced)

ExpressLRS is written in C++ using the Arduino framework.

  • Rather than using the Arduino IDE (which let's face it, πŸ—Ώ is pretty clunky), we use PlatformIO
  • To ease the use of pio we recommend using the extension for Visual Studio Code


  1. πŸ”½ Download a copy of VSCode for your computer
  2. πŸ“‚ Open VSCode, and click on the "Extensions" icon in the toolbar on the right (see Managing Extensions πŸ“˜)
  3. πŸ”Ž In the search box, enter platformio, and install the extension (see the pio install documentation πŸ“š)

Git Setup

We recommend using VSCode's built-in Git client, as it requires the least 3rd party software πŸ€–.

  1. πŸ”½ Download a copy of git (this is also needed for PlatformIO)
  2. Install git, click yes to the default options (there are a LOT πŸ’―)


Make sure you select this option during installation, it adds git to PATH which is necessary for VSCode cloning (the next step).

git install

Cloning the Repo

  • In VSCode open the command palette (using Cmd+Shift+P on MacOS or Ctrl+Shift+P on Windows)
  • Enter Git: Clone

clone repo

  • Click that! πŸ‘ˆ
  • Then, enter ExpressLRS Repo URL -> πŸ’»
  • Choose a folder for ExpressLRS. πŸ“‚

Selecting the Latest Release

Before we can do any building, you need to select a release build of ELRS. For example, release 0.1.0-RC1. In Visual Studio Code select that tag. The location of the selector is shown below. πŸ–±οΈ

latest release

branch selecttion

Click the selector, and then type in the name of the tag, in this case 0.1.0-RC1.

PlatformIO Building

Once you had the time of your life setting up your toolchain 🧰 you are ready to Flash ⚑ ExpressLRS to supported hardware.

Building Targets using PlatformIO

  1. πŸ“‚ When you first launch Visual Studio Code, you should see the PlatformIO Home Page in a tab. Click the Open Project button. Navigate to the ExpressLRS repo directory. Navigate into the src folder (i.e. ./ExpressLRS/src/). Finally, press the Open button.
  2. ✏️ Edit the file ./src/user_defines.txt to define user specific variables. 😈 Please make sure you edit the file according to your needs!
  3. πŸ“Š In the toolbar on the left, click the PlatformIO icon, which will show the list of tasks. Now, select Project Tasks, expand your desired target and select Build/Upload (depending on the method). You should see the result in the terminal.
  4. πŸ™ƒ If something went wrong - please check the Terminal, too. It will contain at least a hint of what the issue is. Please ask the community for further helpπŸ§‘β€πŸ”§!

Updating your Local Repo

You've cloned the repository and are now wondering how to get new updates down the line. Then this document is meant for you! Here's a primer on how to keep your local copy of the repository up-to-date.

Method 1: The Clean Way - Fetch & Reset

Probably the easiest and least troublesome method, however, it'll overwrite any changes you've made to your local copy. ⚠

  1. Open the terminal

    You can either straight up open bash/cmd and navigate to your project folder or open an integrated terminal in VSCode:

    • Open the command palette (using Cmd+Shift+P on MacOS or Ctrl+Shift+P on Windows)
    • Enter: Create New Integrated Terminal


  2. In the terminal, type: git fetch -pu && git reset --hard origin/master

    This will get you the latest version and destroy any local changes you've made.

Method 2: The lazy way - Commit, Pull & Merge

The advantage this method has over the first method is that all your changes to the user_defines.txt (or any other file, for that matter) will get merged with any new updates. There's a possibility that, if changes are too big, you could end up with a merge conflict. If that doesn't appeal to you, stick to the first method.

  1. Commit your changes to your local repository

    • In VSCode open the command palette (using Cmd+Shift+P on MacOS or Ctrl+Shift+P on Windows)
    • Enter: Git: Commit

      VSCode will tell you that there are unstaged changes and ask if you want to add them to the commit. Confirm this! This will just commit your changes to the user_defines.txt to your local repository. No worries, you're not overwriting anything on GitHub! :octocat:

  2. Open the terminal, how-to is detailed in method 1

  3. In the terminal, type: git pull -f

    This will pull a new revision of the remote repository to your local repository and automatically merge it with your changes.