Portable environment for the MSP430 Launchpad

I love portable environments. I like programming using an external hard drive, moving the HDD from one PC to another, and continue programming using the same tools and data.

Here I explain the method I use to create a Windows portable Eclipse based development environment for the MSP340 family using the Launchpad as the programming/debugging link.

MSP430 Launchpad

As a compiler I will use MSP430 GCC. For every element in the toolchain I try to use as much open software tools as possible but I will also try to keep things simple so sometimes it will be a compromise.

This is a deep rewrite of the portable development environment for the MSP430 Launchpad board  I set up in 2012. I then wrote an article in my spanish blog AIM 65 and, since then, some things have changed. So, here I am repeating all the steps I made before. Some things are the same but most are quite different.

This procedure works in Windows 7 and it should work also in Windows XP. Don't know about other operating systems.

Basics

Unfortunately Eclipse is not fully portable between machines. Some paths in the projects are absolute, not relative. That means that if you want to move your Eclipse development environment from one machine to another you have to guarantee that the files have the same location in both places. The easiest way to do that is changing the drive letter in windows so that it is the same in any machine. In my case, my moving HDD uses the letter M, so its M: on all systems.

Check your operating system for the method to assign the external drive letters. It usually involves using the Disk Manager, selecting the drive and selecting one option with the right mouse button contextual menu.

Eclipse is a java application. That means that you need to have java installed in any computer where you want to use the development environment.

There are several free toolchains available for the MSP430 devices. Texas Instruments provide a free version of the Code Composer Studio. As they state:

"A free license will be generated that supports a 16KB code size limit for the optimized TI compiler or no code size limit with GCC."

You are limited to 16KB but as no MSP4340 value line MCU has more memory that that it's no big deal. Moreover, you can always USE GCC and not be constrained at all.

If you want to have an easy install of the tools needed to develop on the MSP430 value line of MCUs, nothing is easier that downloading and installing CCS.

This application is not, however, the target of this article.

One of the complex elements in the development environment is the debug chain. To successfully debug successfully a MSP430 device you usually need:

•     USB drivers for the board of FET used
•     DLLs needed to communicate with the USB drivers
•     GDB Proxy to communicate with a GDB program
•     GDB program

The GDB program is usually included with the compiler but the rest of the elements sometimes have to be found in different places.

Fortunately nowadays the USB drivers are detected and installed automatically and Texas Instruments provides a file that provides the rest of elements together with the GCC compiler.

Downloading the files

First, we will start downloading the required files.

Go to  the Eclipse donwload web page http://www.eclipse.org/downloads/ and download the required installer. At the time of writing this article it was Eclipse Luna.

Eclipse Luna Download

As I'm using Win7 32 bit I selected the 32 bit installer.

Then we need to download the make and other Unix-like companion commands from this link:

http://sourceforge.net/projects/unxutils/files/latest/download?

You should get a UnxUtils.zip file.

Finally you should get the Red Hat msp430 gcc compiler from Texas Instruments using this link:

http://www.ti.com/tool/msp430-gcc-opensource

MSP430 GCC at Texas Instruments

You could use the MSPGCC from the sourceforge location. The problem is that it doesn't include all the needed debug elements.

Second Step downloading MSP430 GCC

That will lead to a page were you need to use a TI account to download the software. It's free, but it could not suit everyone.
At the end you should get a file with a name like msp430-gcc-full-windows-installer-2.1.1.0.exe.

That are all the files needed to download. You should have something like this list:

• eclipse-cpp-luna-SR1-win32.zip
• UnxUtils.zip
• msp430-gcc-full-windows-installer-2.1.1.0.exe

Creating and filling the directories

I locate all the microcontroller files inside a MCU folder insider M:. You can  do as you please but you'll need to change the directories.

Create the main directory, in my case, as I use Eclipse Luna it will be:

M:\MCU\msp430_Luna

Open the eclipse zip file and copy the eclise folder it contains over the newly created directory.

The main executable of all the environment will be M:\MCU\msp430_Luna\eclipse\eclipse.exe. Feel free to put a link to this file somewhere that is easy to reach like your desktop or your main folder in the external drive.

Create te following four directories inside M:\MCU\msp430_Luna:

• UnxUtils
• msp430-gcc
• workspace
• projects

Copy the contents of UnxUtils.zip inside the UnxItils directory.

Finally execute the msp430-gcc-full-windows-installer-2.1.1.0.exe GCC installer, accept the license and instruct it to put all the files inside the msp430-gcc folder.

MSP430 GCC Install

 So far we have filled the eclipse, UnxUtils and msp430-gcc folders and we have empty the workspace and projects folders.

Configuring Eclipse

Now it's time to run and configure eclipse. Run the eclipse.exe program located inside M:\MCU\msp430_Luna\eclipse (directly or using a previously created link).

You will see a window like the one shown that prompts for a workspace folder.

Eclipse workspace selection

Select M:\MCU\msp430_Luna\workspace and hit OK.

After some initialization you will see a window like that:

Eclipse Start Window

Before continuing we must install the needed debug elements inside eclipse. To do that, select "Install New Software" from the Help menu.

Install new software

Select "All Available Sites" as "Work with" option and write down "GDB Hardware Debugging" as is shown in the next window. It can take a while to do the search.

GDB Support Installation

Select the C/C++ GDB Hardware Debugging item and click Next.

Hit Next in the following window, accept the License in the next one and click Finish.

After the install it will prompt to restart, let it do it and use the same workspace when it restarts.

Restarting Eclipse

You will get the same start screen. Here click over the workbench icon to continue.

Workbench ICON

That will give the standard Eclipse C/C++ view:

Eclipse C/C++ view

Compiling a Blink example

Next step is to compile a simple example. In embedded systems a LED blink program is the equivalent of a hello world program in a normal console C program.
The msp430 GCC distribution comes with an example.
I don't like to compile the program in its provided location, so I suggest to copy it to the projects folder, that means copying the folder:

M:\MCU\msp430_Luna\msp430-gcc\examples\windows\msp430g2553

To the projects folder location:

M:\MCU\msp430_Luna\projects

And rename it from msp430g2553 to blink

That way you should have the following folder contents:

Blink project contents

Then we will include this project in Eclipse using the New "Makefile Project with Existing Code" option inside the File menu.

Creation of a Makefile Project

That will give a dialog window were you can use the browse button to locate the project directory. Eclipse will give it the "blink" name. You can leave as is or change it.

Creation of new project dialog

After clicking on "Finish" the project will be created and you return to the C/C++ view.
Then, you can use the project explorer to view the contents of the Makefile.

Original project Makefile

As we have moved the make file from its original location we need to change the paths.
You can use relative or absolute paths, using relative paths you can set:

GCC_DIR =  ../../msp430-gcc/bin
SUPPORT_FILE_DIRECTORY = $(GCC_DIR)/../include

Then we can change the -O2 optimization option to -O0 so that the compiler doesn't optimize the code. This is needed if we want to do step by step debugging as the compiler optimizations break the relation between written and executed code. After all debugging is done its best to replace -O0 with -O2 to optimize the program so that the memory is reduced and the program speed is increased.

Finally, we can change the name of the output file to do that, we will create a new variable called "EXECUTABLE" and use it in the GCC reference.
As we won't use the GDC target in the makefile and we could era its last two lines.
That will give the following Makefile.

Makefile modifications

This is the final Makefile after all modifications:


 
Observe that the makefile is designed to use a MSP430G2553 MCU, this is the MCU mounted on the MSP430 Launchpad version 1.5 board. If you want to compile for another MCU you should change this line.

After all modifications are made you can save them using the save button.
You can also examine the main blink.c source file:

blink.c source file

 You will see that there are plenty of errors. As this is not an eclipse managed project, the error checker don't know how to process the includes needed to provide several literal definitions. As those errors are quite ugly we can remove them. To do that, select the Project properties on the contextual menu on the blink folder of the Project Explorer. And then select Code Analysis and unselect the 5 elements than end in "..resolved". Then hit OK.

Code Analysis

That will get us rid of those nasty error messages.
 
The last step to obtain an executable is to compile the project. Just select Build Project in the Project menu.

Building the project

 If all goes well you will see something like that in the console:

Console after compilation

You can now see in the project explorer that you have two new files in the blink directory . The blink.o object file obtained from the compilation of blink.c and the blink (with no extension) executable file.

Optionally we can create a command to see the memory usage of the program.
To do that, select External tools configuration in the contextual menu in the tools icon.

External tools

Select program and click the New Launch Configuration button. And fill the data indicated below:

Name: Resource Size
Location: M:/MCU/msp430_Luna/msp430-gcc/bin/msp430-elf-size.exe
Working Directory: ${container_loc}
Arguments: ${resource_loc}

Resource size main tab

In the build tab unselect Build before launch.

In the Common tab select External Tools in the Display in favorites menu section.

After that, just hit Apply and then Close.

To see, for instance, the size of the executable binary file we can select it in the Project explorer and select the Resource Size element in the External tools menu.

Resource size of the main binary file

Here we can see that the binary file includes 708 bytes of code for a total size of 746 bytes. As the MSP430G2553 features 16KB of flash memory we have plenty of space left.

Program Run and Debug

To program and run the program on the MSP430G2553 MCU included in the Launchpad board we need o use several software elements.

First we need the USB drivers for the launchpad board. They will normally be installed automatically when you connect the board to the computer, but if you need to manually locate them, there are some drivers in this location inside the GCC folder:

M:\MCU\msp430_Luna\msp430-gcc\emulation\drivers\msp430

Alternatively you can download the energia drivers from:

https://github.com/energia/Energia/raw/gh-pages/files/EZ430-UART.zip

Then we need to start the GDB Agent that will communicate the gdb program with the USB drivers. I was not able to properly use the command line program gdb_agent_console.exe without debugging errors so I used the GUI version gdb_agent_gui.exe file instead.
You can run this program directly but I prefer to run it from eclipse. To do that you can create a new external tool configuration:

Name: GDB Agent GUI
Main TAB:
  Location: M:\MCU\msp430_Luna\msp430-gcc\bin\gdb_agent_gui.exe
  Working Directory: M:\MCU\msp430_Luna\msp430-gcc
Common TAB:
  Select tick in External Tools

Then click Apply and then close. You have now the GDB Agent GUI program next to the Resource Size one. Launch the GDB Agent GUI and then click on Configure and select msp430.dat. After that click on the Start button.
If all goes well you will see a "Waiting for client" message like in the following window:

GDB Agent

After the GDB agent is successfully running we need to create a debug configuration. Use the contextual menu on the debug icon to select Debug Configurations...

Select Debug Configurations

Selecting GDB Hardware Debugging, click on the New Launch Configuration button and fill the following data:

Name: Blink
Main TAB:
  C/C++ Application: blink
  Project: blink (Select it from the browse button)

Debug configuration Main tab

Then click on Select other... at the bottom of the window and select in the new window Use configuration specific settings and Legacy GDB Hardware Debugging Launcher. Then click OK.

Selecting the debugger launcher

Next continue with the other tabs:

Debugger TAB:
  GDB Command: M:\MCU\msp430_Luna\msp430-gcc\bin\msp430-elf-gdb.exe
  Port number: 55000

Debugger tab

Startup TAB:
  Set breakpoint at: main
  Resume

Startup tab

Common TAB:
  Set tick in Display in favorites menu "Debug"

After that, Apply all changes and then Close.

Now you have a new element in the debug icon contextual menu. Check that the GDB Agent is still running and select the Blink option in the debug icon contextual menu.

Launch the debugger

You will see message recommending to change the perspective to the debug one. Just say yes.

The Debug View will open and you will see something like the following window.

Debug View

We see that the program is stopped at the start of the main program. To continue running the program just push the play button.

You should see the red LED blinking on the Launchpad board. Congratulations!!!

You can now use the pause button to pause program execution. To continue, just push the play button another time. You can also see the variables contents and use breakpoints but all that goes out of the scope of this long article.

To end the debugging you can hit the Terminate red square icon and remove the terminate debugin session selecting it and hitting the DEL key.

Terminate the debugging session

After all debug is done, the GDB Agent can also be terminated selecting it and pushing the red square terminate button. After that, the DEL key will eliminate it from the debug view.

Closing Words

After all this work we have a blink project and a MSP430 portable development environment to be used with it. To create a new project you can duplicate the blink entry on the projects folder and repeat the needed steps to incorporate the project in eclipse.

You don't need to repeat the creation of the items in the run programs menu, but you must replicate the debug entry for each new project. To do that, the easiest way is have the blink and the new projects open at the same time and duplicate the debug entry in the debug configurations window.

Duplicating a debug configuration

That's all for now. The eclipse environment is so complex that there is no more space in this article to talk about it. I will probably write more on the subject in future articles.

Compiler woes   (update at  November, 25  2014)

It seems that the TI sponsored msp430 gcc compiler is not able to determine how to do multiplications on the MSP430G2553. I got strange results in multiplications and I suspect that the compiler is trying to use a hardware multiplier that this MCU lacks.

I needed to do some guesswork to find the needed  -mhwmult compiler option as I could not find where it is documented. Finally I know, by asking the gcc compiler, that there are 5 available options: 16bit, 32bit, auto, f5series and none.

In order to correctly compile the code I had to include the compiler option:

 -mhwmult=none

That way multiplications go as they should.

The interrup macro at iomacros.h is also broken. It is defined:

#define __interrupt(vec) __attribute__((__interrupt__(vec)))

but msp430-gcc don't like this format. I have developed a new definition:

#define interruptNew(vec) __attribute__((interrupt(vec)))

That way I can properly compile, for instance, the port 1 RSI:

void interruptNew(PORT1_VECTOR) PORT1_ISR (void)
 {
 // Do RSI things
 }

Gist Embedded Makefile (Update at 30/11/2014)

Now the Makefile code is embedded in the blog using Gist