3.1. Installing on Ubuntu Linux

3.1.1. Overview

To generate executable code for the MSP430, popular commercial solutions include IAR and Code Composer Studio (CCS). Since these are paid versions, they are not preferred by hobbyists and students. The open source community has therefore developed mspgcc based on the gcc toolchain. Mspgcc is free to download and use. It can also be modified if necessary since the source code is available. Mspgcc is released under GPLv2.

This document presents three ways of setting up the toolchain:

  1. The entire build environment is configured and ready as a plug-n-play solution on a bootable USB drive. This is the easiest and recommended solution for beginners, including those who don’t have Ubuntu Linux. Bootable USB is available at a nominal cost from WiSense.
  2. Those who already have Ubuntu Linux, they can install the toolchain on their system from available binaries.
  3. Experienced users who would like to build from source can take the difficult route for the purpose of learning and experimentation. Building from source may be necessary if bugs need to be fixed or a new variant of MSP430 has to be supported. This is the option if you want to start contributing to the open source community.

3.1.2. USB Plug-n-Play Solution

This solution enables you to get started with Ubuntu Linux and mspgcc without requiring any installation or changing your current operating system. This solution will work if your current system is Windows, Mac or any variant of Linux. This means that you can safely try out Ubuntu and mspgcc without installing or reconfiguring your existing system.

The default version distributed on the bootable USB is Ubuntu 12.04.3 LTS, where LTS refers to Long Term Support. This version also has the name Precise Pangolin. Because it is LTS, Ubuntu will support upgrades till April 2017. The default USB is meant for Intel compatible (i386) machines, including Apple Macs based on Intel processors. WiSense can supply bootable USB for AMD machines upon request.

Plug in the bootable USB from WiSense. Boot your system. If your system is configured to boot from USB, you should see Ubuntu booting up. If not, enter the boot menu and select the option to boot from USB. Entering the boot menu differs from system to system. Typically, your system will tell you what key to press to enter the boot menu.

After booting up, you will be prompted to Try Ubuntu or Install Ubuntu. It is recommended that you try out Ubuntu. After you become familiar with the system, you may wish to install Ubuntu on your system. However, installation requires that you have a second partition on your hard drive and this partition is empty. In general, installation is a risky procedure and you should do it only if you have taken full back of your current system. The Try Ubuntu option means that the next time you boot up, you can safely go back to your current system.

Once you have selected the option to try out Ubuntu, you will have all the required tools to use mspgcc and program MSP430-based hardware. Code you write or documents you create will be saved on the USB. They will be available every time you boot from USB. For next steps, please read section Using the Tools.

3.1.3. Installing Binaries

The steps described here are for installing binaries on top of Ubuntu 12.04.3 LTS version. However, any other Ubuntu distribution will have similar steps. You will have to search and install package versions suitable to your distribution.

  1. Go to http://packages.ubuntu.com. Search for msp430 under distribution precise. Similarly, you can search for mspdebug. It is also possible to search across all distributions by selecting any.

Figure 1: Ubuntu Package Search

_images/UbuntuPackageSearch.png
  1. From the search results, navigate and find the right packages. If yours is an AMD machine, you need to select the right binary under the Architecture column (Figure 2). Once you select the architecture, you will be taken to the download page. Click on any mirror URL and *.deb file for the package will be downloaded. To save you some time, Table 1 gives links to each package page for Ubuntu 12.04.3 LTS:

Figure 2: Select the Architecture

_images/UbuntuArchSelection.png
Table 1: Required Packages
Package Version Distribution Package Page
msp430mcu 20110613-3 Precise http://packages.ubuntu.com/precise/msp430mcu
msp430-libc 20110612-2 Precise http://packages.ubuntu.com/precise/msp430-libc
binutils-msp430 2.22~msp20110716p5-1 Precise http://packages.ubuntu.com/precise/binutils-msp430
gcc-msp430 4.5.3~mspgcc-20110716-4 Precise http://packages.ubuntu.com/precise/gcc-msp430
gdb-msp430 7.2a~mspgcc-20111205-1ubuntu1 Quantal http://packages.ubuntu.com/quantal/gdb-msp430
mspdebug 0.18-1 Precise http://packages.ubuntu.com/precise/mspdebug
  1. Please note that version 7.2 of gdb-msp430 that comes with precise distribution has bugs. Hence we need to use version 7.2a that comes with quantal distribution. Also note that manual installation is preferred since installation via Ubuntu Software Center, aptitude or synaptic tools have not been known to work for mspgcc toolchain. In any case, if you are using the latest Ubuntu distribution, select packages for that distribution.
  2. Once all `*.deb files have been downloaded, you need to install each one using the command (replace package-name as appropriate): sudo dpkg -i package-name.deb. Because of dependencies, packages should be installed in exactly the same order as listed in Table 1.
  3. As of December 2013, Ubuntu packages do not support the latest MSP430 variants. For example, MSP430G2955 is not supported. To fix this, we need to update and build from source for msp430mcu. This is described in section Building From Source. This can be done on top of earlier versions already installed. This step is mandatory since latest versions of WiSense boards are based on MSP430G2955.

3.1.4. Building From Source

In general, building from source is not recommended for beginners. One reason to build from source is if latest code changes are not available via Ubuntu. In rare cases when available binaries don’t work on your system, building from source is an option. Since we are building from source, it is sensible to take the latest code regardless of the current Ubuntu distribution.

3.1.4.1. MSP430MCU

  1. This step is mandatory so that we are able to work with latest MSP430 processors. Download http://sourceforge.net/projects/mspgcc/files/msp430mcu/msp430mcu-20130321.tar.bz2/download. Unzip the contents. Update a line in the README file: scripts/install.sh /usr
  2. Execute the README file: sudo sh README
  3. Check that installation has completed correctly by looking for the file /usr/msp430/include/msp430g2955.h

3.1.4.2. Other Packages

Installation from source for other packages is not detailed in this section. For those wishing to try this out, you can follow these links as a starting point:

Table 2: URLs to Obtain Source Files
Package Description Download URL
mspgcc-20120406 Contains patches for binutils, gcc and gdb. http://sourceforge.net/projects/mspgcc/files/mspgcc/mspgcc-20120406.tar.bz2/download
binutils-msp430 Apply patch from mspgcc before building. ftp://ftp.gnu.org/pub/gnu/binutils/binutils-2.21.1a.tar.bz2
gcc-msp430 Apply patch from mspgcc before building. ftp://ftp.gnu.org/pub/gnu/gcc/gcc-4.6.3/gcc-4.6.3.tar.bz2
gdb-msp430 Apply patch from mspgcc before building. ftp://ftp.gnu.org/pub/gnu/gdb/gdb-7.2a.tar.bz2
msp430-libc Necessary libraries. http://sourceforge.net/projects/mspgcc/files/msp430-libc/msp430-libc-20120224.tar.bz2/download
mspdebug Utility to connect debugger and target. This is also necessary to program the target. http://sourceforge.net/projects/mspdebug/files/mspdebug-0.22.tar.gz/download

You may wish to refer to this script to facilitate easy installation. This should be used as a starting point. In particular, even after successful build, there is an issue relating to paths. Wrong path settings can prevent building and/or linking for MSP430 target. The script was originally written for Ubuntu 12.04.3 LTS but may work for other distributions with minor modifications.

3.1.5. Eclipse IDE

The steps noted here are for Ubuntu 12.04.3 LTS version. Some steps may be different for your distribution.

3.1.5.1. Basic Installation

  1. From Ubuntu toolbar, access Ubuntu Software Center.
  2. Search for Eclipse. Select and install the same. Typically, this would be Eclipse Indigo on Ubuntu 12.04.3 LTS. Later versions are Juno and Kepler.

3.1.5.2. CDT

  1. CDT is a plugin required for Eclipse to support the C language. Open Eclipse. Go to Help » Install New Software.
  2. Click on Add. Enter name as CDT. Enter location depending on your version of Eclipse:
  1. Select all the components and install. Restart Eclipse.

3.1.5.3. Embedded CDT

  1. Follow the same steps as CDT, except that enter name as Embedded CDT and location as http://opensource.zylin.com/zylincdt.

3.1.5.4. EGIT

  1. Eclipse GIT helps in connecting to the GIT version control system from within Eclipse. This is useful to compare changes before pushing them to the respository. It is also convenient to obtain latest code changes done by team members into your development environment. Note that this step can be skipped if you do wish to use GIT.
  2. Follow the same steps as CDT, except that enter name as GIT and location as http://download.eclipse.org/egit/updates.

3.1.6. Using the Tools

For the benefit of beginners, the steps in this chapter are particular for Ubuntu 12.04.3 LTS supplied on a bootable USB. Those who have installed binaries or built from sources will find this as a useful reference.

3.1.6.1. Default Desktop

Once Ubuntu has booted up, the default screen you will see is the desktop. In case you are using the bootable USB, you will see the screen shown in Figure 3. On the desktop, ignore the icon Install Ubuntu 12.04.3 LTS. On the left is the toolbar. Time, power status, network connectivity, mail and keyboard options are on the top right corner.

Figure 3: Ubuntu Desktop

_images/UbuntuDesktop.png

In your particular case, wireless networking connection will not happen unless you configure the settings. You can do this by clicking on the wireless icon on the top right corner and clicking on Create New Wireless Network... If you are using an Ethernet cable, you will generally obtain LAN connection immediately.

3.1.6.2. Compiling a Sample Program

  1. Eclipse needs a workspace, basically a folder where all your projects will be stored. A default workspace named /home/ubuntu/workspace has been created where /home/ubuntu is the home folder for user ubuntu.
  2. From the toolbar on desktop, open Eclipse by clicking the icon shown in Figure 4. Select the default workspace noted above. If the Eclipse icon is missing for some reason, you can open Eclipse via Dash Home, which is the first icon on the left toolbar.

Figure 4: Launching Eclipse and Selecting the Workspace

_images/UbuntuLaunchingEclipse.png
  1. Once Eclipse is up, you should see a project named led. If the project is not open, open it by clicking Project » Open Project. Take a look at the C file led.c. This contains basic code to toggle a pair of LEDs on the WiSense MSP430 board.
  2. Familiarize yourself with the project properties by clicking Project » Properties. In particular, under Properties, go to C/C++ Build and take note of all the settings. These important settings are summarized in Table 4. For other MSP430 variants (for example, MSP430G2553), you will need to change -mmcu value and the compiler symbol definition.
Table 4: Project Settings Under Eclipse
Settings Tab Tool Field Value
Tool Settings GCC C Compiler Command msp430-gcc
Symbols __MSP430G2955__
Includes /usr/msp430/include
Optimization None (-O0)
Debugging Maximum (-g3)
Warnings All warnings (-Wall)
Miscellaneous -c -fmessage-length=0 -mmcu=msp430g2955
GCC C Linker Command msp430-gcc
Libraries Library search path: /usr/msp430/lib
Miscellaneous -mmcu=msp430g2955
GCC Assembler Command msp430-as
General Assembler flags: -mmcu=msp430g2955
Include paths: /usr/msp430/include
Build Artifact   Type Executable
Name ${ProjName}
Extension elf
Binary Parsers     Elf Parser
  1. Build the project by clicking on Project » Build Project. The project should build without errors. A file named led.elf should be created.
  2. Click on Dash Home from Ubuntu desktop toolbar. Open an application named Terminal. In the terminal, go to workspace folder. You should see the ELF file: /home/ubuntu/workspace/led/Debug/led.elf
  3. It is possible to analyze this file to know address locations, segments and their sizes. To do this type: msp430-readelf --all led.elf
  4. You can explore other options of the read program by first learning its different options: msp430-readelf --help

3.1.6.3. Programming the Target

  1. Connect the target to the TI LaunchPad. Connect the LaunchPad to the host system via USB cable. Go to Terminal and type command dmesg. If the connections are proper and the driver has been recognized, the last few lines of the output should be similar to what you see below:
[ 3767.764113] usb 4-1: new full-speed USB device number 3 using uhci_hcd
[ 3767.966160] usb 4-1: New USB device found, idVendor=0451, idProduct=f432
[ 3767.966172] usb 4-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[ 3767.966181] usb 4-1: Product: Texas Instruments MSP-FET430UIF
[ 3767.966188] usb 4-1: Manufacturer: Texas Instruments
[ 3767.966195] usb 4-1: SerialNumber: 09FF4A7AB74A5533
[ 3767.975224] cdc_acm 4-1:1.0: This device cannot do calls on its own. It is not a modem.
[ 3767.975236] cdc_acm 4-1:1.0: No union descriptor, testing for castrated device
[ 3767.975275] cdc_acm 4-1:1.0: ttyACM0: USB ACM device
  1. Program the target by typing mspdebug rf2500 "prog led.elf" from the folder where the ELF file resides. If there are no errors, you should see something similar to the listing below. This example shows programming the MSP430G2553. In addition, the LEDs on the target should start blinking alternatively.
ubuntu@ubuntu:~/workspace/led/Debug$ mspdebug rf2500 "prog led.elf"
MSPDebug version 0.18 - debugging tool for MSP430 MCUs
Copyright (C) 2009-2011 Daniel Beer <dlbeer@gmail.com>
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Trying to open interface 1 on 003
Initializing FET...
FET protocol version is 30394216
Configured for Spy-Bi-Wire
Set Vcc: 3000 mV
Device ID: 0x2553
Device: MSP430G2553
Code memory starts at 0xc000
Number of breakpoints: 2
Erasing...
Programming...
Writing  160 bytes to c000 [section: .text]...
Writing   32 bytes to ffe0 [section: .vectors]...
  1. It is possible to program the target as part of the build procedure managed by Eclipse. This is left as an exercise.

3.1.6.4. Debugging Target Execution

  1. To debug on target, we need to first create a debug configuration within Eclipse. Go to Run » Debug Configurations.
  2. Select Zylin Embedded debug (Native). Click on New button. Configuration settings are noted in Figure 5 and Figure 6. You may wish to study the commands in gdbcmds file.

Figure 5: Debug Configuration (Main)

_images/UbuntuDebugMain.png

Figure 6: Debug Configuration (Debugger)

_images/UbuntuConfigDebugger.png
  1. Open file led.c and set breakpoint on any line with C source code.
  2. Go to Terminal. Type command mspdebug rf2500 gdb. This program will now wait on port 2000 for msp430-gdb to connect (which will happen via Eclipse).
  3. From Eclipse, start debug session by clicking on Run » Debug Configurations, selecting led Debug created earlier and clicking on Debug. The program will begin execution and it will stop at the start of main function. If you continue execution, it will stop at the breakpoint. You may now single-step, observe the stack or inspect the values of variables.
  4. Note that when compiler optimization is used, it is often not possible to set breakpoints at the correct place in C code. In this case, set breakpoints in assembly in the disassembly window.