This Repository stores the embedded code for our real-time telemetry system. The system is built off of an STM32F4 MCU that pulls data from the ECU and other sensors around the car and sends it in real-time to a wireless receiver, and logs it locally to an SD card. The system uses FreeRTOS to schedule telemetry-related tasks as well as ARM's CMSIS headers to interface with registers on the MCU. The mainboard includes a uBlox Neo-M9N for collecting GPS data, as well as an RFM95W for transmitting data over LoRa WAN.
The Firmware for this system is developed in WSL using Arm compilers and make files. To get started, follow the steps below.
Install WSL by opening up a Powershell terminal and running the command wsl --install -d Ubuntu. This command will set up WSL using an Ubuntu Linux distribution. It will ask to create a username and password to complete the setup. When typing the password, no characters will appear, which is normal; just enter your password. Once installed, you can access the Ubuntu terminal by searching for Ubuntu in Windows, or it will be available in VSCode once the setup is complete.
Install usbipd from the releases page using the .msi file.
Install VSCode for Windows by going to the VSCode download page and select the correct package for your system. Follow the directions in the installer.
Next, we will link VSCode to WSL using the WSL Extension. Navigate to the extensions tab in VSCode and search for WSL. VSCode has detailed instructions on how to set this up and how to open a remote connection to WSL.
Next, we will install a series of build tools that are needed to compile the firmware. Open up a WSL terminal and run the following commands:
sudo apt update
sudo apt upgrade
sudo apt install git make gcc-arm-none-eabi gdb-multiarch stlink-tools
Here is a short explanation of each of these tools:
Finally, we are ready to clone the repository. Go to the repository that you will be working on in Github. There is a large green code button near the top; click the dropdown arrow next to it and copy the HTTPS. Open a WSL terminal, you can do this by connecting VSCode to a WSL session or just searching wsl in the windows search. Run these commands to clone the repository
cd -- Make sure you are in the Linux home directory (folder)mkdir formula -- this will make a folder called formulacd formula -- this changes your current directory to the new formula foldergit clone <paste-link-from-step-6> -- You have to press ctrl + shift + v to paste in the terminal; this command actually downloads the repols -- You should see the contents of the git repo in your folder; this command lists the items in the current folderOnce you have cloned the repo, you can run the command code ./ in the top level of the repository. This will open the repository in VSCode. Once you are in VSCode, a few notifications will appear in the bottom right corner. The only one that is crucial is installing the recommended extensions.
Once you've completed these steps, you can start building and developing firmware. The best place to start will be the Microcontroller Reference Manual. Read through the section about the peripheral you are trying to work with.
In order to build the code, use Make and Makefiles. Open up an Ubuntu terminal and navigate to the project directory. Next, run the command make in the terminal. This will build the code using the instructions in the makefile. Make will only build files you change; if you would like to rebuild the whole project, run the command make clean before running make.
In order to use the WSL environment, you'll have to pass the target board/debugger into WSL. This involves using the usbipd tool that we installed earlier.
If you are on Windows, open up Powershell as an administrator and run usbipd list. This will list all of your current USB devices on your computer. Look for the STMircroelectronics device and note the BusID in the left column.
If you have never connected this board/debugger to WSL before, or if the ST Link device doesn't say Shared in the right column of the list, run the command usbipd bind --busid <BUS_ID> replace <BUS_ID> with the ID shown in the above list command. This will share the device to WSL.
Once the device is shared, you are able to attach it to WSL by running the command usbipd attach --busid <BUS_ID> --wsl again replacing <BUS_ID> with the ID of your device. To make sure that this command worked, you are able to open a WSL terminal and run the command lsusb which should now show the STMicroelectronics device.
To debug and upload code, we use the Cortex-Debug extension. This extension uses 2 configuration files in the .vscode folder: settings.json and launch.json. Basic versions of these files are provided in the repository and can be modified if needed. You must build the code using the make command at least once before you attempt to use the Cortex-Debug configuration.
- settings.json has 3 important keys: cortex-debug.armToolchainPath, cortex-debug.gdbPath, and cortex-debug.stutilPath. All of these file paths are universal in WSL/Ubuntu and should be the same if you setup your dev enviroment by following the directions above.
- launch.json configures the debugging profile for Cortex-Debug. The default values in this file should also work well apart from two: svdFile and device. svdFile is the path to an svd file for the microcontroller that you are using and svd file tells the debugger what peripherials are at what memory addresses and allows for easier debugging. The device will need to match the microcontroller on whichever board you are debugging.Once these files are configured, go to the run and debug window on the left column in VSCode (Looks like a play button with a bug) and you should see an option called Cortex Debug. With the Cortex Debug option selected, press the green play button.
This will create a debug menu at the top of the screen to control the debug session which gives you options such as step over, step into, and step out as well as reset and end session.
At the bottom of the left column, there is also a xPeripherials option. These are the register values of the device you are debugging and are very useful to find issues.
Finally, you are able to set breakpoints by clicking the red dot next to the line number you want to place the breakpoint at. This will stop the code while it is running so that you can look at the register values.
TODO: Once finalized, this will list the peripheral connections for the Telem Mainboard for easy reference
GNU GPLv3