Introduction: Getting Started With TI's MSP430-gcc and the MSP430 Launchpad on Linux
In this Instructable I will show you how to get started with the TI msp430-gcc toolchain on Linux, specifically Lubuntu. TI officially released msp430-gcc after taking it over from the open source community. This [hopefully] means there will be support for the latest chips as well as improvements and bug fixes. TI has actually provided a Linux installer, but I will show you how to compile it from source. Finally, using mspdebug we will load a sample application onto the MSP430 Launchpad with the MSP430G2553. These steps are taken from my website where I am posting free tutorials on embedded software development. For more details and information checkout simplyembedded.org
Step 1: Get the Compiler Sources and Support Files
Fire up your browser and go to TI’s download site. At the bottom in the “Products Downloads” table, you should download these two files:
- msp430-gcc-source.tar.bz2
- msp430-support-files.zip
Open up a terminal, navigate to your downloads folder and extract the first package.
cd ~/Downloads tar xvf msp430-gcc-source.tar.bz2
This might take a while… If you are not familiar with the tar command, it is a very widely used archiving utility which supports multiple compression algorithms. The command line parameters we passed are as follows:
- x – extract
- v – verbose
- f – for file, always followed by the filename of the file you want to compress/extract
If you want to learn more about the tar command you should read the man page (i.e. “man tar” in the command line). Navigate to the newly created “sources/tools” directory. What you see in here may be a bit overwhelming, but really what TI has done is packaged all the components required to build the compiler and created a build system around it. Technically, gcc itself is only the compiler. The toolchain consists of many other packages which perform various tasks such as assembling, linking, built-in functions etc… Most of these are contained in binutils, but there are separate math libraries like mpc, mpfr and gmp. A standard C library (libc) is also typically included unless you are developing an operating system. In the case of TI’s package, newlib is the C library they have chosen to include but there are plenty others such as glibc and uClibc.
Step 2: Compile the Toolchain
Compiling gcc takes long, so I let’s get it started and while it is compiling you can read the explanation for everything below. This is assuming that gcc and make are already installed on your system. If not you will need to install them.
cd ~/Downloads
sudo apt-get install texinfo expect libx11-dev g++ flex bison libncurses5-dev
sudo mkdir /opt/msp430-toolchain mkdir build cd build
export PREFIX=/opt/msp430-toolchain
export TARGET=msp430-none-elf
export PATH=$PREFIX/bin:$PATH
../sources/tools/configure --target=$TARGET --prefix="$PREFIX" --program-prefix=msp430- --enable-languages=c --disable-nls
make all
Now that its running, here is the breakdown of what you just did.
sudo apt-get install texinfo expect libx11-dev g++ flex bison libncurses5-dev
Here we are installing packages that are required to compile gcc
- texinfo: utility to help create documentation in various formats
- expect: program which talks to other programs interactively, used in scripts
- libx11-dev: X11 windowing system development package
- g++: gnu C++ compiler
- flex: fast lexical analyser generator
- bison: parser generator
- libncurses5-dev: screen handling and optimization package, basically a terminal upgrade
As mentioned above, if you do not currently have gcc and make installed already, you must add them to this list.
sudo mkdir /opt/msp430-toolchain
This is directory in which the toolchain will be installed. Personally I like to install my toolchains under the “/opt” directory. This directory is owned by root, and other users can only read and execute so any time you install to this directory you must do so as root.
mkdir build
cd build
Next we have to create a build directory. One very important note about compiling gcc is you cannot build it in the source directory. If you try, you are very likely to get build errors.
export PREFIX=/opt/msp430-toolchain
export TARGET=msp430-none-elf
export PATH=$PREFIX/bin:$PATH
Before building gcc, some environment variables should be set. We don’t want them to be system wide or persistent so we will set them only in the context of our shell. To do so we use the export command. The environment variables defined are:
- PREFIX – the directory where your cross-compiler will be installed
- TARGET – the target architecture in the format -- or something of that nature (its not really well defined). In our case the arch is msp430, target-os is none because it will be bare metal development, and output is elf format
- PATH – the system path, already defined but we must add location of the binaries we will build to it
../sources/tools/configure --target=$TARGET --prefix="$PREFIX" --program-prefix=msp430- --enable-languages=c --disable-nls
As with most gnu programs, the build environment is based on automake/autoconf. These tools can be fairly complicated to understand and the parameters that you have pass into them are sometimes obscure and poorly documented. Basically this is what need to be done:
- Run the configure script passing in the required arguments which are defined by the configuration file for a specific program
- The script analyses your system for various dependencies and from the information it collects, it is able to generate makefiles, configuration files and sometimes header files that will be compatible with your system. If you are not familiar with makefiles, don’t worry about it for now, I will have a lesson dedicated to them. Sometimes dependencies cannot be resolved in which case the configuration (or build) will fail
- Compile the code
- Install the program
In the case of gcc, the configure script accepts many arguments but only a few are required in most cases. The target and prefix argument are as described above in the environment variables section. The program-prefix simply adds a prefix to all the binary files, so for example gcc will become msp430-gcc. This is useful when you want to have one makefile that can build the same code for many architectures. For example, if I wanted compile main.c for both msp430 and arm, I could define my compiler as $(target)-gcc and then configure with target=msp430 to use msp430-gcc or configure with target=arm to use arm-gcc. The disable-nls flag tells the build to disable Native Language Support (NLS) which basically means GCC only outputs diagnostics in English. Finally, enable-languages tells the build system to compile only the specified languages. Only C is enabled since that is the language we will be using. If you are interested in the many other options for gcc compilation you can read all about them here.
One last thing, if you need to completely clean your build directory or rebuild from scratch, the “make distclean” command is supposed to do this for you but in my experience it is often not effective. Its easier and safer to just delete the whole build directory and start again.
Did the compilation finish? If not take a coffee break…
Now that its done, you have to install it. Since /opt is owned by root, the install command has to be run with sudo.
sudo make install
This copies all the required files from the build directory to the directory specified by the environment variable PREFIX.
Step 3: Adding the Support Files
The final step before we are done is installing the device support header and linker files. These files are provided separately from TI in the second file downloaded in step 1.
cd ~/Downloads unzip msp430-support-files.zip
The files will be extracted to an “include” directory. Inside you will see a lot of header files and linker scripts. The header files include all the device specific definitions and memory locations for registers and peripherals. The linker scripts tell the linker how to map various sections of code to physical memory locations on the device. Although they are all packaged together, the header and linker files belong in different locations in your installation. Use the following commands to copy the files to the appropriate location.
cd include
chmod -R 755 *
sudo cp *.ld $PREFIX/msp430-none-elf/lib/430/
sudo cp *.h $PREFIX/msp430-none-elf/include
The second command is used to change the permissions of the files to match the default permissions of the /opt directory. The location where the files are copied to is defined by the toolchain. If you put them somewhere else, it won’t find them. The compiler is now installed on your system.
Step 4: Getting the Code
The source code I have provided is available on github. When you create a repository on github it is assigned a URL which can be used to obtain a copy of the repository using the git clone command.
cd
git clone https://github.com/simplyembedded/msp430_launchpad.git
git checkout -b lesson_3_devel lesson_3
The cloned repository will now be available in the directory called msp430_launchpad. Navigate into this directory. You should now see two files, README and main.c. This code blinks one of the LEDs on the device.
Step 5: Running the Code
Finally let us compile and run the code! Start by using the following command to compile using gcc. This assumes you have installed the MSP430G2553 device on your Launchpad.
/opt/msp430-toolchain/bin/msp430-gcc -mmcu=msp430g2553 main.c
The the ‘mmcu’ flag tells the compiler which microcontroller to compile for. When compiled with –mmcu=msp430g2553, the compiler will, amongst other things, define __MSP430G2553__ (i. e. #define __MSP430G2553__ in code) . This define is used to determine which header file should be used. Once the code is compiled, there will be a new file called a.out. The name of the file ‘a.out’ is the default gcc output filename if one is not specified. Next the file can be downloaded to the target. There are a few tools which can be used to download the code to the target. The first is gdb, which is the standard in the open source community for debugging. GDB can run standalone if you are debugging on your host machine. However, if you are debugging on a target, there needs to be an additional interface available. This is sometimes implemented as a utility called gdbserver, which creates a TCP/IP connection that gdb can connect to. Manufacturers of some JTAG (diagnostics interface) tools make their own gdbserver for their tools. GDB is extremely powerful and very mature, but can be a bit difficult to set up and learn. For this reason, I will start off with the second option, mspdebug. This utility is an open source project created specifically for programming and debugging the MSP430s. It is very simple to use and is available for download in the Ubuntu repositories, so let’s install this utility.
sudo apt-get install mspdebug
Now, connect the USB cable to the MSP430 Launchpad and to your computer. Mspdebug supports a number of drivers to accommodate various hardware interfaces. In the case of the MSP430 Launchpad, we must use the ‘rf2500’ driver. To start mspdebug with this driver, use the following command:
mspdebug rf2500
You should see the program connecting to the device. Once it is connected, program a.out to the device.
prog a.out
Each section of code will be written to the device flash. Now you can run the program by typing ‘run’ into mspdebug. The red LED on the board will start flashing. To stop the program use CTRL-C. To reset the board, use the ‘reset’ command. And there you have it. If you found this Instructable useful, make sure to check out the full tutorial and more at simplyembedded.org
