brianoh1979 / firmware

Firmware projects, shared libraries, and code generation for PER car

PER Component Firmware Projects

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

Getting Started

Before you can compile software for PER car, here are some steps you need to take to configure your system.

Install Software

1. Initialize the git submodules in this project with the command git submodule update --init --recursive to download the source for the various git submodules.

2. Install the required python packages with the command pip install -r requirements.txt.

3. Install arm-none-eabi-gcc: Compiler specific to ARM based targets.

   • Windows
   • Mac
   • Linux - Find it yourself

4. Install OpenOCD 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, especially on MacOS
   • Installation Instructions here. Again, use v0.11.0-3 as linked above.

5. Install CMake: 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

6. Install Ninja: Small & fast build system used by CMake

7. Install Git: Tool for managing source code and uploading to GitHub.

8. Install Visual Studio Code: Text editor with extensions for helping build the firmware components using CMake.

9. Install STLink Drivers Windows drivers for STM32 debugging probe

   • Alternate open-source drivers for all platforms

Setup VSCode

1. Create a /.vscode/settings.json file
2. Configure two cortex-debug extension settings (make sure to install the recommended VSCode extensions first)
   • "cortex-debug.openocdPath": "<path to openocd executable>"
   • "cortex-debug.gdbPath": "<path to arm-none-eabi-gdb executable>"

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

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.

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_".

CircleCI Integration

Each pull request into the master branch will be automatically built using CircleCI. 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

docker image build . -t <docker hub username>/per_firmware:latest

You can then push that to docker hub with

docker push <docker hub username>/per_firmware:latest

Make sure that image tag is being referenced in the .circleci/config.yaml:

    docker:
      - image: <docker hub username>/per_firmware:latest