Programming and Debugging with the TI Launchpad on Mac OS X

Scope: These instructions are a summary of the steps I followed to start using the TI Launchpad under Mac OS X. This isnʼt as straightforward as it sounds, but it is possible develop code, debug and program from within Mac OS X without having to boot into a copy of Windows (these instructions can also be extended to most variants of Linux).

Introduction: The TI Launchpad is Texas Instruments low cost microcontroller development board for the MSP430 microcontroller line. These microcontrollers are very low power, very low cost and reasonably fast. There are many variants in each class, each with different peripherals and features.

Unfortunately, TI doesnʼt ofﬁcially support anything except Windows, and the limited support for Mac they do offer extends to a broken driver for communicating through USB. Furthermore, TIʼs closed source policy hampers clever people trying to write open source compilers, debuggers and programmers. I canʼt speak to the true reasons for this, but my cynical side would say that they do this to force people to use their size limited free version of IAR or Code Composer (~$500 for a single seat license with the unrestricted version). Contrast this policy with the free development tools for Windows by ATMEL for its AVR line, and the well developed, open source AVR GCC toolchain that forms the basis of the Wiring environment used by the Arduino.

Arguments about operating systems and open versus closed source software aside, the MSP430 line of microcontrollers are actually quite attractive (for more on the open versus closed source debate or what the best operating system is, please refer to any public forum on the internet)(Be aware that Godwinʼs law is accelerated in these sorts of discussions.). In comparison to the AVR line of microcontrollers, the MSP430 line has the following advantages: a smaller instruction set, 16 versus 8 bits, easier ﬂash access, lower power consumption and lower cost. Its (relative) simplicity and low cost were the main reasons behind using it for this course.

Getting under the hood of your Mac: Mac OS X is a great operating system for surﬁng the web, editing pictures, listening music, and all the other stuff that people actually use their computers for these days. At its core, however, it is really just a variant of Unix (BSD, actually), and all that power user functionality you associate with Unix/ Linux is still there. If youʼve never opened up Terminal, head to /Applications/Utilities/ and run Terminal.app. You should have a window like this open up: A Terminal Window

If youʼve never used the command line before, then youʼve got some learning to do. Start here: http://www.doc.ic.ac.uk/~wjk/Unixintro/ or http://laplace.physics.ubc.ca/210/ Notes_unix.html . You need to be comfortable working at the command line to get the MSP430 development tools installed. If this is a real problem, then you may want to reconsider microcontroller software development as a vocation.

Once youʼve got a handle on the terminal, you need to set up your Mac to develop software. To do any development on a Mac, you need to install the XCode developer tools. These arenʼt installed be default, but they are included with every Mac on the install disk, or you can register as a developer with Apple and download the latest version (itʼs free to register). This should be a straightforward install, since itʼs been nicely packaged by Apple, so I wonʼt go into details.

The next piece of software you need to install is ﬁnk. Fink is a package manager for Mac that allows you to easily install open source programs on your computer without having to download, compile and install all of the libraries and software by hand. It is possible to install software from source by hand in the same way it is possible to build your own car from scratch. Weʼll let ﬁnk do the heavy lifting.

The fink website has a very good set of directions for installing fink from source (you just installed the Xcode developer tools, you may as well use them): http://www.finkproject.org/download/srcdist.php

Some notes: -The ./bootstrap call will ask you a lot of questions. The default answers should be fine for most people. -There will be a lot of text streaming across the screen as the software compiles. This is good, but it does take a while. When the process is finished, be sure to read the last few lines to be sure there were no errors. If there are, youʼll have to sort them out before you continue. -Be sure to close the terminal window and re-open it after the /sw/bin/ pathsetup.sh command, or the next commands wonʼt work. -fink selfupdate-rsync takes awhile to run, be patient. -When you run fink, it may ask you for your user password. This is expected, since it is writing to system files that are normally protected from the user.

Now that you have fink installed, we are almost ready to install the MSP430 development tools. However, these tools are still a little buggy, so in the fink database, theyʼve been labeled as unstable. This doesnʼt mean they donʼt work, it just means that they havenʼt been around long enough to be thoroughly tested. However, it does require a little more work on our part to get them working. We need to tell fink that we want to work with the unstable packages. To do this, we type the following:

ﬁnk conﬁgure

This will run you through a series of questions. You can choose the defaults for most of them, except one that asks if you want to use unstable packages. For this, choose y (yes).

After youʼve conﬁgured ﬁnk to use unstable packages, update the package list:

ﬁnk selfupdate

Now, we are ready to install the msp430 development tools (the “toolchain”). Run the following ﬁnk command to get the packages:

ﬁnk install msp430-libc msp430-gdb mspdebug

You are almost ready to plug in the device and connect. The only thing that is missing is the USB driver to communicate with the Launchpad. This is the only bit of software that TI provides (unsupported) for the Mac, and it doesnʼt work. We need to rely on reverse engineered tools from clever people. Download and install the MSP430LPCDC 1.0.3b.zip driver from http://www.mediaﬁre.com/?7zurj5ncg5794 . This has been nicely packaged with a Mac installer, allows you to communicate the the USB as if it were a serial port to the chip and also allows you to program and debug the chip.

At this point, if you plug in the the launchpad, you should be able to communicate with it. With the board plugged in, type the following: mspdebug rf2500 This should bring cause a lot of text to ﬂow by, and leave you at a command that looks like:

(mspdebug)

Type exit to leave the program. To check if we have the compilers and debuggers, type the following on separate lines: msp430-gcc --version msp430-as --version msp430-gdb --version

If any of these commands gives an error, there was a problem somewhere along the line that needs to be ﬁxed, and you wonʼt be able to compile code for the microcontroller until you do.

At this point, you could open up your favorite text editor, paste in some code, compile and link at the command line, and ﬁnally upload it to the microcontroller.

Be aware that the gcc compilers have a slightly different syntax than the IAR or code composer compilers, especially for interrupt routines. There are notes at the bottom of this document on how to switch between the different compilers. However, the C language is standardized, so using code examples from other compilers very instructive.

It is also possible to compile assembly in gcc, but the Code Composer or IAR examples will be difﬁcult to use because the directives of the various assemblers are very different (the assembly language is the same in each case, but the book keeping conventions are different). A trick to get the gcc directives is to write an empty C program and then look at the intermediate assembly that the compiler produces. Use this as a template for your assembly program, and start adding your own code.

Synopsis:

Step 1: Install Xcode developer Tools. Step 2: Install ﬁnk from source. Step 3: Set up ﬁnk to use unstable packages. Step 4: Install the msp430 development toolchain. Step 5: Install the USB driver. Step 6: Check the driver and toolchain work.

Links:

Unix Intro: http://www.doc.ic.ac.uk/~wjk/Unixintro/ Matt Choptuikʼs Unix Intro: http://laplace.physics.ubc.ca/210/Notes_unix.html Wikipedia Page on the MSP430 microcontroller: Tons of good information and history of the MSP430 16 bit microcontroller. http://en.wikipedia.org/wiki/TI_MSP430

Launchpad Wiki: A good place to start getting information on the TI Launchpad and the MSP430 microcontroller line. http://processors.wiki.ti.com/index.php/MSP430_LaunchPad_(MSP-EXP430G2)

Getting Started with the MSP430 Launchpad: A video tutorial and workbook to get started using the MSP430 launchpad. Based around windows and their Code Composer software, but it gives you a really solid foundation and worked examples. http://processors.wiki.ti.com/index.php/ Getting_Started_with_the_MSP430_LaunchPad_Workshop mspdebug: Open source version of msp430-gdbproxy; a tool that allows you to talk to the microcontroller using the Launchpad board through spy by wire (itʼs actually more than that, but thatʼs what we use it for. http://mspdebug.sourceforge.net/

Fink: Package manager for Mac OS X (like apt-get for Ubuntu or portage for Gentoo). We use it to get the open source MSP430 compilers, assemblers and tools and the required dependencies. This is just good software to have if you ever want to use Linux software in Mac. It is truly painful to compile from source on a Mac http://www.ﬁnkproject.org/

Mac USB driver: http://www.mediaﬁre.com/?7zurj5ncg5794

Hack A Day MSP430 projects: Lots of things people have done with the MSP430 line of microcontrollers. http://hackaday.com/tag/msp430/

Compiling Notes:

To get assembly from c: msp430-gcc -S minimalProg.c

To get object code from assembly: msp430-gcc -g -Os -mmcu=msp430g2213 blinky.s -o blinky.o

Full process: msp430-gcc -mmcu=msp430g2231 -O2 -Wall -g -c -o blinky.o main.c msp430-gcc -mmcu=msp430g2231 -o blinky.elf blinky.o msp430-objcopy -O ihex blinky.elf blinky.a43 msp430-objdump -dSt blinky.elf >blinky.lst mspdebug rf2500 prog blinky.elf

I have put all this into a makefile now. make does the compiling, make download loads the code on the board, make clean removes non-code files. You just have to change the attributes at the top of the file to use it in a new project.

You can download my makeﬁle from http://www.phas.ubc.ca/~rwicks/phys319/makeﬁle. Put it in the directory with you source code.

Interrupts on different compilers (if youʼve followed my directions, use option 4): from http://justinstech.org/category/hardware/msp430/

The different compilers out there for msp430 chips and Launchpad have different syntax for each one - Hopefully this post will help you ﬁnd out which one you need. (all examples are for chip msp430g2231, just substitute your chip that you are working with) First – CSS/IAR — TI ofﬁcially supported compilers/IDEs #pragma vector=TIMERA1_VECTOR __interrupt void Timer_A1(void) { //ISR code }

second – mspgcc4 – IDE of your choice Makefile — must have this option to compile correctly to chip -mmcu=msp430x2231 – most chips are supported but you will have to find the correct one for yours. Main.c file or main project file you must include these #include #include and then the syntax for your ISR interrupt(TIMERA0_VECTOR) Timer_A (void) { //code goes here}

Third — Uniarch mspgcc – Newest compiler – replacement for mspgcc4 makefile– -mmcu=msp430g2231 you must use the one specific for your chip and should not include an x in the mmcu option since that is for the depreciated mspgcc4 inlcude these header files #include #include ISR syntax interrupt(TIMERA0_VECTOR) Timer_A (void) { //code goes here}

Fourth way– Official uniarch mspgcc ISR syntax makefile – same as before no extra includes needed, just the msp430.h or specific chip header __attribute__((interrupt(TIMERA0_VECTOR))) void Timer_A(void){ //code goes here }