This repository holds all the code written by UW Orbital's firmware team.
This section will explain how to set up the repo, and how to build, flash, and debug the code.
-
Download HALCoGen: https://www.ti.com/tool/HALCOGEN#downloads
- This will be used for configuring the HAL. Unfortunately, the tool is only available on Windows.
-
Download UniFlash: https://www.ti.com/tool/UNIFLASH#downloads
- This will be used for flashing the RM46.
-
Download Code Composer Studio (CCS): https://www.ti.com/tool/CCSTUDIO
- This will be used for debugging.
-
Download WSL2: https://learn.microsoft.com/en-us/windows/wsl/install
-
In WSL2, run the following:
sudo apt-get update sudo apt-get install build-essential
-
Choose the environment where you'll be running
git commit
(either WSL2 or the host). In that environment, install Python 3.8+ and pip if they're not already installed. Then, run the following in the OBC-firmware directory:pip install -r requirements.txt # You may want to create a Python virtual env before this pre-commit install
- You may receive a message in yellow saying where pre-commit.exe was installed and that you need to add it to PATH
- To do this go to View advanced System settings -> Environment Variables -> Path -> Edit and click new to paste the path to where pre-commit.exe is installed into here. You may need to restart after doing this for the changes to take place.
- Once your PATH is set up and pre-commit is installed you can use
pre-commit run --all-files
to format all of your files before committing Note: pre-commit is used to format your code whenever you make a commit.
- You may receive a message in yellow saying where pre-commit.exe was installed and that you need to add it to PATH
You'll be using WSL2 primarily for building the firmware and running tests.
Install required build tools (CMake, Make, gcc)
brew install cmake
brew install make
brew install gcc
Install Python 3.8+ and pip if they're not already installed, then run the following commands in the OBC-firmware directory:
pip install -r requirements.txt # You may want to create a Python virtual env before this
pre-commit install
Download UniFlash: https://www.ti.com/tool/UNIFLASH#downloads
Download Code Composer Studio (CCS): https://www.ti.com/tool/CCSTUDIO
Install required build tools (CMake, Make, gcc)
sudo apt-get update
sudo apt-get install build-essential
Download UniFlash: https://www.ti.com/tool/UNIFLASH#downloads
Download Code Composer Studio (CCS): https://www.ti.com/tool/CCSTUDIO
Install Python 3.8+ and pip if they're not already installed, then run the following commands in the OBC-firmware directory:
pip install -r requirements.txt # You may want to create a Python virtual env before this
pre-commit install
To clone this project and pull all required submodules, run the following:
git clone git@github.com:UWOrbital/OBC-firmware.git
From the top-level directory, run the following to build the OBC firmware.
mkdir build_arm && cd build_arm
cmake .. -DCMAKE_BUILD_TYPE=OBC
cmake --build .
Take a look at cmake/fw_build_options.cmake
to see the available build options.
From the top-level directory, run the following to build the ground station. Currently, the ground station is only supported on Windows.
mkdir build_gs && cd build_gs
cmake .. -DCMAKE_BUILD_TYPE=GS
cmake --build .
From the top-level directory, run the following to build and run the tests.
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Test
cmake --build .
ctest --verbose
To flash the RM46 (our microcontroller), we use Uniflash. Open Uniflash and select the appropriate device and connection.
- Device = LAUNCHXL2-RM46
- Connection = Texas Instruments XDS110 USB Debug Probe
- Device = RM46L852
- Connection = Texas Instruments XDS110 USB Debug Probe
Then, click Start
to begin a session. Select the OBC-firmware.out
executable that you built (located in the build_arm/
directory) and click Load Image
. This will begin the flash process.
We use Code Composer Studio for debugging the firmware. TODO: Write a tutorial on how to use CCS.
- Make sure you're added as a member to the UW Orbital organization on GitHub.
- Create a feature branch for whatever task you're working on.
- Our branch naming scheme is
<developer_name>/<feature_description>
.- Example:
danielg/implement-random-device-driver
- Example:
- Our branch naming scheme is
- Make a PR.
- For the PR description, make sure to fill in all the required details in the generated template.
- Add at least 3 PR reviewers, including 1 firmware lead. When a PR is created, PR stats are added as a comment. You can use these stats to choose reviewers. Send a message in the #pr channel on Discord to notify the reviewers of your PR.
- Make any requested changes and merge your branch onto main once the PR is approved.
Variable and function names should be descriptive enough to understand even without comments. Comments are needed to describe any complicated logic. You may use //
or /* */
for single line comments.
Function comments should exist in the .h file. For static functions, they should exist in the .c file. Function comments should follow the format shown below:
/**
* @brief Adds two numbers together
*
* @param num1 - The first number to add.
* @param num2 - The second number to add.
* @return Returns the sum of the two numbers.
*/
uint8_t addNumbers(uint8_t num1, uint8_t num2);
- File comments are not required
We use #pragma once
instead of include guards.
variableNames
in camelCasefunctionNames()
in camelCase#define MACRO_NAME
in CAPITAL_SNAKE_CASEfile_names
in snake_casetype_defs
in snake_case with _t suffix- Ex:
typedef struct { int a; int b; } struct_name_t
- Ex:
- Import statements should be grouped in the following order:
- Local imports (e.g.
#include "cc1120_driver.h
) - External library imports (e.g.
#include <os_semphr.h>
) - Standard library imports (e.g.
#include <stdint.h>
)
- Local imports (e.g.
Some of these rules don't apply in certain cases. Use your better judgement. To learn more about these rules, research NASA's Power of 10.
- Avoid complex flow constructs, such as goto and recursion.
- All loops must have fixed bounds. This prevents runaway code.
- Avoid heap memory allocation.
- Use an average of two runtime assertions per function.
- Restrict the scope of data to the smallest possible.
- Check the return value of all non-void functions, or cast to void to indicate the return value is useless.
- Limit pointer use to a single dereference, and do not use function pointers.
- Compile with all possible warnings active; all warnings should then be addressed before release of the software.
- Use the preprocessor sparingly
- Restrict functions to a single printed page
This repository was developed by the members of UW Orbital, the University of Waterloo's CubeSat design team.