Getting started with the development environment for the Avionics codebase
The Container Environment section will go over setting up the tools for compiling firmware, the Writing and Compiling Firmware section will go over compiling the firmware, and the Flashing Programs to the Microcontroller section will go over writing compiled code to hardware.
Avionics distributes a container which contains all the tools for compiling our firmware. Some of the development tools we use for firmware development are a mild pain to install (particularly for beginners), so using the container is recommended for quick set up.
If you have tried out the container and have problems given your setup, and you really want to install yourself, go ahead. This is not recommended unless you are well acquainted with installation of compilers, etc.
To use the container environment, you will need to install the Docker or Podman first. Podman is the fully open source alternative to Docker, and they share the same commands format. Either can be used, although most of this tutorial will use Podman because it is easier to use on Windows.
If on Linux, there's too much variety to put anything here. I'm sure someone in avionics will want to help! Podman is very easy to use on Fedora and works out of the box.
If on Mac, this is all currently untested.
On Windows, you the recommended procedure is to install Windows Subsystem for Linux (WSL) and run Podman within it.
Since WSL is a non-standard linux environment that lacks of some important syscalls and processes, Docker cannot be run on WSL without some hassles. Podman has been tested on WSL, and you should follows the instruction below.
If your Windows 10 is Home version, you might not be able to enable Hyper-V. You should upgrade to Windows 10 Pro, or just use the free educational version from the school: https://software.berkeley.edu/microsoft-operating-system
Follow the instruction on https://docs.microsoft.com/en-us/windows/wsl/install-win10. You should install WSL 2. This tutorial is based on OpenSUSE, but it is possible to use other distros.
Once you finish, install Podman by running
Then, run the following instruction to create and modify the config file to make it run on WSL:
Then, use an editor of your choice, open /etc/containers/containers.conf with sudo :
Uncomment the line with events_logger, then change the value to file.
Uncomment the line with cgroup-manager, then change the value to cgroupfs.
You should be able to run the docker file right now. Note that you must run Podman with sudo, or you won't be able to do anything. If you are getting No CNI Configuration file error, do the following steps:
Run sudo podman network create. It should give you a filename.
In the command you used to run docker, add --net <config-name> after podman run. <config-name> is the filename you got from the first step.
The toolchains repo here has a readme with additonal information about the development environment.
First download the toolchain container image.
Then, create a directory where the files in the container will be stored.
The location of this directory can be viewed with :
Finally, create the container
Once the container is setup, it can be started with:
You can enter the toolbox to a bash prompt with the below. This is where you will be actually running commands to use the compiler, etc.
Finally, once the container bash prompt is exited with exit, the container can be stopped with
An alternate way to transfer files is using the Visual Studio Code editor. This may be convenient if you already use VS Code, and may be a method that works if this does not. See the VS Code & Containers section.
To copy a file from the image to the host system (your normal operating system), you need to first get the mount point of your workspace by running
where star-workspace is the volume name. If you use another volume name, you need to change the command accordingly. You can save it to a environment variable to avoid copying the long path every time.
Since the path is usually only accessible with root privilege, you need to copy it to a place that you can access without sudo, like your home directory:
Then, if on Windows, open Windows Explorer, type in \\wsl$ in address bar. For every distros you install, you can see a folder with the same name as the distros in this folder. Go to the distro folder that you use to run Podman, and go to the path you copy the file to in the last step, like home/<user-name>. You should be able to see the file you want in that directory, and you can copy and paste it to anywhere you want in your Windows file system.
If not on Windows, simply open a terminal and go to ~. The file will be there.
To setup, install the Remote Containers extension in VS Code.
Then, go to the "Remote Explorer" tab on the left bar of VS Code, right click on the container you created in the previous step and click attach to start a VS Code instance in the container. From here you should be able to open a terminal inside the container by going to Terminal->New Terminal and interact with the filesystem through VS Code and clone stuff, open folders, etc.
In this section we detail how to compile code into binaries which can be written onto the hardware.
'Firmware' is the code which runs on the hardware, named so because it is 'closer to the hardware' than normal desktop software.
We use MbedOS for libraries and a lot of the support code needed. The tools needed to run mbed are all included in the container. Run the commands below from the container prompt.
For most cases, you will only need the Developing STAR firmware projects section.
For documentation on the Mbed API, look at the official docs here. If you don't find a library for what you want there, look at community built libraries by searching using the search box in the upper right corner.
For more detailed documentation on Mbed Command Line Interface (CLI), look at the official docs here.
While the mbed utilities can be used directly, most often in STAR we iterate on existing STAR projects. Therefore we have abstracted away most of the mbed commands using Makefiles. Note that the specific build system can vary slightly from git repository (repo) to repository, so make sure to check the Readme of the specific project you are working on.
If you are unfamiliar with the Git version control system, check the Git Tutorial out before continuing.
First clone the desired repository from within the container, e.g.
Then from within the repository, clone the submodules and run mbed deploy
Finally, compile with a command like
Check the repository Readme for details on the command to run to compile. The output, the binaries to flash to the microcontroller, will be put in the output folder.
To create a new project called mbed_project, run the following:
To compile a project, run the following from within the project folder
The target, NUCLEO_F401RE is a development board that has the STM32F401RET6 microcontroller on board, the same microcontroller unit (MCU) that we use. The toolchain selects which compiler we are using.
This should give you something like the following if it compiled successfully.
Find libraries by searching in the search bar on mbed's website. Then, once on a library's page, look at the box titled "Repository toolbox" and select the down arrow on the yellow "Import into Compiler" button.
Then select "Import with mbed CLI" and copy the command listed.
The command should be of the form mbed add <project link>. Run this command from command line inside your mbed project.
'Flashing' a program onto a microcontroller means to write the compiled code onto the microcontroller to be run when the microcontroller is powered off and back on.
As of right now, usb-detection and programming through the container is not working. Instead install and use a utility on the host system.
Windows: Download and install the St-Link Utility from the file below. To use, first File > Open file the binary of the program output by mbed compile. Then Target > Connect to the board, and Target > Program & Verify
Linux: Install the stlink package from the package manager if available or compile from source here.
To use, open stlink-gui and perform similar steps to the windows version to flash.
Alternatively, use st-info --probe to search for programmers and st-flash write $binary_output_file 0x8000000 to flash.
