Debugging with SWD

The TBD-16 exposes the RP2350’s SWD (Serial Wire Debug) and UART pins on the right side of the enclosure, so you can flash, set breakpoints, and read serial output without opening the case. This page explains how to set everything up with the Raspberry Pi Debug Probe and PlatformIO in VS Code.

Why Use a Debug Probe?

The default upload method works fine — hold BOOTSEL, drag a UF2 file. But a CMSIS-DAP debug probe unlocks a much faster workflow:

  • One-click flash — Upload over SWD without touching BOOTSEL or unplugging cables.

  • Breakpoints & stepping — Pause execution, inspect variables, and step through code line by line — right inside VS Code.

  • PIO serial output — Read Serial.println() debug messages over UART without using any of the RP2350’s hardware UARTs (which are reserved for MIDI).

  • No reboot cycle — Flash and debug without resetting the board.

What You Need

Raspberry Pi Debug Probe

The official debug probe from Raspberry Pi. It connects to your computer via USB and provides both a CMSIS-DAP SWD interface and a UART bridge in a single device.

Jumper wires

4 female-to-female jumper wires to connect the debug probe to the TBD-16’s debug header.

USB cable

A USB Micro-B cable to connect the debug probe to your computer (ships with the probe).

You can also use a regular Raspberry Pi Pico or Pico 2 board flashed with the debugprobe firmware as a cheaper alternative. The dedicated Debug Probe is recommended because it provides both SWD and UART in a single USB connection with proper connectors.

Wiring

The TBD-16 has a debug header on the right side of the case with the following pins:

Pin

Signal

Description

GND

Ground

Connect to GND on the debug probe

SWCLK

SWD Clock

Connect to SC on the debug probe

SWDAT

SWD Data

Connect to SD on the debug probe

UART TX

Serial output

Connect to RX on the debug probe’s UART port

Connect the four wires between the debug header and the debug probe:

TBD-16 Debug Header

→

Debug Probe

GND

→

GND (SWD cable)

SWCLK

→

SC (SWD cable)

SWDAT

→

SD (SWD cable)

UART TX

→

RX (UART cable)

PlatformIO Configuration

Open platformio.ini in your project and uncomment the two CMSIS-DAP lines:

[env:pi2350]
platform = https://github.com/maxgerhardt/platform-raspberrypi.git
board = generic_rp2350
framework = arduino
; ... other settings ...

debug_tool = cmsis-dap
upload_protocol = cmsis-dap

With these lines active, PlatformIO will:

  • Upload firmware over SWD instead of UF2 — no BOOTSEL button needed.

  • Debug using the CMSIS-DAP interface — breakpoints, stepping, and variable inspection work out of the box.

Flashing over SWD

Once wired and configured, flashing is the same as before:

Click the right-arrow icon (→) in the PlatformIO toolbar, or run:

pio run --target upload

PlatformIO will detect the debug probe and flash the firmware over SWD. The device does not need to be in BOOTSEL mode.

Debugging in VS Code

  1. Set a breakpoint by clicking in the gutter next to a line of code.

  2. Click Debug in the PlatformIO sidebar, or press F5.

  3. The firmware is compiled, flashed, and halted at the entry point.

  4. Step through code with F10 (step over) or F11 (step into).

  5. Inspect variables in the Variables panel, or hover over them in the editor.

If the debugger does not connect, try deleting the .pio folder and rebuilding the project (pio run --target clean && pio run). PlatformIO occasionally caches stale debug configurations.

Serial Output via PIO UART

The TBD-16 template firmware includes a PIO-based serial transmitter that uses the SDA pin on the debug header (GPIO 20). This is a software UART implemented via the RP2350’s PIO state machine, so it does not consume any of the hardware UART peripherals (which are used for MIDI).

To enable serial debug output, uncomment these lines in the main sketch:

// In global scope
SerialPIO transmitter(20, SerialPIO::NOPIN);

// In setup()
transmitter.begin(115200);
transmitter.println("CTAG TBD started");

// In loop()
transmitter.println("CTAG TBD Loop");

Then use PlatformIO’s Upload and Monitor button or run:

pio device monitor --baud 115200

The serial output appears on the debug probe’s UART port, visible as a second serial device on your computer.

Troubleshooting

Debug probe not detected

  • Make sure the USB cable to the debug probe is connected and the probe’s LED is on.

  • Verify that debug_tool = cmsis-dap and upload_protocol = cmsis-dap are uncommented in platformio.ini.

  • On macOS, no driver installation is needed. On Windows, the probe should appear automatically; if not, check Device Manager for a CMSIS-DAP device.

Upload succeeds but debug session does not start

  • Delete the .pio folder and rebuild: pio run --target clean.

  • Make sure no other application is using the debug probe (only one debug session at a time).

No serial output

  • Confirm the UART TX wire is connected to the debug probe’s RX pin.

  • Ensure the SerialPIO lines are uncommented in your code.

  • Check that the baud rate matches (115200).

Intermittent connection issues

  • Use short jumper wires (< 20 cm). Long wires can cause SWD signal integrity issues.

  • Make sure GND is connected — SWD will not work without a common ground.