Development Environment Setup
Visual Studio Code
Install it from https://code.visualstudio.com/Download.
Python
Install the latest Python from https://www.python.org/downloads/. We require version 3.13 or newer. When prompted, add Python to your PATH.
Verify its installation by running
python --version # on windows
python3 --version # on Linux/Mac
PlatformIO
PlatformIO is a VS Code extension which provides cross-platform support for embedded-systems development.
Follow the PlatformIO IDE installation instructions at https://platformio.org/platformio-ide.
Install the "Native" platform dependencies https://docs.platformio.org/en/latest/platforms/native.html.
Optional: You may also install PlatformIO Core for CLI support.
Note on C++ Extensions
The PlatformIO VS Code extension will automatically install the C/C++ extension to provide language support.
Prior to 2025-26, Mac Formula used Clangd for C++ language support. You should disable/uninstall the Clangd extension when working on racecar
.
STM32CubeMX
CubeMX is a program which generates configuration code for our microcontrollers.
-
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.
-
Download and install STM32CubeMX version 6.15.0 from https://www.st.com/en/development-tools/stm32cubemx.html.
Warning
You must install exactly version 6.15.0 (not even 6.15.1). Using a different version than your team members will cause conflicts when opening files.
Git & GitHub
-
Create a GitHub account https://github.com/. As a student, you should join GitHub Education https://github.com/education to get benefits like increased storage and free GitHub Actions.
-
Install Git from https://git-scm.com/downloads.
Git Bash (for Windows only)
Git Bash is an alternative terminal shell which is installed alongside 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 must use Git Bash as your shell when developing in racecar/
. (i.e. not Command Prompt or Powershell).
In VS Code, you can change your default shell by pressing F1 and entering >Terminal: Select Default Profile
and selecting Git Bash.
Clone the racecar
Repository
Find our repository on GitHub https://github.com/macformula/racecar.
Copy the repository address:
Navigate to a directory where you want to hold the racecar
repo, then run
git clone --recurse-submodules https://github.com/macformula/racecar.git
Choosing a folder
Good locations are short and memorable. Consider C:\formula\
on Windows or ~/formula
on Linux/Mac.
Do not use a directory that has spaces anywhere in its path, such as C:\Users\My Files\Formula
. Spaces wreak havoc on automated scripts.
Automated Backups
Never put Git repo somehwere that is automatically backed-up by another program (ex. OneDrive).
Git is itself a backup system, so it will fight with OneDrive and corrupt your local repository.
Pre-Commit
We use pre-commit to run formatting and code checks before the code is pushed.
pip install pre-commit
Now go to the racecar/
folder and run
pre-commit install
Optional VS Code Extensions
These extensions are not required but will improve your development experience.
- Git Graph https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph
- GitLens https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens
You should now check out Using VS Code and Platformio.