stm32f1-template-project

stm32f1-template-project is a Makefile based template for stm32f1 projects.

Currently it's configured to support stm32f103c8t6 MCU found on the "Blue Pill" boards. Switching to another MCU or MCU series should be fairly straightforward.

Prerequisites

Install the following software:

ARM toolchain, stlink, and must be added to PATH (use ~/.bash_profile). Assuming everything is installed in ~/stm32/:

# add ARM toolchain path
export PATH=~/stm32/gcc-arm-none-eabi/bin:$PATH
# add stlink path
export PATH=~/stm32/stlink-install/bin:$PATH

Path to STM32CubeF1 should be also exported (use ~/.bash_profile):

# export STM32Cube
export STM32CUBE_PATH=~/stm32/stm32cube

Building Project

Run

make

to build the project and create the firmware hex file.

Run

make flash

to flash MCU using st-link.

Run

make clean

To remove object and dependency files.

Run

make distclean

to remove object, dependency, and firmware files.

Note on Linker Script

Currently the Makefile uses STM32F103XB_FLASH.ld, which defines 128K flash size. However, stm32f103c8t6 has 64K flash. Make sure firmware fits MCU memory.

Hardware Documentation

Continuous Integration (CI)

The project pipeline consists of the following stages:

lint for performing style checks on source and documentation files;
analyze to run static code analysis on project source files;
build to build the project;

Lint Stage

The job of the lint is to make sure that source code and documentation formatting remains consistent. It contains the following jobs:

Markdown Lint

markdown lint job checks all markdown files with markdownlint-cli.

It performs very similar checks to what VSCode markdownlint does. As long as you use the default settings and have no issues with your markdown in VSCode you should be fine.

Clang-format Check

This job makes sure all C source and headers files have consistent formatting according to the coding style provided in .clang-format configuration file in the root directory of the project.

You can reformat your files with Clang-Format VSCode extension. You should have clang-format binary installed in your system.

The default settings should be just fine.

NOTE: clang-format version should be 8.0.0 or above. Please don't use clang-format that comes from the Ubuntu 18.04 packages repository as it contains a severely outdated version.

See Step 3: Install Clang-Format for Ubuntu 18.04 installation instructions.

Install 8 version of clang-format from https://apt.llvm.org instead.

Analyze Stage

This stage contains a single job to run static code analysis on source files listed in the SRCS variable of the Makefile.

The cppcheck job uses cppcheck with the following options:

cppcheck --enable=all --error-exitcode=1

Build Stage

The build stage contans a single job to build the project. It outputs the firmware binary in the Intel HEX format with the following name:

$CI_PROJECT_NAME-$CI_COMMIT_REF_NAME-$CI_COMMIT_SHORT_SHA.hex

Configuring GitLab Runner on Ubuntu 18.04

Step 1: Install And Register GitLab Runner

curl -L https://packages.gitlab.com/\
install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
cat <<EOF | sudo tee /etc/apt/preferences.d/pin-gitlab-runner.pref
Explanation: Prefer GitLab provided packages over the Debian native ones
Package: gitlab-runner
Pin: origin packages.gitlab.com
Pin-Priority: 1001
EOF
sudo apt-get install gitlab-runner
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner register

Set tags to: "stm32, linux" when registering the runner.

Step 2: Install Markdown Linter

sudo npm install -g markdownlint-cli

Step 3: Install Clang-Format

This installs clang-format from https://apt.llvm.org.

wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
sudo add-apt-repository\
'deb http://apt.llvm.org/bionic/ llvm-toolchain-bionic-8 main'
sudo apt install clang-format-8
sudo ln -s /usr/bin/clang-format-8 /usr/bin/clang-format

Step 4: Install Cppcheck

sudo apt install cppcheck

Step 5: Install ARM Toolchain

sudo su -l gitlab-runner
mkdir -p stm32 && cd stm32
wget --content-disposition https://developer.arm.com/-/media/Files/downloads/gnu-rm/8-2019q3/RC1.1/gcc-arm-none-eabi-8-2019-q3-update-linux.tar.bz2?revision=c34d758a-be0c-476e-a2de-af8c6e16a8a2?product=GNU%20Arm%20Embedded%20Toolchain,64-bit,,Linux,8-2019-q3-update
tar xjf gcc-arm-none-eabi-8-2019-q3-update-linux.tar.bz2
ln -s gcc-arm-none-eabi-8-2019-q3-update gcc-arm-none-eabi

Step 6: Install STM32CubeF1

Note: adjust this section if you use another MCU series.

Download STM32CubeF1 and copy en.stm32cubef1.zip to /home/gitlab-runner/stm32.

unzip en.stm32cubef1.zip
ln -s STM32Cube_FW_F1_V1.8.0 stm32cube

Step 7: Set up Environment Variables

cat <<EOF | tee -a /home/gitlab-runner/.profile
# set PATH to gcc-arm-none-eabi if it exists
if [ -d "\$HOME/stm32/gcc-arm-none-eabi/bin" ] ; then
    PATH="\$HOME/stm32/gcc-arm-none-eabi/bin:\$PATH"
fi

# set PATH to stm32cube if it exists
if [ -d "\$HOME/stm32/stm32cube" ] ; then
    STM32CUBE_PATH="\$HOME/stm32/stm32cube"
    export STM32CUBE_PATH
fi
EOF

r2axz / stm32f1-template-project