How to debug an Teensy Arduino project with GDBStub

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

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, 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:

ESP8266 Debug Toolbar Settings

 

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.

You will need to add a couple of additions to your sketch (also 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 debug.begin(SerialUSB1) call to your setup() (use which ever Serial Port you want the debugger to run through here)
    1. If you know where you want the first breakpoint in your code, add it now
    2. 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
    Teensy 4.x 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

     

    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.