Debugging IRIS motes

Even when a program executes without any problem on TOSSIM, it might not do so on a mote. If we do not have a JTAG ICE, we can use The TinyOS printf Library (TOS_2.1.1) to print out debug messages. However, if the program crashes, printed out message can only reveal very roughly where the crash occurs. For this reason, a JTAG ICE (in-circuit emulator) is a useful tool. This guide explains how to use AVR's JTAGICE mkII (mkII in short) with IRIS motes. For now, this guide is Linux-specific, because AVaRICE seems to have problems with the mkII.

First, say you connect a mote to /dev/ttyUSB2, build the TinyOS application with the "debug" target, e.g.

 make iris debug install,0 mib520,/dev/ttyUSB2

Then, without having the mkII (i.e., JTAGICE mkII) connected, you should run

 avrdude -cmib510 -pm1281 -P/dev/ttyUSB2 -U hfuse:w:0x99:m -U efuse:w:0xff:m -C/etc/avrdude/avrdude.conf

to enable the JTAG fuse. Note: to find out the proper fuse values to use, please consult this website. If you get the error "Device signature = 0xffffff", please make sure right now the JTAG is not yet connected.

Now, being very careful with the correct orientation of the JTAG connectors (TODO: provide an image), connect the mkII to the JTAG connector on the IRIS mote, and run

 sudo avarice -2 -j usb localhost:4242

The "sudo" command is necessary. If for some reason this command does not complete successfully, reset the mkII (there is an on/off switch at the back) and try again. Upon successful execution, you will see something like this:

 AVaRICE version 2.8, Jan 13 2009 03:25:55
 
 Defaulting JTAG bitrate to 250 kHz.
 
 JTAG config starting.
 Found a device: JTAGICEmkII
 Serial number:  07:00:00:00:38:29
 Reported JTAG device ID: 0x9704
 Configured for device ID: 0x9704 atmega1281
 JTAG config complete.
 Preparing the target device for On Chip Debugging.
 
 Disabling lock bits:
   LockBits -> 0xff
 
 Enabling on-chip debugging:
   Extended Fuse byte -> 0xff
       High Fuse byte -> 0x19
        Low Fuse byte -> 0xff
 Waiting for connection on port 4242.

AVaRICE is now waiting for connection by the gdb debugger. Now, assuming the TinyOS image is in the build/iris sub-directory, run

 avr-gdb build/iris/main.exe

On the command prompt of avr-gdb, input

 target remote localhost:4242

That is, on the screen, you should see something like this:

 $ avr-gdb build/iris/main.exe
 GNU gdb 6.4
 Copyright 2005 Free Software Foundation, Inc.
 GDB is free software, covered by the GNU General Public License, and you are
 welcome to change it and/or distribute copies of it under certain conditions.
 Type "show copying" to see the conditions.
 There is absolutely no warranty for GDB.  Type "show warranty" for details.
 This GDB was configured as "--host=i486-linux-gnu --target=avr"...
 (gdb) target remote localhost:4242
 Remote debugging using localhost:4242
 0x00000000 in __vectors ()

avr-gdb should have connected to AVaRICE on localhost:4242 and you should see that AVaRICE reports successful connection. On the avr-gdb command prompt, you can now run whatever gdb commands you want to run. Some useful commands are

 list func

which list all functions. For some reason, avr-gdb may not list all function names. To make a breakpoint, type

 b function_name

where function_name is just a sample function name. Specifying breakpoints by line number is problematic for nesC programs though. To start executing the program being debug, type

 c

With luck, the program should stop at the specified breakpoint. Type Control-C to interrupt the program. Sometimes avarice will lose synchronization.

For those who are interested, there is a legacy document on debugging TinyOS-1.x programs.