树莓派调试套件(Raspberry Pi Debug Probe)
调试套件简介

树莓派调试套件(Raspberry Pi Debug Probe)是一款同时提供 UART 串口和标准 Arm 串行线调试(SWD)接口的 USB 设备。该调试套件专为简单、免焊接、即插即用的调试而设计,具有以下功能:
注意
有关树莓派三针调试连接器的更多信息,请参阅规格说明。
这使得在 Windows、macOS 和 Linux 等没有 GPIO 排针、无法直连 Pico 串口 UART 或 SWD 端口的平台上,也能轻松使用树莓派 Pico。
调试套件本体
调试套件在标称 3.3V 的 I/O 电压下运行。

调试套件随附一根 USB 电源线和三根调试线:
三针 JST-SH 连接器转三针 JST-SH 连接器的电缆
三针 JST-SH 连接器转 0.1 英寸排针(母)的电缆
三针 JST-SH 连接器转 0.1 英寸排针(公)的电缆
两根 0.1 英寸排针电缆分别用于面包板(公头)或直接连接到带排针的板子(母头),颜色如下:
橙色:TX/SC(调试套件输出)
黑色:GND
黄色:RX/SD(输入到调试套件或 I/O)
带有三针 JST-SH 连接器的电缆,用于配合较新的树莓派主板在 SWD 调试端口和 UART 连接器上使用的标准三针连接器。
警告
当目标设备由独立的电源或计算机供电时,请在连接信号线之前确保两者有共同的参考地。要么先断开目标设备的电源,要么先在目标设备与树莓派调试套件之间连接 GND;待 GND 连接好之后,再连接 RX、TX、SC 和 SD。两个系统之间潜在的电压差可能损坏调试套件。
调试套件有五个 LED:一个红色 LED 指示电源,另外四个为活动指示 LED。

注意
当目标设备连接时,OpenOCD 会同时点亮两个 DAP LED,并在调用
DAP_DISCONNECT时将它们熄灭。
入门指南

根据你的实际配置,有多种方式可以将调试套件连接到 Pico 系列设备。下面的示例将调试套件连接到带有更新式三针 JST-SH SWD 连接器的树莓派 Pico H。
按如下方式连接:
将调试套件的 “D” 端口连接到 Pico H 的 SWD JST-SH 连接器
将调试套件的 “U” 端口通过三针 JST-SH 连接器转 0.1 英寸排针(公)的电缆连接:
调试套件的
RX连接到 Pico H 的TX引脚调试套件的
TX连接到 Pico H 的RX引脚调试套件的
GND连接到 Pico H 的GND引脚
注意
如果你使用的是不带 JST-SH 连接器的非 H 版 Pico 或 Pico W,仍然可以将其连接到调试套件。在板子的
SWCLK、GND和SWDIO排针上焊接一个公头连接器。使用调试套件随附的另一根三针 JST-SH 连接器转 0.1 英寸排针(母)的电缆,连接到调试套件的 “D” 端口。将 Pico 或 Pico W 上的SWCLK、GND和SWDIO分别连接到调试套件上的SC(橙色线)、GND(黑色线)和SD(黄色线)引脚。

安装工具
要使用调试套件,需要 OpenOCD 和 GNU 项目调试器(GDB)。集成开发环境(IDE)也可能对你有帮助。
在树莓派系统、大多数 Linux 变体、macOS 和 Microsoft Windows 上,我们建议你安装我们的 VS Code 扩展。该扩展捆绑了 OpenOCD、Arm 工具链、GDB 以及 Pico 系列微控制器的寄存器定义。
更多信息请参阅我们的《树莓派 Pico 入门指南》第 3 章。
或者,也可以按照该指南的附录 C 手动安装这些工具。
注意
不建议在 Windows 上手动安装这些工具。
开始调试会话
调试套件让你可以通过 SWD 端口和 OpenOCD 加载二进制文件:无需在每次向 Pico 推送新二进制文件时先拔下设备,再按住 BOOTSEL 按钮。使用调试套件上传新的二进制文件完全是自动化的。
随后使用 GDB 调试运行在 Pico 上的二进制文件。
我们推荐使用树莓派 Pico VSCode 扩展,它集成了 OpenOCD 和 GDB,可用于上传和调试程序。更多信息请参阅《树莓派 Pico 入门指南》第 4 章。
单独上传程序
构建好二进制文件后:
注意
当你使用调试套件上传二进制文件时,使用的是文件的 ELF 版本,而不是拖放时使用的 UF2 文件。
单独调试会话
这种方式会以服务器模式使用 openocd,并连接 GDB,从而通过控制台界面提供断点和单步调试。
重要
要进行调试,你必须以
Debug而非Release构建类型来构建二进制文件:
在调试构建中,当你在调试器下运行程序时,你会获得更多信息,因为编译器在构建程序时会带上告诉 GDB 你的程序正在做什么的信息。
注意
在非树莓派设备上,需要一个能够调试 Arm 处理器的 GDB 变体。请根据你的操作系统和设备选用以下替代方案:
在 Linux 设备上,使用
gdb-multiarch。在 macOS 和 Windows 设备上,使用来自 Arm GitLab 仓库工具链的
arm-none-eabi-gdb。
要启动 OpenOCD 服务器,请运行以下命令:
然后打开第二个终端窗口,切换到包含你构建的二进制文件的目录,并启动一个调试器,将其连接到 OpenOCD 服务器:
串行连接
确保调试套件已连接到树莓派 Pico 的 UART 引脚。

树莓派 Pico UART0 的默认引脚如下:
GND
3
不适用
UART0_TX
1
GP0
UART0_RX
2
GP1
连接后,树莓派 Pico UART 上的通信流量将由调试套件中继到你的计算机,并呈现为一个 CDC UART。在树莓派上,它会显示为 /dev/ttyACM0;在其他平台上,该串口的显示方式有所不同(例如在 macOS 上显示为 /dev/cu.usbmodemXXXX)。
如果你还没有安装 minicom,请先安装:
然后打开串口:
技巧
要退出
minicom,请先按 CTRL-A,再按 X。
要测试串行通信,你可以构建并上传 “Hello World” 示例应用程序。
进入 pico-examples 目录树中的 hello_world 目录并运行 make。随后你可以使用 openocd 将其上传到树莓派 Pico。构建 hello_serial 示例程序的完整流程请参阅《树莓派 Pico 入门指南》第 4 章。
打开 minicom 后,你会看到控制台上打印出 “Hello, world!”。
对于支持该功能的终端程序,USB 串口 UART 的描述信息会包含在 USB 设备描述中。

该描述中的唯一序列号意味着在 Windows 上,你的 COM 端口编号对每个设备是“粘性”的,你可以据此编写 udev 规则,将命名的设备节点与特定的调试套件关联起来。
RTT 连接
你还可以将应用程序配置为直接通过 SWD 接口发送输出,而无需 UART 连接。这使用了一种称为 Segger 实时传输(Real-Time Transport,RTT)的机制。
为此,你必须在应用程序中启用 RTT stdio 驱动,并使用调试套件连接到 RTT。
注意
必须使用应用程序的 调试构建,才能通过 SWD 发送输出。
启用 RTT stdio 驱动
C/C++ SDK 为 RTT 提供了一个 stdio 驱动,就像 UART 和 USB 的 stdio 驱动一样。更多信息请参阅 pico_stdio_rtt。
要在构建中启用该驱动,请在你的 CMakeLists.txt 文件中加入以下一行(或者链接 pico_stdio_rtt,效果相同):
调用 stdio_init_all() 之后,应用程序通过 printf() 发送的任何输出都会发送到 RTT。如果你还想把输出同时复制到 UART,也可以启用该功能。
从 VSCode 连接 RTT
OpenOCD 和 VSCode 的 Cortex-Debug 扩展都支持 RTT;这两者都会在安装工具的过程中完成设置。
要为调试会话启用 RTT,需要在其启动配置中添加一个配置节。打开你项目的 .vscode 文件夹,将以下几行添加到 launch.json 文件中,放入合适的配置节,例如 "Pico Debug (Cortex-Debug)":
更多信息请参阅 cortex-debug 启动属性。
如果你现在在一个启用了 RTT 的应用程序上启动调试会话,并打开 TERMINAL(终端)标签页,你会在右侧看到一个列表,其中包含 RTT Ch:0 console。选中它,即可查看你的应用程序发送到 pico_stdio_rtt 驱动的输出。
在单独调试会话中连接 RTT
如果你使用的是开始调试会话一节中描述的单独调试会话,可以通过以下步骤连接到 RTT:
构建并上传启用了 RTT 的应用程序。
连接调试套件,并在单独的终端中启动
openocd和gdb。更多信息请参阅单独调试会话。在
gdb提示符下输入以下命令:
注意
前缀为
monitor的gdb命令会被透传给openocd。关于这里所用命令的更多信息,请参阅 OpenOCD 手册的第 15.6 节。
OpenOCD 会在目标上搜索 RTT 控制块,然后在本地创建一个监听 60000 端口的 TCP 套接字。
打开第三个窗口,使用
nc(netcat)或类似工具连接到该本地套接字,即可查看应用程序的 RTT 输出:
更新调试套件固件
调试套件固件由树莓派以 UF2 文件的形式分发。
调试套件固件的最新版本是 2.3.1。如果你运行的是较旧的版本,或者不小心覆盖了调试套件上的固件,可以在 debugprobe GitHub 仓库中找到最新版本的固件。
要检查调试套件的固件版本,请运行:
对于 2.3.1 版的调试套件固件,该命令会报告 bcdDevice 2.31。
注意
openocd报告的Info : CMSIS-DAP: FW Version = 2.0.0一行只表示 CMSIS-DAP 协议级别(与调试套件固件版本不同)。
按以下步骤更新调试套件的固件版本:
从最新版本下载
debugprobe.uf2。掀开调试套件外壳的顶部。
在把调试套件插入计算机的同时按住 BOOTSEL 按钮,以挂载名为 “RPI-RP2”(Pico)或 “RP2350”(Pico 2)的卷。
将
debugprobe.uf2复制到挂载的卷上。文件复制完成后,卷会自动卸载。调试套件会重新启动,现在运行的是更新后的调试套件固件,可以开始调试了。
原理图
调试套件的原理图和机械图纸可在以下位置获取:
原理图上标示的测试点(TP)位于下图所示位置。

最后更新于