Firmware

This repo has been archived. It is succeeded by firmware-dev for development work, and firmware-core for flight code.

Welcome to Firmware! This repo is the main location for all code generated by the Firmware System, including drivers, frameworks, microcontroller (MCU) configurations, and testing code.

Structure

Below is the general structure of the repo. This is subject to change, but generally code should be organized as follows:

• Drivers: Code generated by STM32CubeMX or STM32CubeIDE, in order to enable low-level features and provide other core functionality for the MCUs. If you want to add a new peripheral to an MCU, follow the instructions here.
  • Common: Driver code shared by all MCUs.
  • STM32xx: Driver code specific to a family/model of MCUs.
• Manual_Tests: Programmer code to test the functionality of new features, commonly used for debugging and proofing effectiveness in pull requests (PRs). A manual test should fully compile and operate as the user specifies; additional steps should be noted in the PR.
  • common: Testing code operable on multiple MCUs. This often uses macros to adjust include statements and other code as necessary.
  • nucleo_xxxxxxx: Testing code specific to a devkit
• Projects: IDE files that separate each MCU from one another, allowing multiple projects to be hosted in the same repo.
  • STM32xxxxxxxx: Project files for a specific MCU model (ex. STM32H743ZITX)
• Src: Custom driver wrappers, feature support, and other code created by members to enable features on the MCUs.
  • common/stm32: Code that works across multiple MCU models
  • nucleo_xxxxxxx: Code that works for a specific NUCLEO development board (devkit)

Issue Reports

If you want to report a bug or other feedback on potential features, create a GitHub issue (if you're new to GitHub, follow these steps). Make sure to include:

• Steps on how to encounter the bug
• Suspected code location of the bug
• Potential fixes, if you have any ideas

You can also tag relevant people by using their @username in the issue.

Contributing

If you're planning on contributing to the Firmware repo, you can follow the IDE setup instructions to get setup with the IDE and cloning the repo (note that most documents are internal to UTAT). In a brief summary, clone this repo, open the STM32CubeIDE, and when importing projects from filesystem, select all projects in the folder except the root Firmware folder.

Writing and Merging Code

When working on code:

1. Create a new branch (likely based on the main branch) whose name is the TaskID (or other relevant name) and place all of your in progress code there. Task IDs (format is FIRM##) can be found on the Activity Tracker, and wherever you track your work on Confluence/Google Drive.
   1. Command: git checkout -b <TaskID>
2. When committing code, your commits should be in the format <TaskID>:<commit description>. Commit often!
3. When you are ready to merge your work into the main branch, restore any #include's in the IDE you made while testing to their original state. Make sure to rebase your code onto the most current main branch with the following steps:
   1. git checkout main
   2. git pull
   3. git checkout <TaskID>
   4. git pull
   5. git rebase main // Update your code to branch off the latest commit from the main branch
   6. Resolve any merge conflicts that appear, and follow Git's instructions to save these changes
   7. git push --force-with-lease // Since the history of local and remote branches are now different, a force push is necessary
4. Create a pull request (PR) to merge in your branch on GitHub. It should include the following:
   1. Title includes the TaskID
   2. Brief description on functionality that is added or fixed. If a specific GitHub issue is fixed, include the phrase "Fixes #issue-number", as this will automatically close the issue when the pull request is merged.
   3. Additional information that may be relevant to the PR
5. A repo admin will review your pull request, and may ask you to make changes; ask questions if your unsure about something or feel it can be better done another way.
6. When your branch is merged, you can optionally delete it by following these steps
   1. On GitHub, go to your pull request, and click the Delete branch button.
   2. Go to your local copy and run the following commands
      1. git checkout main
      2. git pull
      3. git branch -d <TaskID> // Delete the local branch
      4. git fetch --all --prune // This command removes the tracking for the remote branch origin/TaskID, which you deleted on GitHub
7. Start a new task!