How to Debug your AVR Project with the Atmel-ICE

How to Debug your AVR Project with the Atmel-ICE

Debug

Microcontroller projects are complex beasts: the combination of hardware and software gives bugs plenty of room to hide from you. If you’ve ever struggled to debug your AVR microcontroller projects then jump on board – this post is just for you!

One of the tools that I valued most in my software development days was the debugger – the ability to step through code to find bugs quickly by tracing the execution path. Nowadays I don’t work on pure software projects any longer – I’ve ratcheted up the complexity by working on AVR projects combining hardware with the software. You’re dealing with this same complexity, so thankfully we have access to a debugger that can help us to step through our microcontroller-based projects. I’m sure that it’s no surprise that the debugger is a physical piece of hardware that connects to your microcontroller in order to track the code execution.

The tool that I currently use is an Atmel-ICE Basic debugger, a combination of great value and functionality. This tutorial is intended to give you an overview of how to debug your AVR projects with the Atmel ICE, focusing on the ATmega328P that I cover in my Nuts & Volts “Beyond the Arduino” series (and have built into my Toadstool mega328 board).

First Time Connections

The first time you connect your Atmel-ICE to your PC, the USB drivers will be installed. Make sure that you have installed Atmel Studio before connecting your ICE, or the drivers will not be available. When you select the Atmel ICE as the tool in the Atmel Studio “Device Programming” dialog, Atmel Studio will check whether firmware on the debugger is up to date – and if needed upgrade it for you. Read more about this here.

Step 1: Atmel-ICE Connections

Atmel-ICE connected to Toadstool

1.1 Connect the Atmel-ICE to the Target Microcontroller

The ICE uses an interface called debugWIRE to talk to the ATmega328P, although is also able to use aWire, JTAG and SWD which allow you to debug AVR 32-bit and the range of Atmel ARM Cortex microcontrollers.
SPI Pinout
The Atmel-ICE Basic only comes with one ribbon cable, which is all we need for our purposes here. Connection is really straightforward: connect the one end of the cable to the “AVR” 10-pin connector on the ICE, and connect the 6-pin ISP connector to your board. If you’re using a board with a 6-pin header (such as the Toadstool), then this is a quick plug-in; if you’re connecting to a breadboard then connect the pins in the same order as you do when connecting your programmer.

1.2 Connect the Atmel-ICE to your PC

Connect the USB cable supplied between the ICE and the PC. I have heard that the micro-USB connector on the ICE is not very robust, so I’d suggest leaving that connected and performing any connections/disconnections at the USB-to-PC connection.

1.3 Connect Power to Your Project

Unlike some programmers that are able to provide power to your project, the Atmel-ICE is not able to. You’ll need to power your project separately – and if you’re anything like me you’ll forget to do this, and spend time wondering why you can’t debug your project!

Step 2: Start a Debug Session

IMPORTANT: It it critical that you always end your debug sessions properly – do not skip Step 4 in this process, or may need to use a special high-voltage programmer to recover your microcontroller.

2.1 Select the ICE as a Tool

From the Project menu, select Project Properties and then the Tools tab. Here you need to select the Atmel-ICE and then debugWIRE interface.

Choose the Tool and debugWIRE Interface

2.2 Select the Debug Configuration

It makes sense that your project be configured in Debug mode and not in Release mode. Choose this from the drop-down on the menu bar.

Choose Debug Configuration

2.3 Start Debugging

This step can get a little complicated, so follow along carefully. When you program your microcontroller using a standard old programmer, you’re using an SPI interface. When you debug a project you need to switch to a debugWIRE interface – it can’t be in both modes at the same time. To switch to debugWIRE mode, you need to enable the DWEN fuse bit – for more on Fuses see this post. Thankfully Atmel Studio helps you to do this, but it can be quite clumsy. Here’s what you need to do:

  1. Click on the Debug menu, then Start Debugging and Break (or press Alt+F5). You should receive the below error message:
    Failed to launch debugWIRE
  2. Click on Yes. You’ll now be in debugWIRE mode but will see the below dialog:
    debugWIRE Toggle Power
  3. Follow the instructions by disconnecting and reconnecting the power on the target, and clicking on OK

You should now be in debug mode.

Step 3: Debugging a Project with the ICE

Now that you’re connected to your project using the Atmel-ICE, it’s time to start debugging the project. There are a couple of commands that you need to familiarise yourself with – we won’t go into all the possibilities here, but the following should be enough to get you started.

3.1 Stepping Through Code

The beauty of debugging is that you can execute your code one line at a time – called stepping. You are able to:

  • Step Into (F11): This executes the current line of code, and if it is a function call it will drop down into that function so you can step through the function itself.
  • Step Over (F10): This executes the current line of code, but will not drop down into a function if the instruction is a function call.
  • Step Out (F12): This completes execution of the current function, and then halts again up at the calling routine.

The best way to get comfortable with these is to experiment.

3.2 Setting Breakpoints

If your “F11” finger is getting tired stepping to the section of code you actually want to debug, then breakpoints are here to save you! Program execution halts when it hits a breakpoint, allowing you to continue stepping from that point. Toggle a breakpoint on the highlighted line of code by pressing F9, or by clicking in the grey margin to the left. A red dot in the margin indicates that a breakpoint has been set. To run up to a breakpoint click on the Continue button on the toolbar or press F5

3.3 Monitoring Variables

Now we’re getting to the good stuff – while debugging you can track the values stored in your program variables. There are a few ways to do this:

  • Hover over the variable, and a tooltip will appear with the value
  • QuickWatch: Press Shift+F9 to look at the value of the highlighted variable in a pop-up dialog box
  • Quickwatch Window

  • Locals Window: This is available at the base of your screen, and shows current available local variables
  • Locals Window

  • Watch Window: The watch window is more powerful, and allows you to keep a permanent eye on the value of a variable (or an expression) as you step through code. To add a variable to the watch window, simply drag it there, or type an expression on a new line.
    Watch Window with Expression

For more detail on watching variables, I recommend you take a look at this section in the Atmel Studio online documentation. Also be aware of Atmel Studio’s compiler optimisations – variables can “optimised out” of your code, in which case they won’t be available to be examined.

3.4 Ending Your Debug Session

When you’re done with your debugging session, click on the Stop Debugging button on the toolbar or press Ctrl+Shift+F5. You can now make changes to your code, and are ready to initiate another session.
If you have completed all debugging of your project, you should return to SPI mode!

Step 4: Leaving Debugging Mode

Here is another clunky bit of behaviour by Atmel Studio. If you don’t leave debugging mode then your microcontroller will permanently be configured for the debugWIRE interface. This means that you can’t program it using a normal SPI programmer! To leave debugging mode, disable debugWIRE and re-enable the SPI interface you need to:

  1. Start a debugging session using “Start Debugging and Break”
  2. Click on the Debug menu, then Disable debugWIRE Mode and Close

I cannot stress the importance of this enough. If you disconnect your debugger, you will no longer be able to program your microcontroller using an SPI interface unless you use a special (and costly) high-voltage programmer.

Wrapping it Up

We’ve only touched on the debugger at a high level – if you would like a more detailed tutorial please drop me a mail or pop a comment below; otherwise experimentation can go a long way. Focus on the buttons on this toolbar:
Debugging Toolbar

I hope this helps you to squish more of those bugs!

Go Beyond the Arduino
ebook - Arduino to AVR

I’ve just completed my brand new guide Arduino to AVR: Get Started in 3 Steps.
Get it now on Payhip for only $1.65.

Challenge yourself and learn how to gain the flexibility and additional control that the AVR microcontroller offers.

As a free bonus, get an ATmega328P pinout cheatsheet.

19 thoughts on “How to Debug your AVR Project with the Atmel-ICE

  1. I am trying to learn something about Arduino.
    I don’t like the way to debug on arduino with serial.port. I am trying to investigate if there is a possibility of a real debug with arduino boards,or not.
    I have some experience with some ICE of different producers. Using these Ice i can Jump from the debug to the editor, make the changes I need, rebuild the project, again to Debug and so on. So could confirm the following:
    1) Having made a project from a ,ino file on studio7, is it possible to program arduino’s board with Atmel-ICE Basic ?
    2) Having made the modifications on the reset pin (resistor an capacitor), is it possible to go in debug mode according with your tutorial
    3) Leaving Debugging Mode properly Is it possible to restart from point 1)
    4) The original bootloader is saved or you need to reinstall ?

    • Hi Paolo

      To be honest I have never tried to use the Atmel ICE on the Arduino, so I don’t have the exact answers you’re looking for. Here’s what I think:
      1) It should be possible – the Arduino UNO has an ISP header, so you would be able to. You would need to power your Arduino, as the Atmel ICE doesn’t provide power to the board
      2) I am not sure that you would need to make modifications to the board. I would try first and see how you go.
      3) Yes, that would work. You should always leave the debug mode properly!
      4) The bootloader will be overwritten, so you would need to burn a new one. Eg:http://www.crash-bang.com/resource/bootload-atmega328/

      If you are going to all this trouble, I would challenge you to build your own Arduino on a Breadboard – it’s not too hard, and good fun.

      Let me know how things go.

      Cheers
      Andrew

  2. HI Andrew
    I am back again
    At first i have to say that your tutorial is the best thing that i found on web ut to now.
    Two points;
    1) Assuming we are using the new Studio7 and the atmel-ice basic, Arduino have an ISP header to program it, i have to presume that it is working, so Arduino is or should be programmable via Atmel-ICE. In this case should be no need of a bootloader and you have same more flash to use. So you need to restore the bootloader only if you have to reprogram the board using Arduino IDE. Is it true ? 2) You are debugging then you discover you have to modify your code than debug again. Could you explain the sequence of the command you have to do ? Thank in advance Paolo

    • Hi Paolo
      Great – welcome back 🙂 And thanks for the kind words!
      1) Yes, that is correct. The bootloader is needed when you use a Serial device (eg. Arduino USB connection, FTDI board) to program your microcontroller
      2) You simply make the change to your code, then click on “Start Debugging and Break” – in other words from step 2.3. You really only need to follow step 4 when you’ve finished debugging for the day – otherwise you can really just press “Stop Debugging”, make the change, compile, and start debugging again.

      Hope that helps!
      Andrew

  3. Thanks for posting this, I can’t believe atmel has no step by step instructions like this, AVR is a strange animal to me coming from the microchip pic world. I have never bricked a pic chip, but so far I have bricked 2 ATMEGA328 chips trying to debug them using the atmel-ice, your tutorial is well done and greatly appreciated.

    • Thanks Jeff – pleased that it worked for you. The AVR is tricky, although I don’t have experience with PIC. Here’s to less bricked chips!

    • I’s sorry to tell you that I bricked my 6th chip(I use Arduino uno board ) today after following your instruction,It happen in the step 2.3 when the “debugWIRE is enabled,Toggle the target power then click ok ” message shows , I disconnect the power of my arduino uno board and reconect the power the power ,after doing that,I click ok,and the atmel studio 7 IDE tell me “Failed to enable DW:Failed to enter programming mode,ispEnterProgMode:Error status received:Got 0xc0,expected 0x00(command has failed to execute on the tool)”,Did you ever meet that problem?Do you have a solution?

      • Very sorry to hear that Steve. I haven’t come across that before, other than for another reader who had some of the connections incorrect. He had the exact same message, and we eventually traced it down to his programmer connections being incorrect.

        If you’ve checked everything, I’d suggest visiting http://www.avrfreaks.net – some of the forum readers there work for Atmel so may be able to help? Sorry, not having experienced this before makes it tough for me to help.

      • Hi
        I have receive since same days a new atmel ICE, but not yet used, . What says steve_liu make some troubles to me. I am working with TI and Freescale without this kind of problem.
        Reading the ICE manual I picked up the following informations, so the question to steve_liu is: have you applied these rules of atmel ? Because if the answer is yes we have to ask atmel why.

        “Note
        It is important to leave the SPIEN fuse programmed, the RSTDISBL fuse unprogrammed! Not doing this will render the device stuck in debugWIRE mode, and high-voltage programming will be required to revert the DWEN setting.”

        Pull-up resistors on the dW/(RESET) line must not be smaller (stronger) than 10kΩ.
        Any stabilising capacitor connected to the RESET pin must be disconnected.

        So before using the ICE I shall wait for the answer of steve_liu then i shall report my test hopping not to repeat the same experience.

          • Hi
            Thank for your answer and for the interesting address. I don’t have no DIP chips. I am using just a clone of arduino mini. Don’ t worry for time, I am making something else but I am curious to know what happen, it will save time and … Let me make a question: if I had well understood you was not able to enter in the debug session, have you
            disconnected the resistor and capacitor on the reset line of arduino ?
            By the way, there is something like ” AVR HV Rescue Shield 2″ to use with the boards instead of the chips ?

        • Hi! Paolo,I solved my problem on Arduino Uno board finally! The key is that there are two pads on Arduino Uno board called RESET-EN,if you want to enable the debugWire function on this board,you have to use a screw knife to cut the line of two pads physically(Sounds weird? but it does!),by the way,I never thought of the designer of Uno would let their users do this shanghai(rude) things, after you doing that,magic happens!

  4. By the way Happy new year
    I have tested atmel Ice with an Arduino mini (clone) and Studio7 I don’t have any problem in debugging and going back. i made it some time without any problem. The way seem to be the Following:
    a) click to PROJECT ,PROPERTIES and than TOOL modify the INTERFACE from ISP to debugWIRE. Now you have to follow the instructions of Andrews from point1.
    If you don’t select as interface debugWIRE but ISP when you click on DEBUG AND STOP You will have a message saying that with ISR is not possible to debug.
    During the debug you can make modifications of the program. You will have a message saying you have modified the program and if you will recompile or not the solution. If you say yes, it rebuild and you can going on debugging the modified program . During this actions you will stay in the debug session.
    b) when you have ended your job click on DEBUG and then DISABLE debugWIRE AND CLOSE than change again the INTERFACE (point a) from debugWIRE to ISP.
    So the enabling of fuses is done automatically by STUDIO7
    On an Arduino board it is compulsory to unsold the 100nF capacitor from the reset line and the 1Kohm resistor or replace this last one with at least 10Kohm

  5. Hi,

    This is a nice article on the new Atmel-ICE programmer – there is not much else out there on this, so you are ahead of the game. Thanks for helping everyone out.

    Some people have been frustrated by the lack of comprehensive documentation on the new programmer, especially as there is nothing ‘in the box’. I just want to point out that Atmel actually has written a good and comprehensive manual on the programmer. You can find it from within Studio 7 (not much use if you don’t use Studio 7 of course) but it is also available in PDF here:

    http://www.atmel.com/Images/Atmel-42330-Atmel-ICE_UserGuide.pdf

    One other thing which is confusing is the pinout of the 6-pin 0.1″ connector on one of the cables. What seems to be odd at first glance is that the red wire (marking wire #1 on the ribbon cable) goes to pin 3 of the 6-pin connector. There is also no explicit mention in the documentation of a prominent ‘nub’ on the 6-pin connector which seems to be a way to orient it but which is not shown on the drawings of the connector (i.e. on Figure 4-8 on page 23 of the above mentioned manual). It turns out you can trace this out by looking at the cable and reading the manual, and if you do that you can interpret Figure 4-8 as being a view down onto the 6 pin connector from above, and the red wire from the ribbon cable going to pin 3 on that connector is actually correct (it carries the SCK signal which is the red #1 wire if you look at the assignments to the wires on the ribbon cable itself). It’s just unfortunate that the 6-pin header wiring breaks convention, even more unfortunate that Atmel didn’t explicitly make a note of that, and even worse that Figure 4-8 doesn’t indicate where the ‘nub’ is (it is right next to pin 3, SCK).

    So Figure 4-8 on page 23 of the manual does correctly represent the 6-pin header connections, if you look down on that connector from above. It does check out against the wire assignments for the 10-way ribbon cable given in the manual on page 17 in Table 3-5. ‘Atmel-ICE SPI Pin Mapping’.

    Someone could/should make a nice clear diagram with a photo of the connector to clear that up for everyone! =D

    swulf

    • Hi Swulf

      Thanks for your comments, and for sharing the pinout issues. I hadn’t encountered those as I normally connect my ICE to an SPI header that I designed on my Toadstool boards – I trusted that the pinouts and “nub” position would match those of a standard SPI connector, and I was fortunately not let down. Thanks for the insight, I’m sure others will find it helpful!

      Cheers
      Andrew

  6. Please let the know the Debugging procedure for a sam controller with sam port on Atmel -ice (Swd interface). Thanks !

  7. I’ve purchased avr dragon last year. I could not manage time much working with that due to my job pressure. Seeing this tutorial I wanted to work with avr mcu. Should I buy avr ice or I can do the same using dragon since it has debugWire interface? Do you have tutorial on using avr dragon?

    • Hi I’ve never used the Dragon, but I would suggest that you look for a tutorial on using the Dragon first, and if you don’t come right then look at the ICE – just to save you money.

Leave a comment

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