Skip to content

doc/guides: Extend STM32 Flashing Guide with OpenOCD and WSL Remark #21794

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 15, 2025
Merged

doc/guides: Extend STM32 Flashing Guide with OpenOCD and WSL Remark #21794

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 37 additions & 7 deletions doc/guides/board_specific/stm32.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,15 @@ title: STM32 Flashing
description: Guide on how to flash STM32 boards
---

## General

The Nucleos often ship with very old ST-Link Firmware.
If the flash operation fails for some reason, it is possible that
the embedded ST-Link firmware is either too old or has bugs that have been
fixed in the meantime. You can find updates for the ST-Link on
[this STM webpage](https://www.st.com/en/development-tools/stsw-link007.html).
You can also use the `STM32CubeProgrammer` software to update the firmware.

## Flashing the Board Using OpenOCD

The ST Nucleo32, 64 and 144 boards include an on-board ST-LINK programmer
Expand All @@ -24,8 +33,36 @@ select it by explicitly setting the `PROGRAMMER` variable:
make BOARD=xxxxx PROGARMMER=openocd flash
```

:::note
The OpenOCD release cycle is quite slow and newly released chips might not be
supported by the latest release. For example the STM32C0 series is not yet
supported by OpenOCD 0.12.0, resulting in the following error message:
`Warn : Cannot identify target as an STM32G0/G4/L4/L4+/L5/U5/WB/WL family device.`.

Furthermore, some distributions ship even older versions, which might not have
support for new devices or for the ST-Link V3 that is built-in on new
generation Nucleos, resulting in a diffuse LibUSB error message such as this:
`Error: libusb_open() failed with LIBUSB_ERROR_ACCESS`.
If you have a recent OpenOCD version, you can check if your user is
in the `dialout` and/or `plugdev` group and therefore has the appropriate
access rights.

In either of the first two cases you have to compile the latest OpenOCD
sources for your system and manually update the
`/etc/udev/rules.d/60-openocd.rules` file with the
file provided in the `contrib` subfolder of the OpenOCD repository.
Please refer to the OpenOCD documentation for further information.
:::

## Flashing the Board Using the ST-LINK Mass Storage Device

:::note
This method does not (easily) work with WSL, as the standard kernel provided
does not support Mass Storage Devices. While you can access the MSD through
e.g. `/mnt/d/` if the ST-Link is mounted under Windows, you can not use the
VCP (Virtual COM Port) via `usbipd` inside of WSL at the same time.
:::

The on-board ST-Link programmer found on all Nucleo32, 64 and 144 boards
will show up as a mass storage device when plugged in via USB.
Copying a HEX file to the mass storage device will trigger the flashing
Expand All @@ -37,13 +74,6 @@ you can use the following command:
make BOARD=nucleo-xxxx PROGRAMMER=cpy2remed flash
```

:::note
If the flash operation fails for some reason, it is possible that
the embedded ST-Link firmware is either too old or has bugs that have been
fixed in the meantime. You can find updates for the ST-Link on
[this STM webpage](https://www.st.com/en/development-tools/stsw-link007.html).
:::

## Flashing the Board using stm32flash

It is possible to automatically boot the STM32 board into the in-ROM bootloader
Expand Down