调试探针Debug-Probe

关于调试探针

树莓派调试探针（Debug Probe）是一款 USB 设备，提供 UART 串行端口和标准 Arm 串行线调试 (SWD) 接口。该探针专为方便、无焊、即插即用的调试而设计。它具有以下功能：

• USB 至 ARM 串行线调试 (SWD) 端口
• USB 至 UART 桥接器
• 兼容 CMSIS-DAP 标准
• 可与 OpenOCD 和其他支持 CMSIS-DAP 的工具配合使用
• 开源、易于升级的固件

注意

有关树莓派三针调试连接器的更多信息，请参阅规范。

这样就可以在 Windows、macOS 和 Linux 等平台上轻松使用 Raspberry Pi Pico，这些平台缺乏 GPIO 头，无法直接连接到 Pico 的串行 UART 或 SWD 端口。

调试探针

该探针的标称 I/O 电压为 3.3V。

调试探针随附一条 USB 电源线和三条调试线：

• 三针 JST-SH 连接器转 3 针 JST-SH 连接器电缆
• 三针 JST-SH 连接器转 0.1 英寸接头（母头）
• 三针 JST-SH 连接器转 0.1 英寸接头（公头）

两根 0.1 英寸针座电缆的颜色如下--用于面包板（公）或直接连接到带针座针脚（母）的电路板：

橙色
  TX/SC（探针输出）

黑色
  接地

黄色
  RX/SD（探针或 I/O 输入）

配备三针JST-SH连接器的线缆专为标准三针连接器接口设计，该接口用于新型树莓派主板的SWD调试端口和UART连接器。

注意

当目标设备由独立电源或计算机供电时，连接信号线前务必建立公共参考电位。请先切断目标设备电源，或在目标设备与树莓派调试探针间连接GND接地线；接地完成后方可连接RX、TX、SC和SD信号线。两系统间的电压差可能导致探针损坏。

调试探针有五个 LED 灯，其中一个红色 LED 灯指示电源，另外四个指示活动的 LED 灯分别是

注意

OpenOCD 会在目标连接时打开两个 DAP LED 指示灯，并在调用 DAP_DISCONNECT 时关闭它们。

开始

根据您的设置，有几种方法可以将调试探针连接到 Pico 系列设备。下面，我们将调试探针连接到 Raspberry Pi Pico H，它有一个较新的用于 SWD 的三针 JST-SH 连接器。

译注：这里插入Youtube视频

连接以下设备

• 调试探针 "D "连接器连接 Pico H SWD JST 连接器
• 调试探针 "U "连接器的三针 JST 连接器与 0.1 英寸针座（公头）连接
  • 调试探针 RX 连接到 Pico H TX 引脚
  • 调试探针 TX 连接到 Pico H RX 引脚
  • 调试探针 GND 连接至 Pico H GND 引脚

注意

如果您拥有非 H 型 Pico 或 Pico W（无 JST-SH 连接器），仍可将其连接至调试探针。将一个公连接器焊接到电路板上的 SWCLK、GND 和 SWDIO 针座引脚上。使用调试探针随附的备用 3 针 JST-SH 连接器转 0.1 英寸接头（母头）电缆，连接至调试探针 "D "端口。将 Pico 或 Pico W 上的 SWCLK、GND 和 SWDIO 分别连接至调试探针的 SC(橙色)、GND(黑色) 和 SD(黄色) 引脚。

安装工具

要使用调试探针，需要安装OpenOCD和GNU调试器（GDB）。集成开发环境（IDE）也可能派上用场。

在Raspberry Pi操作系统、大多数Linux发行版、macOS和Microsoft Windows上，建议安装我们的VS Code扩展。该扩展包包含OpenOCD、ARM工具链、GDB以及Pico系列微控制器的寄存器定义。

请参阅我们的指南 Raspberry Pi Pico 入门的第 3 章。

或者，可以按照指南中的附录 C 手动安装工具。

注意

不建议在 Windows 上手动安装这些工具。

启动调试会话

调试探针允许您通过SWD端口和OpenOCD加载二进制文件：您无需每次将新二进制文件推送到Pico时都拔下并按住BOOTSEL按钮。使用调试探针上传新二进制文件是一个完全无需手动操作的过程。

随后使用GDB对Pico上运行的二进制文件进行调试。

我们建议使用 Raspberry Pi Pico VSCode 扩展，该扩展集成了 OpenOCD 和 GDB 的使用，用于上传和调试程序。有关更多信息，请参阅 Raspberry Pi Pico 入门 的第 4 章。

独立程序上传

构建二进制文件后

sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "program blink.elf verify reset exit"

注意

使用调试探针上传二进制文件时，使用的是 ELF 版本的文件，而不是拖放时使用的 UF2 文件。

独立调试会话

这将使用 openocd 服务器模式，并连接 GDB，使您能够通过控制台界面设置断点并进行单步调试。

重要

要进行调试，必须将二进制文件编译为 Debug 而非 Release 编译类型，例如

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

在调试编译中，当你在调试器下运行程序时会得到更多信息，因为编译器在编译程序时会告诉 GDB 你的程序在做什么。

注意

对于非树莓派计算机，需要使用能够调试 ARM 处理器的 GDB 变体。根据您的操作系统和设备，选择以下其中一种替代方案：

• 在 Linux 设备上，使用 gdb-multiarch。
• 在 macOS 和 Windows 设备上，使用来自 Arm 官网 工具链中的 arm-none-eabi-gdb。

要启动 OpenOCD 服务器，请运行以下命令：

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

然后打开第二个终端窗口，切换到包含已构建二进制文件的目录，并启动调试器将其连接到 OpenOCD 服务器：

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

串行连接

确保调试探针与树莓派Pico的 UART 引脚相连。

树莓派Pico UART0 的默认引脚如下：

默认 UART0	物理引脚	GPIO 引脚
GND	3	N/A
UART0_TX	1	GP0
UART0_RX	2	GP1

连接后，树莓派Pico的 UART 通信将由调试探针转发到计算机，并显示为 CDC UART。在树莓派上，该串口显示为 /dev/ttyACM0；在其他平台上，该串口将以不同方式显示（例如，在 macOS 上显示为 /dev/cu.usbmodemXXXX）。

如果尚未安装 minicom，则应安装：

sudo apt install minicom

并打开串行端口：

minicom -b 115200 -o -D /dev/ttyACM0

提示

要退出 minicom，请使用 CTRL-A，然后按 X。

要测试串行通信，您可以构建并上传 "Hello World "示例应用程序。

将目录更改为 pico-examples 树中的 hello_world 目录，然后运行 make。然后，使用 openocd 将其上传到 树莓派Pico。有关构建 hello_serial 示例程序的完整步骤，请参阅《树莓派Pico 入门》第 4 章。

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

打开 minicom 后，您将看到 "Hello, world!"打印到控制台。

对于支持它的终端程序，USB 串行 UART 的描述会在 USB 设备描述中公布。

该描述中的唯一序列号意味着在 Windows 系统中，每个设备的 COM 端口编号都是 "粘性 "的，这将允许您编写 udev 规则，将命名的设备节点与特定调试探针关联起来。

RTT 连接

您还可以配置应用程序通过 SWD 接口直接发送输出，而无需 UART 连接。这使用了一种称为 Segger 实时传输（RTT）的机制。

要实现这一点，您必须在应用程序中启用 RTT stdio 驱动程序，并通过调试探针连接到 RTT。

注意

您必须使用应用程序的调试构建版本才能通过 SWD 发送输出。

启用 RTT stdio 驱动程序

C/C++ SDK 提供了用于 RTT 的 stdio 驱动程序，就像用于 UART 和 USB 的驱动程序一样。有关更多信息，请参阅 pico_stdio_rtt。

要在构建中启用该驱动程序，请在 CMakeLists.txt 文件中包含以下行（或链接到 pico_stdio_rtt，效果相同）：

pico_enable_stdio_rtt(<your_project_name> 1)

调用 stdio_init_all() 后，应用程序使用 printf() 发送的任何输出都将发送到 RTT。如果您还想将输出复制到 UART，也可以同时启用该功能。

从 VSCode 连接到 RTT

RTT 受 OpenOCD 和 VSCode Cortex-Debug 扩展支持；这两者都是作为安装工具的一部分设置的。

要为调试会话启用 RTT，请在其启动配置中添加一个部分。打开项目的 .vscode 文件夹，并将以下行添加到 launch.json 文件中，将它们放在适当的配置部分，例如 "Pico Debug (Cortex-Debug)"：

"rttConfig": {
    "enabled": true,
    "address": "auto",
    "decoders": [
        {
            "label": "",
            "port": 0,
            "type": "console"
        }
    ]
}

有关更多信息，请参阅 cortex-debug 启动属性。

如果您现在在启用了 RTT 的应用程序上启动调试会话并打开 TERMINAL 选项卡，您将在右侧看到一个列表，其中包括 RTT Ch:0 console。选择它以查看应用程序发送到 pico_stdio_rtt 驱动程序的输出。

在独立调试会话中连接到 RTT

如果您按照独立调试会话中所述使用独立调试会话，可以通过完成以下步骤连接到 RTT：

1. 构建并上传启用了 RTT 的应用程序。
2. 连接调试探针并在单独的终端中启动 openocd 和 gdb。有关更多信息，请参阅独立调试会话。
3. 在 gdb 提示符下输入以下命令：

(gdb) target remote localhost:3333
(gdb) monitor reset init
(gdb) monitor rtt setup 0x20000000 2048 "SEGGER RTT"
(gdb) monitor rtt start
(gdb) monitor rtt server start 60000 0
(gdb) continue

注意

以 monitor 为前缀的 gdb 命令会传递给 openocd。有关此处使用的命令的更多信息，请参阅 OpenOCD 手册的第 15.6 节。

OpenOCD 会在目标上搜索 RTT 控制块，然后在端口 60000 上创建本地 TCP 套接字。

4. 打开第三个窗口，使用 nc（netcat）或类似工具连接到本地套接字，以查看应用程序的 RTT 输出：

nc localhost 60000

更新调试探针的固件

调试探针的固件是由 Raspberry Pi 发布的 UF2 文件。

调试探头固件的最新版本是 2.2.3。如果您运行的是旧版本，或者不小心覆盖了调试探针上的固件，您可以在 the debugprobe GitHub repository 中找到最新版本的固件。

要检查调试探针的固件版本，请运行：

lsusb -v -d 2e8a:000c | grep bcdDevice

对于固件版本 2.2.3 的调试探针，将显示 bcdDevice 2.23。

提示

openocd 报告的 Info : CMSIS-DAP: FW Version = 2.0.0 仅指 CMSIS-DAP 协议版本（与调试探针固件版本不同）。

更新调试探针固件版本：

1. 从最新版本中下载 debugprobe.uf2。
2. 捏住并取下调试探针外壳的顶部。
3. 将调试探针插入计算机时按住 BOOTSEL 按钮，挂载名为 "RPI-RP2 "的卷。
4. 将 debugprobe.uf2 复制到 "RPI-RP2" 卷上。文件复制到设备后，卷将自动卸载。
5. 调试探头将重新启动，并运行更新版的调试探头固件。现在可以进行调试了。

示意图

提供调试探针的原理图和机械图纸：

• 原理图 (PDF)
• 机械图(https://datasheets.raspberrypi.com/debug/raspberry-pi-debug-probe-mechanical-drawing.pdf) (PDF)

原理图上显示的测试点 (TP) 位置如下图所示。

---

中文翻译版以英文版相同知识授权方式共享：CC-BY-SA 4.0。