Updates So That Lame SerialCommand Library Supports SoftwareSerial

A frequent request has been that my SerialCommand library be usable with SoftwareSerial objects. I’ve never had a use for this myself, so I never tried to code anything for it. In order to test this I had to put a setup together where I could be reading/writing to a SoftwareSerial port and still have access to the hardware serial for debugging.

For this I used a CP2103 Breakout I bought a long time ago from Sparkfun and had sitting in a box. How old? It has a green-not-red circuit board, that should be an indicator.   To make it more complicated I used an entire second computer connected to that CP2103 using our old friend Hyperterminal so I could debug it.  I tested this on an UNO R3 and Arduno IDE 1.0.5.

This version is now on github.    I have not tested it extensively, except to modify the included demo program to see that it works correctly with the SoftwareSerial line.

If you have trouble, be sure your SoftwareSerial ports are actually working the way you intend.  The library includes a tiny test program that spits stuff out your SoftwareSerial port and your hardware serial port, so you can identify which one is which.

As a note, if you used this library before, you now have to include SoftwareSerial.h in your project, even if you’re not using it.  Don’t blame me, blame the way the Arduino IDE compiler wants to preprocess things.  You could also keep using the old version of the library, as there were no functional changes other than the SoftwareSerial support.  Other than the include I don’t think it should have any effect on existing code.

Dualling Serials

Useless Updates to Useless Software

Not that it matters much, but if you’re a user of some of my Arduino libraries, there are updated versions of a couple of them now on Github.

Library for the ADT7310 16-bit temperature sensor (original posting)

SerLCD Library for the Sparkfun Serial LCD Module (original posting)

and, since it’s a requirement on the internet to have a picture of an arduino in an article about them:

ADT7310

SerLCD

Hardware Debugging the Arduino using Eclipse and the AVR Dragon

There is no music associated with this post.

I’ve written before about using an Atmel AVR Dragon to debug an Arduino board, using AVR Studio 4. I recently had some communication from Stephen Lake where he mentioned he was using Eclipse for Arduino development. I’d looked at Eclipse a long time ago and setting it up was an absolute terror with no real benefit. Stephen said it was much easier now, so I figured I’d have a look. Along the way I found the toolchain is robust enough these days to support DebugWIRE debugging of the Arduino and not have it suck too hard. I spent a lot of time trying to get the setup right, so I figured I’d detail it out if you’re trying to figure it out too, and save you the effort.

I’m standing on the shoulders of giants here. I’ve developed none of the software/plugins involved. I just put the pieces together from some disparate sources, some of which are a little out of date. The real credit goes to the authors of the software used in this. I did the setup on Windows and Linux, and the steps are 90% the same. I haven’t tried any of this out on OSX. This worked for me, maybe it will work for you. Maybe it won’t. I did this with Arduino IDE 1.0 installed.

Here’s what you’re going to need:

  • An Arduino that’s been modified for DebugWIRE operation
  • Eclipse
  • An AVR Dragon. Other debuggers might work, but a Dragon is what I have
  • WinAVR (Windows) or the AVR Toolchain (Linux)
  • libusb for Windows
  • Some patience. Okay, a lot of patience.

Get a DebugWIRE-capable Arduino

I wrote a whole big-ass article on this before, so you can reference that. For this experiment I used my modified Diecimila board. It will probably work with the UNO and other boards, I just haven’t tested them. Your mileage may vary.

Eclipse

More specifically, Eclipse IDE for C/C++ Developers (includes Incubating components). At the time of this writing Eclipse was 3.7.2. The nice thing about Eclipse is that it doesn’t have to be “installed” on your system, you can just unzip the folder and run it from that. That means you can keep many, many different versions of Eclipse configured for different tasks like I do around and not have to worry about trying something that will foul it up in some other aspect. I started out with the base CDT version and added into it. You’ll also need Java for this, of course, since Eclipse requires Java to run. Hey, I hear Eclipse can be used for Java development. groan.

On Ubuntu you can just apt-get it, but I chose to download and unzip it.

Atmel AVR Dragon

The dragon is (still) only $54 from Digikey in Canada. I’m sure you can get one just about everywhere. You can probably make all this work with the Atmel JTAG ICE III (I didn’t even know they had a III out), but those are expensive and so I don’t have one. You don’t have to do any mods to the Dragon other than maybe put some pin headers on it. I put a ZIF socket onto mine, but we won’t use it for this exercise.

AVR Dragon connected to Diecimila via ISP cable

WinAVR (ie – GCC Toolchain)

For Windows you want WinAVR. I used WinAVR 20100110 in this, and there’s nothing newer (and not likely to be anything newer). You might think that 2010 is old and you need something newer and cooler, but trust me working with the 20100110 is a lot easier than trying to build your own toolchain on Windows. When I started with this I had problems and I thought “a newer version might fix it”, and the problems just turned out to be me, and the building new stuff turned out to be a colossal pain.

You’ll also want some version of AVR Studio. In this I used 5.1 but I know it works with AVR Studio 4, since my previous article involved Studio 4. The thing to note is that v4.x and v5.x want different versions of the Dragon firmware, so if you want to go back and forth between 4.x and 5.x you’ll have to keep re-flashing the Dragon too. That’s a pain in the ass.

On Ubuntu you can just use the stock available AVR toolchain stuff,

apt-get install gcc-avr binutils-avr gdb-avr avr-libc avrdude avarice

As of this writing, the versions were gcc-avr (1:4.5.3-2), binutiles-avr (2.20.1-2), gdb-avr (7.2-1), avr-libc (1:1.7.1-2), avrdude (5.10-3), avarice (2.10-3ubuntu1). Like WinAVR, there are newer versions available but the stock ones worked (I did build avarice 2.12 to test, didn’t make any difference in what I saw). I also had the stock Ubuntu 11.10’s OpenJDK for Eclipse.

From here on out I’m going to stick to the Windows side of things, but really, if you use Ubunnnntu you’ll figure out how to set the right stuff in Eclipse, you’re smart like that.

libusb for Windows

Here’s where the pain in the ass really comes in. I spent the longest time trying to get this sequence of stuff right, and here’s what worked. This is the primary reason I wrote this article, because it was such an orderal figuring out the right way to make this all work correctly.

If you install one of your AVR Studio (v4 or v5), it will install the AVR Dragon USB driver. That’s great. The Dragon works fine in AVR Studio. Problem: nothing else will. The WinAVR stuff won’t talk through the Jungo driver to the Dragon. Instead, you’ll have to install libusb-win32 to provide an alternate usb access that the WinAVR stuff can work with.

Difficulty: when you install the libusb stuff, the Jungo driver is not active, and so AVR Studio doesn’t work with the Dragon. So if you’re like me and you keep popping back and forth between environments, you have to keep changing the driver. The good part is, it’s easy to do, it’s just busyness. There may be an alternate way to make this work, but I couldn’t find it.

So you need libusb-win32 for this. I used version 1.2.6. There is a version that comes inside the WinAVR directory itself, but I wasn’t successful getting it to work flawlessly. It probably does, but if so I wasn’t doing it right. I was able to do it right with the 1.2.6 version, so that’s what I’ll describe.

With AVR studio installed, and your dragon attached, you can check in the Windows device manager that you have a driver for “Jungo” in play, and the AVR Dragon is associated with it. Unzip the libusb-win32 stuff, and look inside for the “install-inf.exe” program. If you run that, this will make a very nice .INF style installer for your Dragon that uses the libusb driver.

Once you’re done you can push the “Install Now” button to actually install the driver.

From here on out, if you’re going to go back and forth between AVR Studio and the WinAVR-style toolchain you’ll have to learn how to switch between the Jungo driver and the libusb driver. It’s pretty easy. With your Dragon attached, bring up the device manager. Select whatever driver is currently installed, right-click and select “uninstall.” Don’t worry, this doesn’t remove anything, the driver sticks around on your computer. The driver will disappear from the device manager list. Unplug and re-plug in your Dragon via USB and you’ll see the Windows “found new hardware” message. Walk through the Install New Hardware wizard, but don’t let it automatically install anything. Choose “Install from a list or specific location”, and “Don’t search. I will choose the driver to install.” Then you’ll get to pick between the Jungo driver and the libusb driver.

Verify Dragon Operation with Jungo and libusb drivers

AVR Studio

Before you go any futher, you should verify that you can get your Dragon to work in AVR Studio and the WinAVR toolchain. Switch to the Jungo driver, start up AVR Studio, and start up the “AVR Programmer”.

You should be able to connect to your Dragon, and read the fuses on the chip. The nice thing about AVR Studio 5.1 is the programmer will tell you the correct chip if you’ve picked the wrong one. On my Diecimila it’s an ATMega168.

NOTE THE FUSE CONFIGURATION. Messing up the fuses is the easiest and fastest way to making your Arduino experience unhappy. We’re going to be changing some fuses during the course of debugging, so you’ll have to learn how to put all the fuses back correctly when you’re done. If you screw up the fuses, the on-board Arduino bootloader will not work correctly. Also note that the fuses are different for the different Arduino models. The ones I show are for my Diecimila. The ones on the UNO are set differently.

Also, you can use the AVR Studio programmer to burn the bootloader back to the Arduino in the event you mangle things up pretty good. This is useful since the Arduino IDE will let you burn the bootloader with a variety of devices but the Dragon is not one of them. Remember to choose the right bootloader for your chip for pity’s sake.

AVRDUDE and libusb

With your Dragon connected, and connect to your modified-Arduino via the ISP cable, switch over to the libusb driver as described earlier. Open up a command prompt (Start -> Run -> cmd). The main command-line program from WinAVR we’ll use will be AVRDUDE. WinAVR sets that PATH variable, so you can type avrdude commands from any directory.

Easy: Check to see that your dragon even responds. Use dragon_isp with avrdude:

avrdude -p atmega168 -c dragon_isp -Pusb 

You should get something like this:

avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.17s
avrdude: Device signature = 0x1e9406
avrdude: safemode: Fuses OK
avrdude done.  Thank you.

Sometimes you have to hit the command a couple of times before the Dragon will start talking. You’ll hear windows make that little “dunk” sound as the Dragon resets itself, and if you try to avrdude it too quickly it won’t respond correctly. With the libusb driver installed and set to be the current driver you can unplug/replug as much as you want and it’ll always use the libusb driver. It won’t go back to Jungo unless you uninstall the libusb one and switch back manually.

If you get something like this:

avrdude: Version 5.10, compiled on Jan 19 2010 at 10:45:23
         Copyright (c) 2000-2005 Brian Dean, http://www.bdmicro.com/
         Copyright (c) 2007-2009 Joerg Wunsch
         System wide configuration file is "C:\WinAVR-20100110\bin\avrdude.conf"
         Using Port                    : usb
         Using Programmer              : dragon_isp
avrdude: usbdev_open(): did not find any USB device "usb"

That means you have usb issues. Check that the libusb driver is being used. Try replugging your Dragon and see if that helps.

For even more detail, use the -v flag on avrdude:

avrdude -p atmega168 -c dragon_isp -Pusb -v

You’ll get reams of data. Remember, this is for the Diecimila with the ATMega168. If you have an UNO or a Mega or something with the ATMega328 your results will be different.

avrdude: Version 5.10, compiled on Jan 19 2010 at 10:45:23
         Copyright (c) 2000-2005 Brian Dean, http://www.bdmicro.com/
         Copyright (c) 2007-2009 Joerg Wunsch
         System wide configuration file is "C:\WinAVR-20100110\bin\avrdude.conf"
         Using Port                    : usb
         Using Programmer              : dragon_isp
avrdude: usbdev_open(): Found AVRDRAGON, serno: 00A200011176
JTAG ICE mkII sign-on message:
Communications protocol version: 1
M_MCU:
  boot-loader FW version:        255
  firmware version:              7.21
  hardware version:              1
S_MCU:
  boot-loader FW version:        255
  firmware version:              7.21
  hardware version:              7
Serial number:                   00:a2:00:01:11:76
Device ID:                       AVRDRAGON
         AVR Part                      : ATMEGA168
         Chip Erase delay              : 9000 us
         PAGEL                         : PD7
         BS2                           : PC2
         RESET disposition             : dedicated
         RETRY pulse                   : SCK
         serial program mode           : yes
         parallel program mode         : yes
         Timeout                       : 200
         StabDelay                     : 100
         CmdexeDelay                   : 25
         SyncLoops                     : 32
         ByteDelay                     : 0
         PollIndex                     : 3
         PollValue                     : 0x53
         Memory Detail                 :
                                  Block Poll               Page                       Polled
           Memory Type Mode Delay Size  Indx Paged  Size   Size #Pages MinW  MaxW   ReadBack
           ----------- ---- ----- ----- ---- ------ ------ ---- ------ ----- ----- ---------
           eeprom        65     5     4    0 no        512    4      0  3600  3600 0xff 0xff
           flash         65     6   128    0 yes     16384  128    128  4500  4500 0xff 0xff
           lfuse          0     0     0    0 no          1    0      0  4500  4500 0x00 0x00
           hfuse          0     0     0    0 no          1    0      0  4500  4500 0x00 0x00
           efuse          0     0     0    0 no          1    0      0  4500  4500 0x00 0x00
           lock           0     0     0    0 no          1    0      0  4500  4500 0x00 0x00
           calibration    0     0     0    0 no          1    0      0     0     0 0x00 0x00
           signature      0     0     0    0 no          3    0      0     0     0 0x00 0x00
         Programmer Type : DRAGON_ISP
         Description     : Atmel AVR Dragon in ISP mode
         Vtarget         : 5.0 V
         SCK period      : 8.00 us
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.16s
avrdude: Device signature = 0x1e9406
avrdude: safemode: lfuse reads as FF
avrdude: safemode: hfuse reads as DF
avrdude: safemode: efuse reads as 0
avrdude: safemode: lfuse reads as FF
avrdude: safemode: hfuse reads as DF
avrdude: safemode: efuse reads as 0
avrdude: safemode: Fuses OK
avrdude done.  Thank you.

Remember our little talk about fuses earlier? Take note of your fuse values (in my case, FF DF 00), as you’ll need them later to reset stuff. You can choose to have avrdude write them to a file, but it’s also good just to make a note somewhere.

If your Dragon talks to avrdude correctly with the libusb driver, you’re all set. Practice going back and forth between AVR Studio configuration and avrdude configuration for your Dragon.

You can also use avrdude to re-flash the arduino bootloader, in case you mess it up. Just change references to the dragon_isp and -Pusb for the configuration.

For example, for my Diecimila, and the Dragon programmer I use this, which also sets the fuses:

avrdude -p atmega168 -c dragon_isp -Pusb -v -U flash:w:ATmegaBOOT_168_diecimila.hex:i -U hfuse:w:0xDF:m -U lfuse:w:0xFF:m -U efuse:w:0x00:m

For just the bootloader, and no fuses:

avrdude -p atmega168 -c dragon_isp -Pusb -v -U flash:w:ATmegaBOOT_168_diecimila.hex:i 

Where the ATmegaBOOT_168_diecimila.hex is from the arduino bootloader directory in the Arduino IDE tree (in Arduino-1.0’s case that’s arduino-1.0\hardware\arduino\bootloaders), pick the right bootloader for your chip. Remember your fuses are probably different. Which is why it’s good to use AVRDUDE or AVR Studio to find them out and write them down before you mess with anything. The ultimate reference is your arduino boards.txt (arduino-1.0\hardware\arduino\boards.txt). If you’re too lazy to look there, there is this reference as well, but I note that one of my fuses is slightly different in my Diecimila. Look up what all the fuse codes do if you’re concerned.

AVRDUDE will erase all the flash as a feature of doing this, so if you had an arduino program on the chip it will also be gone when you re-flash the bootloader. When the Arduino is “empty” it sits there flashing the LED (pin 13) on the arduino board on and off.

Ladyada also has a tutorial on using AVRDUDE, where they talk about more of the options.

Install Arduino Support for Eclipse

This is the reason that this whole post is even possible. It used to be a huge pain in the ass. No stop, don’t do anything that article says. Instead take the advice at the top of it and go get this plugin instead. The full installation instructions are there on that nice person’s site. Thanks very much for that.

In short: in Eclipse, choose “Install new software”, enter his plugin repository address, and add the latest version of the plugin (1.2.1 as of this writing).



Now at this point you’re all set to do Arduino development in eclipse. You can write code in Eclipse, and upload it in Eclipse (via avrdude). There are some differences between doing development in Eclipse vs. doing it in the Arduino IDE. If you’re new to Eclipse you’ll find it has a shit-tonne of features and things that make you scratch your head. Also, code you develop has to be modified slightly to conform to the Eclipse CDT standards. This is detailed in the baeyens.it instructions. In particular Eclipse will throw out tons of warnings you never knew about for code that works fine in the Arduino IDE, because the Arduino IDE is set to compile with the warnings off. Warnings on is helpful if you’re trying to figure out problems, but if you’re new to the whole coding scene it will probably be pretty daunting to wrap your head around them. Also, the Eclipse ide still requires prototypes for functions, which if you’re written functions in the Arduino IDE you’re probably asking “What are prototypes?” I wouldn’t call using Eclipse for Arduino development a beginner’s task. Learn to do stuff with the Arduino IDE first. Again, the reason I’m writing this is because we want to move on to doing hardware debugging with Eclipse.

Install GDB Hardware Debugging into Eclipse

Most of this is similar to this setup for doing debugging with basic AVR chips, and not specific to the Arduino. I’ll give some specific setup points for integrating this with the Arduino plugin.

Here’s some more magic install stuff. In Eclipse “Install New Software”, and you can select “Work With: all available” sites. You will see a staggering amount of extra stuff you can install into Eclipse, only a fraction of which I even know what it does. What you’re looking for is GDB Hardware Debugging, so you can enter “gdb” into the filter box, and it will narrow the list down.

I didn’t install SimulAVR (the simulator), because I didn’t care about that. I also didn’t set up AVARice as an Eclipse “external tool” because quite frankly figuring out this debugging setup was more difficult that way. I found it much easier just to rely on running the WinAVR tools from an open command-line window.

Most of the settings are project dependent, so you’ll have to set them every time you start debugging a new project in eclipse, so I’ll go through that using some demo code.

A Simple Project in Eclipse

First off, make a new Arduino sketch in Eclipse using the Arduino plugin instructions. (File -> New Project)

Note that this will make two projects in your Eclipse tree. One for your test project, and one which contains the core Arduino code in a separate project meant for your specific Arduino board. In my case, the Diecimila. I called my project “ArduinoDebugTest.”

In the ArduinoDebugTest.cpp file, let’s use this code:

// Do not remove the include below
#include "ArduinoDebugTest.h"
#define LEDPIN 13
//The setup function is called once at startup of the sketch
void setup()
{
// Add your initialization code here
    pinMode(LEDPIN,OUTPUT);
    Serial.begin(9600);
}
// The loop function is called in an endless loop
void loop()
{
//Add your repeated code here
    digitalWrite(LEDPIN,HIGH);
    digitalWrite(LEDPIN,LOW);
    delay(1000);
    digitalWrite(LEDPIN,HIGH);
    Serial.println("I turned the LED on, off, and on again");
}

This code is pretty simple, because all we want is something simple we can use with the Dragon debugger to see that it works. It’ll flash the LED on the arduino board, then print something via the Serial porn on the Arduino.

Build this code with Eclipse (there are many ways to do this, including the little hammer icon on the toolbar, also right-clicking on the project). You’ll see in the console lots of messages go by as it builds the Arduino Core and then builds your program. If everything works out the final message will include the size of your code:

Device: atmega168
Program:    2568 bytes (15.7% Full)
(.text + .data + .bootloader)
Data:        232 bytes (22.7% Full)
(.data + .bss + .noinit)

That should look at least partially familiar, since the Arduino IDE also reports a size when it’s done compiling. Connect your Arduino board via USB to your computer and upload the code with Eclipse (the AVR upload button). Note that the Arduino Plugin very nicely sets up avrdude for you for the upload.

Here’s a fine point to remember: because you’ve modified this Arduino board to work with DebugWIRE, you’ve also lost the ability for avrdude (and the Arduino IDE, which uses avrdude) to auto-initiate the upload. So you have to be quick and push the reset button on the Arduino board when you start the upload. That will trigger the bootloader to look for a new upload for a couple of seconds, then it starts your on-chip arduino program. Timing is important. I find I can push the “AVR Upload” button, then immediately push the reset on the Diecimila and the upload works fine. You can see it works if the TX/RX led’s on the Arduino furiously light up for a few seconds. With the Arduino 1.0 IDE your timing has to be more precise because the IDE always does a build before the upload, so you have to wait until the build part is done – push the reset button – and then catch when the IDE’s upload starts. Also, in Eclipse you’ll see some status messages in the Console saying the upload is working and finishes.

After the upload finishes you should see the Arduino LED start to flash. Then start up the Arduino IDE’s serial monitor (or your favourite terminal program that you know how to get to talk to the Arduino’s usb-serial), and you should see this:

Congratulations, you’ve successfully gotten the code-edit-build-upload workflow working. Now the real fun starts. You can actually stop here and happily continue on your life using Eclipse for Arduino development and never have to bother yourself with hardware debugging.

Build your project with Debugging Info Available

With Eclipse, normally you have build configurations for “Release” and “Debug” versions. When you build for debug the compiler adds in extra symbols and shit which the debugger (GDB) uses to figure out just what the heck is going on in your compiled code, and trace that back to what the source code was.

I had issues making a “Debug” build configuration work with the Arduino plugin, and I think it’s because of the separate project for the Arduino Core that has to be compiled against. Headers would get confused and code wouldn’t build (“pins_arduino.h” kept getting involved, so something was wrong). So in the end I just elected to turn on debugging in the Release configuration and it works fine. The Arduino IDE normally does build things in debug mode (-g), and I think from the output the Arduino Eclipse Plugin is the same, so this may not make any difference – but I set some options to be sure.

In the properties for your project (not preferences for eclipse – these properties are stored for each project), go to the C/C++ Build Settings, and in the Release configuration (the only one which should be there) you want to turn on debugging information.

Normally it looks like this by default:

Change it to “Standard debugging info -g2” and “stabs (avr-gdb / insight)”. Do this for both “AVR Compiler” and “AVR C++ Compiler” to be sure.

(This may not make any difference, as the Arduino Plugin is already setting flags, but this makes me feel better).

After this you should rebuild your program, and upload it to the Arduino over the USB port.

If you have consistency problems with building, trying doing the “make clean” before rebuilding, as that will make it recompile everything. Computers are fast, you can wait the ten extra seconds.

Put Arduino chip into DebugWIRE mode

This is pretty easy, but very important. The Dragon can only debug in debugwire if debugwire is turned on in the AVR chip (duh). Problem is when debugwire is active SPI is not available, so you can’t leave debugwire on all the time. So get used to putting it in and out of debugwire mode.

To set debugwire mode, the easiest way in this workflow is to use avrdude to set the appropriate fuse. You can use the fuse calculator in eclipse, or one of a million online ones. You can also use AVR studio, but if you do this you’ll have to pop back to the Jungo USB driver, then back to the libusb driver to get anything more done.

In my case, the Diecimila’s regular hfuse setting is 0xDF (we saw that earlier with avrdude, remember?). To enable DebugWIRE the hfuse setting has to be changed to 0x9F. Use avrdude to change it:

avrdude -p atmega168 -c dragon_isp -Pusb -v -U hfuse:w:0x9F:m

Results are something like this:

Changing fuses:
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.16s
avrdude: Device signature = 0x1e9406
avrdude: safemode: lfuse reads as FF
avrdude: safemode: hfuse reads as DF
avrdude: safemode: efuse reads as 0
avrdude: reading input file "0x9F"
avrdude: writing hfuse (1 bytes):
Writing | ################################################## | 100% 0.16s
avrdude: 1 bytes of hfuse written
avrdude: verifying hfuse memory against 0x9F:
avrdude: load data hfuse data from input file 0x9F:
avrdude: input file 0x9F contains 1 bytes
avrdude: reading on-chip hfuse data:
Reading | ################################################## | 100% 0.06s
avrdude: verifying ...
avrdude: 1 bytes of hfuse verified
avrdude: safemode: lfuse reads as FF
avrdude: safemode: hfuse reads as 9F
avrdude: safemode: efuse reads as 0
avrdude: safemode: Fuses OK
avrdude done.  Thank you.

To change it back, reset them to 0xDF:

avrdude -p atmega168 -c dragon_isp -Pusb -v -U hfuse:w:0xDF:m

You may have to do the operation twice, as avrdude might have trouble on the first pass and ask you to redo the command without powercycling. There is a “-c dragon_dw” mode you can use, but I find that avrdude is smart and notices the dragon is in Debugwire mode and switches as needed.

After you change the debugwire fuse state, you have to power-cycle your Arduino. You also might as well power-cycle the Dragon itself, since I have much more “first try worked” success if both get power-cycled.

Once you’ve enabled the debugwire fuse, the Arduino’s on-board bootloader will not work. SPI is disabled and so the bootloader doesn’t function correctly. So make sure you’ve got the correct code uploaded before you enable debugwire. Otherwise you’ll have to disable it, upload, then re-enable it.

Hardware GDB Debugging with the Dragon

If you found the stuff up until now not complicated enough, this probably will satisfy you. What we’ve done up until this point is essentially the same workflow as the Arduino IDE does. What we’re going to have to do now is change the build process slightly in order to accommodate GDB, which is the program behind all the debug session stuff we’re about to do. Then we’re going to find a really big pitfall, but more when we get to that.

Debugging is accomplished through GDB. Eclipse talks to GDB. GDB knows how to talk to AVARICE. AVARICE is the program that knows how to run DebugWIRE on the AVR Dragon. The Dragon is the board that talks via DebugWIRE over the ISP cable to control the execution of code on the Arduino board. Make sense? We have to get all these layers to talk to each other correctly or none of this shit works.

We’ll start on the Eclipse end. Start by making a new “Debug Configuration” in Eclipse (click the arrow next to the little picture of the bug, a couple of squares to the right of the hammer… sigh). A dialog starts up with a bunch of C/C++ options on the left side. Click and add a new configuration on the one called “GDB Hardware Debug”

Then we’re going to march through the tabs on this debug configuration.

First thing is in the “Main” tab to pick your .elf file, which is the compiled code used by the debugger which has all the symbols and shit in it. When I use this with the standard AVR development plugin it auto-inserts the proper .elf file for me, but with the Arduino plugin you have to navigate to your Arduino Eclipse workspace and select the .elf by hand. No big deal.

Set your GDB command to be the avr-gdb.exe in the WinAVR directory. You need to change the preferred launcher to the “Standard GDB Hardware Debugging Launcher” down at the bottom of the dialog window. I couldn’t make this work with the DSF launcher. You can tell you’ve got the right one because it has the option for “protocol version: mi” as shown. I change the port number to 4242, only because the original AVR Debugging article does that.

Then in the “Startup” tab have the setup as shown. Note this is different than the AVR debugging article setup. In particular rather than break on “main” we’re going to break on “setup” since in the Arduino version of the world the “main” is hidden. Turn off reset, halt, and load image (I couldn’t get it to work anyway). Turn on load symbols. I don’t make any changes in the next two tabs (source, common) so you can leave those as is.

Once you’ve got all the settings done, you can click “Apply” and close the dialog. Don’t bother trying to start “Debug” yet, because we need to get AVARICE running.

Running AVARICE is pretty easy. In a command window:

avarice --debugwire --dragon --ignore-intr :4242

If your Dragon is connected properly, you have libusb active as the driver, and your chip is in DebugWIRE mode. you’ll see this:

AVaRICE version 2.9, Jan  7 2010 22:42:57
JTAG config starting.
Found a device: AVRDRAGON
Serial number:  00:a2:00:01:11:76
Reported debugWire device ID: 0x9406
Configured for device ID: 0x9406 atmega168
JTAG config complete.
Preparing the target device for On Chip Debugging.
Waiting for connection on port 4242.

If you get an error, check that you’re using libusb. Also in most cases just cycling the power on both the Dragon and the Arduino puts it back to working. If you give avarice a -v flag for verbose it will constantly spit shit out for you to read and not be interested in as you debug.

Are we there yet? Start the Debug Session

Okay, with your eclipse debug configuration set, debug-enabled code uploaded to the arduino, debugwire enabled, and avarice up and running and waiting for a connection, it’s time to start up the debugger. Click the little bug and select your debug configuration. It will want to change “perspective” on eclipse to show the debug windows, go ahead. It’ll also rebuild your code, but don’t worry about that, since it should be the same version that’s on your arduino already (right?).

if you look at your command window, you should see AVARICE has hooked up with GDB:

Connection opened by host 127.0.0.1, port 4951.

and ta-dah, that’s really it. Because you set the breakpoint for “setup” the code initialized and stopped at the beginning of your setup() routine. Now you can use the single-step commands in the toolbar to march through your code. When you end your debugging session AVARICE will quit, so you need to restart that before you restart debugging. The chip will remain in debugwire mode so you’re all set.

So now, you’re debugging, is it what you expected? Arduino’s success as a platform comes from the fact that the hardware is cheap, the IDE is easy to use, and the Arduino Core is a shitload huge library of awesome functions that make coding for it easy. If you use the “step into” command you’re going to be buried under the mountain of code that goes together to make your own Arduino code run, which will get pretty tedious, and you normally don’t have to debug yourself anyway. Also, timing based things (delay(), sending serial stuff) is going to get seriously broken if you try single stepping through it. Your friend in these cases is the “step over” command in the toolbar, which essentially says “run this whole command, including any subroutines, and come back after you’re done since I don’t want to see any of that single-stepped”.

As the exercise, you can single-step (step into/step over) until you get into your loop() routine, and then you can use step-over each of the digitalWrite() commands, and you should see the light on the Arduino change accordingly. When you hit the delay() and the Serial.print() you’ll want to use step-over unless you’re not bored enough single stepping.

You can set breakpoints and use the “resume” toolbar icon to say “just run until this line gets hit, then I’ll start stepping”, which can be useful if you have a lot of code that runs before your routines you want to debug are executed.

You’ll find your code keeps jumping out to this previously-hidden main() routine, which is how C/C++ actually works, so you just have to step through that back into your loop() code each time.

Also debugwire disables SPI, so if you were hoping to use this to check SPI hardware, I’m afraid you’re out of luck. Back to Serial.print(), or using something like a logic analyser (I have the Salae one).

To get back out of debugging, there’s a red button on the toolbar called “terminate”.

Note that when single-stepping it can take a seemingly long time between steps, because GDB/AVARICE/Dragon is doing a lot of talking amongst themselves getting status from your chip. I believe every time the single-stepper stops the Dragon dumps the entire contents of the Arduino’s ram for display by GDB/Eclipse. You do get lots of fun light flashing on the Dragon during all this, though.

Optimization Can Be a Bitch

The sample program above didn’t have any variables, on purpose. When you’re debugging in Eclipse one of the windows shows the variables in your program, which is – in my opinion – the best part of debugging. It lets you spy into the variables and see if variable “a” is really holding what you think it’s holding. I didn’t use any variables for illustration above because it wouldn’t have worked right, here’s why, and here’s how you work around that.

The Arduino is an embedded platform with limited ram and storage (flash). The Arduino people (correctly) turned on size optimization in the Arduino’s compiler. Optimization is big topic in compiler design, and it essentially boils down to “the user wrote this code to do this task, and as the compiler I will re-write it to make it work faster/better/smaller”

The problem with debugging optimized code is that… well, it’s different code than what you wrote. In particular, the size optimizer (-Os) on GCC will do some amazing stuff like “you set this variable, and never used it, so I removed all references to it from the actual compiled code.” There’s also the general case of “oh, you didn’t have a lot of variables, so instead of keeping them in ram I kept them in registers instead for easier access.” Variables held in registers tend not to show up in the “variable” window so you can’t spy on them, you have to go look at the registers directly.

Let’s do a little experiment to show this. Make a new Eclipse Arduino Sketch called ArduinoOptimizerTest and use this code in your .cpp file:

// Do not remove the include below
#include "ArduinoOptimizerTest.h"
//The setup function is called once at startup of the sketch
void setup()
{
    Serial.begin(9600);
}
// The loop function is called in an endless loop
void loop()
{
    int a;
    int b;
    a=25;
    b=a+a;
    Serial.print("a is ");
    Serial.println(a);
    Serial.print("b is ");
    Serial.println(b);
    delay(1000);
}

Now this is a damned boring program. It stores a number in a variable, does some math, and prints it out. Yawn. You don’t need an Arduino for this, but we will do this to show just how much the Optimizer works to make you a better person. To show we’re not cheating, build this with the debugger info set, load it onto your arduino, and check it with the serial monitor to see that it does give output. (“a is 25” “b is 50” over and over).

Easy, it worked, right? This is a stupid experiment, right? So now go into debugging mode with the Dragon. Put the chip into debugwire mode, do a debug config, and start debugging in Eclipse and have a look at what’s going on.

Oh shit, check it out. See when you ran your program and single stepped it… it never ran the a=25 / b=a+a lines, for some reason the single step went right over them to the Serial.print() line. Why did it do that? Well, check the disassembly window on the right hand side. The Disassembly is the “these are the actual machine code instructions GCC compiled your code into and are running on the Arduino.” It’s a lot of strange looking little single-purpose instructions but you can see how your code has been translated into the machine code.

See how it says “loop:”, a couple of push r16/push r17 and then the instruction pointer for “Serial.print” is that “ldi” instruction? The GCC -Os optimizer said “you know what, you set those a and b variables, but never actually use them other than to do that print, so we just skipped all that and moved it all into the print call itself. The code was simple enough that the optimizer optimized it all away. The results are the same, but the execution is different than you expected.

Note that this is not actually a problem, this is a good thing. It means the compiler is looking out for you and trying it’s damnedest to make your code fit in the limited Arduino space and still do everything you want. It does mean that if you’re stepping through the code you may get surprised.

As an aside, many many many years ago when I was writing unix code on Sun systems you could not debug optimized code at all with the debugger. You had to debug with the un-optimized code only. So if you had a bug that showed up when optimized, but not when un-optimized, you were really shit-outta-luck. It was the best thing evar(tm) when GCC started doing enough work to let you debug stuff that had been mangled by the optimizer.

So okay, as an academic exercise now, what if you want the “pure” code you wrote to debug, and not the optimized version? Easy. We go back into the project properties and turn off the optimizer (-O0 instead of -Os for both the AVR Compiler and AVR C++ Compiler).

Then you have to rebuild – right click your project and do “make clean” first, to make sure all the code gets rebuilt without optimzations. When your build finishes you’ll see that sure enough, your code is larger than when it was built with -Os. You could get a problem where the code could be too big to fit in your Arduino, but in this test case it’s still okay. Upload the code to your Arduino (remember you’ll have to take it out of debugwire mode to do that, then re-enable debugwire again), start up AVARICE, start up the debugger, and here’s what you’ll see:

See that the instruction pointer will actually be able to land on the “a=25” line, and the disassembly shows that there’s actual code assigned to it now. You can also see the disassembly directly for each of the instructions that follow (a shit load of instructions to do something that seems simple, isn’t it? This is why the optimizer works so hard for you).

In the two screenshots you can also see that “a” and “b” were set to some random values before being initialized, which is the reason you initialize variables.

Remember to re-build your projects with optimization on (-Os) again if you’re going to continue.

If you’re doing all this on Linux, you don’t have to worry about the libusb steps, since avrdude/avarice work on linux just fine with the default ubuntu install. Also there’s no AVR studio for linux, so hey, no having to deal with that end at all. Just remember how to set your chips back to factory with avrdude if you mess things up.

Condensed Version

  • Write Code in Eclipse, build without errors
  • Upload to Arduino over usb-serial in Eclipse
  • Enable DebugWIRE on Arduino with AVRDUDE
  • Start AVARICE
  • Configure and start up debugging in Eclipse
  • Debug until your eyes cross
  • Disable DebugWIRE when done

Summing Up

So this works for me, maybe it will work for you. Is it easier than debugging using my previous method with AVR Studio? I guess that depends on how much you like Eclipse.

Is this any better than debugging using AVR Studio? Not sure on that one yet, I’m still investigating doing the debug with AVR Studio 5.1. Certainly less toolchain setup in that case. Using Eclipse in the mix does give you better diagnostics on code errors than using the Arduino IDE, at the cost of more complexity.

Is any of this easier than just using Serial.print() statements? Hell no. But if you really can’t figure out why something’s not right, this might be the best way.

Finally, here’s another Arduino picture, as required by law.

Really, that's all folks.

More on the Speakjet and TTS256 Chip

As fun as it is to use the Magnevation Speakjet shield for the Arduino, perhaps you want to do an application where you don’t want to have to program all those stupid codes, as I showed in an earlier post.

At that time I mentioned the TTS256 chip from Sparkfun, which is essentially a little text-to-speech dictionary chip made to work with the Speakjet. You pump in some regular boring text over the serial connection to the TTS256, it converts it to that phoneme stuff and presto, the chip speaks.

At the time I did that previous post I didn’t have a TTS256, but now I do. Sparkfun have a very nice tutorial on how to wire up the chip into your Speakjet shield. That tutorial is really good, and has demo code and so I will repeat none of it here.

I followed the instructions as shown and had no problems, but the difference to what I did is that rather than solder the speakjet onto the shield, I soldered on a 24-pin socket (technically two sockets, since I didn’t have a 24-pin, but the effect is the same). The advantage of doing things this way is that if you want to go back to the ‘old’ way of using the Speakjet – in direct phoneme mode – all you have to do is jumper two areas in the socket and it works as it did before you ruined it.

Seriously, always use a socket with a through-hole part if you can get away with it. Makes replacing the chip a dream when you blow it up.

I have the ‘newer’ version of the board which has the surface-mount version of the speakjet (the tutorial has the through-hole version), but the pins are the same so the locations of the solder points don’t change.

Also, the sparkfun pictures are good but aren’t so clear where the connections are, so I tried to take some clearer pictures.


A Minimal Arduino Library for Processing Serial Commands

Here’s some nice music to listen to while you read this long and boring article:

Note: there have been updates to this library to include support for SoftwareSerial since this post was originally published.  The github version is the most current.

For lots of software projects, I end up writing stupid little utility libraries so I don’t have to keep re-writing crap over and over. Hence my earlier SerLCD and ADT7310 libraries I’ve published here. Here’s another dinky little thing I wrote because I was unsatisfied with the alternatives. Frequently I write code that has to interact with a host computer. The Arduino boards have a very nice, very easy to use USB-to-Serial connection on them, so you just have to write your host program to send serial bytes and you can communicate with the arduino board. Frequently what I end up needing is the arduino to respond to some commands sent from the host computer. Things like “turn off that relay” or “process this” or “move this motor to this position and stop” or “holy shit the building is burning down everybody run”. If you RTFM, the arduino libraries tell you to use the “Messenger” library for doing serial command processing (which I did, a long time ago). Unfortunately, as you then follow the trail, you are suggested in the modern age to instead of Messenger to use CmdMessenger. Stupid documentation in a Wiki. There are also things like Firmata and Bitlash, but they’re really more extensive than just having your arduino program talk to your host program. There’s nothing really wrong with CmdMessenger. It works fine. I just don’t like it. I don’t like that it depends on two other libraries (Arduino Streaming Library and Arduino Base64 Library ). I also don’t exactly see why you need base64 except to run the demo code. I also don’t like the messenging format. The commands back and forth end up just being enum’s of the commands you’ve added handlers for, so the commands all look… strange. From the example in the CmdMessenger library:

// Try typing these command messages in the serial monitor!
//
// 4,hi,heh,ho!;
// 5;
// 5,dGhlIGJlYXJzIGFyZSBhbGxyaWdodA==;
// 5,dGhvc2UgbmFzdHkgY29udHJvbCA7OyBjaGFyYWN0ZXJzICws==;
// 2;
// 6;

(The actual commands shouldn’t make any sense unless you’ve looked at what the demo code does, I just repeat it here to show the formats). All the commands become “number,something,something, …” and the number depends on what order you’ve added the handlers, so you have to do your own bookkeeping to know which number belongs to the enum of the command handlers. There’s nothing wrong with this. If you’re writing code on a host computer, the host just wants consistent format. Frequently when I’m testing I sit with the serial monitor window open and fire down commands myself. There are also times when debugging that it’s nice to just look at the commands and understand what the hell is going on. So I finally got fed up and wrote my own SerialCommand library. I based a lot of the conceptual idea off how Dreamcat4 organizes CmdMessenger. You initialize a SerialCommand object by pushing pointers to functions and associating them with a received string. The string is case-sensitive. e.g. –

// Setup callbacks for SerialCommand commands
SCmd.addCommand("ON",LED_on);       // Turns LED on
SCmd.addCommand("OFF",LED_off);        // Turns LED off
SCmd.addCommand("HELLO",SayHello);     // Echos the string argument back
SCmd.addCommand("P";,process_command);  // Converts two arguments to integers and echos them back
SCmd.addDefaultHandler(unrecognized);  // Handler for command that isn't matched  (says "What?")

The second parameter is just the function to call when that command is received:

void LED_on()
{
  Serial.println("LED on");
  digitalWrite(arduinoLED,HIGH);
}

A SerialCommand object maintains a char[] buffer, that fills with characters from the Serial() stream. When the terminator character is received (in my case, the carriage return, or ‘\r’), it then scans the buffer looking for the first word in the buffer to be the command (delimiter defaults to the space character, but you can configure that in the library). The buffer is of fixed size (configurable), and just wraps around if you overwrite the end, so it doesn’t crash but might give unintended results if you try to receive a command larger than the buffer. There is a .clearBuffer() routine, which you can use to zero out the buffer to be sure. The buffer also zeros out when a command gets recognized and processed. In the handler, you can call the .next() function to parse out the next token. It comes out as a pointer to a char string, so you can use atoi() or whatever to convert to a numeric format or do further parsing. You can keep calling next() until it returns NULL, meaning no more arguments.

void SayHello()
{
  char *arg;
  arg = SCmd.next();    // Get the next argument from the SerialCommand object buffer
  if (arg != NULL)      // As long as it existed, take it
  {
    Serial.print("Hello ");
    Serial.println(arg);
  }
  else {
    Serial.println("Hello, whoever you are");
  }
}

Essentially the whole library is just an interface to a string buffer and the strtok_r() command. It doesn’t do a lot, but it does what I want. Maybe you’d like it, but I doubt it. You can download the library here or from my repository on github. My github version is the most current one. It includes a stupid demo program. You won’t like it, it won’t do what you want, you won’t like my coding style, and if you do end up using it you’ll tell your boss you wrote it yourself and strip out my attribution and LGPL license, but hey. It works for me, that’s why I wrote it. You’ll probably like CmdMessenger a lot better. As well, it was pointed out to me by Stephen Lake that Stefan Rado (github user kroimon) has made a modified version available on github, which you might find more appealing. As usual, unzip it and drop the folder into your libraries folder (e.g. My Documents\Arduino\libraries, on Windows). In the tradition of useless sample output, here’s some useless sample output: and because apparently you’re not allowed to post about arduino on the intarweb without including a picture of an arduino, here’s arduino Mega running the SerialCommand demo program. Not like you can actually tell, but hey.

Woe to the Stupidshield

(There still is no music associated with this post)

Here’s what I figured was a useful shield for an arduino that I wanted when I was debugging all that bullshit SPI interaction when I was making the ADT7310/Logshield combination. It’s a passthrough shield that has a breakout for all arduino pins that can be inserted between the arduino and a shield. Not fancy, but let’s you get access to any pin easily without having to grope around and get a spring clip onto a board.

Having said that, I finished the ADT7310/Logshield long before this thing showed up from the boardhaus. Maybe this will be helpful on my next project.

You don’t need me to show you this, here’s the schematic and the board layout. These were done with Eagle, but come on – you could lay these out with an ink marker if you wanted. I hand routed the traces since that was easier than watching the autorouter put tons of vias in.

I started the Eagle design from the Macetech Scaffold (there is a newer version than I used), simply because it has the board outline and header positions right. The Arduino has non-standard pin spacing between the headers for some unfathomable reason, and now that shields are designed around it they can’t change. Another option is to start from a design like the Adafruit protoshield, and just toss out the bits you don’t want.

The two 90-pin connectors are digikey # S5559-ND and # S5561-ND. I’m sure you can get them just about everywhere.

90-Pin Connectors S5559-ND and S5561-ND

You can get the stacking headers from Adafruit, although I got mine from eBay.

Stackable Headers

Unfortunately, there was an error at the boardhaus, and the boards showed up… wrong.

That was supposed to be copper, not silkscreen

At first I thought I messed up the gerbers, which would be pretty damned embarassing considering how simple this board is. I checked with le boardhaus, and it turned out to be manufacturing on their end – the place that actually produced the board mistook the copper layer for a silkscreen layer. I have no clue how you could, they were named correctly and passed all the DRC checks, but hey. They offered to make me another set for free, or give me a refund. I elected to get them to make me a proper set, what the heck.

Of course, the last set took a month to arrive, and I didn’t really want to wait another month before writing this post assembling the board, so I resorted to my gorilla/guerrilla bluewire ratnest fix.

and finally, here it is doing it’s actual job – sandwiched between an Arduino and a shield.

Stupidshield on Arduino Stupidshield and Logshield, note connectors peeking out from the stupidshield

An Arduino Library for the ADT7310 SPI Temperature Sensor

(There is no music associated with this post, either)

I wanted a temperature logger for monitoring one of my labs. In the first iteration I used an Adafruit Data Logging Shield with a TMP36 sensor, pretty much as they describe in their fridge logger tutorial.

Problem: the problem that always comes up with microcontroller measurements. That stupid 10-bit A/D converter. I realize that microcontrollers aren’t supposed to be high-accuracy data acquisition systems, but damn I wish they were at least 12-bit. 10-bit means 1024 (2^10) discrete measurement levels. That’s great when reading a potentiometer position, but it introduces a lot of quantize error with things like the TMP36.

Quantizing sucks

The TMP36 works from -40 C to +125C, with 750mV output at 25 C and 10mV/C range. If you use the TMP36 with the 3.3V source and reference, that means that 10-bits gives you… 3.22 mV resolution per bit.

Example: The arduino A/D reads a value of 200 (0.645 V with a 3.3V reference). That corresponds to temperature (0.645-0.5)*100 = 14.45 C. If the A/D reads 201 (one bit higher), that corresponds to a temperature of 14.77 C. So you can see that your temperature quantizes to 0.32 C. You can’t read 14.6 C, it clips to either 14.45 or 14.77. If you’re monitoring room temperature that kinda sucks.

Who cares

So, what to do? You can get a more sensitive temperature sensor. The TMP37 has a sensitivity 20 mV/C. Still not a lot of bits in the range I want to use it in. If the lab gets above 100 C I figure it’s time to get the fuck out anyway.

Another solution You could get a different outboard A/D and use it to read the TMP36. I’ve used MCP3304’s (12/13-bit SPI A/D), but that’s a lot of effort just to read one sensor. the TMP’s are only really rated at +/- 1 C at 25 C anyway, so at some point the sensor itself is going to be the limit.

The route I went was: find a temperature sensor with a digital output (SPI, I2C, whatever) that has higher resolution, skipping the A/D issue. For no good reason I picked the Analog Devices ADT7310. It has an SPI interface, doesn’t require calibration, and is 16-bit capable (0.0078 C resolution). They were also fairly cheap ($3 from digikey).

Package issues

First issue was just wiring the stupid thing up. I wanted to use it with that Adafruit Logger Shield I mentioned earlier. The ADT7310 is an SOIC package, and the Logshield doesn’t have any footprint placement for SOIC parts (the protoshield does, but the logshield just has some through-hole places). A long time ago I shunned surface-mount parts because I solder like a gorilla, but in these times if you want IC’s you have to go surface-mount. At least it wasn’t a BGA.

To solve this first problem, I used a couple of different little SOIC-pin header adapter boards. The first couple I built I adapted from a 20-pin SOIC board I had lying around, so I cut the board short with a dremel. Nice but the spacing is wide, so it covers lots of holes. A later one I use some really sexy small adapters from Sparkfun. $2.95 was a little much, but still cheaper than making my own board.

I’m old, half blind, and my hands aren’t all that steady. All of that can be compensated for by doing something easy: solder under a microscope. I bought a cheap stereo dissecting scope from eBay a few years ago and it makes soldering all these fine pitch things a dream. Use a fine-tip iron, thin solder, and a solder fluxpen and yer golden.

Here’s some of the completed modules.

I put on a 0.1 uF capacitor, as recommended (ADT7310 needs it), and the two recommended pullup resistors for the alarm pins. I don’t know if the chip works just as good without the pullups, but it was easy to put them on. Shows how small this package is when it’s dwarfed by the through-hole resistors. In a better design you could use some SMT chip resistors.

Some issues found during the breadboard stage

First thing, is this silly chip is really fussy. That decoupling cap on the power? Yeah, you really need that. I had a hell of a time getting the communication over SPI to work with this chip, and a lot of it was fixed by adding the decoupling cap, and using shorter leads to the breadboard. The chip would happily clock along and drop an error every few measurements. Decoupling cap dropped that to a few dozen measurements, and short leads meant I could run tens of millions of measurements (no joke) without errors.

Errors? Yeah. With some SPI devices, selecting them with the chip select does the reset and sets things up for a read/write and you’re good to go. The MCP3304 works like that, I believe. The ADT7310 powers up, gets its registers configured, and then you communicate with SPI. If the chip gets fussy or you lose a bit or a clock somewhere, it goes into sulk mode and won’t respond with anything other than “0” on output. The only way out of this is to do the soft reset – clock in 32 or more “1’s” on the SPI line and the ADT7310 resets itself. It also means you have to reconfigure your configuration registers if you changed them from the default powerup settings.

In the first few trials writing for this guy I was doing “bit-bang” SPI, where I was providing my own clock and control signals directly. This works great, but again mr. fussy ADT7310 was very specific about when the clocks had to come. Mysterious stuff like losing the last bit on a read, that sort of thing. Although I did get that working I then re-coded everything to use the Hardware SPI, as I was able to make the SD card (which also uses SPI) and the ADT7310 co-exist on the Arduino logshield without interfering. Using Arduino’s hardware SPI library is a lot easier, too – let it do all the heavy lifting.

The problem I had was trying to determine if you’ve lost communication sync. If the chip is sulking all it will do is crank out “0” on the output. If you were actually reading a temperature that was around zero that might make it hard to detect. The technique I eventually settled on was to do things the hard way: after reading the temperature, check the Tcrit setpoint register (the ADT7310 has a couple of setpoint registers that can hardware assert two pins on the chip for alarm interrupt purposes, the setpoints are set through writing to one of the registers, and can be read back). Register 0x04 (Tcrit) very nicely has a default value of 0x4980 (147 degrees) at powerup, so it’s got enough bits to give me confidence things are still reading right (0x06-Thigh has 0x2000 and 0x07-Tlow has 0x0500, not enough ‘set’ bits to be confident you’re reading them all correctly). Mind you, you can always load one of these registers with whatever value you wanted.

Something that would have really helped doing this was spying on the SPI bus with a logic analyser. Using an oscilloscope is okay, but it can be hard to track what you’re seeing if you don’t have storage. Although I figured out my bit-bang issues before it showed up, I broke down and bought a Saleae Logic Analyser. I hooked that shit up and it worked exactly as advertised. I should have bought it sooner.

So in general, my strategy was:

  • Read temperature register 0x02
  • Read Tcrit register 0x04, compare with known value (0x4980)
  • If you get 0x4980 from 0x04, the temp was probably fine. If not, you’re probably desynchronized and should reset the chip.

So once I had things actually working, I coded everything up into a functional ADT7310 Arduino Library. Like the SerLCD library I’ve previously discussed, putting it up as a proper object-oriented library makes things nice and clean and encapsulates a lot of the busy work so you don’t have to worry about it.

The ADT7310 has lots of operation modes (16-bit, 13-bit, continuous, one-shot, etc). I really only tested all this in 16-bit continuous mode. Everything is just SPI commands though, so it should work (cough). The Datasheet explains what all the modes do, and I include some #define‘s to make it simpler to initialize the chip. I didn’t include any support for the “continuous read” method (I didn’t really care about doing that), or reading the status of the Tlow/Tcrit/Thigh flags (since they don’t appear in the 16-bit read), but you can just pull the bits out yourself from the register 0x02 read value.

Download the library here. This version is now old, the github version is the current one.

You can also download it from github.

Again, like the SerLCD one I made it’s under LGPL because I really don’t give a crap, and I know all you people trying to do your homework aren’t paying attention to licenses anyway.

The library includes functions for reading and writing registers in 8/16 bit modes. It also has a reset function to reset the chip (but does not reprogram the mode, you do that yourself), and it includes a function to convert the 16/13/10/9bit values into temperatures. Why you would use this chip and not go for full on badass 16-bit mode is beyond me, but it’s there. The library also includes a demo example on using reading temperature and checking for desynchronization error. It does depend on the SPI.h library, which is included in the Arduino software package now. I’ve tested this under arduino-0021.

It’s one of those “it works for me” situations now, your mileage may vary. If you don’t like it, tough.

The Arduino Duemilanove with ATMega328 and that Reset Line

This one is a small followup to my earlier discussion of how to pop of the capacitor of an Arduino Diecimilia so you can both disable the auto-reset and use debugWIRE.

At the time I did that post I had Duemilanove’s in my posession but I was doing the project with the Diecimila, so I didn’t really go into that board. The Duemilanove has the advantage of not having to change a jumper for the DC power/USB power, as it auto-switches.

In the documentation page for the Duemilanove. they discuss the auto-reset line (not in the context of debugWIRE, but it’s the same thing):

The Duemilanove contains a trace that can be cut to disable the auto-reset. The pads on either side of the trace can be soldered together to re-enable it. It’s labeled “RESET-EN”.

I never made the mod to any of my Duemilanoves as I never needed it, but certainly nicer than the “pop off the capacitor” method, since it’s reversible with just a soldering iron and doesn’t require you to re-solder the chip capacitor. I’ve also wondered if you could solder a jumper onto the pads and so be able to enable/disable the auto-reset/debug at will.

But never mind that. A couple of days ago I got a new batch of Duemilanoves for projects. These ones I ordered were the ones that advertised that they were the ATMega328 version (as opposed to the ATMega168 on the Diecilimia and original Duemilanove). Here’s a look at the top and bottom.


Top View


Underside

The board is marked with the appropriate logos and such, and I bought it from a reputable place, so I think it’s an authentic Duemilanove, as opposed to a workalike from the same design (there are lots of Arduino clones, since it’s open design, and there’s nothing wrong with them).

So I was working with this one today, and I thought, “huh, this looks different”. I lined it up against one of my existing Duemilanoves.

Old Duemilanove on Top, ATMega328 Version on bottom

I didn’t see it at first, either. Here, let me point it out.

RESET-EN pads are missing from ATMega328 Version

Yep, the newer ATMega328 version of the board (which shouldn’t be any different other than the chip plugged in the socket) is missing those “RESET-EN” pads. That’s disappointing.

Here’s a couple of views under my microscope, since I like using my microscope.

Original Duemilanove with pads

Pads missing from the ATMega328 version

The hardware reference page doesn’t mention this change.

What does this mean? Well, nothing really. Board still works fine, and you get the ATMega328 for more space. It just means that if you want to do the auto-reset/debugWIRE changes, you’re back to doing them by my “Pop off the capacitor” method. Have fun.

Modify an Arduino for DebugWIRE

This article talks about the Diecimila, but there is a newer article that talks about the Duemilanove

Here’s a departure. Today I’m going to give a little instruction in how to modify an Arduino board so you can actually do something useful with it – like debug it.

No warranty is expressed or implied in this. If you do this and you wreck your Arduino, your AVR Dragon, your wife leaves you and the dog eats your shoes don’t complain to me. Blah blah blah.

The Arduino (http://www.arduino.cc) is a very nice idea. Little boards based on the Atmel 8-bit line of microcontrollers. Nice and cheap basic little boards that have a USB connection, and an onboard bootloader so you don’t need another piece of hardware to program it. You program in a language they say is based on Processing, but to the user just looks like C++ with a lot of busy-work done in libraries for you. If you’re new to microcontrollers but want to do stuff, the Arduino is a good choice for a start. There’s also a significant community built up around the Arduino now, so you have lots of other people to compare with for help and ideas.

What’s nice about the Arduino is the hardware isn’t particularly bound to the pseudo-Processing-C++ language. If the day comes you become frustrated with the limitations on Arduino code and want to go on and be a full on Atmel Assembler/GCC nerd, you can. You can also ditch the onboard bootloader for more space, if you feel like it.

Speaking from my background, I do some embedded system stuff, and the frustrating part of the Arduino is the lack of an “ICE” (In-Circuit-Emulation)/”OCD” (On-Chip-Debugging) workflow. Sure, you can pepper your code with Serial.println() statements, but that only gets you so far if you’re staring at the board and asking “Just why aren’t you doing what I want?”

With previous Atmel microcontrollers I’ve worked with they have an interface called JTAG. A few years ago I went out and bought a JTAGICE clone so I could debug my stuff. JTAG is great.

Problem: The chip on the Arduino Diecimila/Duemilanove (ATMega168 or ATMega328), doesn’t have JTAG. Whoops.

The chips used in the Arduino use Atmel’s fancy new proprietary method called “DebugWIRE.” JTAG uses a ten-pin connector and uses I/O lines that your circuit might want during debugging. DebugWIRE allegedly uses just one – the reset line. I say “allegedly” since you seem to have to be hooked up via the ISP (in-circuit-programming) six-pin connector to make it work, but at least it doesn’t take out one of your I/O banks.

The barrier to DebugWIRE for me for a long time was the cost. Normally you had to buy the JTAGICEMKII. which is damned expensive (CDN$352 at Digikey. I seem to recall a couple of years ago that thing was $600. There aren’t any clones that I know of for the JTACICEMKII since DebugWIRE is proprietary. I think my JTAGICE clone was only $70 in 2005.

Enter… the Dragon.

The AVR Dragon is a nice little programmer that

  • Has USB (no fussing with 9-pin serial ports)
  • Does DebugWIRE, ISP, and JTAG
  • Is Cheap ($57.74 at Digikey. Not super-cheap, but not $352).

In the picture of my Dragon, I’ve added a 40-pin ZIF socket and some more pin headers. The default Dragon does have ISP and JTAG headers mounted, so it’ll work for this stuff right out of the box.

In my first experiment with the Dragon I was unhappy to find it did not work with the Arduino board. Hook it up, kinda get a response, but generally nothing worked right. Did some reading, did some looking at schematics, and here’s the problem:

This is for an Arduino Diecimilia board, the Duemilanove might be a little different, check first.

One of the nice things the Arduino does for the casual user is eliminate the need for fussing with bootloaders and external programming hardware. One trick it uses is to trigger the RESET line via the USB controller chip – this way when you go to “Upload” your program from the Arduino IDE it issues a board reset (thus activating the bootloader) and slurps up your code over USB. The problem: it does this by tying one of the USB FTDI chip serial control lines to the ATMega168 RESET line via a 100 nF capacitor.

Remember, DebugWIRE uses the RESET pin to do all the chip control and debugging. The protocol is proprietary, but let’s be realistic – there’s no easy way to do On-Chip-Debugging via one stupid pin and not have to signal the hell out of that pin – who knows in what weird ways. With this 100 nF dude in place, DebugWIRE gets all confused and… you get disappointing results.

So I figured, I spent my $57.74, and I have some time, I’d see if this assertion was correct. I tracked down in the schematic (shown above) and from the Diecimila page what component would have to be removed. I couldn’t trace very well on the nice little board itself, so I dug out the schematic in Eagle and made sure of the location of the capacitor to be removed in the board layout. (Aside: Eagle is nice, free to use for small things, cheap for non-profit hobby folks).

As lots of people will tell you, hand-soldering with surface-mount components is a pain. Luckily you don’t have to solder anything onto the board, you just have to remove the one there. I did it my favourite way, which is looking down a stereo dissecting microscope – which you can buy off eBay for a hundred bucks. If you’re going to solder small things and you’re half-blind like I am, a microscope is worth it.

So, a quick trip under the microscope. I took out the Atmel microcontroller from the board (it’s in a socket, hey hey smart people) to make sure I didn’t destroy it by accident. Heat up the pad with the iron, use a little soder-wick, use a little pressure and the capacitor pops off. You could use a vacuum desoldering gun, one of those spring-loaded jobs, or you could probably just cut the capacitor in half with an x-acto knife if you’re so inclined, I suppose.

That was pretty easy, wasn’t it? If you were super-ambitious you could wire in a jumper so you could engage the capacitor when you weren’t needing to use the debugger. I wasn’t that ambitious. Here’s why you might want to consider this:

You’ll recall from earlier I said that Arduino’s IDE used this capacitor to auto-reset the board via USB when you went to do a code upload. Well, thanks to this surgery that capability’s been removed. What that entails is that when you want to program the Arduino now, you have to manually hit the big reset button on the board a couple of seconds before the Arduino IDE attempts to download it. Arduino’s IDE does a compile before an upload, so in my case I just wait for the message about a successful compilation to appear and hit the reset. Chip goes into bootloader mode, IDE triggers a new upload, everything’s great.

So let’s consider getting setup for a DebugWIRE session on the Diecimila. We’ll use this boring demo code from the Blink demo that everyone can understand:

This is a graphic because WordPress\’ code tag doesn\’t work right.

I used arduino-0017 for this. I’ve heard with 0018 that it changes handling for locations of compiled code, so take that into account. Compile the code with the Arduino IDE and upload it to the board, and watch the hardware perform as it should.

Now, hookup the Dragon via the ISP connector

Hardware for debugging is only half the magic. The other magic is AVR Studio 4, which is Atmel’s own free development environment for programming Atmel stuff. Couple this with the free GCC compiler WinAVR. AVR Studio does Assembler, and if you have WinAVR installed will also let you jack in and program with GCC (C normally, C++ if you’re a risky fellow). You’ll need WinAVR for this experiment, for reasons that will become obvious.

This is important, because microcontrollers like the ATMega168 don’t ‘speak’ C, they speak assembler opcodes. When you program it you’re downloading a bunch of assembler hex bytecode that actually makes the chip operate. AVR Studio lets you jump one step back and use your GCC source code to step through program operation on the chip.

Here’s why this works: although Arduino’s language is called a variant of “Processing”, under the hood it’s really just GCC C/C++ with a lot of nice libraries for handling the hardware easily. When the Arduino IDE compiles, it invokes the GCC compiler and produces a hexcode file to upload to the Arduino.

So this means – you compile your code in Arduino’s IDE, then you load the compiled project into AVR Studio. In AVR Studio 4 you open an existing file, navigate into the subdirectory called “applet” under where the “Blink.pde” source was saved, and open the file that ends in “.elf” ELF is a format that AVR can use to “connect the dots” between the .hex you loaded onto the Arduino, and the Arduino (secretly C/C++) source code you actually wrote. AVR Studio will want to save your project as a new project, which you should.

Note you don’t have to recompile anything with AVR Studio, just open up the .elf in it, and AVR Studio will take over.

Then it’s just a matter of hooking up the Dragon and configuring it in AVR Studio. Configure your project to use the AVR Dragon (not the Simulator) and set the installed chip type correctly (ATMega168 in this case). “Select Platform and Device”. .

Tell it you’re using ISP to start. With the right chip selected, pick “Read Signature”. This makes the Dragon talk to the chip, and find out who it is. If you have trouble with your hardware setup this is where you’ll find it first. Make sure it reads the correct signature before you go any further.

You can check the fuses of the chip (more on this later):
Fuses are ATMega settings that are stored on the chip, like which interfaces are active, and the chip’s reset condition. If this is your first time looking at this board, take note of all the fuse settings in case you goober them up and have to reset them to the Arduino’s default settings.

Then it’s just a matter of starting a debug session (“Start Debugging”). If your chip isn’t in funky DebugWIRE mode AVR Studio will prompt you to change it. Here’s where things start to get dangerous. Once you enable DebugWIRE, you can’t use the ISP interface anymore (the SPI interface is disabled). This means if you goof something up in DebugWIRE mode you can’t use the ISP or the Arduino Bootloader to reprogram the chip.

This isn’t what some call “bricking” the chip. It’s still perfectly fine, you just have to get it out of DebugWIRE mode first. The problem is there’s only one spot to actually do that, so you tend to forget to do it. That’s in the Dragon programmer options. Once you disable DebugWIRE everything goes back to normal.

If you’re like me, and you accidentally did goober your chip up, you can pull the chip and put it into another programmer (like your Dragon, if you’ve outfitted it with the sockets, or an STK500 in my case) and use the high-voltage programming mode. HVPP mode doesn’t care about SPI being enabled or not, and is how I saved myself every time I did a “whoops, screwed that up, time for a reset” while figuring all this out. This is where those fuses are important. If you use HVPP and muck up the fuses for bootloader and boot reset configuration, the Arduino’s Bootloader will mysteriously work exactly once and never again, making you reflash the bootloader code. I know, I did that. The bootloader code is in the Arduino software directory, with a .hex for your particular board. You can reflash it to the chip with AVR Studio.

Protip: To get the chip out of DebugWIRE mode, you just have to start a debug session with the Dragon in place. You don’t have to have the actual code that’s on the Arduino at the moment. Just load up something (like the blink.cpp.elf project), go into the Dragon options and just disable DebugWIRE. Presto, good as new. Someday Atmel may fix this deficiency in AVR Studio, but this works for now.

So… hardware hooked up? DebugWIRE enabled? Well hell, start debugging. AVR Studio will find all your source code files and give you all the magic you need to single-step and breakpoint operate your Arduino. You’ll find your code has some extras in it you didn’t write, since that’s the nature of the preprocessor that Processing uses to get the code to compile by GCC, but that’s a story for another time.

That’s a lot of words to say “remove a capacitor and it works.”