How to debug a Portenta M7 with an Arduino project and GDB?

× Not what you are looking for? Did you want USB/WiFi debug, trace and performance monitoring instead?

We Need Your Help:

If you want to see the Peripheral View feature in Visual Studio 2022 like we do, please upvote this issue with Microsoft.

MRI Debug (Built In)

The Portenta H7 M7 has support for an in-built debugger "Monitor for Remote Inspection" (MRI).

This can now be used out of the box in vMicro in a few simple steps, with no additional hardware.

Note:

This is available from vMicro versions 2021.0606.13 onwards, in conjunction with the "Arduino Mbed OS Portenta Boards" platform.

Debugger Connections

Simply connect your Portenta H7 M7 to your PC via the USB(C) cable as normal:

Portenta H7 USB Connection

Software Setup

Ensure you have Visual Studio and the vMicro Extension Installed

Open your Sketch, and select the options from vMicro > Debugging as shown below:

Portenta Debug Toolbar Settings

NOTE - as the debugger uses the SerialUSB interface of the Portenta, you will have to remove all calls to Serial from your code. Alternatively use a seperate serial interface for your messages.

You will need to add a couple of additions to your sketch (also in output window on debugger select):

Ensure you have the Debug Configuration selected from the Configuration Manager Window
Check the COM Port on the Debug Toolbar is correct.
Include the ThreadDebug.h file at the top of your sketch by adding the ThreadDebug Library

Add the below code above setup():

// Check we are using GDB Debugging and include the additional code
#ifdef VM_DEBUG_GDB
#include "ThreadDebug.h"
UsbDebugCommInterface  debugComm(&SerialUSB);
ThreadDebug            threadDebug(&debugComm, DEBUG_BREAK_IN_SETUP); 
// Set to DEBUG_NO_BREAK_IN_SETUP to prevent automatic stop in setup
#endif

setup(){}
loop(){}

If you know where you want the first breakpoint in your code, add it now
Double Tap the Reset button to put the board into DFU Mode (Green LED fades in and out)
Check the COM Port selected for Upload is still correct, and build and upload the code to the board
To start the debugging session use "Debug > Attach to Process" (your code does not start executing until the debugger has attached)

Portenta Debugging in vMicro and Visual Studio

Congratulations - you should have the debugger running, and further windows can be opened from the "Debug > Windows" menu once you have started debugging

See our GDB Debugging in Brief guide, or our detailed GDB Debugging Tutorial for Arduino to learn more about using the debugging interface.

There is also a video guide on this below:

Segger JLink (1Core)

The Portenta H7 now has support in vMicro for the Segger JLink for both the M7 and M4 Cores.

This can now be used out of the box in vMicro in a few simple steps.

Note:

This is fully available from vMicro versions 2021.1108.06 onwards, in conjunction with the "Arduino Mbed OS Portenta Boards" platform.

External Debug Interface: SWD

External Debugger Connections

To connect your JLink probe to the Portenta Breakout Board you will need to connect the below pins:

Portenta SWD Connections

Then you will also need to connect your Debugger to the PC on one USB port, and the Portenta H7 on another USB Port

Software Setup

Ensure you have Visual Studio and the vMicro Extension Installed

Open your Sketch and select the Debug > Hardware, and the Segger J-Link Debugger (NOT the "NoOpenOCD version)

Visual Studio Toolbar Selections for Portenta H7

You will need to install an additional USB Driver on Interface 0 of your debugger to allow it to function with this software - check in the debugger list here

Remember - If you have installed a new driver, you may have to do it again if you connect the debugger to a different USB port next time.....

Start Debugger

Ensure you have the Debug Configuration selected from the Configuration Manager Window
If you know where you want the first breakpoint in your code, add it now
To start the debugging process, you can either:
- "Debug > Attach to Process" button if your code has already been uploaded to the Portenta H7 board
- "Debug > Start Debugging" if your code has not been uploaded

Portenta H7 Debugging in vMicro and Visual Studio

Congratulations - you should have the debugger running, and further windows can be opened from the "Debug > Windows" menu once you have started debugging

See our GDB Debugging in Brief guide, or our detailed GDB Debugging Tutorial for Arduino to learn more about using the debugging interface.

There is also a video guide on this below:

Segger JLink (DualCore)

The Portenta H7 now has support in vMicro for the Segger JLink for both the M7 and M4 Cores.

This can also be used to debug BOTH cores simultaneously using two instances of Visual Studio and a shared instance of OpenOCD.

Note:

This is fully available from vMicro versions 2021.1108.06 onwards, in conjunction with the "Arduino Mbed OS Portenta Boards" platform.

External Debug Interface: SWD

External Debugger Connections

To connect your JLink probe to the Portenta Breakout Board you will need to connect the below pins:

Portenta SWD Connections

Then you will also need to connect your Debugger to the PC on one USB port, and the Portenta H7 on another USB Port.

Remember - If you have installed a new driver, you may have to do it again if you connect the debugger to a different USB port next time.....

Software Setup: M7 Core

Ensure you have Visual Studio and the vMicro Extension Installed

Open your M7 Core Sketch and select the Debug > Hardware, and the Segger J-Link Debugger (NOT the "NoOpenOCD version)

Visual Studio Toolbar Selections for Portenta H7

Ensure you have the bootM4() call in the setup of your M7 Core sketch.

You will need to install an additional USB Driver on Interface 0 of your debugger to allow it to function with this software - check in the debugger list here

Build and upload your M7 Sketch to the M7 core at this point.

Software Setup: M4 Core

Ensure you have Visual Studio and the vMicro Extension Installed

Open your Sketch and select the Debug > Hardware, and the Segger J-Link Debugger (NoOpenOCD)

Build and upload your M4 Sketch to the M4 core at this point.

Start Debugger

First start debugging using the M7 Core sketch by using "Debug > Attach to Process".

Then start debugging using the M4 Core sketch by using "Debug > Attach to Process".

Congratulations - you should have the debugger running for both cores, and further windows can be opened from the "Debug > Windows".

See our GDB Debugging in Brief guide, or our detailed GDB Debugging Tutorial for Arduino to learn more about using the debugging interface.

Ensure you stop debugging on both instances of Visual Studio, and reset the board using the reset button to make it available for debugging again.

There is also a video guide on this below:

STLink (1Core)

The Portenta H7 now has support in vMicro for the STMicroElectronics STLink v1/2/3 for the M7 Cores only.

This can now be used out of the box in vMicro in a few simple steps.

Note:

This is fully available from vMicro versions 2024.1211.09 onwards, in conjunction with the "Arduino Mbed OS Portenta Boards" platform.

External Debug Interface: SWD

External Debugger Connections

To connect your STLink probe to the Portenta Breakout Board you will need to connect the below pins:

Portenta SWD Connections

Then you will also need to connect your Debugger to the PC on one USB port, and the Portenta H7 on another USB Port

Software Setup

Ensure you have Visual Studio and the vMicro Extension Installed

Open your Sketch and select the Debug > Hardware, and the STLink v1/2/3 Debugger.

Visual Studio Toolbar Selections for Portenta H7

You will need to install an additional USB Driver on the "STM32 STLink" Device to allow it to function with this software - check in the debugger list here

Remember - If you have installed a new driver, you may have to do it again if you connect the debugger to a different USB port next time.....

Start Debugger

Ensure you have the Debug Configuration selected from the Configuration Manager Window
If you know where you want the first breakpoint in your code, add it now
To start the debugging process, you can either:
- "Debug > Attach to Process" button if your code has already been uploaded to the Portenta H7 board
- "Debug > Start Debugging" if your code has not been uploaded

Congratulations - you should have the debugger running, and further windows can be opened from the "Debug > Windows" menu once you have started debugging

See our GDB Debugging in Brief guide, or our detailed GDB Debugging Tutorial for Arduino to learn more about using the debugging interface.

How to debug a Portenta M7 with an Arduino project and GDB?

MRI Debug (Built In)

Debugger Connections

Software Setup

Segger JLink (1Core)

External Debugger Connections

Software Setup

Start Debugger

Segger JLink (DualCore)

External Debugger Connections

Software Setup: M7 Core

Software Setup: M4 Core

Start Debugger

STLink (1Core)

External Debugger Connections

Software Setup

Start Debugger

Useful Links

Further Reading

How to debug a Portenta M7 with an Arduino project and GDB?

MRI Debug (Built In)

Debugger Connections

Software Setup

Segger JLink (1Core)

External Debugger Connections

Software Setup

Start Debugger

Segger JLink (DualCore)

External Debugger Connections

Software Setup: M7 Core

Software Setup: M4 Core

Start Debugger

STLink (1Core)

External Debugger Connections

Software Setup

Start Debugger

Useful Links

Further Reading

Cookie Consent and Privacy