How to debug the Pro Mini XL or Atmega1284p using JTAG in PlatformIO

by | Oct 16, 2020 | 1 comment

On-Chip AVR Debugging Options

The on-chip debugging options available for AVRs are typically constrained by the debug architecture of the chip, the debugger hardware and supported IDEs.

Typically, Atmel Studio is the preferred IDE option given it’s full support of AVR chips and debugging interfaces, such as JTAG, debugWire and PDI.

The Atmel ICE currently provides the widest AVR architecture support for debugging as well as IDE compatibility.

The MPLAB Snap also provides wide AVR architecture support for debugging but is currently only supported in Microchip’s IDEs.

Therefore, if you are able to use these IDEs with either debugging hardware, this would be the recommended method.

However, if you must, or would prefer, to use a GDB-compatible debugging IDE, such as PlatformIO, there is another albeit a not-officially-supported option.

AVaRICE is an open source software tool that can interface the Atmel ICE with GDB and is the option presented below.

PlatformIO: Adding a Custom Debug Tool

Following the steps below will enable PlatformIO to use an Atmel ICE to upload and debug code running on an ATmega1284p chip or Pro Mini XL board.

But if you would prefer to use another IDE that does GDB-based debugging, the downloaded tools (AVaRICE and AVR-GDB) remain the same.

It is assumed that PlatformIO has already been configured and is working with the ATmega1284p or Pro Mini XL.

If not, please follow the steps detailed here before continuing.

Step 1:  Launch the VisualStudio IDE.

I’m using version 1.48 in the screenshots that follow.

Microsoft Visual Studio Code with PlatformIO Extension

Step 2:  Click on the PlatformIO button.

Note:  If you haven’t installed PlatformIO yet, I recommend following the instructions in this tutorial.

Microsoft Visual Studio Code: PlatformIO Button

The following menu system should slide out of the left hand side of the main Visual Studio Code window:

Microsoft Visual Studio Code: PlatformIO Home Quick Access Menu

Step 3:  Select the “Open” option under the section called PIO Home from the QUICK ACCESS menu.

Microsoft Visual Studio Code: PlatformIO Home - Quick Access Menu - Open

A new tab should appear with the PlatformIO home page displayed in the main Visual Studio Code window:

NoteCore version 4.3.4 and Home version 3.2.3 are shown below.  Please let me know if the following steps cause issues for any newer versions.

Microsoft Visual Studio Code: PlatformIO - Home Page Tab - Versions

Step 4:  Click on the “New Projectbutton in the Quick Access menu.

Microsoft Visual Studio Code - PlatformIO - Home Page Tab - New Project Button

The Project Wizard window should appear allowing you to set-up your new project:

Microsoft Visual Studio Code: PlatformIO - Project Wizard

Step 5:  Enter the following information for each entry in the Project Wizard window form.

The “Project name” can be anything you like – in the screenshot below, I’ve called mine “Debug Atmega1284p”. But for the other options, please select the following:
Board:     ATmega1284p (Microchip)  [or, Pro Mini XL - v1/v2, if you created a custom board for it.]
Framework: Arduino
When you are done, click the “Finishbutton.
Microsoft Visual Studio Code: PlatformIO - Project Wizard - Options

PlatformIO will now generate all the necessary project files and these files and directory structure should appear in the left hand workspace area.

Microsoft Visual Studio Code: PlatformIO - Project Wizard - New Project Opened

Note:  You can close the “Welcome” and “PIO Hometabs if you like, by clicking the “Xnext to their titles.

Step 6:  Add some example code to debug in the main.cpp file under the src (Sources) directory.

Clicking the “> srcsection in the left hand workspace area, expands to reveal the main.cpp file to click on.

Microsoft Visual Studio Code - PlatformIO - main.cpp Displayed

You can add any example code you would like to try debugging in the main.cpp file.

In the example screenshot below, I just added some simple blinky code.

Microsoft Visual Studio Code - PlatformIO - main.cpp Updated

Make sure you save the main.cpp file after you’ve finished editing it – just press Ctrl+S.

Step 7:  Edit the platformio.ini file by clicking on the filename at the bottom of the left hand workspace area.

Microsoft Visual Studio Code - PlatformIO - platformio.ini Displayed

Add the following lines to the platformio.ini file:

; Uploading with AVARICE
upload_port = --edbg
upload_flags =
 --part
 atmega1284p
 --reset-srst
upload_command = C:\Users\[Your User Name Here]\.platformio\packages\tool-avarice\bin\avarice.exe $UPLOAD_PORT $UPLOAD_FLAGS --erase --program --file $SOURCE --verify
Microsoft Visual Studio Code - PlatformIO - platformio.ini Updated

Make sure you save the platformio.ini file after you’ve finished editing it – just press Ctrl+S.

Step 9:  Download the AVaRICE software and copy the executable to the directory detailed in the upload command above.

If you are using Windows and would prefer not to have to deal with Cygwin, you can download this ZIP archive which includes all the relevant Cygwin DLLs.

The ZIP archive contains the following files and internal structure:

AVaRICE: PlatformIO ZIP Archive Contents

Extracting the above ZIP archive into the directory detailed in the upload command above, should create a new tools-avarice directory and associated files:

PlatformIO Packages Directory with AVaRICE Tool

Note:  The version of AVaRICE used in the following steps is a slightly modified v2.13svn20160229.

Step 10:  Perform an upload test to verify the AVaRICE installation works with the Atmel ICE.

Ensure your Atmel ICE is plugged in and enumerated correctly as the appropriate USB device on your computer.

In Windows 10, this looks something like the following in Device Manager:

Windows 10 Device Manager - Atmel ICE

Click the upload button at the bottom of the Visual Studio Code window.

Microsoft Visual Studio Code - PlatformIO - Upload Button

PlatformIO will now attempt to compile and upload your code through your Atmel ICE.  If it’s successful, you should see something like the following:

Microsoft Visual Studio Code - PlatformIO - Successfully Uploaded

Assuming the upload (referred to as a “Download” in the above message log) was successful, your code should now be running on your Atmega1284p.

Step 11:  Edit the platformio.ini file again and add the following lines:

build_type = debug
debug_build_flags = -g3 -ggdb3
debug_tool = custom
debug_port = localhost:4242
debug_server =
C:\Users\[Your User Name Here]\.platformio\packages\tool-avarice\bin\avarice.exe
--edbg
--part
atmega1284p
--reset-srst
$DEBUG_PORT
debug_init_cmds =
define pio_reset_halt_target
monitor reset
interrupt
end
define pio_reset_run_target
monitor reset
end
file "$PROG_PATH"
target remote $DEBUG_PORT
debug_extra_cmds =
tbreak main
break exit
Microsoft Visual Studio Code - PlatformIO - platformio.ini Debug Options

Note:  The above configuration will automatically add breakpoints on the main and exit functions.

Step 12:  Add any other breakpoints by clicking next to the corresponding source code line.

In the screenshot below I’m adding breakpoints on lines 18 and 24.

Microsoft Visual Studio Code - PlatformIO - Breakpoints - Click to Add

Before debugging, we now need to perform a few tasks through PlatformIO.

Step 13: Click on the PlatformIO button (as in Step 2).

PlatformIO should display a list of available “PROJECT TASKS” that can be carried out by simply selecting them.

Microsoft Visual Studio Code: PlatformIO - Task List

Step 14:  First, clean the project of any previously compiled object files, etc.

Microsoft Visual Studio Code: PlatformIO - Tasks - Clean

Assuming this task completes successfully, you should see something like the following in the terminal window:

Microsoft Visual Studio Code: PlatformIO - Tasks - Cleaned

Note:  Simply “press any key” as instructed to close the terminal window.

Step 15:  Once cleaned, run a “Verbose Uploadtask as this should compile the source code with all the debug symbols and then upload that code.

Microsoft Visual Studio Code: PlatformIO - Tasks - Verbose Upload

Assuming this task completes successfully, you should see something like the following in the terminal window:

Microsoft Visual Studio Code: PlatformIO - Tasks - Verbose Uploaded

If you scroll up in the terminal, you should see a line that confirms your code has been built in debug mode.

Microsoft Visual Studio Code: PlatformIO - Tasks - Verbose Uploaded - Debug Mode

Step 16:  Next, launch a debugging session by clicking on the “Start Debuggingtask, or simply press F5.

Microsoft Visual Studio Code: PlatformIO - Tasks - Start Debugging

Assuming all goes well with launching AVaRICE and GDB, you should see something like the following:

Microsoft Visual Studio Code: PlatformIO - Debug Started

In the above screenshot, you should see two breakpoints already listed under the “BREAKPOINTS” section – these are the two selected before in Step 12.

You should also see that the debugger has already stopped the Atmega1284p on the first line of main.cpp.

This is one of the temporary breakpoints (tbreak) set in the configuration options from Step 11.

Microsoft Visual Studio Code: PlatformIO - Debug Started - Breakpoints and tbreak

Step 17:  Click the Continue button or type “Cont” in the “DEBUG CONSOLE” to begin executing your compiled code on your Atmega1284p:

Microsoft Visual Studio Code: PlatformIO - Debugging - Continue

This will continue code execution on the Atmega1284p until it hits your first breakpoint.

Microsoft Visual Studio Code: PlatformIO - Debugging - First Manual Breakpoint

From the debug interface, all the usual debug operations are possible, such as stepping into or over code, or view the disassembly:

Microsoft Visual Studio Code: PlatformIO - Debugging - Disassembly

Or hover over and watch variable values in the code:

Microsoft Visual Studio Code:PIO - Debugging - Variables

Or view the memory map:

Microsoft Visual Studio Code: PlatformIO - Debugging - Memory Map

For more information on using PlatformIO’s debug interface please see their documentation.

You should now be able to upload and debug your code through PlatformIO using your Atmel ICE .

Enjoy!

Any feedback on the above instructions would be much appreciated!

1 Comment

  1. Richard

    From someone who is massively struggling with his new installation of VBC, PlatformIO, ESP-Prog (Debugger hardware) and a new ESP-32 WROOM 32 board (AZ), I appreciate your efforts. Help in any detail whatsoever is very rare! Too much advice assumes that one talks in ones sleep in Hex and pointers, has intimate knowledge of VSC and PlatformIO and knowledge about the finer details of grappling with the two cores in the ESP32. If at any point you become expert in overcoming the “environment”, or care to, I would be eager to tune in.

    Reply

Submit a Comment

Your email address will not be published. Required fields are marked *