Doc

Self-hosted runner for execution test

The CMSIS-Toolbox implements and Run and Debug Configuration for command line usage with pyOCD.

This section explains how to setup a Linux machine that runs a GitHub self-hosted runner for programming and execution of an application. The build workflow is executed on a GitHub hosted runner that stores the build output as an artifact.

Prepare a self-hosted runner

These installation instructions are written for a Raspberry Pi (mode 3/4/5) running an Arm64 Ubuntu server edition.

Note

This has been tested on Ubuntu Server 24.0.3 LTS. For other Linux OS, please adapt the steps.

Prerequisites

Update you local machine with the latest changes.

# Make sure your system is up-to-date
sudo apt update && sudo apt upgrade

# Install required tools
sudo apt install net-tools zip unzip python3.12-venv

pyOCD

pyOCD is a debug connector used in Keil Studio that offers also command-line operation for Continuous Integration (CI).

Install pyOCD

Extract the latest pyocd release from the GitHub repository and store the download URL in a variable:

PYOCD=$(curl -s https://api.github.com/repos/pyOCD/pyOCD/releases/latest \
  | jq -r '.assets[] | select(.name | test("linux-arm64.*\\.zip$")) | .browser_download_url')

Download the latest pyocd release using the variable:

curl -o pyocd.zip -L $PYOCD

Create a new directory to store pyocd and extract the Zip file to it:

mkdir pyocd && unzip pyocd.zip -d pyocd

Add the path to the pyOCD executable:

export PATH=$PATH:~/pyocd

Check if the installation was successful:

pyocd --version

The Zip file is no longer needed, remove it:

rm -rf pyocd.zip

vcpkg

vcpkg is a free C/C++ package manager for acquiring and managing libraries and is used in the CMSIS solution workflow to download additional tools.

Install vcpkg

Extract the latest vcpkg release from the GitHub repository and store the download URL in a variable:

VCPKG=$(curl -s https://api.github.com/repos/microsoft/vcpkg/releases/latest | jq -r '.tarball_url')

Download the latest vcpkg release using the variable:

curl -o vcpkg.tar.gz -L $VCPKG

Create a new directory to store vcpkg and extract the tar.gz file to it:

mkdir .vcpkg && tar xf vcpkg.tar.gz --strip-components=1 -C .vcpkg

Execute the bootstrap script:

.vcpkg/bootstrap-vcpkg.sh

Add the path to the vcpkg executable:

export PATH=$PATH:~/.vcpkg

Check if the installation was successful:

vcpkg version

The tar.gz file is no longer needed, remove it:

rm -rf vcpkg.tar.gz

Activation

Download the vcpkg-configuration.json file that contains the CMSIS-Toolbox:

curl -o vcpkg-configuration.json -L https://raw.githubusercontent.com/Arm-Examples/Safety-Example-STM32/refs/heads/main/vcpkg-run-configuration.json

Then, update the registry:

vcpkg x-update-registry --all

Note

If node is not installed on your machine, it will be downloaded automatically.

Finally, activate vcpkg:

vcpkg activate --json=env.json

Get the path to the CMSIS-Toolbox from the generated env.json file:

CMSIS_TOOLBOX=$(jq '.paths.PATH[]' env.json | tr -d '\"')
export PATH=$CMSIS_TOOLBOX:$PATH

Note

Setting environment variables using the export command only affects the current shell session. To make this change permanent across sessions, add the export command to your shell's profile script (e.g., ~/.bashrc).

Make binary paths persistent

Before we add the paths to the .bashrc file, check the real path to the CMSIS-Toolbox:

echo $CMSIS_TOOLBOX

Make a note of this path.

Open the .bashrc file with the nano editor:

sudo nano ~/.bashrc

In the editor, go to the last line and add:

export PATH=$PATH:~/pyocd
export PATH=$PATH:~/.vcpkg
export PATH=$PATH:~/.vcpkg/downloads/artifacts/[enter your folder number here]/tools.open.cmsis.pack.cmsis.toolbox/2.11.0/bin

Press CTRL-o to save the file, close the editor with CTRL-x. This ensure that every new shell has the correct path settings available.

Install the required CMSIS-Packs

Now, you have access to the CMSIS-Toolbox which also contains the cpackget tool which is used to download CMSIS-Packs from the web. For this example, we need the device family and board support packs from Infineon.

cpackget add -a -F Infineon::T2G-B-H_DFP@1.2.1
cpackget add -a -F Infineon::KIT_T2G-B-H_LITE_BSP@1.2.1

Note

Run this command again if the pack versions change.

Install the self-hosted runner

Download and extract the runner

In your GitHub repository, go to Settings → Actions → Runners and select "New self-hosted runner".

Select the appropriate OS and architecture (here: Linux/ARM64).

Follow the instructions that are given on that page until you start the self-hosted runner.

Run persistently

In the last step, you have started the runner manually. If you want to start it at boot time, install a systemd service:

sudo ./svc.sh install

Start the service manually:

sudo ./svc.sh start

Check the status of the service:

sudo ./svc.sh status