Firmware Upgrade

There are many ways to update your Black Magic Probe. For most users, the stable release firmware will be sufficient and in most cases will not require to compile anything. We recommend updating the firmware using bmputil, however if you want to use a different tool (dfu-util, etc) you can find some instructions for some other tools at the end of this document. If you have trouble using bmputil please let us know, as we strive to make the experience as easy as possible.

Install bmputil-cli

Binary releases for Linux, mac OS (amd64/AArch64) and Windows (amd64/AArch64) are now available with every release. These should work out-of-the-box with no extra dependencies or software needing to be installed.

Alternatively cargo binstall can be used to have an easily-updatable binary installation of bmputil-cli. We recommend the following order of operations:

The tool will be available as bmputil-cli starting with v1.0.0 and bmputil for older releases.

Another alternative is to use cargo install instead of cargo binstall which will install the tool from source. In such case cargo-binstall can be skipped in the instructions above. The binstall path will fall back to source compilation if a binary build is not available for the specific os/architecture combination.

Note

If you decide to choose the cargo install path on Windows, please refer to the detailed documentation about the process as it is not trivial.

bmputil on Windows will automatically setup driver installation on first run for a probe if appropriate. This will require administrator access when it occurs, and uses the Windows Driver Installer framework.

Setup permissions

In case you are using Linux we highly recommend setting up the official project udev rules.

Warning

On Windows bmputil-cli will automatically take care of the needed drivers. Do not run Zadig on the DFU endpoint if using bmputil.

You can check if everything is working correctly by running:

bmputil-cli probe info

The tool should be able to find and list the Black Magic Probe connected to the system, which should look something like this:

Found: Black Magic Probe 2.0.0
  Serial: 81C5797B
  Port:  0-85000192

Update using bmputil

Automatic Update

This is the recommended procedure.

Note

This procedure is currently only supported by the native hardware. Third party hardware running Black Magic Firmware is not currently supported and the appropriate firmware has to be manually built. Refer to the Manual Update proceedure for instructions.

Run update

To upgrade the firmware on the connected Black Magic Probe all that should be necessary is running:

bmputil-cli probe update

And follow the instructions.

If you would like to update the firmware to the latest release candidate you can run the following:

bmputil-cli probe update --use-rc

Manual Update

This procedure is necessary when the host platform is not the native hardware. We currently do not offer an automatic update path for third party hardware.

This is also the procedure to follow if you have some other reason to build the firmware manually. For example, if you are adding new hardware support.

Download or build the firmware

Download or compile the Black Magic Debug (BMD) firmware. Regarding firmware selection:

  • You can find the newest pre-built binaries on the GitHub Release Page.

  • You can download cutting edge binaries built with every commit to the main branch here. When using the daily builds

  • expect breaking changes. Please report issues on our issue page or ask on our Discord server.

  • You can also build your own firmware from the cloned sources. Follow the build instructions in the project README.

Flash Using bmputil

To flash a downloaded or manually built binary, the resulting .elf file can be provided to the bmputil-cli probe update command.

bmputil-cli probe update blackmagic-binary.elf

Update using other tools

Besides bmputil you can also update the firmware on your Black Magic Probe using dfu-util or stlink-tool. Both can be useful if you have trouble getting bmputil to work on your system, your Black Magic host platform is not the native platform, or your platform is not supported by bmputil.

dfu-util on Linux/macOS

Install dfu-util. On macOS you can use homebrew, macports or fink depending on your preferred package manager. You will need version 0.8.0 or greater to support the dfuse commands.

Plug the Black Magic Probe into your computer and run the following command:

sudo dfu-util -d 1d50:6018,:6017 -s 0x08002000:leave -D blackmagic-native.bin

To upgrade non-native hardware see the READMEs of the different platforms on GitHub.

Note

If dfu-util fails to switch your BMP into bootloader mode, or you feel like you might have bricked your BMP, you can also plug in your BMP while holding down the button. This will force the BMP to stay in the bootloader on power up.

dfu-util on Windows

Download the Windows release of dfu-util.

Plug the Black Magic Probe into your computer and run the following command:

dfu-util.exe -d 1d50:6018,:6017 -s 0x08002000:leave -D blackmagic.bin

To upgrade non-native hardware see the readme of the different platforms on GitHub.

You may need use Zadig to install the WinUSB driver. Both PID 0x6017 and 0x6018 need to be known to Zadig.

Note

On first run Zadig may not see the 6017 PID. Once the dfu exe runs and detaches the device, it should appear in Zadig. Install the WinUSB driver on it and re-run the dfu exe.

Note

If dfu-util fails to switch your BMP into bootloader mode, or you feel like you might have bricked your BMP, you can also plug in your BMP while holding down the button. This will force the BMP to stay in the bootloader on power up.

The firmware on an ST-Link can be upgraded using blackmagic-debug/stlink-tool.

To upgrade, run the following command:

stlink-tool blackmagic.bin

Note

This software upgrades the firmware of the ST-Link probe, not the firmware of a target connected to the probe. Therefore please ensure you want to upgrade the firmware of the ST-Link probe, and use a blackmagic.bin file built specifically for ST-Link.

The firmware on an ST-Link can be upgraded using blackmagic-debug/stlink-tool.

The linked repository is forked from UweBonnes/stlink-tool, which in turn is a fork from jeanthom/stlink-tool.

To upgrade, run the following command:

stlink-tool blackmagic.bin

Note

This software upgrades the firmware of the ST-Link probe, not the firmware of a target connected to the probe. Therefore please ensure you want to upgrade the firmware of the ST-Link probe, and use a blackmagic.bin file built specifically for ST-Link.