Toolchain Setup

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

PlatformIO¶

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 3^rd 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 💯)

Cloning the Repo¶

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

• Click that! 👈
• Then, enter ExpressLRS Repo URL -> https://github.com/ExpressLRS/ExpressLRS.git 💻
• 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. 🖱️

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.

Avoid user_defines.txt ending up in a commit or getting overwritten¶

Don't change user_defines.txt for setting up your local configuration. Instead create a new text file `super_defines.txt in the same location as user_defines.txt to define your local build configuration. super_defines.txt will be git-ignored and will not be part of any commits and won't be overwritten by pulls. Example super_defines.txt:

#-DRegulatory_Domain_EU_CE_2400
-DRegulatory_Domain_ISM_2400
#-DRegulatory_Domain_FCC_915
#-DRegulatory_Domain_EU_868

-DMY_BINDING_PHRASE="bindphrase"
-DHOME_WIFI_SSID="ssid"
-DHOME_WIFI_PASSWORD="password"
-DLOCK_ON_FIRST_CONNECTION

-DUART_INVERTED

!-DAUTO_WIFI_ON_INTERVAL=60
-DAUTO_WIFI_ON_INTERVAL=40

Note: the ! flag is called the removal flag. It removes other flags that completely match the text after the !.