Skip to content

Commit 3cf4936

Browse files
author
Alasdair Allan
authored
Merge pull request raspberrypi#2784 from raspberrypi/debug-probe
Add documentation for Debug Probe
2 parents d61cad6 + bf316e9 commit 3cf4936

15 files changed

+348
-0
lines changed

‎documentation/asciidoc/microcontrollers/debug-probe.adoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
include::debug-probe/introduction.adoc[]
2+
3+
include::debug-probe/installing-tools.adoc[]
4+
5+
include::debug-probe/getting-started.adoc[]
6+
7+
include::debug-probe/swd-connection.adoc[]
8+
9+
include::debug-probe/uart-connection.adoc[]
10+
11+
include::debug-probe/updating-firmware.adoc[]

‎documentation/asciidoc/microcontrollers/debug-probe/getting-started.adoc

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
== Getting started
2+
3+
image:images/labelled-wiring.png[width="100%"]
4+
5+
Depending on your setup, there are several ways to wire the Debug Probe to a xref:raspberry-pi-pico.adoc[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.
6+
7+
Here we have connected:
8+
9+
* The Debug Probe "D" connector to Pico H SWD JST connector
10+
* The Debug Probe "U" connector has the three-pin JST connector to 0.1-inch header
11+
** Debug Probe RX connected to Pico H TX pin
12+
** Debug Probe TX connected to Pico H RX pin
13+
** Debug Probe GND connected to Pico H GND pin
14+
15+
image:images/wiring.png[width="70%"]
16+

‎documentation/asciidoc/microcontrollers/debug-probe/images/debug-probe.jpg

164 KB
Loading

‎documentation/asciidoc/microcontrollers/debug-probe/images/description.jpg

138 KB
Loading

‎documentation/asciidoc/microcontrollers/debug-probe/images/labelled-wiring.png

24.7 MB
Loading

‎documentation/asciidoc/microcontrollers/debug-probe/images/the-probe.png

139 KB
Loading

‎documentation/asciidoc/microcontrollers/debug-probe/images/wiring-real.jpg

3.45 MB
Loading

‎documentation/asciidoc/microcontrollers/debug-probe/images/wiring.png

194 KB
Loading

‎documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
== Installing Tools
2+
3+
Before we get started we need to install some tools.
4+
5+
=== Installing OpenOCD
6+
7+
You need to install OpenOCD.
8+
9+
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.
10+
11+
==== Linux (and Raspberry Pi)
12+
13+
On Raspberry Pi OS you can install `openocd` directly from the command line.
14+
15+
----
16+
$ sudo apt install openocd
17+
----
18+
19+
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 distrbution installs an older version, or require SMP support, you can build and install `openocd` from source.
20+
21+
Start by installing needed dependencies,
22+
23+
----
24+
$ sudo apt install automake autoconf build-essential texinfo libtool libftdi-dev libusb-1.0-0-dev
25+
----
26+
27+
and then build OpenOCD.
28+
29+
----
30+
$ git clone https://github.com/raspberrypi/openocd.git --branch rp2040 --depth=1 --no-single-branch
31+
$ cd openocd
32+
$ ./bootstrap
33+
$ ./configure
34+
$ make -j4
35+
$ sudo make install
36+
----
37+
38+
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 https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting Started with Raspberry Pi Pico] for more details.
39+
40+
==== macOS
41+
42+
Install https://brew.sh/[Homebrew] if needed,
43+
44+
----
45+
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
46+
----
47+
48+
and then OpenOCD.
49+
50+
----
51+
$ brew install open-ocd
52+
----
53+
54+
Alternatively you can install needed dependencies,
55+
56+
----
57+
$ brew install libtool automake libusb wget pkg-config gcc texinfo
58+
----
59+
60+
and build OpenOCD from source.
61+
62+
----
63+
$ cd ~/pico
64+
$ git clone https://github.com/raspberrypi/openocd.git --branch rp2040 --depth=1
65+
$ cd openocd
66+
$ export PATH="/usr/local/opt/texinfo/bin:$PATH"
67+
$ ./bootstrap
68+
$ ./configure --disable-werror
69+
$ make -j4
70+
$ sudo make install
71+
----
72+
73+
NOTE: If you are using a newer Arm-based Mac, the path to `texinfo` will be `/opt/homebrew/opt/texinfo/bin`.
74+
75+
NOTE: Unfortunately `disable-werror` is needed because not everything compiles cleanly on macOS
76+
77+
==== MS Windows
78+
79+
An OpenOCD Windows package is available https://github.com/raspberrypi/openocd/releases/tag/latest[for download].
80+
81+
Alternatively to you can build OpenOCD using https://www.msys2.org/[MSYS2]. Download and run the installer, and then update the package database and core system packages,
82+
83+
----
84+
$ pacman -Syu
85+
----
86+
87+
NOTE: If MSYS2 closes, start it again (making sure you select the 64-bit version) and run `pacman -Su` to finish the update.
88+
89+
Install required dependencies,
90+
91+
----
92+
$ pacman -S mingw-w64-x86_64-toolchain git make libtool pkg-config autoconf automake texinfo
93+
mingw-w64-x86_64-libusb
94+
----
95+
96+
Pick all when installing the `mingw-w64-x86_64` toolchain by pressing ENTER.
97+
98+
Close MSYS2 and reopen the 64-bit version to make sure the environment picks up GCC,
99+
100+
----
101+
$ git clone https://github.com/raspberrypi/openocd.git --branch rp2040 --depth=1
102+
$ cd openocd
103+
$ ./bootstrap
104+
$ ./configure --disable-werror
105+
$ make -j4
106+
----
107+
108+
NOTE: Unfortunately `disable-werror` is needed because not everything compiles cleanly on Windows
109+
110+
NOTE: Manual installation of `openocd` on MS Windows is not recommended.
111+
112+
=== Installing GDB
113+
114+
We also need to install the GNU debugger (GDB).
115+
116+
==== Linux (and Raspberry Pi)
117+
118+
Install `gdb-multiarch`.
119+
120+
----
121+
$ sudo apt install gdb-multiarch
122+
----
123+
124+
==== macOS
125+
126+
Install https://brew.sh/[Homebrew] if needed,
127+
128+
----
129+
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
130+
----
131+
132+
then install `gdb`.
133+
134+
----
135+
$ brew install gdb
136+
----
137+
138+
NOTE: You can safely ignore the request for "special privileges" messages on installation.
139+
140+
IMPORTANT: If you have an Arm-based (M1-based) Mac `gdb` is not available via Homebrew, instead you will either have to https://gist.github.com/m0sys/711d0ec5e52102c6ba44451caf38bd38[install it from source] or use `lldb` instead of `gdb`. At this time there is https://inbox.sourceware.org/gdb/3185c3b8-8a91-4beb-a5d5-9db6afb93713@Spark/[no official support] from the developers for running GDB on Arm-based Macs. Suppport for GDB can be found on the https://inbox.sourceware.org/gdb/[GDB mailing list] on Sourceware.org. `lldb` is installed as part of the Xcode Command Line Tools.
141+
142+
==== MS Windows
143+
144+
GDB is available as part of our https://github.com/raspberrypi/pico-setup-windows[Pico setup for Windows] installer.
145+
146+
Alternatively information about manual installation can be found in Chapter 9 and Appendix A of our https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting Started with Raspberry Pi Pico] book.
147+
148+
NOTE: Manual installation of GDB on Windows is not recommended.

‎documentation/asciidoc/microcontrollers/debug-probe/introduction.adoc

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
== About the Debug Probe
2+
3+
image::images/debug-probe.jpg[width="100%"]
4+
5+
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:
6+
7+
* USB to ARM https://developer.arm.com/documentation/ihi0031/a/The-Serial-Wire-Debug-Port--SW-DP-/Introduction-to-the-ARM-Serial-Wire-Debug--SWD--protocol[Serial Wire Debug] (SWD) port
8+
* USB to UART bridge
9+
* Compatible with the https://developer.arm.com/documentation/101451/0100/About-CMSIS-DAP[CMSIS-DAP] standard
10+
* Works with https://openocd.org/[OpenOCD] and other tools supporting CMSIS-DAP
11+
* Open source, easily upgradeable firmware
12+
13+
NOTE: For more information on the Raspberry Pi three-pin debug connector see the https://rptl.io/debug-spec[specification].
14+
15+
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.
16+
17+
=== The Debug Probe
18+
19+
The probe operates at 3.3V nominal I/O voltage.
20+
21+
image:images/the-probe.png[width="70%"]
22+
23+
Included with the Debug Probe is a USB power cable and three debug cables:
24+
25+
* 3-pin JST connector to 3-pin JST connector cable
26+
* 3-pin JST connector to 0.1-inch header (female)
27+
* 3-pin JST connector to 0.1-inch header (male)
28+
29+
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:
30+
31+
Orange:: TX/SC (Output from Probe)
32+
Black:: GND
33+
Yellow:: RX/SD (Input to Probe or I/O)
34+
35+
While the cable with 3-pin JST connectors is intended to be used with the https://rptl.io/debug-spec[standard 3-pin connector] which newer Raspberry Pi boards use for the SWD debug port and UART connectors.

0 commit comments

Comments
 (0)