From 15cae54563bfc93ff96f184ce03d9ffc4147c75e Mon Sep 17 00:00:00 2001 From: Patrick Menschel Date: Fri, 3 Jan 2025 11:32:08 +0100 Subject: [PATCH] Docs: Add Developer Guide for Linux Users This patch adds a straight-forward quick start guide for linux users to get involved with the project. --- docs/software/toolchain-install.md | 78 ++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/docs/software/toolchain-install.md b/docs/software/toolchain-install.md index 88af58859..8a1a42b95 100644 --- a/docs/software/toolchain-install.md +++ b/docs/software/toolchain-install.md @@ -133,3 +133,81 @@ Don't change ``user_defines.txt`` for setting up your local configuration. Inste -DAUTO_WIFI_ON_INTERVAL=40 Note: the `!` flag is called the removal flag. It removes other flags that completely match the text after the `!`. + +## Toolchain Setup (Advanced) for Linux Users + +!!! note "Note" + These instructions are meant as a quick start guide for those who develop on Linux. + Typically developers on Linux don't need much of an explanation and just look for the right commands for the toolchain. + That's what this guide will provide, without any nudging to use Microsoft VSCode IDE. + + +### Cloning the Repo +Open a Shell (Bash) in your regular workspace and clone the repo recursively like always and change into that directory. +It is assumed that Linux users know how to use git. + +``` +git clone --recursive https://github.com/ExpressLRS/ExpressLRS.git +cd ExpressLRS +``` + +### PlatformIO +PlatformIO is available as a Python package and can be installed via Pip. +Following best practices we will create a virtual environment in the repo directory first. + +1. Install virtual-env (just in case it's not installed by default) + +``` +pip install virtual-env +``` + +2. Setup a virtual environment to not taint your system's python installation. +It does not matter where you create this but it makes sense to create it in the project directory, because best practice is to have a separate venv for each python project. + +``` +python -m venv .venv +source .venv/bin/activate +``` + +3. Install the required python packages. Empy and pexpect are listed because modules like `dronecan` fail to correctly specify +their dependencies for pip to install them automatically. + +``` +pip install platformio dronecan setuptools empy==3.3.4 pexpect +``` + +### Building Targets using PlatformIO + +The platformio package comes with the [pio](https://docs.platformio.org/en/latest/core/userguide/cmd_run.html) executable. +It is the build command of the toolchain. +Pio expects a platformio.ini file in the directory where it is invoked, so change into src directory first. + +There find and open the `user_defines.txt` file in your favorite editor. +This file contains the build flags that you know from ELRS Configurator. +At least uncomment the line for your regulatory domain. That's the minimum requirement for the build to work. +You may also want to set your binding phrase and everything else you would normally set in the ELRS Configurator. + +To verify your build environment does work, start building firmware for a common 900Mhz target. It obviously needs a corresponding regulatory domain setting. + +``` +cd src +pio run --environment Unified_ESP32_900_RX_via_BetaflightPassthrough +``` + +At some point at the end of the build you will be asked to select some configuration between different manufacturers and products. +This sets parameters to provision a unified software binary with information about the device hardware, e.g. if the device has a power amplifier, diversity, etc. . + +When you reach that point, this indicates that everything did work. You can abort with Ctrl-C and Enter now. + +### Finding the right configuration for your target + +This is the most tricky and obscure part of the ELRS project. +Browsing through the `platformio.ini` file already gives hints about the correct environment, but typically you need to look into the [targets](https://github.com/ExpressLRS/targets) and into the [devices](https://github.com/ExpressLRS/ExpressLRS-Configurator/tree/master/devices) to back-track what the configurator would select for your device. +Another option is to look into the logs of the ELRS Configurator after it flashed your device. You should find the call to pio together with the arguments there. + +### Flashing + +When you select `--target upload` and provide an `--upload-port`, pio will flash the device as the final step of the build, again asking you about manufacturer / device. Under the hood pio then invokes [esptool](https://github.com/espressif/esptool). + +``` +pio run --target upload --environment Unified_ESP32_900_RX_via_BetaflightPassthrough --upload-port /dev/ttyUSB0