GoodFET MSP430 Tutorial

by Travis Goodspeed <travis at radiantmachines.com>

N.B., that this is quite outdated. See the GoodFET Tutorial for a more recent description.



This is a quick tutorial for using the GoodFET to program an MSP430. This should work for all classic MSP430 chips which support 4-wire JTAG, but it will not yet work with SpyBiWire or MSP430X2 chips, such as the MSP430F5xx and CC430. As these instructions will likely become dated very quickly, expect some surprises.

Prerequisites

You will need a GoodFET board, complete with the clock crystal. Your workstation should have Python, Subversion, MSPGCC, and msp430-bsl installed. I assume below that you are using some form of Unix, but the software ought to be compatible with Cygwin. Those who are unfamiliar with Cygwin should wait for a GUI client that I'll release later this year.

If you are familiar with SMD soldering, email or catch me at a conference for a gratis board of the most recent revision.

Subversion Checkout

Grab the entire project by running "svn co https://goodfet.svn.sourceforge.net/svnroot/goodfet". Future updates may be grabbed by "svn update".

Clients

CD to "goodfet/trunk/client" and run "sudo make link". This will link the client scripts to /usr/local/bin/, keeping the originals in the subversion directory to be easily updated. At this point, you can call up the "goodfet.msp430" command's usage by running it without parameters.

Firmware

Change your directory to "goodfet/trunk/firmware", then run "make" to compile a firmware image. If there are errors, check your MSPGCC installation. Once compilation succeeds, run "make install" to load the firmware into the GoodFET device.

Dumping an Image

The "goodfet.msp430" script is a stand-in until I get around to writing a proper client. To dump a target's firmware, the usage is "/usr/local/bin/goodfet.msp430 dump $foo.hex [0x$start 0x$stop]". To dump the BSL, which resides in the region [0xC00,0xFFF],


As I collect BSL images, it would be neighborly of you to send the bsl.hex file my way. Dump with no range will dump all memory above 0x200, which is to say all memory that may be safely read without side effects.

Erasing a Chip

The "erase" verb will mass erase all memory except for the DCO configuration. An erase is automatically performed prior to a flash.

Flashing an Image

The "flash" verb of this client will flash an image to the target board. Every address evenly divisible by 0x100 is printed as a sort of progress meter,


Each word is validated as it is written, making it easy to identify when writes go bad. In the photo below, words were miswritten from 0x2500 to 0x2508, but later words were written properly.


That's all, folks. Expect a slew of firmware updates for the GoodFET over the next few weeks, and perhaps a GUI client of some sort.

Cold, Labless HNO3 Decapping Procedure

by Travis Goodspeed <travis at radiantmachines.com>
with thanks to Brooke Hill

The following are instructions and matching photos for removing the packaging of microchips without a proper chemical laboratory. Neither a hot plate nor a fume hood is required, and the only chemicals necessary are fuming nitric acid and acetone. The result is a bare die, with bonding wires. The bonding wires may then be removed and the die photographed using microscope.

The same as any author of a lay chemistry article, I must caution you to be very careful with the procedure that I describe. If you've no prior experience with chemistry, purchase an introductory book and study the safety instructions thoroughly. Nitric acid in these concentrations is nasty stuff, even when cold.

Materials

You will need two small vials with wax-paper seals, high-purity HNO3, acetone, tweezers, and a few pipettes. A fume hood is not required, as the reaction will be performed at room temperature. Safety glasses are recommended.

Surface mount chips are preferred for this method, as they have considerably less packaging to dissolve. I chose the CC2430, CC2431, and EM250 chips because they were handy, but also because I don't yet have die photographs of them.

Procedure

Begin by dropping the chips to be decapped into a vial.


Then add nitric acid to cover the chips, plus a bit more. This will react slowly, rather than violently, but for safety's sake be damned sure never to look down any sort of glassware when mixing in a new reactant. You will see the reaction as small bubbles that come from the chip casing as it dissolves.


This will slowly turn the nitric acid from yellow to a dark green. Agitate it occasionally to ensure that all of the plastic gets a chance to break away.


Leave the mixture overnight, allowing the plastic sludge to settle to the bottom of the vial. The liquid above it is still-potent nitric acid, which may be skimmed off with a pipette. Save this in a second bottle for future use, but do not reintroduce it to your bottle of clean acid.


At this point, you've got a vial which contains a lot of plastic gunk and very little liquid. Flush it with water to remove the soluble gunk, then dump the remainder into a shot glass for sorting with tweezers. (Pick the chips up by their bonding wires, as you might scratch the surface.)

Result

Once decapped, each die should be cleaned in acetone. For microscope photography, the bonding wires ought to also be plucked by tweezers.

SPI Client Tutorial for the GoodFET

by Travis Goodspeed <travis at radiantmachines.com>



I've just confirmed that SPI support is functional on the GoodFET, but I've done so with my ugly-as-sin Python client. I'd much rather that neighborly souls write their own clients for this device. The following article describes the protocol by which this is done, as well as some snippets of the GoodFET firmware. The present code should be sufficient to write an AVR programmer, an interface for Chipcon radios, and all sorts of other neighborly things.

SPI is a synchronous, full-duplex serial protocol, which is an uptown way of saying that it has a clock and that bits are simultaneously transmitted and received. Whenever you transmit a byte, you are actually exchanging values of a register. Instead of start and stop bits, clocks are synchronized by the falling of the !SS (Slave Select) line, and then they remain synchronized by counting bits. Data is transmitted MSB-first, received LSB-first.

The GoodFET attaches by a USB serial port, one which is also used for programming. As the DTR, Data Terminal Ready, line is connected to the !RST pin of the GoodFET's microcontroller, you will find that the GoodFET turns off when you connect to it with Minicom or Hyperterminal, then turns back on when you disconnect! To remedy this, you must drop the DTR line low by using ioctl() in Posix C or your language's equivalent. This will boot the GoodFET, beginning a session.

The session itself will begin at 9600 115200 8/N/1, although faster speeds will be supported in the near future. When you drop the line low, you will receive the three bytes {0x00, 0x7F, 0x00}. This is a GoodFET packet, and like all packets it follows the same, simple form. The first byte indicates the application, 0x00 being the Monitor. The other application that we will use is 0x01, SPI. The second byte is a verb, with all bytes less than 0x80 being generic verbs and all bytes higher being application-specific verbs. 0x7F means "OK" in every application. Other verbs include READ (0x00), WRITE (0x01), SETUP (0x10), and NOK (0x7E). A complete list of generic verbs is available in the Manual. The third byte, 0x00, indicates the number of data bytes that follow.

The GoodFET's protocol is transaction based, with every transaction after the first being begun by the host. It is recommended that your transmit function also automatically receive this reply. Further, any verb may have data attached. While the OK verb of the Monitor might never include data, your client had better accept whatever data it chooses to send your way.

Inside of the GoodFET, an application is merely a handler. All application present in the firmware are active simultaneously, and where it doesn't cause problems you may mix and match them. For example, you might wish to use the Monitor to manage the Test pin manually in order to implement an AVR programmer.

In any case, you can implement an SPI library through the GoodFET with only a few verbs. A sample session with commentary follows.

Transaction

First, the host adjusts to 9600 8/N/1, then the device announces its presence.
D: {0x00 (Monitor), 0x7F (OK), 0x00 (0 bytes)}

The host calls the SETUP verb of the SPI application to configure the I/O pins.
H: {0x01 (SPI), 0x10 (SETUP), 0x00 (0 bytes)}
D: {0x01 (SPI), 0x10 (SETUP), 0x00 (0 bytes)}

At this point, the I/O pins are now properly configured. Pins 1, 2, 5, and 7 are now MISO, MOSI, !SS, and SCK. As the READ and WRITE verbs are interchangeable for SPI, the host may use either. If nothing is connected, the MISO pin's pullup resistor will ensure that the reply is always 0xFF.
H: {0x01 (SPI), 0x00 (READ), 0x01 (1 byte), 0xDE}
D: {0x01 (SPI), 0x00 (READ), 0x01 (1 byte), 0xFF}
H: {0x01 (SPI), 0x01 (WRITE), 0x01 (1 byte), 0xAD}
D: {0x01 (SPI), 0x01 (WRITE), 0x01 (1 byte), 0xFF}

If pins 1 (MISO) and 3 (MOSI) are bridged, the output (MOSI) will feed right back into the input (MISO), causing the output value to be returned.
H: {0x01 (SPI), 0x01 (WRITE), 0x01 (1 byte), 0x80}
D: {0x01 (SPI), 0x01 (WRITE), 0x01 (1 byte), 0x80}

If multiple SPI devices are chained together, such as in a gang programmer, data may be shifted through one into the other. To do this, make a ring with each MISO line connected to the next's MOSI, then perform a transaction of as many bytes as you have devices. This will cause !SS (Slave Select) to drop low, then all bytes will be shifted, then !SS will rise high to indicate the end of the transaction. The same is appropriate for registers in multiples of 8 bits, such as a 16 bit device. The first byte in the reply is the first byte to be received, so when ganging devices the bytes of the reply will need to have their order swapped.
H: {0x01 (SPI), 0x01 (WRITE), 0x02 (2 bytes), 0xDE, 0xAD}
D: {0x01 (SPI), 0x01 (WRITE), 0x02 (2 bytes), 0xBE, 0xEF}

Ideas

A programmer/dumper for SPI EEPROMs could be written in short order, as could a command console for various Zigbee radio modules. The present application only supports SPI's master mode, but slave and sniffing support will be added at a later date.

A separate tutorial on extending the firmware will be available soon. If you'd like to get a head start, fork spi.c to make an I2C adapter. Email or catch me at a conference for a free board.