Skip to content
This repository was archived by the owner on Sep 17, 2023. It is now read-only.

Getting Started

Jump to bottom
Samuel Dewan edited this page Oct 5, 2021 · 2 revisions

Getting the Required Tools

There are a number of software tools required to work on the avionics firmware. We have a wiki page that describes how to get them.

Cloning the CU InSpace Avionics Software Repository

We collaborate on our avionics software using this git repository. We have a guide to using git which you can find here. The rest of this section is a higher level overview of how to clone the project and a few graphical interface options for git. I highly recommend reading through the git guide for much more detailed information on how to use git to contribute the CU InSpace code. If you are already familiar with git go ahead and skip this section.

The best way to clone the repository is to use git directly, which is as simple as running git clone https://github.com/CarletonURocketry/avionics-software.git. Of course running a command isn't necessarily all that simple depending on your operating system. If you are running Linux or macOS using git from the command line is a good approach. On Windows you may need to use git from inside of WSL or install git for Windows to get the git bash command line.

You can clone the repository wherever you would like on your computer. The above command will create a folder called avionics-software which contains our repository. If you are running Windows cloning the repository to a location inside of the WSL filesystem can make building the project a little bit faster, but our tools will all still work whether you clone inside WSL or not.

For those who are less comfortable with a command line interface, this is a great opportunity to practice! If you really insist on having a graphical interface for git there are a few options though. First off, many IDEs have git integration build in. If you are using and IDE it is a very good idea to check is documentation to see if it has a convenient way of managing git repositories built in. If you aren't using your IDE or your IDE does not have good git support you may want check out GitHub Desktop which is a graphical git client that also has many GitHub specific features.

Compiling, Uploading and Debugging

Once you have the toolchain installed and the repository cloned the next step is to compile the avionics firmware. We have a wiki page here that describes that process in detail as well as discussing how to upload the compiled firmware to a board and perform on chip debugging.

Working on Changes

Before starting to write any code for CU InSpace, please read our coding standard.

We have a guide on the workflow for making changes the CU InSpace code here. In summary, we use issues on our GitHub repo to track who is working on what, we create a new branch for each feature we work on and we create pull request so that features can be reviewed before they are merged into mainline. We also have a small continuous integration pipeline on GitHub which makes sure the project builds without errors and runs our unit tests for every pull request or commit.

One thing that is worth mentioning explicitly here is that things work a lot more smoothly if you ensure that your code compiles cleanly without any warnings before you push it the GitHub. Ideally, every commit should compile without warnings and work properly.

VS Code

Since Visual Studio Code is rather popular these days we have a VS Code workspace configuration that allows you to easily build and debug our project from within VS Code.

There is a step by step guide to setting up VS Code on Windows with WSL, but if you are already familiar with VS Code you can skip that and download just an archive here which will unpack to reveal a folder called vscode. If you move this folder into your local copy of the repository and rename it .vscode VS Code will use the configuration when you open the repository folder. There are instructions below on how to modify the VS Code configuration files if you are not using VS Code on Windows with WSL.

Step by Step Guide to Setting up VS Code for WSL

There are a few extensions required to get everything working, and some hoops to jump through if you are using Windows since you will need to configure VS Code to run the project inside of the Windows Subsystem for Linux.

  1. Install the extension named "Remote - WSL" by Microsoft. You can search for and install extension from the extension tab, which looks like four boxes, one of which is separated from the others.
  2. Open your WSL installation as a remote in VS Code. To do this, click on the green button with two triangle on it in the bottom left corner of the VS Code window. In the resulting menu, choose "New WSL Window using Distro..." then select the WSL distribution you use from the resulting list (if you don't have any WSL distributions you need to follow our documentation on install the toolchain before continuing).
  3. In the new VS Code Windows that opens, install the "C/C++" extension by Microsoft and install the "Cortex-Debug" extension marus25. There are many other available extensions which could be useful, one that is not required but that you might want to check out is Microsoft's "C/C++ Extension Pack".
  4. Open the CU InSpace avionics software repository from within VS Code. This can be done using the "Open Folder..." option in the "File" menu which will present a dialog that lets you choose a folder. If you have cloned the repository inside your home folder within WSL there should be an "avionics-software" option visible, which is the folder you want to open. If you cloned the repository somewhere else you will need to navigate to it, remember that your Windows C: drive can be found from within WSL at /mnt/c. If you have not yet cloned the repository follow the instructions from above, you can open a WSL terminal from within VS Code using the "New Terminal" option in the "Terminal" menu and run the git clone command from there.
  5. Now we will download the archive from here which contains our VS Code configuration, unpack it and move the resulting folder inside the repository with the name ".vscode". This will take a few steps:
    • Open a WSL terminal inside VS Code by choosing "New Terminal" from the "Terminal" menu. Then this terminal opens it should already be in the repository directory.
    • Download the archive that contains our workspace configuration using the command wget https://github.com/CarletonURocketry/avionics-software/wiki/Other/cuinspace-vscode.tar.gz.
    • Unpack the archive with the command tar xf cuinspace-vscode.tar.gz.
    • Delete the archive with the command rm cuinspace-vscode.tar.gz since we don't need it any more.
    • Rename the extracted vscode folder to .vscode by running mv vscode .vscode. Sometimes VS Code can get in the way of this command. If you see an error along the lines of mv: cannot move 'vscode' to '.vscode': Permission denied you will need to close VS Code completely, then open a separate WSL terminal, navigate to the the avionics software repository (possibly cd avionics-software), and run the mv command from above.

After completing the above step you should be able to build the project from within VS Code by using clicking "Run Build Task" in the "Terminal" menu. You can also clean the project by clicking "Run Task..." in the same menu then selecting "clean". You should also be able to do on-chip debugging inside of VS Code, though you may need to modify some the configuration files a little bit to match the board and debugger hardware you are using.

Modifying the VS Code Configuration Files

You will need to modify the VS Code configuration files if you are using a setup other than Windows with WSL or you want to build the avionics firmware for something other then the test variant on the revision B SAMD21 MCU board.

You can select the board and variant you wish to build for as well as the type of debugger hardware (CMSIS-DAP or J-Link) you are using with OpenOCD by changing the environment variables specified near the top of tasks.json.

If your toolchain is installed in a location other than /opt/cortex-toolchain you will need to edit compiler path in c_ccp_properties.json as well as the ARM toolchain path in launch.json. c_ccp_properties.json also has a number of include paths and preprocessor macros that you may wish to change to reflect whether you are working on code for the SAMD21 or the SAME54. In launch.json you may need to modify the serverpath field if your OpenOCD executable is something other than /mnt/c/Program Files/openocd/bin/openocd.exe and you may want to change the svdFile field to have ATSAME54P20A instead of ATSAMD21J18A if you are debugging on the Big MCU board (the SVD file is used to give you a little window that you can use to inspect all of the peripheral registers on the target from the debugging view).

Clone this wiki locally