Blackmagic probe revisited

electronics, embedded, stm32

Turn Your $2 STLink Clone Into a Black Magic Probe

TLDR: Transform that cheap Chinese STLink V2 clone into a proper debugger by flashing Black Magic Probe firmware. 15 minutes of work, intermediate difficulty, and a surprisingly good outcome for something that probably came in a plastic bag with no labels.

Historical Context

Back in 2016, I wrote about installing Black Magic Probe on STLink clones. My main contribution was discovering the correct SWD/SWIM pinout through systematic testing (or as I like to call it, “guided pin juggling”) – since every Chinese clone seems to have its own creative interpretation of pin assignments.

Since then, the Black Magic Probe project has evolved significantly – moving from Make to Meson build system. This guide covers the current (2024) method.

What You’re Getting

Black Magic Probe (BMP) provides direct GDB support without needing OpenOCD or other middleware. It’s perfect for STM32 development and transforms your basic STLink clone into a full-featured debugging tool.

Prerequisites

  • STLink V2 clone (tested on Baite)
  • Linux/macOS (Windows users: use WSL)
  • Required tools: – git – meson & ninja – arm-none-eabi-gcc – st-flash (from the stlink-tools package) – dfu-util

Part 1: Build & Flash Bootloader

The bootloader (8KB) manages firmware updates. It must be flashed first to the correct address.

# Clean start
rm -rf build

# Configure and build bootloader
meson setup build --cross-file cross-file/arm-none-eabi.ini \
    --cross-file cross-file/stlink.ini -Dprobe=stlink \
    -Dbmd_bootloader=true -Dtargets=stm -Drtt_support=false
ninja -C build boot-bin boot-elf

# Flash bootloader to address 0x08000000
st-flash erase
st-flash write build/blackmagic_stlink_bootloader.bin 0x08000000

Part 2: Build & Flash Main Firmware

Critical: Use DFU for the main firmware, not st-flash. Your device should now appear as a DFU device after the bootloader flash.

# Build main firmware
meson setup build --cross-file cross-file/arm-none-eabi.ini \
    --cross-file cross-file/stlink.ini -Dprobe=stlink \
    -Dbmd_bootloader=true -Dtargets=stm -Drtt_support=false
ninja -C build -j$(nproc)

# Flash firmware to address 0x08002000 using DFU
dfu-util -a 0 -s 0x08002000:leave -D build/blackmagic_stlink_firmware.bin

Verification

After a successful flash, your clone is now a proper Black Magic Probe. Here’s what to look for:

  • Two new serial ports: This is the strongest sign of success. – /dev/ttyACM0 (or similar): The GDB server port. Connect with target extended-remote /dev/ttyACM0. – /dev/ttyACM1 (or similar): A bonus USB-to-UART converter for printf debugging.
  • Test with the command-line tool: The `blackmagic` executable built alongside the firmware is a powerful utility. Use it to scan for your target.
❯ ./build/blackmagic -t
Black Magic Debug App v2.0.0-rc2-80-g305d4d00
 for Black Magic Probe, ST-Link v2 and v3, CMSIS-DAP, J-Link and FTDI (MPSSE)
Using 1d50:6018 E0C2C8C2 Black Magic Debug
 Black Magic Probe (ST-Link/v2) v2.0.0-rc2-80-g305d4d00
Running in Test Mode
Target voltage: 3.25V
[...]
***  1   STM32F1 L/M density M3
RAM   Start: 0x20000000 length = 0x5000
Flash Start: 0x08000000 length = 0x20000 blocksize 0x400

Troubleshooting the Inevitable

You are using a cheap Chinese clone. It’s safe to assume something will not work as described. Here are the issues I personally encountered and how to fix them:

  • Symptom: `dfu-util` Fails with `Lost device after RESET?`
    You run the DFU command, the device disconnects, but it never reappears in the correct DFU mode and `dfu-util` times out. This is the most common failure mode.
    Solution: The “Magic” Unplug/Replug. The bootloader on these clones often fails to properly re-enumerate into DFU mode via a software command.
    1. Run the `dfu-util` flash command. It will connect and then hang, waiting for the device to reattach.
    2. Unplug your ST-Link clone from USB.
    3. Immediately plug it back in.
    4. The waiting `dfu-util` command will now detect the device in its proper DFU mode and the flash will proceed.
  • Symptom: GDB fails with `No usable targets found`
    This happens after a successful firmware flash when you try to connect to your target MCU.
    Solutions:
    1. Check Wiring: Ensure SWDIO, SWCLK, and GND are correctly connected between the BMP and your target.
    2. Power Your Target: The BMP does not have a strong power supply. You must provide power to your target MCU separately.

Why This Order Matters: A Look at the Flash

You are manually partitioning the microcontroller’s flash memory. The `st-flash` tool, if run without a specific address, defaults to writing at `0x08000000`. If you use it to write the main firmware, you will silently erase your DFU bootloader. That’s why we must switch to `dfu-util` for the main firmware, as the BMP’s DFU bootloader is hardcoded to only allow writes to the application region, thus protecting itself. 

+--------------------------------+ 0x08000000 (Flash Start)
|                                |
|   Black Magic DFU Bootloader   |  <- Flashed once with st-flash.
|          (8 KB)                |     NEVER TOUCH AGAIN WITH DFU.
|                                |
+--------------------------------+ 0x08002000 (Firmware Start)
|                                |
|  Black Magic Probe Firmware    |  <- Update this part anytime
|                                |     using dfu-util.
|                                |
+--------------------------------+
|                                |
|         Unused Flash           |
|                                |
+--------------------------------+ 0x08020000 (Flash End for 128KB part)

Conclusion

With Black Magic Probe firmware, your STLink clone becomes a capable debugging tool with direct GDB support. Consider setting up udev rules and exploring ARM debugging with GDB for your next project.