Skip to the content
2 layers41.7 × 68.6 mmMri swd, the printed circuit board in 3D

Work In Progress! - MRI-SWD - GDB compatible hardware probe which allows debugging of Cortex-M based microcontrollers over SWD.

Size
41.7 × 68.6 mm
Copper layers
2
Thickness
1.6 mm
Parts
8
Nets
43
Pads
76
Tracks, vias
107, 1
Pours
34
Routed
Yes
KiCad
KiCad 8.0 (file 20240108)
Created
30 Apr 2023
Updated
18 Jun 2026

Overview

Mri swd is an open-source printed circuit board by adamgreen, from the adamgreen/mri-swd repository on GitHub, published under the Apache-2.0 licence. It is a 2-layer board of 41.7 × 68.6 mm with 8 parts on 43 nets, routed with 107 tracks and 1 via.

Its parts include 3 connectors, 2 switches, 1 resistor, 1 IC and 1 diode. It belongs with the interfaces and adapters boards and the RP2040 boards of this library.

README

README.md

MRI-SWD - A Work In Progress!

Monitor for Remote Inspection - SWD Edition

mri-swd is a Pico W based debug probe for debugging Cortex-M based microcontrollers with the GNU debugger (GDB). GDB can connect to the mri-swd debug probe over WiFi and the debug probe then connects to the debug target using SWD.

mri-swd PCB mounted on 3π+ 2040 bot

Table of Contents

Important Notes

Dogfood Setup

  • [8/25/2024]: The code found within this repository is now at the point where I regularly use it for debugging the mri-swd firmware itself and other RP2040 based projects. The WiFi abilities make it really useful for debugging RP2040 based electronics on mobile robot paltforms. Dogfooding it like this continue to surface more issues that can then be addressed to make it even better. I will continue with this dogfooding for several more months yet before deciding whether I should port mri-swd to the Raspberry Pi Debug Probe and make a more public announcement about this alternative debug probe firmware.
  • The initial goal is to just be able to debug and program the dual core RP2040 and RP2350 microcontrollers. Support has also been added for the nRF52xxx family of microcontrollers which was good for making sure that it doesn't only work on the RP2xx parts. Support for other Cortex-M based microcontrollers may be added in the future but it isn't currently a priority.
  • The mri-swd firmware is initially being developed to run on the low cost Pico W. It will use the Pico W's WiFi capabilities to wirelessly communicate with GDB. No intermediate program like OpenOCD will be required since the mri remote debug stub functionality will be running on the Pico W itself.
  • I want to concentrate on making this debugger work as well as possible for the devices and features that it does support. This brings me to my list of Non-Goals:
    • JTAG Support
    • Devices other than Cortex-M microcontrollers

Supported Features

  • Supports debugging and programming of the Raspberry Pi RP2040 and RP2350 microcontrollers.
    • Does support the nRF52xxx microcontroller as well.
    • If may also be able to auto-detect other Cortex-M microcontrollers if they are attached but this isn't guaranteed. Any such detected devices will only support debugging and not programming.
  • RAM/FLASH/ROM Read
  • RAM Write
  • CPU Register Read/Write
  • load (FLASH Programming of RP2040, RP2350, and nRF52xxx)
  • step and next (Single Stepping)
  • break (Hardware Breakpoints)
  • watch, awatch, rwatch (Hardware Watchpoints)
  • monitor reset [halt] (Reboot the microcontroller)
  • monitor detach (Power down target DAP and shutdown mri-swd)
  • info thread and thread:
    • Only used to expose the second core on the RP2040 and RP2350 microcontrollers at this point in time
    • No RTOS support
  • GDB connection over WiFi on port 2331
  • Host access to the Target's UART on port 2332 (UART<->WiFi Bridging)
  • Semihosting
  • 128x32 Monochrome OLED for reporting Debugger/Target status

Unsupported Features

  • RTOS Thread Support
  • Connecting GDB over USB. Only WiFi for now.

WiFi Configuration

Currently the SSID and Password for accessing the WiFi network need to be compiled into the firmware. You need to create a wifi_config.cmake file in the root of the project to provide the values appropriate for your network. Here is an example of its required contents (update with your particular SSID and password):

wifi_config.cmake Example

cmake
set(WIFI_SSID YourSSID)
set(WIFI_PASSWORD YourPassword)

This file is included in the repository's .gitignore so that it isn't accidentally committed and pushed to a public server.

Note: I will provide a way to set these WiFi settings over USB in the future.

How to Build

GNU Make based Auto Setup

This repository contains the pico-sdk and mri core repositories as submodules. The following GNU Make command will initialize these submodules:

shell
make init

GNU Make can also be used to kick off the initial build:

shell
make all

This will generate output files in the build/ folder. Subsequent builds can be performed by executing the Makefile now found in this folder:

shell
cd build/
make

CMake based Manual Setup

As this is a pico-sdk project, it uses CMake to perform the build. The above described /Makefile has only been tested on macOS but may work on other Posix systems such as Linux as well. If you are running on Windows and are already familiar with using CMake to build pico-sdk based projects on that platform then you can instead perform the setup manually:

shell
cd mri
git submodule update --init
cd pico-sdk
git submodule update --init
mkdir build
cd build
cmake -G "NMake Makefiles" ..
nmake

Wiring Diagram

Target to Debugger Wiring Diagram

Currently only 2 signal wires (and ground) need to be connected between the target RP2040 device and the Pico W based debugger device:

Pico W DebuggerPico Target
GPIO 2SWCLK
GPIO 3SWDIO
GndGnd

Both devices, target and debugger, need power. It is common to power each of the devices via their individual USB connectors.

Connecting GDB

IP Address

Using OLED

Now that mri-swd supports using an Adafruit 128x32 Monochrome OLED for showing its status, what follows is now the preferred method of determining the IP address assigned by DHCP.

When mri-swd first powers up it will show an animating WiFi icon as it attempts to connect to the specified WiFi network:

OLED Animation of WiFi Connection

Once the connection has been made the logo will stop animating and the DHCP assigned IP address will be shown below the logo:

OLED immediately after WiFi Connection

The assigned IP address is shown as 10.0.0.201

Over USB Serial

Originally the only way to determine the DHCP assigned IP address was by using the output mri-swd sends to the USB based serial port as described below.

A terminal program must be connected to the USB based serial connection made available from the Pico W running the mri-swd firmware. When mri-swd is starting up output like the following will be seen in this terminal session:

text
  info: main.cpp:33 main() - Starting up...
 info: mri_platform.cpp:214 attemptSwdAttach() - Found DPv2 SWD Target=0x01002927 with DPIDR=0x0BC12477
 info: mri_platform.cpp:227 attemptSwdAttach() - Initializing target's debug components...
debug: swd.cpp:645 checkAP() - peripheralComponentIDs[]=
debug: swd.cpp:646 checkAP() - {
debug: swd.cpp:649 checkAP() -     0x00000004
debug: swd.cpp:649 checkAP() -     0x00000000
debug: swd.cpp:649 checkAP() -     0x00000000
debug: swd.cpp:649 checkAP() -     0x00000000
debug: swd.cpp:649 checkAP() -     0x000000C0
debug: swd.cpp:649 checkAP() -     0x000000B4
debug: swd.cpp:649 checkAP() -     0x0000000B
debug: swd.cpp:649 checkAP() -     0x00000000
debug: swd.cpp:649 checkAP() -     0x0000000D
debug: swd.cpp:649 checkAP() -     0x00000010
debug: swd.cpp:649 checkAP() -     0x00000005
debug: swd.cpp:649 checkAP() -     0x000000B1
debug: swd.cpp:651 checkAP() - }
debug: swd.cpp:660 checkAP() - CPUID=0x410CC601
 info: mri_platform.cpp:234 attemptSwdAttach() - SWD initialization complete!
 info: mri_platform.cpp:240 initNetwork() - Initializing network...
 info: mri_platform.cpp:251 initNetwork() - Attempting to connect to Wi-Fi router...
 info: mri_platform.cpp:254 initNetwork() - Connected to Wi-Fi router.
 info: gdb_socket.cpp:36 init() - Starting server at 10.0.0.201 on port 2331
 info: mri_platform.cpp:795 initDWT() - CPU supports 2 hardware watchpoints.
 info: mri_platform.cpp:857 initFPB() - CPU supports 4 hardware breakpoints.

The third line up from the bottom shows the 10.0.0.201 IP address assigned to the mri-swd device on this particular network. Take note of this IP address so that it can be used later when attaching GDB.

GDB Connection

The following is an example shell session where GDB is launched and told to connect and start debugging a RP2040 microcontroller via the WiFi IP address that was noted in the previous section (10.0.0.201). Port 2331 is the default TCP/IP port number used by mri-swd but it can be changed in the config.h file discussed further down in this documentation.

console
$ arm-none-eabi-gdb -ex "set target-charset ASCII" -ex "set print pretty on" -ex "set remotelogfile mri.log" -ex "target remote 10.0.0.201:2331" -ex "set mem inaccessible-by-default off" test.elf

GNU gdb (Arm GNU Toolchain 12.2 (Build arm-12-mpacbti.34)) 13.1.90.20230307-git
Copyright (C) 2023 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=aarch64-apple-darwin20.6.0 --target=arm-none-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://bugs.linaro.org/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from build/QuadratureDecoder.elf...
Remote debugging using 10.0.0.201:2331
get_absolute_time () at /depots/QuadratureDecoder/pico-sdk/src/common/pico_time/include/pico/time.h:63
63	    update_us_since_boot(&t, time_us_64());
(gdb) load
Loading section .boot2, size 0x100 lma 0x10000000
Loading section .text, size 0x7130 lma 0x10000100

UART<->WiFi Bridging

The target's UART pins can be connected to the mri-swd debugger as shown in this table:

Pico W DebuggerPico Target
GPIO 0UART Rx
GPIO 1UART Tx
GndGnd

If those connections are made then the target can configure its UART for 230400-8-N-1 communication and this UART will then be accessible from the PC host connected to mri-swd on TCP/IP port 2332 (can be changed in config.h). The PC host can then use a simple TCP/IP terminal emulator such as telnet to communicate with the target's UART over WiFi on this port:

console
~$ telnet -N 10.0.0.201 2332
Trying 10.0.0.201...
Connected to 10.0.0.201.
Escape character is '^]'.
Send this data to target over UART and have it loop it back to the PC!
Send this data to target over UART and have it loop it back to the PC!
^]
telnet> quit
Connection closed.

Note: The IP address to be used with telnet above should match the IP address you use for connecting GDB to the same mri-swd debug probe.

Firmware Configuration

The root folder contains a config.h file which can be used to customize the mri-swd firmware. This header file allows configuration of things such as:

  • GPIO pins to be used for connections to the target.
  • TCP/IP port numbers to which GDB and Telnet should connect.
  • Default SWCLK rate.
  • Various timeouts to use.
  • Logging enable/disable settings for each module in the mri-swd firmware:
    • logError() calls let the user know about unexpected errors. They can be disabled per module in config.h but typically should be left enabled.
    • logDebug() calls give information about the inner workings of the code and are most useful to mri-swd developers. They can be disabled per module in the config.h header.
    • logInfo() calls inform the user what the debugger firmware is currently doing. They can't be disabled.
  • The size of the packets to be used for communication between mri-swd and GDB.
  • ...

OLED Status Display

  • When mri-swd is first attempting to connect to the specified WiFi network, it will show the following WiFi logo animation:
    OLED Animation of WiFi Connection
  • Once the connection has been made the logo will stop animating and the DHCP assigned IP address will be shown below the logo. In the following image, the assigned IP address of 10.0.0.201 can be seen along with 2 additional status messages on the bottom line:
    • On the bottom left is the type of target device connected via SWD, RP2040.
    • On the bottom right is the current state of the target device connected via SWD, Halted.
      OLED immediately after WiFi Connection
  • Once GDB connects to mri-swd's port 2331, the word GDB will show up in the upper left hand corner of the display. Similarly when a terminal program like Telnet connects to mri-swd's port 2332, the word UART will show up in the upper right hand corner. The following image shows clients connected to both ports. It also shows the current state of the target as Running in the lower right hand corner:
    OLED after GDB has connected
  • There are also little arrows that light up next to the GDB and UART designators when data is being sent to and from each of their corresponding TCP/IP clients:
    OLED when UART is actively communicating

    OLED when GDB is actively communicating

Current Hardware Progress

I have designed a PCB that allows attaching a PicoW to my Pololu 3π+ 2040 robot. The images below show my current progress on that project.
Image of version 1.1 of the Schematic
Image of version 1.0 of PCB Front Image of version 1.0 of PCB Back

Next Steps

  • GDB connection over WiFi
  • RP2040 FLASH Programming
  • Improve Robustness
  • Basic nRF52 (Cortex-M4F) Debugging Support
  • Semihosting Support
  • Custom PCB
  • Improve Performance
  • RP2040 Core 1 Support
  • Bridge microcontroller's UART on another WiFi TCP/IP port.
  • Addition of a small OLED Display
    • Report IP address
    • Report WiFi connection state
    • Report WiFi activity
    • Report target detected
    • Report target run state
  • RP2350 Support
  • GDB connection over USB
  • Support Raspberry Pi Debug Probe
  • Better ARMv8-M support
  • FreeRTOS Thread Support
  • Improved Usability

Parts

8
QtyValueFootprintReferences
11kΩResistor_SMD:R_0805_2012Metric_Pad1.20x1.40mm_HandSolderR1
1D_SchottkyDiode_SMD:D_SOD-123FD1
1Debug SWDFootprints:CON10_2X5_DUK_FTSH_SAIJ2
1Debug UART/PowerConnector_PinHeader_2.54mm:PinHeader_1x06_P2.54mm_VerticalJ1
1Halt on ConnectFootprints:SW_JS102011JCQNSW2
1OLEDConnector_PinHeader_2.54mm:PinHeader_1x08_P2.54mm_VerticalJ5
1PicoWFootprints:RPi_PicoW_SMD_THU1
1Reset Footprints:Adafruit-SPST-Switch-7SW1

More from adamgreen/mri-swd

1
  • 2 layers13.5 × 12.6 mmRP2040 SWD Adapter, the printed circuit board in 3D

    RP2040 SWD Adapter

    adamgreen/mri-swd

    Work In Progress! - MRI-SWD - GDB compatible hardware probe which allows debugging of Cortex-M based microcontrollers over SWD.

    2 parts1Apache-2.0

Similar boards

  • 2 layers20.5 × 24.8 mmPi interface, the printed circuit board in 3D

    Pi interface

    opulo-inc/lumenpnp

    The LumenPnP is an open source pick and place machine.

    8 parts3.7k
  • 2 layers59.9 × 25.7 mmBuffer, the printed circuit board in 3D

    Buffer

    hoglet67/RGBtoHDMI

    Bare-metal Raspberry Pi project that provides pixel-perfect sampling of Retro Computer RGB/YUV video and conversion to HDMI

    8 parts1kGPL-3.0
  • 2 layers52 × 12.6 mmUSB, the printed circuit board in 3D

    USB

    shanteacontrols/OpenDeck

    A platform for building interactive control and sensing devices using MIDI and OSC built with Zephyr RTOS.

    8 parts960Apache-2.0
  • 2 layers87.5 × 48.5 mm7 input macropad, the printed circuit board in 3D

    7 input macropad

    hackclub/OnBoard

    💡 Join 1,000 teenagers and make your first PCB with a $100 grant!

    8 parts915
  • 2 layers36.2 × 63.1 mmPicoMemcard pico, the printed circuit board in 3D

    PicoMemcard pico

    dangiu/PicoMemcard

    Emulating PSX Memory Card (or controller) using a Raspberry Pi Pico

    8 parts694GPL-3.0
  • 2 layers36 × 10 mmPCB4-PWR BTN Rev.A, the printed circuit board in 3D

    PCB4-PWR BTN Rev.A

    OLIMEX/DIY-LAPTOP

    Do It Yourself Open Source Hardware and Software Modular Hacker's Friendly Laptop

    8 parts578Apache-2.0

Questions

How big is the Mri swd PCB?

It measures 41.7 × 68.6 mm and has 2 copper layers, 1.6 mm thick.

What parts does the Mri swd use?

8 parts. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.

Where can I download the Mri swd KiCad files?

From the adamgreen/mri-swd repository on GitHub, at the commit this page was made from: the board is hardware/DebugBoard/mri-swd.kicad_pcb and its schematic hardware/DebugBoard/mri-swd.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the Mri swd design in my own project?

Its repository publishes it under the Apache-2.0 licence: you may reuse it on that licence's terms (keep the author's notice, and for a copyleft licence share your changes alike).