DEV Community

Hedy
Hedy

Posted on

How to debug STM32F103 using ST-LINK?

#stm32f103 #debug #stlink #stm32f103c8t6

You debug an STM32F103 with ST-LINK by doing three things:

  1. Wire ST-LINK to the chip
  2. Install drivers + IDE/debugger
  3. Set the debug configuration and hit the Debug button

I’ll walk you through the whole flow.

1. Hardware connections (very important)

Use SWD (Serial Wire Debug), not full JTAG (simpler, only 2 data lines):

Minimum pins:

  • SWDIO – debug data
  • SWCLK – debug clock
  • GND – common ground
  • 3V3 – target VCC sense (ST-LINK uses it as reference; some programmers also power the board from here, check yours)
  • NRST (optional but recommended) – hardware reset

Typical connection (STM32F103C8T6 “Blue Pill” example):

  • ST-LINK SWDIO → MCU PA13 (SWDIO)
  • ST-LINK SWCLK → MCU PA14 (SWCLK)
  • ST-LINK GND → Board GND
  • ST-LINK 3.3V → Board 3.3V (or at least to VREF, make sure voltages match!)
  • ST-LINK RST → MCU NRST (if present on your ST-LINK)

Tips:

  • If the board already has a USB interface and 3.3 V regulator, do not power from two sources at once unless the board is designed for it.
  • Keep SWD wires short (<20 cm ideally).

2. Install software

You need:

  • ST-LINK USB driver (Windows) – usually installed automatically by STM32CubeIDE or ST-LINK Utility / STM32CubeProgrammer.
  • A debugger/IDE, e.g.:
    • STM32CubeIDE (recommended, all-in-one)
    • Or: Keil uVision / IAR / PlatformIO / VS Code + OpenOCD (similar ST-LINK configuration idea)

I’ll assume STM32CubeIDE, because it’s free and straightforward.

3. Create / import a project in STM32CubeIDE

  1. Open STM32CubeIDE.
  2. File → New → STM32 Project.
  3. Choose your MCU (STM32F103C8Tx) or board (e.g., Nucleo-F103RB if you use one).
  4. Finish wizard → it generates startup code, linker script, etc.
  5. Build once: Project → Build Project (or hammer icon). Fix any compile errors before debugging.

If you already have a project, just import it (File → Import → Existing Projects).

4. Debug configuration (ST-LINK + SWD)

CubeIDE usually creates this automatically, but check once:

  1. Go to Run → Debug Configurations…
  2. Under STM32 Cortex-M C/C++ Application, select your project.
  3. In the Debugger tab:
  • Interface: ST-LINK (OpenOCD) or ST-LINK (ST-Link GDB server) depending on IDE version.
  • Interface type: SWD (not JTAG).
  • Check “Reset behavior” – typically “Connect under reset” helps if the code messes up SWD pins or clock.
  1. Apply and Close.

Now click the Debug (bug) icon.

  • IDE will flash the code into the STM32F103 via ST-LINK.
  • It will break at main() by default.

If it doesn’t connect, see the “Common problems” section below.

5. Basic debug actions

Once you’re in a debug session:

  • Step Over (F6) – execute current line, step over function calls.
  • Step Into (F5) – go inside functions.
  • Step Out (F7) – run until current function returns.
  • Resume (F8) – run code normally until next breakpoint / halt.

  • Breakpoints – click in the left margin of the code editor to toggle breakpoints.
    Watch variables:

  • Open the Variables or Expressions view.

  • Add variables or register names you want to watch.

View peripheral registers:

  • Open Window → Show View → Other… → Debug → Registers.
  • Many IDEs have an STM32-specific view (SFRs): GPIO, USART, TIM, etc.

6. Using ST-LINK as standalone programmer (optional)

Sometimes you just want to check if connection works:

  • ST’s standalone tool is STM32CubeProgrammer.
  • Connect ST-LINK, open CubeProgrammer, select ST-LINK as interface, click “Connect”.
  • If it connects and you can read the device ID / memory, wiring and driver are OK.

7. Common problems & fixes
Problem 1 – “No target connected” / “Cannot connect to target”

Check:

  1. Power – STM32F103 must be powered with correct 3.3 V.
  2. GND common – ST-LINK GND and board GND must be tied together.
  3. SWD enabled:
  • If your firmware reconfigures PA13/PA14 as regular GPIO, debugger can’t attach.
  • Use “Connect under reset” in debugger settings and hold NRST low during connect.
  1. Option bytes:

If nBOOT0, nBOOT1 or SWD disabled, you may need to use CubeProgrammer → Option Bytes → ensure SWD/JTAG is enabled.

Problem 2 – It resets or stops randomly when debugging

  • Stack overflow or hard fault – check stack size and interrupt code.
  • Watchdog configured – may reset while you’re halted.
    • During debug, either disable WDG in code or configure the debugger to stop the watchdog clock (some chips allow this via debug registers).

Problem 3 – “Breakpoints not working” / always runs past them

  • Ensure you are in Debug build (no link-time optimization removing code).
  • STM32F1 does HW breakpoints; number is limited (often 6). Too many breakpoints can cause weird behavior.

8. Minimal “sanity test” workflow

  1. Create a new STM32F103 blink project in CubeIDE.
  2. Add a simple HAL_Delay LED blink in main().
  3. Click Debug:
  • Verify it stops at main().
  • Single-step past the HAL init.
  • Resume and see the LED blinking on the board.

If that works, your ST-LINK + SWD + IDE setup is good, and any further issues are inside your own firmware.

Top comments (0)