How to debug an Teensy Arduino project with GDBStub

The Teensy now supports a GDB Stub as the breakout for JTAG is not currently easily accessible. This is in addition to, and seperate from the standard vMicro Serial Debugger.

A GDB Stub Library has been published, allowing you to debug in a similar way to the Hardware debugging.....

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

This is also available on Instructables and YouTube for the Uno/Mega, and the ESP8266 boards.

Debugger Connections

Simply connect your Teensy 4.0 / 4.1 to your PC via the USB cable adapter as normal

Software Setup

Ensure you have Visual Studio and the vMicro Extension Installed (version 2020.0618.2 is the earliest to support the below menu items)

Ensure you have the GDBStub library installed as an Arduino Library (https://github.com/ftrias/TeensyDebug)

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

NOTE - As the Teensy boards support more than one serial port, the debugger can use a secondary Serial port such as SerialUSB1 to ensure your existing Serial code can function as normal on a seperate port.

COM Port Identification

To identify which COM port is your Serial Output, and which is the COM port for the Debugger, upload any sketch with the USBType set to Dual Serial as shown in the image above.

Once complete you will see two new COM devices listed.  In this example the lower device port number (e.g. COM10) is your Serial comms, and the next highest (e.g. COM11) is for the Debugger, as we configure it to use SerialUSB1.

Once this is known you can set the debug COM port setting (shown as COM11 in the image above).

Sketch Setup

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

1. Ensure you have the Debug Configuration selected from the Configuration Manager Window
2. Include the TeensyDebug.h file at the top of your sketch
3. Add the while (!SerialUSB1) {} and debug.begin(SerialUSB1) calls to your setup() (change depending on the Serial port you wish to use, this is the second port in Dual Serial Mode)

// Check we are using GDB Debugging and include the additional code
#ifdef VM_DEBUG_GDB
#include <TeensyDebug.h>
#endif

void setup(){
#ifdef VM_DEBUG_GDB
  while (!SerialUSB1) {}    // Wait for Debugger connect
  debug.begin(SerialUSB1);  // Start Debug Serial e.g. COM11
#endif
  Serial.begin(115200);     // Start User Serial e.g. COM10
}

void loop(){
  digitalWrite(LED_BUILTIN, HIGH);   // <<<<< Add A Breakpoint on this line
  delay(500);
  digitalWrite(LED_BUILTIN, LOW);
  delay(500);
}

4. Add one breakpoint to loop()  [This always has to be done for stability of the debugging session]
5. To start the debugging process, you can either:
   • "Debug > Attach to Process" button if your code has already been uploaded to the Teensy 4.x board
   • "Debug > Start Debugging" if your code has not been uploaded, or you wish to enter setup()

# Add a delay after upload before the debugger kicks in by using a ping to ourselves as a delay (Windows has no native "sleep")
recipe.hooks.deploy.postupload.1.pattern=cmd.exe /c ping localhost -n 2

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

Going Further

This specific implementation of GDBStub contains some useful extra features, such as being able to run digitalWrite() from within your debugging session, when stopped on a breakpoint!

The additional GDB Commands available are listed here on GitHub.

The process for executing GDB Commands from within Visual Micro is detailed on this page.