Oberon RTK

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

Tool Purpose Targets
Python 3 Run make-elf, gen-rdb, and other tools in tools/ all
xPack ARM GNU Toolchain arm-none-eabi-gdb-py3, objdump, readelf all
xPack OpenOCD GDB server for STM32U585 (J-Link or ST-LINK) STM32U585
ST OpenOCD GDB server for STM32H573 (ST-LINK) STM32H573
Raspberry Pi OpenOCD GDB server for RP2350/RP2040 (CMSIS-DAP) RP2350
SEGGER J-Link Software Firmware and drivers for J-Link probes STM32
picotool Upload binaries to RP2040/RP2350 via USB RP2040, RP2350
pioasm PIO assembler (used by gen-pio-oberon) RP2040, RP2350
STM32CubeProgrammer Option bytes, TrustZone configuration, ST-LINK firmware STM32
VS Code + Cortex-Debug Interactive hardware debugging all

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.

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. On this project's Windows setup, python is correct.

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.

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.

Environment Variables

  • RTK_GDB – path to arm-none-eabi-gdb-py3 (VS Code launch configs)
  • RTK_OBJDUMP – path to arm-none-eabi-objdump (VS Code launch configs)
  • RTK_READELF – path to arm-none-eabi-readelf (check-elf)

See Environment Variables.

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.

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.

Environment Variables

  • RTK_OPENOCD_XPACK – path to the xPack OpenOCD executable
  • RTK_OPENOCD_CFG_STLINK – path to tools/config/OpenOCD/stlink-swd.cfg

See Environment Variables.

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.

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

Environment Variables

  • RTK_OPENOCD_STM – path to the ST OpenOCD executable
  • RTK_OPENOCD_STM_SCRIPTS – path to the ST OpenOCD st_scripts directory

See Environment Variables.

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).

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.

Environment Variables

  • RTK_OPENOCD_RPI – path to the Raspberry Pi OpenOCD executable
  • RTK_OPENOCD_RPI_SCRIPTS – path to the Raspberry Pi OpenOCD scripts directory

See Environment Variables.

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.

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).

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.

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).

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

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 setup: enabling TZEN (TrustZone enable), configuring the Secure/Non-secure flash boundary (SECWM), setting other security-related option bytes, and to update ST-LINK firmware.

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:

Target Probe GDB Server
STM32U585 J-Link xPack OpenOCD
STM32U585 ST-LINK xPack OpenOCD
STM32H573 ST-LINK ST OpenOCD
RP2350 CMSIS-DAP Raspberry Pi OpenOCD

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

GDB Server Scripts

The tools/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.

Script GDB Server Target Probe
openocd-jlink-stm32u585 xPack OpenOCD STM32U585 J-Link
openocd-stlink-stm32u585 xPack OpenOCD STM32U585 ST-LINK
openocd-stlink-stm32h573 ST OpenOCD STM32H573 ST-LINK
openocd-cmsisdap-rp2350 RPi OpenOCD RP2350 CMSIS-DAP
openocd-cmsisdap-rp2350-sns RPi OpenOCD RP2350 S/NS CMSIS-DAP

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

The scripts require environment variables to locate the OpenOCD executable and scripts directory:

  • RTK_OPENOCD_XPACK, RTK_OPENOCD_CFG_STLINK – STM32U585 scripts
  • RTK_OPENOCD_STM, RTK_OPENOCD_STM_SCRIPTS – STM32H573 scripts
  • RTK_OPENOCD_RPI, RTK_OPENOCD_RPI_SCRIPTS – RP2350 scripts

See Environment Variables for the full list and recommended values.

OpenOCD Configuration Files

The tools/config/OpenOCD/ directory contains an interface wrapper configuration file used by the xPack OpenOCD server scripts:

  • stlink-swd.cfg – selects the ST-LINK interface driver and SWD transport

The STM32H573 scripts use stlink-dap.cfg from the ST scripts directory instead. The 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: 23 April 2026