Appendix A

Installing the development tools

This appendix describes how to install the mspgcc suite of tools for the
MSP430 microcontroller. See http://mspgcc.sourceforge.net/ to
download the tools and additional documentation.

Note that some MSP430 development boards (such as the Texas Instruments
MSP430 Development Tool, model MSP-FET430X140) power themselves solely through
the PC parallel port, via the JTAG adapter.

If you are using such a board and your uploaded program does not run, you
may need to give the --no-close option to the pyJTAG tool. Here is
an example.

$ msp430-jtag --no-close -epvr hello-world.elf

You may have to type msp430-jtag.py instead of
msp430-jtag, depending on how you installed pyJTAG. The
--no-close option is a very recent feature at the time of this
writing, so you may need to download and build pyJTAG from source if your
development hardware requires it.

In any case, you will need a free parallel port in order to use pyJTAG.

Windows installation

Installing mspgcc under Windows is very simple. Download the latest
mspgcc-win32 package (mspgcc-20060119.exe),
run the executable file, and follow the prompts. According to the mspgcc manual (see the
"Windows installation" section), the installer works with Windows 98, ME, NT,
2000, and XP.

Linux installation

Make sure that the parallel port you are planning to use with pyJTAG is not
already in use by a daemon process (such as lpd). The pyJTAG
utility also requires the ppdev kernel module, unless you compiled
it otherwise.

If you want to run pyJTAG as an ordinary user, you can make the port
(/dev/parport0 by default) world-readable and writable.
Alternatively, add your username to the port's group in
/etc/group, then log out and back in again for the change to take
effect. The group should also be able to read to and write from the port for
this to work.

The "Building mspgcc from source code" section of the mspgcc manual and the
mikrocontroller
site both provide detailed building instructions for mspgcc. The
discussion here follows the latter set of directions. Note that it is not
necessary to build gdb (the GNU debugger) or
the gdbproxy (which enables gdb to debug MSP430 programs running on an actual
target) for these articles.

In order to build mspgcc from source, first make a temporary subdirectory in
which you will compile the tools. Your home directory is a good place for this
temporary subdirectory. You will also need a working Internet connection. (Broadband is recommended.) You should know the root password to your system and
must use a 2.4 or higher series Linux kernel. (A 2.4 series
kernel was used to verify the instructions given here).

Now, build the mspgcc compiler. When prompted for the CVS password, just
press Enter. Note that the mspgcc numbering does not correspond to the GCC core
numbering; mspgcc version 3.3 actually matches GCC core version 3.2.3.

Now, become the superuser and install the mspgcc compiler. Under some Linux
installations, you may have to set the path again (export
PATH=/usr/local/msp430/bin:$PATH) every time after becoming the
superuser, but this is usually not the case.

$ su
# make install
# exit
$ cd ..

Create the MSP430 libc. If you need to log in to CVS again, you can always do
so by reissuing the command cvs
-d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mspgcc
login

Finally, build the pyJTAG tool, which you can use to upload your compiled
firmware to the target. The tool requires the Python programming language, version 2.2 or
later. Most major Linux distributions include Python. Use the command
python -V to check your version.

If you want to use something other than your distribution's default Python
to run pyJTAG, you can substitute commands such as python2.3 for
python. Of course, you need to have the additional Python version
installed beforehand. Several different versions of Python can coexist on the
system without problems.

Now you must ensure that your /etc/ld.so.conf contains a line
/usr/local/lib. If necessary, edit the file (as root) to add the
required line. Note that some Linux distributions (such as Gentoo)
generate ld.so.conf from some other file automatically, in which case
you will have to change that file instead.

Also make sure that the ldconfig command is in your path before
attempting to install the JTAG libraries. Usually, ldconfig is in
the /sbin directory.

Appendix B

Installing and handling the hardware

You will need the following components in order to follow the examples in
this series of articles:

an ordinary PC running Windows or Linux

the Olimex easyWeb2 development board

a DC power supply (see the following discussion)

the Olimex JTAG adapter for the MSP430

a straight-through parallel extension cable

a null-modem serial cable

a free parallel port

a free serial port

If you want to substitute another development board for the easyWeb2, see Choosing a Platform for the list of required
features. The discussion in this appendix assumes the use of easyWeb2.

The work required to set up the hardware is absolutely minimal, but please
read this appendix through to the end if you have little experience working
with open circuit boards. The information presented here will help you avoid
frustration, and possible damage to the equipment.

An AC adapter (the familiar "power brick") is a simple, reliable, and
inexpensive solution for supplying DC power. Many distributors (such as Spark
Fun Electronics) will offer you an appropriate adapter when you buy the
easyWeb2 development board. This is the safest option if you have any doubts
about your source of power.

The serial cable (needed for later articles in this series) needs only the
transmit, receive, and ground lines--the additional lines of a full null
modem will go unused. This can save you a lot of effort if you build your own
cables.

Many embedded devices contain static-sensitive components, which a single
careless touch can destroy. The next section describes several basic
techniques for avoiding static discharge damage.

It is safest if you turn off all components (including any peripherals
attached to the PC) before starting.

Connect the JTAG adapter to the PC's parallel port. (You will almost
certainly need an extension cable.) Plug the other end of the cable into the
easyWeb2--there is a connector labeled JTAG on the board. Make sure
that red stripe on the cable is toward the pin 1 side of this
connector. The location of pin 1 is clearly indicated on the board, right
beside the JTAG connector. Figure 2 shows the JTAG
adapter correctly attached to the easyWeb2.

Finally, attach the AC adapter to the board.

A note on static electricity

Static electricity poses a grave danger to many electronic components. It takes only a gentle touch to pass a charge from your body to the device, potentially
causing permanent damage to the system.

Ideally, you should wear a grounded wrist strap when handling open circuit
boards and especially individual components. You should also have a grounded
antistatic mat on your work surface. Note that these tools are designed
with safety features--grounding yourself with just a plain piece of wire can
easily give you a deadly electric shock!

Keep any loose circuit boards in antistatic bags. These bags are often
silver in color, but this is not universal. If you have ever upgraded your PC
and kept the packaging, you should have some antistatic bags around.

Always fold the open end of the bag and tuck the excess underneath the
board so that the weight keeps it folded. Use antistatic foam to line
containers that hold unmounted sensitive parts, such as microcontrollers. Put
the components on the foam. The black squares on which the 486 and MSP430
chips rest in Figure 1 are made of this material. Note
that the chips were placed pin side up in Figure 1 just
to take the picture; the correct position for storage is with the pins on the
foam.

Antistatic bags are often an acceptable substitute to the antistatic mat
and wrist strap. Spread the bag on your work surface, touch the bag to
dissipate static, and then place the board fully on the bag. When putting the
board down, make sure that your hand makes contact with the bag before any part
of the board does. You should also touch the bag on which the device is resting
before picking up or otherwise handling the board. Figure
2 shows the easyWeb2 placed on top of an antistatic bag.

One way of dissipating a high static charge is to touch a fully closed metal
case of a PC. The machine has to be plugged in, but turning it on is
unnecessary. This method of dealing with static, however, requires constant
vigilance, because you must remember to discharge yourself frequently. In
addition, you still have to follow the directions in the previous paragraph for
handling your hardware.

Common sense antistatic precautions are important as well. Use a work
surface (such as a wooden board) that does not generate a static charge
readily. Wear 100 percent cotton clothing instead of synthetics when working with open
circuit boards or unmounted components. Maintain sufficient air humidity, and
be aware that walking on carpet can quickly build up a very high static
charge.

George Belotsky
is a software architect who has done extensive work on high-performance internet servers, as well as hard real-time and embedded systems.