README_TEMPLATE.md

{PROJECT_NAME}

Tools Setup ✔️

At a minium you will need the ARM GNU GCC Toolchain, Make and CMake to compile the source and generate executable artifacts.

• ARM GNU GCC Toolchain - 10-2020-q4-major - Other versions can be used but the current source is actively developed and tested using the 10-2020-q4-major release
• Make - Make is shipped with Linux and should already be present on the developers system. If the developer is running Windows they can either use WSL to run a Linux instance or install Make on Windows via MinGW
• CMake

To flash and debug the target this project uses a couple of different tools. PyOCD or Segger JLink can be used as the programming/debugging medium, and a VScode extension called Cortex-Debug gives a user interface within VScode for stepping through the source, settings breakpoints and viewing registers/variables within the target.

• PyOCD
• JLink
• VScode
• ARM Developer Extension Pack for VScode

NOTE: After installing your desired debug toolset, please ensure the chosen application is accessible from the command line (pyocd or JLinkExe)

To write and execute unit tests on the firmware source, you will need to install the Ceedling unit test framework and the Python package gcovr to generate Cobertura html reports. Ceedling is a Ruby Gem, so Ruby must first be installed on your system. GCC and Make are also needed. If the developer is on Windows, you can find install instructions above.

• Ruby
  • Windows - RubyInstaller 2.7.3-1
  • Linux - sudo apt-get install ruby
• Ceedling
• Python
• gcovr
  • python -m pip install gcovr

Adding new source files 📁

To add a new source file to the src/ folder: From the root directory, use the Ceedling command below to create a new source .c and .h file. This will also create a unit test file in the test/ folder for you.

// Don't include a .c or .h in the filename
$ ceedling module:create[FILENAME]

Compiling, Flashing & Testing ✨

After a fresh clone, the setup scripts can be used to initialize the project. Passing release as an argument will generate a release build. Otherwise a debug build is generated.

Windows

setup.ps1

Linux

./setup.sh

Once a project has been initialized, the following commands should be ran from the build/ folder

To clean the working directory:

make clean

To compile the source:

make -j8

To erase the connected target:

make erase

To flash the connected target:

make flash

To execute unit tests:

make test

Source Documentation Style 📃

Read more about the Source documentation style here

Develop Strategy 📖

Read more about the Git develop strategy used here