ER-0046

Description

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.

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  [ https://rptl.io/debug-spec ].

This makes it easy to use a Raspberry Pi Pico on non-Raspberry Pi platforms such as Windows, Mac, and “normal” Linux computers, where you don’t have a GPIO header to connect directly to the Pico’s serial UART or SWD port.

Specifications

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

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

• 3-pin JST connector to 3-pin JST connector cable
• 3-pin JST connector to 0.1-inch header (female)
• 3-pin JST 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 3-pin JST connectors is intended to be used with the standard 3-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

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

Getting Start

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

• The Debug Probe "D" connector to Pico H SWD JST connector
• The Debug Probe "U" connector has the three-pin JST 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 an "original" Raspberry Pi Pico, or Pico W, without a JST connector, you can still connect it to a Debug Probe. To do so, solder a male connector to the SWDCLK, SWDIO and GND header pins on the board, and connect them to the Debug Probe "D" connector using the alternate 3-pin JST connector to 0.1-inch header (female) cable included with the Debug Probe.

Installing Tools

Before we get started we need to install some tools.

• Installing OpenOCD

You need to install OpenOCD.

NOTE
SMP support for debugging on both RP2040 cores is not yet available in the release version of openocd. However, support is available in the rp2040 branch and will be enabled if you build from source.

• Linux (and Raspberry Pi)

On Raspberry Pi OS you can install openocd directly from the command line. sudo apt install openocd
You need to be running OpenOCD version 0.11.0 or 0.12.0 to have support for the Debug Probe. If you’re not running Raspberry Pi OS, or your distribution installs an older version, or require SMP support, you can build and install openocd from source.

Start by installing needed dependencies,

sudo apt install automake autoconf build-essential texinfo libtool libftdi-dev libusb-1.0-0-dev

and then build OpenOCD.

$ git clone https://github.com/raspberrypi/openocd.git --branch rp2040 --depth=1 --no-single-branch
$ cd openocd
$ ./bootstrap
$ ./configure
$ make -j4
$ sudo make install

---

NOTE
If you are building on a Raspberry Pi you can also pass --enable-sysfsgpio --enable-bcm2835gpio when you ./configure to allow bit-banging SWD via the GPIO pins. See Chapters 5 and 6 of Getting Started with Raspberry Pi Pico for more details.

• macOS

Install Homebrew if needed. [ https://brew.sh/ | Homebrew ]

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

and then OpenOCD.

$ brew install open-ocd

Alternatively you can install needed dependencies,

$ brew install libtool automake libusb wget pkg-config gcc texinfo

and build OpenOCD from source.

$ cd ~/pico
$ git clone https://github.com/raspberrypi/openocd.git --branch rp2040 --depth=1
$ cd openocd
$ export PATH="/usr/local/opt/texinfo/bin:$PATH"
$ ./bootstrap
$ ./configure --disable-werror
$ make -j4
$ sudo make install

---

NOTE
If you are using a newer Arm-based Mac, the path to texinfo will be /opt/homebrew/opt/texinfo/bin.

NOTE
Unfortunately disable-werror is needed because not everything compiles cleanly on macOS

• MS Windows

A standalone OpenOCD Windows package is available [1]. Alternatively it will be installed as part of our Pico setup for Windows installer package. [ https://github.com/raspberrypi/pico-setup-windows/releases/latest ].

But, if you want to, you can also build OpenOCD from source using MSYS2 [ https://www.msys2.org/ ]. Go ahead and download and run the MSYS2 installer, and then update the package database and core system packages,

$ pacman -Syu

NOTE
If MSYS2 closes, start it again (making sure you select the 64-bit version) and run pacman -Su to finish the update.

Install required dependencies,

$ pacman -S mingw-w64-x86_64-toolchain git make libtool pkg-config autoconf automake texinfo
mingw-w64-x86_64-libusb

Pick all when installing the mingw-w64-x86_64 toolchain by pressing ENTER.

Close MSYS2 and reopen the 64-bit version to make sure the environment picks up GCC,

$ git clone https://github.com/raspberrypi/openocd.git --branch rp2040 --depth=1
$ cd openocd
$ ./bootstrap
$ ./configure --disable-werror
$ make -j4

---

NOTE
Unfortunately disable-werror is needed because not everything compiles cleanly on Windows
Manual installation of openocd on MS Windows is not recommended.

• Installing GDB

We also need to install the GNU debugger (GDB).

Linux (and Raspberry Pi) Install gdb-multiarch.

$ sudo apt install gdb-multiarch

• macOS

Install Homebrew if needed,

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

then install gdb.

$ brew install gdb

NOTE
You can safely ignore the request for "special privileges" messages on installation.

• • • IMPORTANT ***

If you have an Arm-based (M1-based) Mac gdb is not available via Homebrew, instead you will either have to install it from source [2] or use lldb instead of gdb. At this time there is no official support [3] from the developers for running GDB on Arm-based Macs. Support for GDB can be found on the GDB mailing list [ https://inbox.sourceware.org/gdb/ ] on Sourceware.org. lldb is installed as part of the Xcode Command Line Tools.

• MS Windows

GDB is available as part of our Pico setup for Windows installer [ https://github.com/raspberrypi/pico-setup-windows/releases/latest ]. It is also included in the Arm GNU Toolchain Downloads.[ https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ]

Alternatively information about manual installation can be found in Chapter 9 and Appendix A of our Getting Started with Raspberry Pi Pico book.[ https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf ]

NOTE
Manual installation of GDB on Windows is not recommended.

Serial Wire Debug (SWD)

Serial Wire Debug (SWD) is a two-pin interface (SWDIO and SWCLK)[ https://developer.arm.com/documentation/101761/1-0/Debug-and-trace-interface/Serial-Wire-Debug-signals ] alternative to the JTAG four- or five-pin debugging interface standard.

• Uploading new programs to your Pico

The Pico 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 uploading new binaries is an entirely hands off affair.

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.

• Debugging with SWD

It’ll also let you use openocd in server mode, and connect GDB, which gives you break points and “proper” debugging.

• • • 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.

See Chapter 6 of Getting started with Raspberry Pi Pico for more information [4].

• Run OpenOCD 'server' ready to attach GDB to:

$ 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 GDB.

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

NOTE
On non-Raspberry Pi Linux platforms you should invoke GDB by using gdb-multiarch blink.elf.

NOTE
If you are on an Arm-based (M1) Mac without gdb, you can make use of lldb, which is installed along with the XCode Command Line Tools. The syntax used by lldb is slightly different to gdb.
<pre>
----

<pre>
$ lldb blink.elf
(lldb) gdb-remote 3333
(lldb) process plugin packet monitor reset
(lldb) continue

Serial connections

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