We use some essential cookies to make our website work.

We use optional cookies, as detailed in our cookie policy, to remember your settings and understand how you use our website.

Raspberry Pi Debug Probe

About the Debug Probe

Edit this on GitHub

debug probe

The Raspberry Pi Debug Probe is a USB device that provides both a UART serial port and a standard Arm Serial Wire Debug (SWD) interface. The probe is designed for easy, solderless, plug-and-play debugging. It has the following features:

  • USB to ARM Serial Wire Debug (SWD) port

  • USB to UART bridge

  • Compatible with the CMSIS-DAP standard

  • Works with OpenOCD and other tools supporting CMSIS-DAP

  • Open source, easily upgradeable firmware

Note
 For more information on the Raspberry Pi three-pin debug connector see the specification.

This makes it easy to use a Raspberry Pi Pico on platforms such as Windows, macOS, and Linux that lack a GPIO header to connect directly to the Pico’s serial UART or SWD port.

The Debug Probe

The probe operates at 3.3V nominal I/O voltage.

the probe

Included with the Debug Probe is a USB power cable and three debug cables:

  • three-pin JST-SH connector to 3-pin JST-SH connector cable

  • three-pin JST-SH connector to 0.1-inch header (female)

  • three-pin JST-SH connector to 0.1-inch header (male)

The two 0.1-inch header cables — intended for breadboard (male) or direct connection to a board with header pins (female) — are coloured as below:

Orange

TX/SC (Output from Probe)

Black

GND

Yellow

RX/SD (Input to Probe or I/O)

While the cable with three-pin JST-SH connectors is intended to be used with the standard three-pin connector which newer Raspberry Pi boards use for the SWD debug port and UART connectors.

The Debug Probe has five LEDs, a red LED to indicate power, and four more activity indicator LEDs

debug leds
Note
 OpenOCD switches both DAP LEDs on when the target is connected, and turns them off when it calls DAP_DISCONNECT.

Getting started

Edit this on GitHub

labelled wiring

Depending on your setup, there are several ways to wire the Debug Probe to a Pico-series device. Below, we connect the Debug Probe to a Raspberry Pi Pico H which has the newer three-pin JST-SH connector for SWD.

Connect the following:

  • The Debug Probe "D" port to Pico H SWD JST-SH connector

  • The Debug Probe "U" port, with the three-pin JST-SH connector to 0.1-inch header (male):

    • Debug Probe RX connected to Pico H TX pin

    • Debug Probe TX connected to Pico H RX pin

    • Debug Probe GND connected to Pico H GND pin

Note
 If you have a non-H Pico or Pico W (without a JST-SH connector) you can still connect it to a Debug Probe. Solder a male connector to the SWCLK, GND, and SWDIO header pins on the board. Using the alternate 3-pin JST-SH connector to 0.1-inch header (female) cable included with the Debug Probe, connect to the Debug Probe "D" port. Connect SWCLK, GND, and SWDIO on the Pico or Pico W to the SC, GND, and SD pins on the Debug Probe, respectively.

wiring

Install tools

Edit this on GitHub

To use the Debug Probe, OpenOCD and the GNU Project Debugger (GDB) are required. An Integrated Development Environment (IDE) may also be useful.

On Raspberry Pi OS, most Linux variants, macOS, and Microsoft Windows, it is recommended to install our VS Code extension. This extension bundles OpenOCD, ARM toolchains, GDB, and register definitions for Pico-series microcontrollers.

See Chapter 3 of our Getting Started with Raspberry Pi Pico guide.

Alternatively, tools can be manually installed by following Appendix C in the guide.

Note
 Manual installation of the tools on Windows is not recommended.

Starting a Debug Session

Edit this on GitHub

The Debug Probe will let you load binaries via the SWD port and OpenOCD: you will not need to unplug, and then push-and-hold, the BOOTSEL button every time you push a new binary to your Pico. Using the Debug Probe to upload new binaries is an entirely hands-off affair.

GDB is then used to debug the binary running on the Pico.

We recommend the use of the Raspberry Pi Pico VSCode extension, which integrates the use of OpenOCD and GDB, to upload and debug programs. See Chapter 4 of Getting started with Raspberry Pi Pico for more information.

Standalone program upload

Once you have built a binary:

$ sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "program blink.elf verify reset exit"
Note
 When you use the Debug Probe to upload a binary the ELF version of the file is used, not the UF2 file that you would use when you drag-and-drop.

Standalone debug session

This will use openocd in server mode, and connect GDB, which gives you breakpoints and single-step over a console interface.

Important

To allow debugging, you must build your binaries as Debug rather than Release build type, e.g.

$ cd ~/pico/pico-examples/
$ rm -rf build
$ mkdir build
$ cd build
$ export PICO_SDK_PATH=../../pico-sdk
$ cmake -DCMAKE_BUILD_TYPE=Debug ..
$ cd blink
$ make -j4

In a debug build you will get more information when you run it under the debugger, as the compiler builds your program with the information to tell GDB what your program is doing.
Note
 For computers that are not Raspberry Pis, a variant of GDB that can debug ARM processors is required. Use one of the following alternatives depending on your operating system and device: * On Linux devices, use gdb-multiarch. * On macOS and Windows devices, use arm-none-eabi-gdb from the toolchain on Arm’s website

To start an OpenOCD server, run the following command:

$ sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000"

Then open a second terminal window, switch to the directory containing your built binary, and start a debugger to attach it to the OpenOCD server:

$ gdb blink.elf
> target remote localhost:3333
> monitor reset init
> continue

Serial connections

Edit this on GitHub

Ensure that the Debug Probe is connected to the UART pins of your Raspberry Pi Pico.

wiring

The default pins for Raspberry Pi Pico UART0 are as follows:

Default UART0 Physical Pin GPIO Pin

GND

3

N/A

UART0_TX

1

GP0

UART0_RX

2

GP1

Once connected, traffic over the Raspberry Pi Pico’s UART will be relayed to your computer by the Debug Probe and exposed as a CDC UART. On a Raspberry Pi this will show up as /dev/ttyACM0; on other platforms this serial port will show up differently (e.g. on macOS it will appear as /dev/cu.usbmodemXXXX).

If you have not already done so you should install minicom:

$ sudo apt install minicom

and open the serial port:

$ minicom -b 115200 -o -D /dev/ttyACM0
Tip
 To exit minicom, use CTRL-A followed by X.

To test serial communication you can build and upload the "Hello World" example application.

Change directory into the hello_world directory inside the pico-examples tree, and run make. Afterwards, you can upload it to your Raspberry Pi Pico using openocd. For a full walkthrough of building the hello_serial example program, see Chapter 4 of Getting started with Raspberry Pi Pico.

$ cd pico-examples
$ mkdir build
$ cd build
$ export PICO_SDK_PATH=../../pico-sdk
$ cmake ..
$ cd hello_world/serial
$ make -j4
$ sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "program hello_serial.elf verify reset exit"
$ minicom -b 115200 -o -D /dev/ttyACM0

On opening minicom you should see "Hello, world!" printed to the console.

For terminal programs that support it, a description of the USB serial UART is advertised in the USB device description.

description

The unique serial number in this description means that on Windows your COM port numbering is "sticky" per device, and will allow you to write udev rules to associate a named device node with a particular Debug Probe.

Updating the firmware on the Debug Probe

Edit this on GitHub

Firmware for the Debug Probe is available as a UF2 file distributed by Raspberry Pi.

The latest version of the Debug Probe firmware is version 2.2. If you’re running an older version, or if you have accidentally overwritten the firmware on your Debug Probe, you can find the latest release of the firmware in the debugprobe GitHub repository.

Download debugprobe.uf2 from the latest release.

Pinch to remove the top of the Debug Probe enclosure.

Push and hold the BOOTSEL button as you plug the Debug Probe into your computer to mount a volume called "RPI-RP2".

Copy debugprobe.uf2 onto the "RPI-RP2" volume. The volume will dismount automatically after the file finishes copying onto the device.

Your Debug Probe will reboot and now runs an updated version of the Debug Probe firmware. It is now ready for debugging.

Schematics

Edit this on GitHub

Schematics and mechanical drawing of the Debug Probe are available:

The test point (TP) shown on the schematics are located as shown in the diagram below.

debug probe tps
On this page

You can view and edit the Raspberry Pi documentation source on Github. Please read our usage and contributions policy before you make a Pull Request.

Raspberry Pi documentation is copyright © 2012-2025 Raspberry Pi Ltd and is licensed under a Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA) licence.

Some content originates from the eLinux wiki, and is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported licence.

The terms HDMI, HDMI High-Definition Multimedia Interface, HDMI trade dress and the HDMI Logos are trademarks or registered trademarks of HDMI Licensing Administrator, Inc