Automate STM32 Firmware Builds with GitHub Actions and Docker Workflow

Introduction

This tutorial will guide you through the process of automating STM32 firmware builds and testing using GitHub Actions and a multi-stage Docker workflow for ARM toolchains. By the end of this tutorial, you will have a continuous integration setup that builds your firmware and runs tests automatically every time you push changes to your GitHub repository.

Prerequisites

• Basic knowledge of Git and GitHub.
• Familiarity with STM32 development and toolchains.
• A GitHub account and a repository for your STM32 project.
• Docker installed on your machine (optional for local testing).

Parts/Tools

• Docker
• GitHub Account
• STM32CubeMX (optional for project setup)
• Makefile or CMake (for building the firmware)

Steps

1. Create a Dockerfile for the ARM Toolchain:

   First, create a Dockerfile in the root of your project. This Dockerfile will set up the environment needed for building your STM32 firmware.

   FROM arm-none-eabi/gcc:latest
   
   RUN apt-get update && apt-get install -y 
       make 
       cmake 
       && rm -rf /var/lib/apt/lists/*
   
   WORKDIR /app
   COPY . /app

2. Set Up a GitHub Actions Workflow:

   Next, create a GitHub Actions workflow file in the `.github/workflows` directory of your repository.

   name: STM32 Build and Test
   
   on:
     push:
       branches:
         - main
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Check out repository
           uses: actions/checkout@v2
         
         - name: Build with Docker
           run: |
             docker build -t stm32-firmware .
             docker run stm32-firmware make

3. Configure Your Build Command:

   Ensure your Makefile or CMakeLists.txt is set up correctly to build your STM32 firmware. Here’s an example of a simple Makefile:

   TARGET = my_project
   CC = arm-none-eabi-gcc
   CFLAGS = -mcpu=cortex-m4 -mthumb
   
   all: $(TARGET).elf
   
   $(TARGET).elf: main.o
       $(CC) $(CFLAGS) -o $@ $^
   
   %.o: %.c
       $(CC) $(CFLAGS) -c $< -o $@

4. Run Tests Using Docker:

   If you have tests set up, you can run them in your Docker container:

   - name: Run Tests
     run: |
       docker run stm32-firmware make test

5. Commit and Push Your Changes:

   Now that everything is set up, commit your changes and push them to your GitHub repository. This will trigger the GitHub Actions workflow.

   git add .
   git commit -m "Set up CI for STM32 firmware"
   git push origin main

Troubleshooting

• Build Fails:

  Check the Docker logs for any errors during the build process. You can add the following line to your Docker command to enable verbose output:

  docker run -it stm32-firmware make VERBOSE=1

• Test Failures:

  If your tests fail, ensure that the test framework is correctly set up in your project, and that all dependencies are included in your Docker image.

• GitHub Actions Not Triggering:

  Ensure your workflow file is correctly named and located in the `.github/workflows` directory. Check the Actions tab in your repository for logs.

Conclusion

By following this tutorial, you have successfully set up an automated workflow for building and testing STM32 firmware using GitHub Actions and Docker. This setup not only streamlines your development process but also helps catch errors early, ensuring a smoother development experience. Feel free to customize the Dockerfile and GitHub Actions workflow to fit your specific project requirements.