diff --git a/README.md b/README.md index 63adf6ba..73e05aec 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,32 @@ # PER Component Firmware Projects + [![CircleCI](https://circleci.com/gh/PurdueElectricRacing/firmware/tree/master.svg?style=svg)](https://circleci.com/gh/PurdueElectricRacing/firmware/tree/master) - [![HitCount](http://hits.dwyl.com/PurdueElectricRacing/firmware.svg?style=flat-square)](http://hits.dwyl.com/PurdueElectricRacing/firmware) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/PurdueElectricRacing/firmware?style=flat-square) +[![HitCount](http://hits.dwyl.com/PurdueElectricRacing/firmware.svg?style=flat-square)](http://hits.dwyl.com/PurdueElectricRacing/firmware) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/PurdueElectricRacing/firmware?style=flat-square) A mega-repository full of all firmware projects, build tools, and dependencies to create firmware modules for the car. ## Directory Structure - - `/cmake` - CMake helper files for compiling common modules - - `/common` - Common firmware modules shared across the codebase - - `/source` - Firmware source code for specific MCUs on the car - - `/output` - Generated output files from compiling - - `/build` - CMake work directory (if CMake gives you errors, some can be solved by deleting this directory and trying again) - - `/.circleci` - Automated cloud build process configuration - - `/.vscode` - Visual Studio Code configuration directory +- `/cmake` - CMake helper files for compiling common modules +- `/common` - Common firmware modules shared across the codebase +- `/source` - Firmware source code for specific MCUs on the car +- `/output` - Generated output files from compiling +- `/build` - CMake work directory (if CMake gives you errors, some can be solved by deleting this directory and trying again) +- `/.circleci` - Automated cloud build process configuration +- `/.vscode` - Visual Studio Code configuration directory ## Getting Started -Before you can compile software for PER car, here are some steps you need to take to configure your system. - -1. Install [Git](https://git-scm.com/downloads): Tool for managing source code and uploading to GitHub. - - If you are on Macos, this should be preinstalled for you. To double-check this, type `git --version` into your terminal -2. Clone this repository -3. Install [Visual Studio Code](https://code.visualstudio.com/): Text editor with extensions for helping build the firmware components using CMake. -4. Initialize the git submodules in this project with the command `git submodule update --init --recursive` to download the source for the various git submodules. -5. Install the required python packages with the command `pip install -r requirements.txt`. - -6. Install [arm-none-eabi-gcc](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads): Compiler specific to ARM based targets. - - [Windows](https://developer.arm.com/-/media/Files/downloads/gnu-rm/10.3-2021.07/gcc-arm-none-eabi-10.3-2021.07win32/gcc-arm-none-eabi-10.3-2021.07-win32.exe) - - Note: You must manually add this to your path. To do so, open the start menu and select "edit the system environment variables". From here, copy the full file path of your arm-none-eabi-gcc executable into the PATH environment variable (C:\Program Files (x86)\GNU Arm Embedded Toolchain\10 2021.07\bin). Your filepath may not look exactly the same, but it should look similar to this. - - - Mac: Install the required compiler using [homebrew](https://brew.sh/): `brew install gcc-arm-embedded` - - Linux - Find it yourself -7. Install [OpenOCD v0.11.0-3](https://github.com/xpack-dev-tools/openocd-xpack/releases/tag/v0.11.0-3/): Open Source On-Chip Debugger used to help GDB debug your code on a STM32 processor. - - It is extremely important that you install this version of openocd or else you might run into issues with debugging - - Installation Instructions [here](https://xpack.github.io/openocd/install/). Again, use v0.11.0-3 as linked above. - - If you are on a Mac, you must install the latest version of OpenOcd (v12), or you will run into issues while debugging STM32F7 microcontrollers. To install, simply run `brew install openocd` -8. Install [CMake](https://cmake.org/install/): Build system generator. This takes care of making all of the build files needed to compile the project. - - On some Mac OS versions, CMake will install as a GUI only, follow the `Tools > Install Command Line Tools` tip inside CMake to fix this -9. Install [Ninja](https://ninja-build.org/): Small & fast build system used by CMake - - On Windows, you must add this to your path environment variable. This time, use the filepath to ninja.exe - - On Macos, check this [link](https://discussions.apple.com/thread/254226896?sortBy=best) -10. Install [STLink Drivers](https://www.st.com/en/development-tools/stsw-link009.html) Windows drivers for STM32 debugging probe - - [Alternate open-source drivers for all platforms](https://github.com/stlink-org/stlink) + +Before you can compile software for PER car, here are some steps you need to take to configure your system. Detailed tool install and setup instructions can be found [here](setup.md). + +- Git +- VSCode +- ARM C Compiler +- OpenOCD +- CMake +- Ninja +- ST-Link + + ## Building Firmware Components ### CMake Extension + VSCode has a recommended CMake extension. This extension is configured throught the bottom ribbon of VSCode where you can select the `GCC for arm-none-eabi` toolchain and specific build targets. The CMake tab has buttons for building specifc firmware components and libraries. ### Python build script @@ -82,34 +70,41 @@ VSCode has a recommended CMake extension. This extension is configured throught ``` python3 per_build.py ``` + > This command is a thin wrapper around CMake to build all of the components which will be placed in a newly created `output` folder. Running `python3 per_build.py --help` will give you more options for building components. ## Debugging on Hardware -In order to begin flashing, executing, or debugging your code, you need to connect to a STM32 device using an STLink. You need to install the latest STLink drivers as mentionted in the getting started section. VSCode has a "Cortex-Debug" extension that we use for connecting to the STM32 devices. + +In order to begin flashing, executing, or debugging your code, you need to connect to a STM32 device using an STLink. You need to install the latest STLink drivers as mentionted in the getting started section. VSCode has a ["Cortex-Debug" extension](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) that we use for connecting to the STM32 devices. The "Run and Debug" window will allow for you to upload code to any firmware component which has a configuration in the `.vscode/launch.json` file. ## Build Bootloader Components -Because there are many bootloader components to build and they only need to be re-built every now and again, building the bootloaders is disabled by default. In order to enable building the bootloaders, you need to edit the CMake cache to set the "BOOTLOADER_BUILD" option to "ON". This can be done inside VSCode using the "Edit CMake Cahce (UI)" command. This needs to be disabled if you want to debug just your application code, as the applications will be built using the bootloader linker script. Notice that a new filename is used for the bootloader .hex and .elf files with the prefix "BL_". + +Because there are many bootloader components to build and they only need to be re-built every now and again, building the bootloaders is disabled by default. In order to enable building the bootloaders, you need to edit the CMake cache to set the "BOOTLOADER*BUILD" option to "ON". This can be done inside VSCode using the "Edit CMake Cahce (UI)" command. This needs to be disabled if you want to debug just your application code, as the applications will be built using the bootloader linker script. Notice that a new filename is used for the bootloader .hex and .elf files with the prefix "BL*". ## CircleCI Integration + Each pull request into the master branch will be automatically built using [CircleCI](https://app.circleci.com/pipelines/github/PurdueElectricRacing/firmware?filter=all). This build needs to pass in order for the pull request to be merged. It is important to keep the build system and docker image up to date. Future work can be put in to add software unit tests and have those block merges as well! This is an attempt at making sure that all code is able to build when pushed to the master branch. In order to update the docker image being used by CircleCI to build the firmware components you must make the necessacary changes to the Dockerfile so the firmware is able to build completley. The docker image is hosted by DockerHub, you will need to create an account there before you can push a new image. After the changes have been made to the Dockerfile, build the docker image with a tag by running -``` + +```bash docker image build . -t /per_firmware:latest ``` You can then push that to docker hub with -``` + +```bash docker push /per_firmware:latest ``` Make sure that image tag is being referenced in the `.circleci/config.yaml`: -``` + +```bash docker: - image: /per_firmware:latest ``` diff --git a/setup.md b/setup.md new file mode 100644 index 00000000..f0defec6 --- /dev/null +++ b/setup.md @@ -0,0 +1,61 @@ +1. Package Manager - A tool to help you easily install the other tools. + + - Windows users should install [MSYS2](https://www.msys2.org/): `winget install MSYS2.MSYS2`. + - MacOS users should install [Homebrew](https://brew.sh/). + +2. Add your package manager's `bin/` directory to your environment path variable to make your tools accessible. Note that your install location may vary. + + - Windows: Add `C:\msys64\usr\bin`. Check this [link](https://stackoverflow.com/questions/5733220/how-do-i-add-the-mingw-bin-directory-to-my-system-path) for help with the process. + - MacOS: Add `/opt/homebrew/bin`. Check this [link](https://stackoverflow.com/questions/35677031/adding-homebrew-to-path) for help with the process. + +3. Install [Git](https://git-scm.com/downloads): Tool for managing source code and uploading to GitHub. + + - Windows: `pacman -S git`. + - MacOS: this should be preinstalled for you. To double-check this, type `git --version` into your terminal. Otherwise, install with `brew install git`. + +4. Clone this repository with the following command: + +```bash +git clone https://github.com/PurdueElectricRacing/firmware.git +``` + +5. Install [Visual Studio Code](https://code.visualstudio.com/): Text editor with extensions for helping build the firmware components using CMake. + +6. Initialize the git submodules in this project with the following command to download the source for the various git submodules: `git submodule update --init --recursive`. + + - This command needs to be run in the base folder of the cloned repository and may take a few minutes to complete. + +7. Install the required python packages with the following command: `pip install -r requirements.txt`. + + - Newer MacOS systems come with python3, you can try using `pip3` instead of `pip`. + +8. Install [arm-none-eabi-gcc](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads): Compiler specific to ARM based targets. + + - Windows: `pacman -S mingw-w64-x86_64-arm-none-eabi-gcc`. + - MacOS: `brew install --cask gcc-arm-embedded`. + + +9. Install [OpenOCD v0.11.0-3](https://github.com/xpack-dev-tools/openocd-xpack/releases/tag/v0.11.0-3/): Open Source On-Chip Debugger used to help GDB debug your code on a STM32 processor. + + - Windows: `pacman -S mingw-w64-x86_64-openocd`. + + + - MacOS: `brew install openocd`. + + +10. Install [CMake](https://cmake.org/install/): Build system generator. This takes care of making all of the build files needed to compile the project. + + - Windows: `pacman -S mingw-w64-x86_64-cmake`. + - MacOS: `brew install cmake`. + + +11. Install [Ninja](https://ninja-build.org/): Small & fast build system used by CMake. + + - Windows: `pacman -S mingw-w64-x86_64-ninja`. + - MacOS: `brew install ninja`. + +12. Install [STLink Drivers](https://www.st.com/en/development-tools/stsw-link009.html) Windows drivers for STM32 debugging probe. + - Windows: `pacman -S mingw-w64-x86_64-stlink`. + - MacOS, use `brew install stlink`.