Zephyr Integration with CMSIS-Toolbox

This repository contains two basic Zephyr examples configured in the zephyr.csolution.yml file for multiple development boards. It uses the GCC toolchain, Keil Studio, and Zephyr's west build system to generate the application image.

The Arm CMSIS Debugger provides kernel-aware debugging and views for device peripherals, including the interrupt system. It is used to download and run the application on target hardware.

pyOCD supports runtime behavior analysis in CI workflows using RTT and SystemView.

Overall, Zephyr development is simplified by managing different build configurations, using an intuitive project tree, supporting multi-core configurations, and providing smart editor features such as code completion.

CMSIS-Toolbox Integration

Zephyr and west remain responsible for configuring and building the Zephyr application. The zephyr.csolution.yml file adds common project information for the selectable application configurations and their target hardware.

CMSIS-Toolbox uses the same common project information in VS Code, command-line, and CI/DevOps workflows. CMSIS-Packs provide device and board data that complements the Zephyr build information with programming, run, and debug configuration, peripheral views, and trace configuration. Generated files such as compile_commands.json and *.cbuild-run.yml connect smart editor features, static code analysis and test tools, target deployment, and trace to the application development workflow without replacing Zephyr or west.

VS Code quick start

1. Install Keil Studio for VS Code from the VS Code marketplace.
2. Install upstream Zephyr and configure its environment variables.
3. Clone this repository (for example using Git in VS Code) or download the ZIP file. Then open the repository folder in VS Code.
4. In VS Code, open the CMSIS View and then the Manage Solution dialog to select the target board and one project.
5. In the CMSIS view, use the Action buttons to build, load, and debug the example on your hardware.

Tip

If configuration or build errors occur, use Clean All 'out' and 'tmp' directories from the CMSIS view menu to remove stale CMake cache files before rebuilding.

Zephyr installation

The following instructions apply to Linux, macOS, and Windows. Install a supported version of Python 3 and Git before continuing.

Warning

On Windows, use Python 3.13 or earlier because the windows-curses package is not yet available for Python 3.14.

Create the workspace

• Open a terminal as a regular user. On Windows, use cmd.exe for the commands below.

• In any suitable working directory, create a zephyrproject directory and change into it:

  mkdir zephyrproject
  cd zephyrproject

• Create a virtual environment. Use the command for your operating system:

  Linux and macOS:

  python3 -m venv .venv

  Windows:

  python -m venv .venv

• Activate the virtual environment.

  Linux and macOS:

  source .venv/bin/activate

  Windows (cmd.exe):

  .venv\Scripts\activate.bat

  Once activated, the shell prompt is prefixed with (.venv). Activate the environment again whenever you open a new terminal. Run deactivate to leave it.

• Install west. After activation, python refers to the virtual environment on every supported operating system:

  python -m pip install west

• Get the upstream Zephyr source code and its modules:

  west init -m https://github.com/zephyrproject-rtos/zephyr.git
  west update

• Install the Python dependencies required by Zephyr:

  python -m pip install -r zephyr/scripts/requirements.txt

Configure VS Code

The CMSIS Solution extension needs the Zephyr workspace and virtual environment paths when it runs west.

1. In VS Code, open Settings and search for Cmsis-Csolution: Environment Variables.

2. Select the User or Workspace setting and choose Add Item for each variable below. Replace <work-dir> with the directory in which you created your zephyrproject workspace.

   Variable	Linux and macOS	Windows
   ZEPHYR_BASE	/<work-dir>/zephyrproject/zephyr	C:\<work-dir>\zephyrproject\zephyr
   PATH	/<work-dir>/zephyrproject/.venv/bin	C:\<work-dir>\zephyrproject\.venv\Scripts
   VIRTUAL_ENV	/<work-dir>/zephyrproject/.venv	C:\<work-dir>\zephyrproject\.venv

3. Fully restart VS Code so that the extension uses the new environment.

For more information, see Work with Zephyr applications.

Command-line build

Install CMSIS-Toolbox, the GCC compiler, and the Zephyr workspace described above. Ensure that the Zephyr virtual environment is active, then run for example:

cbuild zephyr.csolution.yml --packs --active NUCLEO-H563ZI

The command uses the same common project information as VS Code and invokes West to build the selected Zephyr application. Refer to West Build System Integration for details.

Caution

If you see errors during west build (for example during generating a build system), the west installation or PATH is likely incorrect. Check Settings - Cmsis-Csolution: Environment Variables. Verify that the values match the paths in Configure VS Code.

Tip

For more information, see the Keil Studio documentation - Work with Zephyr applications.

Add another board

If you use a different board, extend the zephyr.csolution.yml file with:

  # List the packs that define the device and/or board.
  packs:
    - pack: Vendor::DFP
    - pack: Vendor::BSP

  # List different hardware targets that are used to deploy the solution.
  target-types:
    - type: SpecifyName
      board: Vendor::Board_name      # Vendor is optional
      device: Vendor::Device_name    # Vendor and device name are optional

To find the packs, open https://www.keil.arm.com/boards/ and search for your board.

• pack: Vendor::BSP is listed under CMSIS Pack on the Board page.
• pack: Vendor::DFP is listed under CMSIS Pack on the related Device page.

Board name different in Zephyr and CMSIS Pack

Frequently the Zephyr board name does not match. In this case add the variable west-board: as shown below.

Use Zephyr - Supported Boards and Shields and find your board. Under Supported Features the board_name, board_name/soc_name or board_name/soc_name/core_name is listed; this is what you specify with west-board:.

  target-types:
    - type: B-L475-IOT01A
      board: STMicroelectronics::B-L475E-IOT01A
      device: STMicroelectronics::STM32L475VGTx
      variables:
        - west-board: disco_l475_iot1/stm32l475xx

Zephyr Terminal

Keil Studio includes a built-in Zephyr Terminal for running west commands in the IDE. When you open it, it configures the working directory and Zephyr environment for the selected project.

Example west commands:

# Build the project
west build

# Open GUI configuration
west build -t guiconfig

# Generate RAM report
west build -t ram_report

RTT and SEGGER SystemView

SEGGER Real-Time Transfer (RTT) enables real-time data exchange between a target device and a host debugger without requiring an additional UART interface. RTT is also the transport mechanism used for SystemView.

RTT and SystemView are integrated in Zephyr and enabled in the zephyr.csolution.yml file with the west-defs under the build-type: Debug-RTT. RTT and SystemView are currently used for CI testing and can be used with pyOCD as shown below.

The Debug-RTT configurations for target-type: IFX_T2G_B_H are excluded from the CI build matrix because RTT support is not available for this Zephyr target.

Example invocation for target-type: STM32H7B3I-DK:

pyocd load --cbuild-run <path>\out\zephyr+STM32H7B3I-DK.cbuild-run.yml
pyocd run  --cbuild-run <path>\out\zephyr+STM32H7B3I-DK.cbuild-run.yml

The pyOCD run command now outputs test messages to the debug console and collects the file out\zephyr+STM32H7B3I-DK.SVdat, which can be analyzed with SEGGER SystemView.

CI Test Automation

This repository demonstrates a hybrid CI approach: build steps run on GitHub-hosted runners, while hardware execution runs on a self-hosted Raspberry Pi 5 (RPi5) runner connected to a NUCLEO board.

The CI workflows provide full build coverage and hardware-in-the-loop (HIL) testing:

• Build_All_Variants.yaml builds every project, build type, and supported target combination.
• Build_NUCLEO-H563ZI.yaml compiles the selected Zephyr application and produces build outputs that can be consumed by the run workflow.
• Run_NUCLEO-H563ZI.yaml executes on the self-hosted RPi5 runner and uses an attached debug probe to download and execute the image on the target board.

The run workflow uses pyOCD to flash and run the application. To avoid duplicating board configuration in multiple places, the workflow relies on the generated *.cbuild-run.yml file for target information and uses the ID of the connected debug adapter to select the correct probe. Refer to the CMSIS-Toolbox - Run and Debug Configuration for more information.

In the GitHub Actions view of Run_NUCLEO-H563ZI.yaml, you can review the test results:

• The application output is visible in the action log (for example via RTT-based console output).
• The workflow uploads a SEGGER SystemView trace (*.SVdat) as an artifact. This execution trace can be downloaded and analyzed offline.

See Setup Self-Hosted GitHub Runner on Raspberry Pi 5 for details on configuring the self-hosted runner. It explains installing pyOCD and the required DFP and BSP packs for connecting to the target hardware.