Skip to content

Development Environment Setup

Follow these steps to begin developing in racecar/firmware.

Tip

You can copy a command by clicking the icon

echo "Copy Me --->"

Dependencies

  1. We will use Chocolatey to install most dependencies. Go to https://chocolatey.org/install#individual and follow the instructions under "Install Chocolatey for Individual Use".

  2. Open a Command Prompt as administrator and run

    choco upgrade git msys2 make cmake -y

    Git Bash

    The Git Bash terminal shell is included when you install git. This shell emulates the Linux bash shell, allowing you to use commands like grep, ls, rm and many more on Windows.

    If you are on Windows, you need to use Git Bash as your shell when developing in racecar/. (i.e. not Command Prompt or Powershell).

    In VSCode, you can change your default shell by pressing F1 and entering >Terminal: Select Default Profile and selecting your desired shell program.

  3. Install the newest version of Python from https://www.python.org/downloads/. When installing, ensure Add python.exe to PATH is checked.

  4. Open the MSYS2 directory by searching msys2 in the Start Menu and choosing "Open file location." Run msys2.exe to open a terminal and install the GNU toolchain with

    pacman -Syuu
pacman -S mingw-w64-x86_64-toolchain

    Press Enter when prompted to "Enter a selection."

    Add the MSYS2 mingw64 binary and library directories to your PATH. These paths will be of the form

    C:\path-to-msys2\mingw64\bin
C:\path-to-msys2\mingw64\lib

  1. Set up the Kitware APT repository https://apt.kitware.com/.

    This allows apt to find new versions of CMake.

  2. In your terminal, run

    sudo apt-get update
sudo apt-get install software-properties-common python3-launchpadlib
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install git-all build-essential cmake python3.12 wget gcc-13

Arm Toolchain

Install the Arm GNU Toolchain (v13 or newer) from https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads.

  1. Find the <ARCHITECTURE> hosted cross toolchains section for your computer's architecture then download and install the AArch32 bare-metal target (arm-none-eabi).

    There are multiple downloads available in this section. Choose the installer: .exe on Windows, .tar.xz on Linux, .pkg on MacOS.

  2. Add the folder containing the binaries to your path.

Verify Installation

Check that all programs were installed and have an acceptable version.

Do not copy the # version comments.

git --version     # >= 2.40
python --version  # >= 3.10, use python3 on Linux / Mac
make --version    # >= 4.0
cmake --version   # >= 3.27
g++ --version     # >= 10
arm-none-eabi-g++ --version     # >= 13.0

Install STM32 Tools

Create an ST Account

Go to www.st.com, click on the account icon in the top right and create an account. You will need this username and password later on.

STM32CubeMX

CubeMX is a program which generates configuration code for our microcontrollers.

  1. Download version 6.12.0 from https://www.st.com/en/development-tools/stm32cubemx.html and install it. You may need to sign in with your ST account.

    Warning

    You must install this version exactly (not even 6.12.1). Using a different version will cause issues when opening files.

  2. Open the install path which contains the STM32CubeMX executable and jre/ directory. Add this directory to your PATH.

  3. Open a terminal in that directory and run CubeMX in "interactive" mode to login.

    jre/bin/java -jar STM32CubeMX.exe -i

    jre/bin/java -jar STM32CubeMX -i

  4. Wait for the program to stop printing to your terminal. Press ?+Enter to display the MX> prompt. Login with your username and password.

    login username password y

    Do not omit the y at the end!

  5. Install the STM32F7 firmware pack.

    swmgr install stm32cube_f7_1.17.2 ask

    You can close CubeMX now by typing exit.

STM32CubeProgrammer

Download and install version 2.16 or newer from https://www.st.com/en/development-tools/stm32cubeprog.html.

Clone the Repository

Navigate to a directory where you would like to hold the racecar repo (I used C:\Formula\repos). Run

git clone --recurse-submodules https://github.com/macformula/racecar.git

Install CANgen

Create a Python virtual environment for CANgen. Navigate into racecar/firmware and run.

python -m venv .env
source .env/Scripts/activate

python3 -m venv .env
source .env/bin/activate

The second command "activates" the virtual environment. You will see (.env) beside your terminal prompt when it is activated. It must be activated before building any project.

With the environment activated, change into racecar/ and install CANgen:

pip install -e scripts/cangen

The -e flag is very important. It installs CANgen as an editable package which means you won't have to reinstall when the package is changed.

You can now start developing in racecar! However, I recommend you configure your IDE with clangd, so continue to the next section.

IDE Integration

This section is optional but highly recommended.

clangd

What is clangd?

clangd is a C++ language server that provides intelligent code completion and errors by analyzing compiler commands C/C++ language server. We have configured CMake to export your most recent compilation's build commands meaning you don't need to manually configure include paths or compiler flags for each project.

Whenever you build a project with the Makefile, clangd will see the new build/compile_commands.json and immediately update your IDE's include paths. When you switch which project or platform you are developing for, simply rebuild the project and your development environment will be automatically prepared.

Download and unzip clangd-{OS}-16.0.2.zip from https://github.com/clangd/clangd/releases?q=16.0.2 under "Assets."

Place the executable somewhere on your PATH. Follow these instructions to connect it to your IDE.

Important: Create an empty file named .clangd in the firmware/ directory. This file indicates the "root" directory of the project, so it will look for compile_commands.json in firmware/build.

clangd Configuration

You may optionally configure clangd with the firmware/.clangd file. See https://clangd.llvm.org/config.

Use this configuration to help clangd find system header files.

CompileFlags:
    Add: --target=x86_64-w64-mingw64

On Mac M series chips, this configuration should be used.

CompileFlags:
    Add: --target=arm64-apple-darwin22.6.0

Additional Dependencies

gRPC

Optional Dependency

You probably don't need this.

Within the racecar repo, gRPC is only used by the SIL Client under firmware/validation/sil/. The client is used by the Raspberry Pi MCAL to interact with the HIL / SIL.

You only need gRPC if you will be working on the HIL. Otherwise, do not worry about installing it.

You will need a Unix development environment (Unix machine, WSL, or remote into the Raspberry Pi).

Go through the gRPC C++ Quickstart Guide. Build the example project.

Pre-Commit Setup

We use pre-commit hooks to run formatting and code checks before the code is pushed.

Installing Pre-Commit

  1. Install pre-commit via pip:

    pip install pre-commit

  2. Install the git hooks by running this command in the racecar directory:

    pre-commit install

    This will install the hooks so they run automatically when you use git commit.