Documentation for setting up VS Code should be more clear about changes necessary for using the Pi Pico debug adapter

[Swiftloke]

Problem

The Visual Studio Code section (Section 7.3) of the Pi Pico Getting Started guide suggests that you copy a file from pico-examples for the launch configuration of the examples. But blindly copying this file isn't always the correct solution.

The guide advises that the official development platform for the Pi Pico is a Raspberry Pi. It therefore shows you, in Section 5.2, how to connect the SWD pins of the Pico to the Pis GPIO. There is a footnote below that section advising to see Appendix A to use another Pi Pico for the debug probe instead, and a statement in the docs which specifies what you need to do if you take that approach: -f interface/raspberrypi-swd.cfg: Tells OpenOCD to use Raspberry Pi’s GPIO pins to access the SWD port. To use an external USB→SWD probe such as Picoprobe in Appendix A, specify a different interface.

However, there is no such footnote for the Visual Studio Code section, which also needs modification for the same reason. The launch.json file specifies what debug adapter to use, and by default it also uses the Raspberry Pi GPIO interface. If you're running this on a machine that doesn't support that, however (like my Ubuntu 22.04 machine) it fails, emitting some errors about "nm-multiarch" that are actually spurious while the true problem lies a click away in the Terminal window.

Heading there, we can see the true source of the problem: We didn't update the file to use the correct adapter!

Open On-Chip Debugger 0.12.0-g4d87f6d (2024-02-14-12:53)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
CDLiveWatchSetup
Error: The specified debug interface was not found (bcm2835gpio)
The following debug adapters are available:
1: ftdi
2: usb_blaster
3: esp_usb_jtag
4: ft232r
5: presto
6: usbprog
7: openjtag
8: jlink
9: vsllink
10: rlink
11: ulink
12: arm-jtag-ew
13: buspirate
14: hla
15: osbdm
16: opendous
17: cmsis-dap
18: kitprog
19: xds110
20: st-link

It's simple enough to change the launch.json file to use interface/cmsis-dap.cfg as is necessary, but this is not immediately obvious to the user who hasn't spent a lot of time with OpenOCD.

Suggestion

Add a footnote to Section 7.3 advising to change launch.json to use a different interface much like Section 5.2 already does.

The Pi Pico Project Generator has already somewhat addressed this problem; it offers three options of "SWD", "PicoProbe", and "CMSIS-DAP Debug Probe" and will generate the launch.json files with the correct interface accordingly. But these options are confusingly named.

• SWD refers to ``interface/raspberrypi-swd.cfg". I suggest renaming to "Raspberry Pi GPIO SWD" or similar.
• PicoProbe refers to the Raspberry Pi Debug Probe, or interface/picoprobe.cfg. I don't own a Debug Probe, but I do understand that the project just changed its name due to legal reasons so this might also need an update.
• CMSIS-DAP Debug Probe refers to interface/cmsis-dap.cfg. Some change should be made to make it clear that this is what you get when you use a Pi Pico as a debug adapter.

[lurch]

The Pi Pico Project Generator has already somewhat addressed this problem; it offers three options of "SWD", "PicoProbe", and "CMSIS-DAP Debug Probe" ...

It's actually slightly more complicated than this - I've just created https://github.com/raspberrypi/pico-project-generator/issues/105 which gives some more details.