AVR Debugging with Atmel-ICE in MPLAB X IDE on Linux

Programming and debugging AVR Microcontrollers with debugWIRE interface

Introduction

In this article I will try to explain howto install and use Microchip's MPLAB X IDE and an Atmel-ICE prorgammer/debugger to program and debug a ATMega168P using the debugWIRE interface.

Why the ATMega168P? Because that's the AVR that I'm currently using and the debugWIRE setup can be a bit tricky1.

Installation

First We'll need to download and install some software:
  1. The MPLAB Compiler(s), There are 3
    1. MPLAB XC8 supports all 8-bit PIC® and AVR® microcontrollers (MCUs)
    2. MPLAB XC16 supports all 16-bit PIC MCUs and dsPIC® Digital Signal Controllers (DSCs)
    3. MPLAB XC32/32++ supports all 32-bit PIC and SAM MCUs and MPUs
  2. The MPLAB X IDE itself. It's also available for macOS® and Windows®.
  3. Optionally you can also get the AVR® and ARM® Toolchains which contains a modified version of the GNU Compiler Collection, but if you use the XC8 this is not needed.
Note: The XC compilers are free but there is a professional license option that gives more features, this is not required and fairly expensive for hobby use.

Now let's start the installation of the XC8 Compiler, since that's the only one I'll be using.

I'm using Debian GNU/Linux so if you are using a Debian or Ubuntu based distribution you can copy & paste these instructions, if your distro uses a different package manager you'll need to use that one to install the required dependencies.
  1. To be able to use MPLAB X IDE and the XC compilers on a 64-bit linux distribution, the 32-bit architecture support needs to be enabled. This is not done by default so you'll need to add the i386 architecture first: sudo dpkg --add-architecture i386 followed by sudo apt update.
    Figure 1. sudo dpkg --add-architecture i386
    sudo dpkg --add-architecture i386
  2. Next we'll need to add some additional 32-bit packages: sudo apt install libc6-dev:i386 libgcc-10-dev:i386 libexpat1-dev:i386 libx11-dev:i386 libxext-dev:i386
  3. Now we are ready to install the XC8 Compiler:
    Figure 2. MPLAB XC8 C Compiler
    MPLAB XC8 C Compiler
    Figure 2. License agreement
    Accept the license agreement
    Figure 2. License Type
    License Type
    Unless you have a license, use the default "Free mode"
    Figure 3. default install location
    default install location
    Accept the default installation location
    Figure 3. Add to $PATH
    Add to $PATH
    You can select "Apply settings to all users" if you have multiple user accounts, adding the xc8 to the PATH environment makes sure you can call these tools from anywhere in your filesystem and not only from the installed location.
    Figure 7. Ready to start Installation
    Ready to start Installation
    Click Next to start the installation
    Figure 8. Installation in progress
    Installation in progress
    Figure 9. Licensing Information
    Licensing Information
    When the installation is complete, you'll get a message to active or purchase a Professional license, you can just skip this with the Next button.
    Figure 10. Finisheg installation
    Finisheg installation

    The compiler is now installed. Repeat this for the other 2 compilers if needed.

  4. Finally we install the MPLAB X IDE
    Figure 11. Installing MPLAB X IDE
    Installing MPLAB X IDE
    Figure 11. Accept the License Agreement
    Accept the License Agreement
    Figure 11. Accept the default installation location
    Accept the default installation location
    Figure 11. Select required software
    Select required software
    By default all devices will be installed, but since I don't need the 16 and 32 bit MCU's I've unchecked these since they take up almost 5GB of data.
    Figure 11. Click Next to install
    Click Next to install
    Figure 11. Installation in progress
    Installation in progress
    Figure 11. Starting MPLAB X IDE
    Starting MPLAB X IDE

    After the installer if finished it drops you back into the commandine where you started it. MPLAB X IDE is not yet added to the menu system so you'll need to start it manually the first time. this should be as simple as running mplab_ide, there is also another tool installed (if you didn't uncheck it) called the Integrated Programming Environment that you can use to read/write to the microcontroller. This can be started with the command mplab_ipe. Both will be added to the menu after the first time you've launched them.

Required Hardware

Since this is an article on using an Atmel-ICE you'll offcourse need one of those to follow allong. There are other devices that are supported by MPLAB X IDE, but not all devices that are supported by Atmel Studio 7 are supported by MPLAB (for example the ATSTK600 development board contains a STK600 programmer that is supported in Atmel Studio 7, but it's not listed in the supported hardware section of MPLAB X IDE).

So basically what we need is:
  1. Atmel-ICE Programmer/debugger. There are 3 versions for sale
    1. Atmel-ICE PCBA Debugger (cheapest version without plastic casing and cables
    2. Atmel-ICE Basic Debugger (mid-range with plastic case and USB and flatcable with 10-pin 50mil connector and 6-pin 100mil connector) you'll need the 6-pin 100mil connector to connect to a standard 6-pin ISP header.
    3. Atmel-ICE Debugger (full version also including an Adapter board (20-pin 100mil connector, 6-pin 50mil connector and 10-pin 100mil connector). The 10-pin 100mil connector can be used to connect to a standard 10-pin JTAG header (ATMega2560 for example).
  2. A project that you want to debug and has a 6-pin ISP header to connect the Atmel-ICE programmer/debugger.
  3. PSU for the project. Unlike some tools the Atmel-ICE does not provide power to the target board, so you'll need to power the project board to be able to program or debug it.

Making the connection

To connect the Atmel-ICE debugger connect the flatcable to the 50mil 10-pin header labeled AVR, the red wire should be on the left side (closest to the 3 LEDs). And connect the 100mil 6-pin connector to the ISP header of the microcontroller.

Power on the Atmel-ICE (connect the USB cable). The middle (red LED) should turn on.

Power on the target board, if all goes well the leftmost (green) LED should turn on.

You are now ready to start debugging.

Putting the AVR in debugWIRE mode to program/debug

Open MPLAB X IDE
Figure 18. MPLAB X IDE
MPLAB X IDE
Write a simple test program (like a blinking LED to test programming/debugging).
Figure 19. New project
New project
Figure 19. Select target processor
Select target processor
Under Tool: all available tools are listed, if the Atmel-ICE is connected it should be listed here, if not there is the default ("no tool") and a "simulator", if you want to see all supported Tools check the Show All box and go through the list.
Figure 20. Select the compiler
Select the compiler
Select the XC8 compiler, as you can see I've also installed the Toolchain under /home/patrick/avr8/bin (version 5.4.0) the other versions are provided by my distribution.
Figure 21. Project Name
Project Name
Set a project name and location or use the default MPLAB X IDE project directory.
Figure 23. add new file
add new file
Add a new avr-main.c file (I've called mine blinkLED)
Figure 24. new file named blinkLED.c
new file

write your test program

Figure 25. test program
test program

for those who are wondering, the comments are in Dutch. I guess also the reason there are so many red-lines ;-)

Figure 25. compile and write
compile and write
Compile and write the project to the microcontroller (you can also press the "Debug Main Project" button to compile, write and start debugging).
Figure 26. switch to debugWIRE mode
switch to debugWIRE mode
If this is the first time you've started a debugging session the AVR probably still in ISP mode and this makes it not possible to use the debugWIRE interface. Answer Yes to this question and MPLAB will use the ISP mode of the Atmel-ICE to switch to debugWIRE mode.
Figure 27. Programming complete
Programming complete
If programming fails and you get an error message about a bad BAUDRATE setting, you are probably using a version of MPLAB X IDE that has a bug in it's settings. To solve this click on the Project Properties button in the project Dashboard. and open the Atmel-ICE settings.
Figure 27. Atmel-ICE ISP Settings
Atmel-ICE ISP Settings
Select Communications under Categories and ISP for the Interface. The setting there will be 0.000MHz and the Option Description reads that this setting should be between 0.000 and 0.000MHz (looks like a bug to me).
Note: I've been in contact with Microchip Support about this issue, and they confirm this is a bug in the new version (5.40) here is their reply

The issue has been reported. Kindly try the below workarounds suggested by our internal team and let us know if it helps.

In v5.40 the default speed regressed to 0.0 MHz, which causes errors such as:

Unexpected status code when executing setBaud, expected 0 but got -51 (SPI_STATUS_BAUD_INVALID)

A valid communication (such as 0.125 MHz or 1/4 of the device clock speed) must be entered when selecting the ISP communication protocol.

"workaround" #1 - Create the project in v5.35 and then open and use in v5.40.

"workaround" #2 - manually edit the configurations.xml file in the project to have a valid speed like this:

<property key="communication.speed" value="0.125"/>

Thanks to a post on the AVR Freaks forums I discovered that setting this to a value of 0.01 fixes this problem. MPLAB will say that this is wrong (indicated by the red background) but you can ignore this error message. Now switch the Interface back to debugWIRE and try again.

2
Figure 28. Toggle power
Toggle power

To switch the microcontroller to debugWIRE mode you'll need to cycle the power and click the OK button within 10 seconds. This will force the AVR to reboot and switch to debugWIRE mode.

Now you can start a debugging session
Figure 31. debugging
debugging

Back to ISP Mode

When you are done debugging you will need to switch back to ISP mode if you want to be able to use a standard ISP programmer. To do this open the Project Properties again, and go to the Atmel-ICE settings. There switch the interface from debugWIRE to ISP.

Figure 32. before
before
Figure 32. after
after

Click Apply or Ok and click the Make and Program Device Main Project button.

Figure 33. Go back to ISP mode
Go back to ISP mode

Click Yes and the microcontroller will be put back into ISP mode again.

Done!

1 at least with version 5.40 of MPLAB X IDE which seems to contain a bug in it's ISP Speed settings dialog.
2 Socket Card and Routing Card are not required but I've added those for a "shock effect" ;-) There will most likely also be cheaper HVPP programmers than the ATSTK600 since that's more than just a HVPP.