debugwave – Fast and easy to use STM32 debug server and flash programmer.
debugwave [command] [options] [arguments]
DebugWave is a command-line tool that works as a GDB server,
making it possible to debug running software with the GDB
debugger and its frontends.
It can also be used to read, write and erase internal program
flash memory of STM32 microcontrollers.
DebugWave supports ST-Link/V2 and ULINK2 debug probes and
works on Linux and Windows.
Identify target devices.
Identified targets are printed line by line, in the following format:
target-name cpu-core flash-size debug-probe
If DebugWave cannot determine the target device, one of the
following errors will be displayed in front of the debug probe
- "Access denied." —
DebugWave is unable to communicate the probe due to insufficient
access rights; the CONFIGURING ACCESS section below provides detailed
information on how to configure access to debug probes.
- "Target device is not connected." —
The probe behaves as if no target device is connected to it.
- "Unknown target device." —
The target that can be accessed, but does not identify itself as
a device known to DebugWave.
debug [--port n] [target-spec]
Run GDB server.
--port option can be used with this command to
specify the port number on which the GDB server should be
The default port is 2159.
read [target-spec] output-file
Read target's flash memory.Examples
# Read flash memory of the only connected target.
debugwave read output.bin
# Read flash memory of an STM32L162xx-A MCU.
debugwave read l162-a output.bin
write [target-spec] input-file
Write target's flash memory.Examples
# Write flash memory of the only connected target.
debugwave write input.bin
# Program flash memory of a target connected to the ST-Link probe.
debugwave write stlink input.bin
Erase target's flash memory.
Note that this command only erases the main program flash memory and does not
affect other kinds of flash memories, such as option bytes.
Display usage information.
Specify the GDB server port. See the
debug command for details.
Output version information.
DebugWave supports multiple connected debug probes.
When more than one target is identified, target specifiers are
used to determine the target device to work with.
If none or more than one of the connected targets match the
provided specifier, then DebugWave will generate a corresponding
This can help prevent commands being accidentally sent to the
wrong device — an especially useful safeguard for
erase, which can't be
A target specifier can be any of the following:
- A full target name, e.g.,
- A target family, e.g.,
- A CPU core name, e.g.,
- A debug probe name with or without leading characters of its serial number,
- A combination of the above separated with the colon character (
The specifier can be all-uppercase or all-lowercase.
x wildcard characters denote any characters
and shall remain lowercase in uppercase forms.
Since use of lowercase
x characters is reserved, it
is allowed to use the uppercase
X in place of a target
name suffix in all-lowercase specifiers.
l162vx-x matches to both -A and -X suffixed
l162vx-X only matches to -X suffixed
Target name specifiers that end with periods (
only match to targets without suffixes.
l162vx. matches to STM32L162Vx targets, but
does not match to STM32L162Vx-A or STM32L162Vx-X targets.
For security reasons, in the common default Linux
configurations only root users have access to USB devices like
Since working under the root account is potentially dangerous, we
recommend to create a group of users, say,
and install udev rules granting its members access to the
supported types of probes.
Once this group is configured, it's easy to grant or revoke
access for specific users by including them in or excluding them
from that group.
To simplify the process, we have prepared a shell script that
debugprobe group, adds the current,
non-root user to it, and installs the udev rules.
The script can be downloaded directly from our support repository
$ wget https://raw.githubusercontent.com/debugwave/support/master/configure_access.sh
Before applying, you may want to customize the script or just
examine its content:
$ cat configure_access.sh
Here's how to make it executable and run:
$ chmod +x configure_access.sh
$ sudo ./configure_access.sh
Note that since adding users to a group doesn't affect users
who are currently logged in, the changes will be applied as soon
as you log out, and log back in.
erase commands use an
intelligent algorithm to minimize programming time and flash wear
by making sure no portion of flash memory is erased or
reprogrammed unless it's necessary.
This means DebugWave only guarantees that the given image
file will be in flash memory after programming is completed.
It doesn't guarantee the status of flash memory outside the
binary image address range, which may be erased or left
untouched, depending on the situation.
Thus, the most reliable (and efficient) way to ensure all
data gets flashed correctly is to prepare a complete image, then
write the whole image at once.
For example, the way to flash data to sectors 1 and 2 is to
prepare and flash an image that contains data for both these
sectors, instead of programming them separately.
As of this version, the
write command does not
support areas guaranteed to be unchanged during programming
DebugWave returns the following exit codes indicating the
type of problem:
- 0 – Success.
- 1 – A common failure that doesn't fit into any of the
- 2 – An internal check failed.
This means DebugWave itself has a problem that needs fixing.
If you encounter this error code, please let us know at
<email@example.com> so we can fix the issue as soon as
- 3 – Not enough memory.
- 4 – Usage error.
Such errors usually mean DebugWave failed to parse the commands
and/or options specified in the command line.
- 5 – Input/output error.
Indicates a problem with reading or writing files.
- 6 – Permission denied.
DebugWave returns this code when it fails to gain access to a
file (or some other system resource) due to insufficient access
Please send your suggestions and bug reports to <firstname.lastname@example.org>.
Copyright © 2019 Ivan Labs OOD. All rights reserved.