PlatformIO Community

How to debug on Arduino mega 2560

Hello, I have just installed Platformio and vscode. It’s really nice and thank you to all who have conceived and worked on this, it’s a really nice environment. I am trying to get the debug feature working and although I have been programming arduino to drive stepper motors and worked with various sensors etc, I have no real experience of debugging in the arduino context. Previiously I used the arduino IDE for development work and had a brief foray into Visual Micro and its debug environment.

Having read a few of the debugging tutorials and tried to debug a simple sketch in vscode, I have a few questions - thanks very much for help with this:

What are the key steps I need to undertake before attempting to debug? (e.g. install/ configure something)
Can I use the same serial port as I use to upload code to the arduino or do I need to use a different hardware serial?
When I run the debug feature, I get an error dialog “The preLaunchTask ‘undefined’ terminated with exit code 1.” What des this mean please?
Do I need to download any debug environment for the mega2560?

Thanks very much,
Paul Kirk

The main documentation for the avr-stub debugging tool, which is the only real-hw debugging tool implemented right now, is at

PlatformIO will install everything as needed, and as instructed per the platformio.ini. Configuration of that can be seen above.

Per docs

  • Any part of your application that uses the UART module (e.g. Arduino Serial class) cannot be used in your program together with the debugger.

So you need to move your normal Serial output to another hardware serial (Serial2?) on the Mega.

As a start I’d suggest you debug just a blink sketch to verify the setup.

So a platformio.ini of

platform = atmelavr
board = megaatmega2560
framework = arduino

debug_tool = avr-stub
debug_port = SERIAL_PORT

; GDB stub implementation
lib_deps =
    jdolinay/avr-debugger @ ~1.1

Whereas you have to replace SERIAL_PORT with the actual serial port name of the Mega on your computer, e.g. COM3. (see Windows device manager).

EDIT: In my test I had to say debug_port = \\.\COM14 when using COM14 so that GDB is happy.

And as code / src\main.cpp

#include "Arduino.h"
#include "avr8-stub.h"

void setup()
  // initialize GDB stub

void loop()
  digitalWrite(LED_BUILTIN, HIGH);
  digitalWrite(LED_BUILTIN, LOW);

Works on my Uno with a similiar platformio.ini

platform = atmelavr
board = uno
framework = arduino
debug_tool = avr-stub
debug_port = \\.\COM14
lib_deps =
    jdolinay/avr-debugger @ ~1.1


thanks very much for a comprehensive reply - much appreciated. I’ll give it a go.

yes worked fine,
thanks for help,

1 Like