External Tools

Installation guide for the tools used with Astrobe Oberon programs

Installation guide for the tools used with Astrobe Oberon programs for building ELF files, debugging on hardware, and running automated tests.

All software tools listed here are free. The SEGGER J-Link software requires a licence agreement on first run. A debug probe is needed for on-target debugging: the ST-LINK is built into many STM development boards at no extra cost; the Raspberry Pi Debug Probe is around 15 EUR; SEGGER J-Link probes range from around 70 EUR (educational, non-commercial use) to 650+ EUR.

Overview

Which tools you need depends on your target and debug probe. At minimum you need Python and the ARM toolchain. The GDB server section explains which combinations apply.

Environment Variable Set-up

The tools listed below are wired into the framework's build scripts, debug-server scripts, and VS Code launch configurations through RTK_* environment variables. For step-by-step set-up matched to your MCU and stage, follow the corresponding guide:

• Set-up: Build Scripts on RP – command-line builds for RP2040 / RP2350
• Set-up: Build Scripts on STM32 – command-line builds for STM32U585 / STM32H573
• Set-up: Debugging on RP – debugging on RP2040 / RP2350
• Set-up: Debugging on STM32 – debugging on STM32U585 / STM32H573

Each guide names the tools relevant to that combination, says which RTK_* variables to enable, and points at the framework's setup script (<repo>/tools/setup/set-rtk-env.cmd on Windows, set-rtk-env.sh on macOS / Git Bash) for the apply step.

For the full reference list of RTK_* variables and their meaning, see Environment Variables. The per-tool sections below describe what each tool is and where to obtain it; they do not repeat the environment-variable details.

Python 3

Any recent version (3.9 or later). All tools use the standard library only – no pip install is needed.

Windows

Install from python.org or the Microsoft Store. The python.org installer offers an "Add to PATH" tick box; enable it.

macOS

Install from python.org or via Homebrew:

brew install python

Verification

python --version

On some systems the command is python3 rather than python. Use whichever is present.

xPack ARM GNU Toolchain

Provides the ARM cross-tools: compiler, linker, debugger, and utilities. The important binaries are:

• arm-none-eabi-gdb-py3 – GDB with embedded Python (required for gdbtestengine)
• arm-none-eabi-objdump – disassembler, used to inspect ELF output
• arm-none-eabi-readelf – ELF header/section viewer

The plain arm-none-eabi-gdb (without -py3) lacks Python support and cannot run the test engine. Always use the -py3 variant.

• Project page: https://xpack-dev-tools.github.io/arm-none-eabi-gcc-xpack/
• GitHub releases: https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases

Download the archive for your platform and extract it to a location of your choice. xPack archives are self-contained; no installer is needed. Add the bin/ directory to your PATH.

Verification:

arm-none-eabi-gdb-py3 --version

This should print the GDB version and the Python version it was built with.

GDB Servers

A GDB server bridges GDB to the physical debug probe (ST-LINK, CMSIS-DAP, J-Link). You need at least one, matched to your probe and target.

xPack OpenOCD

For STM32 targets with either a J-Link or an ST-LINK probe.

• Project page: https://xpack-dev-tools.github.io/openocd-xpack/
• GitHub releases: https://github.com/xpack-dev-tools/openocd-xpack/releases

Download, extract, and add bin/ to PATH. The xPack build includes drivers for ST-LINK and J-Link.

Note: The Raspberry Pi OpenOCD fork does not include the J-Link driver. For J-Link on STM32, use xPack OpenOCD.

Verification:

openocd --version

The output should mention "xPack" with the xPack version number.

ST OpenOCD (from STM32CubeIDE)

For STM32H5 targets (STM32H573). The xPack OpenOCD does not include the stm32h5x.cfg target configuration. The ST fork of OpenOCD, bundled with STM32CubeIDE, does.

The ST fork uses a different adapter driver (stlink-dap.cfg) than xPack OpenOCD (stlink-swd.cfg). The two are not interchangeable.

• Download STM32CubeIDE: https://www.st.com/en/development-tools/stm32cubeide.html

After installing STM32CubeIDE, the OpenOCD binary and scripts are located deep within the plugins directory. The exact path depends on the CubeIDE version.

Verification: run the ST OpenOCD binary with --version. The output prints "Open On-Chip Debugger" followed by a version string.

Raspberry Pi OpenOCD

For RP2350 and RP2040 targets with a CMSIS-DAP probe (Raspberry Pi Debug Probe).

• Source: https://github.com/raspberrypi/openocd
• Pre-built binaries: https://github.com/raspberrypi/pico-sdk-tools/releases

Download the openocd-0.12.0+dev-<platform> archive for your platform (available for Windows, macOS, and Linux). Extract and add the directory to your PATH, or place it in a fixed location and reference it from your launch scripts.

The Raspberry Pi fork adds RP2350/RP2040-specific target configuration and flash programming support. It uses the CMSIS-DAP interface.

If both xPack and Raspberry Pi OpenOCD are installed, they will have separate executables. Use the appropriate one for the target at hand, or keep them in separate directories and use full paths in your launch scripts.

Verification: run the Raspberry Pi OpenOCD binary with --version. The output prints "Open On-Chip Debugger" followed by a version string. Unlike xPack OpenOCD, which prefixes the output with "xPack", the Raspberry Pi build has no distinguishing label – verify you are running the correct binary by checking the path.

SEGGER J-Link Software

Provides the USB drivers and firmware updater for J-Link debug probes. The J-Link probe itself is used via xPack OpenOCD (not via SEGGER's own GDB server).

• Download: https://www.segger.com/downloads/jlink/

Run the installer for your platform. The installer adds the tools to a well-known location (eg. C:\Program Files\SEGGER\JLink_V<nnn> on Windows). Installing the J-Link software is required for the USB drivers; without them, OpenOCD cannot communicate with the probe.

picotool

Raspberry Pi's command-line tool for interacting with RP2040 and RP2350 boards over USB.

• Source: https://github.com/raspberrypi/picotool
• Pre-built binaries: https://github.com/raspberrypi/pico-sdk-tools/releases

Download the picotool-<version>-<platform> archive for your platform (available for Windows, macOS, and Linux). On macOS, picotool can also be installed via Homebrew:

brew install picotool

Add the picotool binary to your PATH.

Verification:

picotool version

pioasm

The PIO assembler from the Raspberry Pi Pico SDK. Required by gen-pio-oberon, which uses it to assemble PIO programs into JSON format before generating Oberon modules. Version 2.x or later is required (earlier versions do not support JSON output).

• Source: https://github.com/raspberrypi/pico-sdk (built as part of the SDK)
• Pre-built binaries: https://github.com/raspberrypi/pico-sdk-tools/releases

Download the pioasm-<version>-<platform> archive for your platform and add the binary to your PATH.

Verification:

pioasm --help

The output should list the available output formats, including -o json.

VS Code + Cortex-Debug

For interactive multi-pane debugging with register views, memory inspection, and peripheral displays.

VS Code

• Download: https://code.visualstudio.com/

The portable .zip variant works well if you prefer not to use the installer.

Cortex-Debug Extension

Install from the VS Code marketplace (extension ID: marus25.cortex-debug). Press Ctrl+Shift+X in VS Code, search for "Cortex-Debug", and install.

Cortex-Debug uses OpenOCD as the GDB server back-end. Each project directory includes its own .vscode/launch.json with debug configurations for the supported probe(s). The configurations reference tool paths and SVD files via environment variables (RTK_GDB, Environment Variables).

Verification: open VS Code, press Ctrl+Shift+X, and confirm that Cortex-Debug appears in the installed extensions list.

For VS Code settings and launch configuration, see Debugging.

STM32CubeProgrammer

STM's tool for programming STM32 devices and configuring option bytes. The easiest way for TrustZone set-up: enabling TZEN (TrustZone enable), configuring the Secure/Non-secure flash boundary (SECWM), setting other security-related option bytes, and to update ST-LINK firmware.

• Download: https://www.st.com/en/development-tools/stm32cubeprog.html

Run the installer for your platform. The tool provides both a GUI and a command-line interface (STM32_Programmer_CLI). The GUI is the most convenient way to inspect and modify option bytes.

Typical use: connect to the target via ST-LINK, open the Option Bytes (OB) panel, enable TZEN, set the secure flash watermark (SECWM), and apply. A power cycle may be required for some option byte changes to take effect.

Target / Probe Summary

Which GDB server to use for each combination:

All servers use port 3333 by default. The launch scripts in <repo>/tools/server-scripts/ are pre-configured for this port.

GDB Server Scripts

The <repo>/tools/server-scripts/ directory contains ready-made scripts to start GDB servers for each supported target and probe combination. Each script has a .sh (Bash) and .cmd (Windows) variant.

The S/NS variant for RP2350 adds a virtual flash bank for debugging NS code at translated addresses (10400000H+).

The scripts read the OpenOCD executable and the vendor-bundled scripts directory from environment variables (see Environment Variables).

OpenOCD Configuration Files

The <repo>/tools/server-scripts/openocd/ directory contains project-supplied interface wrapper configuration files used by the xPack OpenOCD server scripts:

• stlink-swd.cfg – ST-LINK probe with SWD transport (used by the STM32U585 ST-LINK script)
• jlink-swd.cfg – J-Link probe with SWD transport (used by the STM32U585 J-Link script)

The connect scripts compose these paths inline from %RTK_REPO_ROOT%\tools\server-scripts\openocd\<probe>-swd.cfg; no separate environment variable is needed for these in-repo files.

The STM32H573 ST-LINK script uses stlink-dap.cfg from the ST scripts directory (a different ST-LINK driver) rather than a project-supplied wrapper. The RP2040 and RP2350 scripts use cmsis-dap.cfg from the RPi scripts directory.

Notes

• xPack tools are relocatable. You can install them anywhere and simply add the bin/ directory to your PATH. There is no system-wide registration step.

• When multiple OpenOCD builds are on PATH, the first one found wins. The RTK_OPENOCD_XPACK and RTK_OPENOCD_RPI environment variables ensure the correct build is used regardless of PATH order.

• The ST-LINK firmware can be updated using STM32CubeProgrammer. Updating is recommended if you encounter connection problems.

Last updated: 8 May 2026