As mentioned in an earlier blog post this year, hardware debuggers are the premier class of embedded debugging tools. However, until today, there were only very few relatively expensive tools around supporting the debugWIRE interface that is used by the classic ATtinys and a few ATmega MCUs.

The good news is that now you can turn an Arduino Uno, Nano, or Pro Mini into a debugWIRE hardware debugger that communicates with avr-gdb, the AVR version of the GNU project debugger.

What is dw-link?

Based on RikusW’s reverse engineering of the debugWIRE protocol and on other people’s work implementing debugWIRE debuggers and GDB stubs for the AVR, such as

I have developed dw-link, an Arduino sketch that turns your Arduino Uno or similar board into a hardware debugging probe. Basically, the probe translates between the debugWIRE protocol communicating with the target on one side and the GDB remote serial protocol (RSP) communicating with the host debugger on the other side, as shown in the following picture.

It is actually a bit more than a simple translation because RSP commands cannot be translated one-to-one into debugWIRE commands. For instance, writing into flash memory happens by arbitrary chunks in RSP, while in debugWIRE flash memory has to be written page-wise. Further, breakpoints are set and removed in a lazy fashion in order to minimize flash memory wear. And then, the different MCU types have all somewhat different ways to implement the debugWIRE operations. All in all, the code takes more than 21 KB when the debugging and unit testing parts are disabled.

How can you use it?

Using the hardware debugger is straight-forward. First, you need to setup a debugging environment/IDE and/or modify some configuration files of your Arduino environment as described in my earlier blog post. Then you simply need to

  1. download the Arduino sketch from the dw-link GitHub repository,
  2. upload it to an Uno or equivalent board,
  3. connect the Uno board to the host (over USB), and
  4. connect the Uno board to a target using a modified ISP cable or 6 single wires.

The details are described in the manual, which you also can download as a PDF file.

What are dw-link’s strong points?

  • It works with all hosts that support avr-gdb.
  • It runs on all ATmega328 boards.
  • It uses a robust and accurate single-wire serial communication library for communication over the debugWIRE line.
  • It supports high communication speed on the debugWIRE line even if the target MCU clock frequency is only 1 MHz.
  • It provides up to 32 software breakpoints.
  • It supports single-stepping that does not jump into interrupt routines.
  • Switching between debugWIRE and normal mode is straight-forward.
  • It has been tested on all MCU types that are supported by ATTinyCore, by MiniCore (except for ATmega48PB, ATmega88PB, ATmega168PB), and by MicroCore.