ST Technical Moderator

How to debug an external .elf file in VS Code

Oct 29, 2026 7:23 PM UTC
0 replies
1980 views

Summary

This article explains how to debug an external *.elf file in Visual Studio Code (VS Code) using the STM32CubeExtension, without requiring a CMake project or a full development environment.

Introduction

Debugging embedded applications on STM32 microcontrollers is an essential step to ensure firmware functionality. The *.elf (executable and linkable format) file is a key factor in this process. It contains the compiled program along with important debugging information, such as symbol names, variable locations, and source code mappings.

This article focuses on setting up VS Code with the STM32CubeExtension to directly debug an existing *.elf file. This approach allows you to configure the debugging interface properly and leverage the STLINK debugger without requiring a complete project setup.

Prerequisites

This article assumes that the following tools and files are installed and available:

Visual Studio Code
STM32CubeExtension and dependencies, including STM32CubeProgrammer and STM32CubeCLT
A compiled *.elf file with debug symbols included
An STLINK debugger connected to your STM32 microcontroller board. This article uses the NUCLEO-G0B1RE

1. Prepare your debugging environment

Create a new folder on your computer and place your compiled *.elf file inside it. In this case, the file is named: STM32G0_BlinkLED.elf:

Open this folder in Visual Studio Code by selecting [File] > [Open Folder].

Ensure your *.elf file includes debug symbols, which are typically generated by default in debug builds.

2. Create debug configuration

Open the [Run and Debug] view (Ctrl+Shift+D).
Click [create a launch.json] file.

Select [STM32Cube: STLink GDB Server] from the list of debuggers provided by STM32CubeExtension.

The extension generates a default .vscode/launch.json file with configurations tailored for STLINK debugging.

3. Modify launch.json

Edit the generated launch.json file to support debugging with all features enabled. Here is an example configuration for a NUCLEO-G0B1RE:

Before:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "stlinkgdbtarget",
            "request": "launch",
            "name": "STM32Cube: Launch ST-Link GDB Server",
            "origin": "snippet",
            "cwd": "${workspaceFolder}",
            "preBuild": "${command:st-stm32-ide-debug-launch.build}",
            "runEntry": "main",
            "imagesAndSymbols": [
                {
                    "imageFileName": "${command:st-stm32-ide-debug-launch.get-projects-binary-from-context1}"
                }
            ]
        }
    ]
}

After:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "stlinkgdbtarget",
            "request": "launch",
            "name": "STM32Cube: Launch ST-Link GDB Server",
            "origin": "snippet",
            "cwd": "${workspaceFolder}",
            "runEntry": "main",
            "imagesAndSymbols": [
                {
                    "imageFileName": "${command:st-stm32-ide-debug-launch.get-projects-binary-from-context1}"
                }
            ]
        }
    ]
}

Explanation of the changes:

Removed “prebuild” command:

Since you are debugging an external *.elf file without a full project or build system, there is no need to trigger a build before debugging.

4. Create ide.store.json

For an external *.elf file, ide.store.json provides teh STM32CubeIDE for VS Code extension with the target information, normally obtained from an STM32 project. In the root of your workspace:

Crete a .settings folder.
In the .settings folder, create the ide.store.json file with the following content, in this case, aimed for the NUCLEO-G0B1RE:

Edit the file with this content:

{
  "board": "NUCLEO-G0B1RE",
  "device": "STM32G0B1RET6",
  "core": "Cortex-M0+"
}

Field description:

board: the name of your board.
device: The exact STM32 microcontroller reference on the board.
core: The Cortex core of the selected STM32.

For a different target, update these fields with the values that match the selected hardware.

5. Start debugging

Connect your STM32 board to your PC using the STLINK debugger, the pop-up message appears at the lower right corner, click [Open DEVICES AND BOARDS view]:

In VS Code, select the debug configuration you created, either the normal or detailed settings:

Press F5 or click the green [Start Debugging] button.
The STM32CubeExtension automatically connects to your board, load the *.elf file, and halt at the main() function (if runEntry: “main”).
You can now:
- Set breakpoints in your source code.
- Step through your program.
- Inspect variables, registers, and memory.
- View call stacks.

6. Troubleshooting: memory viewer not updating

When debugging with the STM32CubeExtension using the “stlinkgdbtarget” type, you may encounter an issue where the “Memory Viewer” in VS Code does not display memory contents or fails to update during your debug session.

By default, the MemoryView extension may not include "stlinkgdbtarget" in its tracked debuggers in the settings.json file. Without this, the debugger cannot properly read memory, causing the memory viewer to remain empty or stale.

To resolve this:

Press Ctrl+Shift+P, type Preferences: Open User Settings (JSON), and select it.

Add the following configuration snippet:

 "memory-view.trackDebuggers": [
 "stlinkgdbtarget",
 ],

Save the file and restart VS Code or press Ctrl+Shift+P and issue the command to Reload Window:

Conclusion

Debugging an external *.elf file in VS Code with the STM32CubeExtension and STLINK is a simple and efficient way to work with STM32 firmware. With the right configuration, you can use all essential debugging features without needing a full project or build system, making your workflow faster and more flexible.