Raspberry Pi Pico 2 and Debug Probe
This skill covers development with Raspberry Pi Pico 2 (RP2350) boards and the Raspberry Pi Debug Probe. It includes hardware specs, SDK setup, build configuration, debugging workflows, and common pitfalls.
Reference Files
Consult these for detailed technical content. Read only the file relevant to the current task:
references/pico2-hardware.md - RP2350 specs, RP2040 vs RP2350 comparison, pin layout, wireless variant, security features, chip variantsreferences/debug-probe.md - Debug Probe hardware, wiring diagrams, OpenOCD setup, GDB workflow, UART serial, RTT, VS Code integration, rescue mode, troubleshootingreferences/sdk-toolchain.md - pico-sdk setup, CMake configuration, ARM vs RISC-V builds, picotool commands, MicroPython/CircuitPython, project structure
Quick Reference
Board Selection (CMake)
| Board |
CMake Flag |
Platform |
| Pico 1 |
-DPICO_BOARD=pico (default) |
rp2040 |
| Pico 1 W |
-DPICO_BOARD=pico_w |
rp2040 |
| Pico 2 |
-DPICO_BOARD=pico2 |
rp2350-arm-s |
| Pico 2 W |
-DPICO_BOARD=pico2_w |
rp2350-arm-s |
| Pico 2 RISC-V |
-DPICO_BOARD=pico2 -DPICO_PLATFORM=rp2350-riscv |
rp2350-riscv |
Debug Probe Wiring (SWD)
| Debug Probe "D" Pin |
Wire Colour |
Pico 2 SWD Pad |
| SC |
Orange |
SWCLK |
| GND |
Black |
GND |
| SD |
Yellow |
SWDIO |
Debug Probe Wiring (UART)
| Debug Probe "U" Pin |
Wire Colour |
Pico 2 Pin |
GPIO |
| TX |
Orange |
Pin 2 |
GP1 (RX) |
| RX |
Yellow |
Pin 1 |
GP0 (TX) |
| GND |
Black |
Pin 3 |
GND |
Note the crossover: probe TX to Pico RX, probe RX to Pico TX.
OpenOCD Target Configs
| Target |
Config File |
| Pico 1 (RP2040) |
target/rp2040.cfg |
| Pico 2 (RP2350) |
target/rp2350.cfg |
| Pico 2 RISC-V |
target/rp2350.cfg with -c "set USE_CORE { rv0 rv1 }" |
| Rescue (RP2350) |
target/rp2350.cfg with -c "set RESCUE 1" |
Typical Debug Session
# Terminal 1: OpenOCD
openocd -f interface/cmsis-dap.cfg -f target/rp2350.cfg -c "adapter speed 5000"
# Terminal 2: GDB
arm-none-eabi-gdb my_app.elf
(gdb) target remote localhost:3333
(gdb) monitor reset init
(gdb) load
(gdb) break main
(gdb) continue
Flash via SWD
openocd -f interface/cmsis-dap.cfg -f target/rp2350.cfg \
-c "adapter speed 5000" \
-c "program my_app.elf verify reset exit"
Use the .elf file for SWD flashing, not .uf2.
Gotchas
These are the most common mistakes and non-obvious behaviours. Pay close attention.
SDK defaults to Pico 1. You must explicitly pass -DPICO_BOARD=pico2 to target RP2350. Forgetting this builds for RP2040 and the binary will not run on a Pico 2.
Use the Raspberry Pi fork of OpenOCD. Upstream OpenOCD (0.12.0) lacks full RP2350 support. Clone from https://github.com/raspberrypi/openocd.git branch rpi-common.
Wrong target config = failed connection. Using rp2040.cfg with a Pico 2 silently fails. Always match the target config to the chip.
SWD uses .elf, BOOTSEL uses .uf2. These are different formats for different flashing methods. Do not try to flash a .uf2 via OpenOCD/SWD.
Debug builds required for meaningful debugging. Always pass -DCMAKE_BUILD_TYPE=Debug to cmake. Release builds optimise away variable state and reorder code, making breakpoints unreliable.
RISC-V mode has no FPU. The hardware floating-point unit is only available on Cortex-M33. RISC-V mode uses software float, which is significantly slower for float-heavy code.
RISC-V requires a clean build directory. When switching between ARM and RISC-V, delete the build directory and re-run cmake. In-place switching does not work.
RISC-V debugging requires pre-selection. The RP2350 boots into Cortex-M33 by default. To debug RISC-V: picotool reboot -u -c riscv, then use OpenOCD with set USE_CORE { rv0 rv1 }.
Debug Probe does not power the target. The Pico 2 must be powered via its own USB or VSYS. The SWD connector carries no power.
LED pin differs on wireless models. Non-wireless Pico 2 uses GP25 for the onboard LED. Pico 2 W uses WL_GPIO0 through the CYW43439 wireless chip. Code must be conditional.
Git submodules are required. The pico-sdk needs git submodule update --init to pull tinyusb, cyw43-driver, lwip, btstack, and mbedtls. Missing submodules cause cryptic build failures.
OTP is irreversible. Writing OTP bits is permanent. Misconfiguring secure boot (setting SECURE_BOOT_ENABLE without a boot key and with PICOBOOT disabled) permanently bricks the device.
Wireless SPI pin sharing. On Pico 2 W, the VSYS ADC reading and CYW43439 IRQ checking are blocked during SPI transactions to the wireless chip.
Connect GND first. When the Pico 2 is powered from a separate source, connect GND between the target and Debug Probe before any signal lines. Voltage differences can damage the probe.
macOS: OpenOCD needs hidapi and libusb. Install via brew install hidapi libusb. If OpenOCD cannot find the probe, check no other process (VS Code, another OpenOCD instance) holds the USB device.
Multiple debug probes. If multiple CMSIS-DAP devices are connected, specify the serial number: adapter serial <serial_number> in your OpenOCD config.
1---
2name: raspberry-pi-pico2
3description: >
4 Use when developing with Raspberry Pi Pico 2 or the Pi Debug Probe.
5allowed-tools: Bash Read Write Edit Grep Glob Agent
6disable-model-invocation: true
7argument-hint: "Thing you want to do"
8---
9
10# Raspberry Pi Pico 2 and Debug Probe
11
12This skill covers development with Raspberry Pi Pico 2 (RP2350) boards and the Raspberry Pi Debug Probe. It includes hardware specs, SDK setup, build configuration, debugging workflows, and common pitfalls.
13
14## Reference Files
15
16Consult these for detailed technical content. Read only the file relevant to the current task:
17
18- `references/pico2-hardware.md` - RP2350 specs, RP2040 vs RP2350 comparison, pin layout, wireless variant, security features, chip variants
19- `references/debug-probe.md` - Debug Probe hardware, wiring diagrams, OpenOCD setup, GDB workflow, UART serial, RTT, VS Code integration, rescue mode, troubleshooting
20- `references/sdk-toolchain.md` - pico-sdk setup, CMake configuration, ARM vs RISC-V builds, picotool commands, MicroPython/CircuitPython, project structure
21
22## Quick Reference
23
24### Board Selection (CMake)
25
26| Board | CMake Flag | Platform |
27|-------|-----------|----------|
28| Pico 1 | `-DPICO_BOARD=pico` (default) | rp2040 |
29| Pico 1 W | `-DPICO_BOARD=pico_w` | rp2040 |
30| Pico 2 | `-DPICO_BOARD=pico2` | rp2350-arm-s |
31| Pico 2 W | `-DPICO_BOARD=pico2_w` | rp2350-arm-s |
32| Pico 2 RISC-V | `-DPICO_BOARD=pico2 -DPICO_PLATFORM=rp2350-riscv` | rp2350-riscv |
33
34### Debug Probe Wiring (SWD)
35
36| Debug Probe "D" Pin | Wire Colour | Pico 2 SWD Pad |
37|---------------------|-------------|-----------------|
38| SC | Orange | SWCLK |
39| GND | Black | GND |
40| SD | Yellow | SWDIO |
41
42### Debug Probe Wiring (UART)
43
44| Debug Probe "U" Pin | Wire Colour | Pico 2 Pin | GPIO |
45|---------------------|-------------|------------|------|
46| TX | Orange | Pin 2 | GP1 (RX) |
47| RX | Yellow | Pin 1 | GP0 (TX) |
48| GND | Black | Pin 3 | GND |
49
50Note the crossover: probe TX to Pico RX, probe RX to Pico TX.
51
52### OpenOCD Target Configs
53
54| Target | Config File |
55|--------|------------|
56| Pico 1 (RP2040) | `target/rp2040.cfg` |
57| Pico 2 (RP2350) | `target/rp2350.cfg` |
58| Pico 2 RISC-V | `target/rp2350.cfg` with `-c "set USE_CORE { rv0 rv1 }"` |
59| Rescue (RP2350) | `target/rp2350.cfg` with `-c "set RESCUE 1"` |
60
61### Typical Debug Session
62
63```bash
64# Terminal 1: OpenOCD
65openocd -f interface/cmsis-dap.cfg -f target/rp2350.cfg -c "adapter speed 5000"
66
67# Terminal 2: GDB
68arm-none-eabi-gdb my_app.elf
69(gdb) target remote localhost:3333
70(gdb) monitor reset init
71(gdb) load
72(gdb) break main
73(gdb) continue
74```
75
76### Flash via SWD
77
78```bash
79openocd -f interface/cmsis-dap.cfg -f target/rp2350.cfg \
80 -c "adapter speed 5000" \
81 -c "program my_app.elf verify reset exit"
82```
83
84Use the `.elf` file for SWD flashing, not `.uf2`.
85
86## Gotchas
87
88These are the most common mistakes and non-obvious behaviours. Pay close attention.
89
901. **SDK defaults to Pico 1.** You must explicitly pass `-DPICO_BOARD=pico2` to target RP2350. Forgetting this builds for RP2040 and the binary will not run on a Pico 2.
91
922. **Use the Raspberry Pi fork of OpenOCD.** Upstream OpenOCD (0.12.0) lacks full RP2350 support. Clone from `https://github.com/raspberrypi/openocd.git` branch `rpi-common`.
93
943. **Wrong target config = failed connection.** Using `rp2040.cfg` with a Pico 2 silently fails. Always match the target config to the chip.
95
964. **SWD uses .elf, BOOTSEL uses .uf2.** These are different formats for different flashing methods. Do not try to flash a .uf2 via OpenOCD/SWD.
97
985. **Debug builds required for meaningful debugging.** Always pass `-DCMAKE_BUILD_TYPE=Debug` to cmake. Release builds optimise away variable state and reorder code, making breakpoints unreliable.
99
1006. **RISC-V mode has no FPU.** The hardware floating-point unit is only available on Cortex-M33. RISC-V mode uses software float, which is significantly slower for float-heavy code.
101
1027. **RISC-V requires a clean build directory.** When switching between ARM and RISC-V, delete the build directory and re-run cmake. In-place switching does not work.
103
1048. **RISC-V debugging requires pre-selection.** The RP2350 boots into Cortex-M33 by default. To debug RISC-V: `picotool reboot -u -c riscv`, then use OpenOCD with `set USE_CORE { rv0 rv1 }`.
105
1069. **Debug Probe does not power the target.** The Pico 2 must be powered via its own USB or VSYS. The SWD connector carries no power.
107
10810. **LED pin differs on wireless models.** Non-wireless Pico 2 uses GP25 for the onboard LED. Pico 2 W uses WL_GPIO0 through the CYW43439 wireless chip. Code must be conditional.
109
11011. **Git submodules are required.** The pico-sdk needs `git submodule update --init` to pull tinyusb, cyw43-driver, lwip, btstack, and mbedtls. Missing submodules cause cryptic build failures.
111
11212. **OTP is irreversible.** Writing OTP bits is permanent. Misconfiguring secure boot (setting `SECURE_BOOT_ENABLE` without a boot key and with PICOBOOT disabled) permanently bricks the device.
113
11413. **Wireless SPI pin sharing.** On Pico 2 W, the VSYS ADC reading and CYW43439 IRQ checking are blocked during SPI transactions to the wireless chip.
115
11614. **Connect GND first.** When the Pico 2 is powered from a separate source, connect GND between the target and Debug Probe before any signal lines. Voltage differences can damage the probe.
117
11815. **macOS: OpenOCD needs hidapi and libusb.** Install via `brew install hidapi libusb`. If OpenOCD cannot find the probe, check no other process (VS Code, another OpenOCD instance) holds the USB device.
119
12016. **Multiple debug probes.** If multiple CMSIS-DAP devices are connected, specify the serial number: `adapter serial <serial_number>` in your OpenOCD config.
sammcj