Wednesday, November 21, 2012

The complete tutorial for Stellaris LaunchPad development with GNU/Linux (I)


So you bought the Stellaris LaunchPad, this powerful and cheap development board. Maybe you are even one of the lucky ones that bought it for only $4.99. You received it, grabbed a breadboard, some wires, resistors, capacitors and ICs, mixed all together and are ready to start writing software, but... what options do you have for developing software for this platform? Let's see what TI has to offer on the Stellaris LaunchPad web page:
  • Code Composer Studio (CCS) is the IDE from Texas Instruments. It's Eclipse based and you can use it with the Stellaris Launchpad without any limit on the code size.
  • Keil RealView MDK-ARM: This is a popular IDE supporting several chip architectures, including the ARM Cortex M4 in your Stellaris LaunchPad. You can freely download an evaluation version, which is 32 kiB code size limited.
  • IAR Embedded Workbench. Another popular IDE. It has also an evaluation version, with a 32 kiB code size limit.
  • Sourcery Codebench. An IDE by Mentor Graphics. You can download a 30-day evaluation version.
If you want to stick to non-limited non-pay options, you can use Code Composer Studio. End of story. See you in Hack a Day when you finish your neat gadget!

Are you still reading? If that's the case, maybe you don't like/have a Windows box for developing, and all the four IDEs I have mentioned are Windows only. But don't worry, of course you can develop for this board using GNU/Linux. Don't forget GNU/Linux is the best OS for software developing ;-).

I'll write some entries detailing all the process needed to set up the toolchain, build the StellarisWare libraries, build your project, flash and debug it and set up an Eclipse project. In the end, we will have a completely FOSS IDE without any time/code size restrictions!

But enough talk, let's get our hands dirty!

Building the toolchain

In these tutorials, I'll put all the tools for Stellaris development in a directory called src/stellaris under my home. The first step is to build the toolchain containing the assembler, C compiler and libraries, linker,  etc. To build it I followed the steps posted in Recursive Labs Blog, almost unmodified.
  1. Create working directory and change to it:
mkdir -p ~/src/stellaris
cd ~/src/stellaris
  1. Install the compiler and dependencies required to build the toolachain. In Ubuntu (and hopefully in most Debian based distros):
apt-get install flex bison libgmp3-dev libmpfr-dev libncurses5-dev libmpc-dev \
        autoconf texinfo build-essential libftdi-dev git
  1. Download the script for building the toolchain and run it. This step will take some time to complete, but when it finishes, you should have the toolchain ready to use, in the sat/ directory under your home:
git clone https://github.com/esden/summon-arm-toolchain
cd summon-arm-toolchain
./summon-arm-toolchain
Once the build is successfully completed, your toolchain will be ready for building programs for the Stellaris Launchpad. For convenience don't forget to add ~/sat/bin to your PATH variable. For example edit .profile file in your home, and add the following line at its end:
export PATH=$PATH:$HOME/sat/bin
You will have to restart your session for this change to take effect.

Building StellarisWare library

The easiest way to configure the Stellaris MCU and its peripherals is to use the StellarisWare library. This library is really complete and easy to use, and has another cool advantage: it's also included in the ROM inside the LM4F120 MCU (you just have to add the ROM_ prefix to the function calls to use the ROM software). This can help saving Flash memory space.

Fortunately the library uses a BSD license, the sources are available and come with gcc friendly makefiles. Building this library is as easy as:
  1. Download the library sources package. You can find it here. You'll need a my.TI account, so if you have not one, you'll have to register.
  2. Unpack and build the library. Make sure you change the path to the library package, in case you don't download it to the Downloads directory of your home:
mkdir -p ~/src/stellaris/stellarisware
cd ~/src/stellaris/stellarisware
unzip ~/Downloads/SW-EK-LM4F120XL-9453.exe
make
These steps will build StellarisWare library and also the examples. StellarisWare example files are not BSD licensed. They have some obscure license terms, including the startup code files, the linker scripts and the Makefiles for building them. This can be a problem for some users, so be warned.

Building and using lm4flash

lm4flash is a tool for flashing binaries to the MCU. This step is not strictly required, because you can flash programs to the MCU using gdb + openocd, but it's easy to do, fast, and sometimes using lm4flash tool is more convenient. Just follow these steps:
  1. Download lm4tools and build lm4flash:
cd ~/src/stellaris
git clone https://github.com/utzig/lm4tools.git
cd lm4tools/lm4flash
make
  1. If everything went OK, you should have the lm4flash binary sitting in the current working directory. Maybe this is not the cleanest installation method, but I moved lm4flash to ~/sat/bin for it to stay in the PATH:
mv lm4flash ~/sat/bin/
  1. Before flashing anything to the board, it's recommended to create a new udev rule so you can use lm4flash (and openocd later) without superuser permissions (i.e. without being root or using sudo). You will also have to add your user to the "users" group if it's not in it already. So only execute the last sentence if you need to do so, and if you do it, replace <username> with your user name:
echo 'ATTRS{idVendor}=="1cbe", ATTRS{idProduct}=="00fd", GROUP="users", MODE="0660"' | \
        sudo tee /etc/udev/rules.d/99-stellaris-launchpad.rules
sudo usermod -aG users <username>
  1. If the board was plugged to the USB debug port, unplug it. Make sure the PWR SELECT switch is at the DEBUG position and connect the USB debug port to a USB port in the PC. If the rule is working, you will have permission to access the /dev/ttyACM* device created when you plug the board. Now you can test everything you have done until now, by flashing one of the examples, like this:
cd ~/src/stellaris/stellarisware/boards/ek-lm4f120xl/blinky/gcc/
lm4flash blinky.bin
The program should be successfully flashed to the MCU, and you should see a green LED blinking in the board. If that's the case, congratulations, your toolchain is working perfect!

In the next chapter we will learn how to set-up OpenOcd and GDB for debugging programs. We will also see how to avoid problems with the clunky license that comes with the examples in the StellarisWare package.

Happy hacking, and stay tuned!

18 comments:

  1. Step #3, under "Building and using lm4flash", should have the second command say:

    sudo usermod -aG users my_username

    Otherwise, this is Awesome!

    Thanks so much for a great step-by-step.

    Jim

    ReplyDelete
    Replies
    1. Blogger took as an HTML tag and ate it :-P. Thanks for the correction, it's fixed now.

      Delete
  2. thanks seems to work, its blinking good.

    ReplyDelete
  3. you don't have to deal with windows binaries at all, you can clone stellarisware from https://github.com/yuvadm/stellaris/

    ReplyDelete
  4. I always get

    'error: bad value (cortex-m4) for -mcpu= switch'

    and

    'error: invalid floating point option: -mfpu=fpv4-sp-d16'

    when invoking 'make' in the stellaris dir:

    $ make
    make[1]: Betrete Verzeichnis '/home/andre/Dokumente/DevBoards/stellaris-lm4f/dev/stellarisware/driverlib'
    CC adc.c
    adc.c:1: error: bad value (cortex-m4) for -mcpu= switch
    adc.c:1: error: invalid floating point option: -mfpu=fpv4-sp-d16
    make[1]: *** [gcc-cm4f/adc.o] Fehler 1
    make[1]: Verlasse Verzeichnis '/home/andre/Dokumente/DevBoards/stellaris-lm4f/dev/stellarisware/driverlib'
    make: *** [all] Fehler 2

    $ uname -a
    Linux an 3.5.0-27-generic #46-Ubuntu SMP Mon Mar 25 20:00:05 UTC 2013 i686 i686 i686 GNU/Linux

    ReplyDelete
  5. You may need libusb developpement files to build lm4flash :
    apt-get install libusb-1.0-0-dev

    ReplyDelete
    Replies
    1. You may also need python-yaml module:
      apt-get install python-yaml

      Delete
  6. Whe i was compiling it I got the following error:


    checking for arm-none-eabi-gcc... ~/lm4tools/summon-arm-toolchain/build/./gcc/xgcc -B/~/lm4tools/summon-arm-toolchain/build/./gcc/ -nostdinc -B/~/lm4tools/summon-arm-toolchain/build/arm-none-eabi/newlib/ -isystem /~/lm4tools/summon-arm-toolchain/build/arm-none-eabi/newlib/targ-include -isystem /~/lm4tools/summon-arm-toolchain/gcc-linaro-4.7-2013.01/newlib/libc/include -B/~/lm4tools/summon-arm-toolchain/build/arm-none-eabi/libgloss/arm -L/~/lm4tools/summon-arm-toolchain/build/arm-none-eabi/libgloss/libnosys -L/~/lm4tools/summon-arm-toolchain/gcc-linaro-4.7-2013.01/libgloss/arm -B/root/sat/arm-none-eabi/bin/ -B/root/sat/arm-none-eabi/lib/ -isystem /root/sat/arm-none-eabi/include -isystem /root/sat/arm-none-eabi/sys-include
    checking for suffix of object files... configure: error: in `~/lm4tools/summon-arm-toolchain/build/arm-none-eabi/libgcc':
    configure: error: cannot compute suffix of object files: cannot compile
    See `config.log' for more details.
    make[1]: *** [configure-target-libgcc] Error 1
    make[1]: Leaving directory `~/lm4tools/summon-arm-toolchain/build'

    Could somebody help me?
    the directory /sat has been created but i don't know what does this error means

    ReplyDelete
    Replies
    1. It looks like you are building as root. Maybe that's not related to this problem, but usually it's not a good idea to build stuff as root.

      Delete
  7. Great tutorial, thanks!

    I am running Ubuntu 12.10 under VirtualBox on Windows.

    Step 2 under Building the toolchain, the apt-get is missing python-yaml, it was needed to build libopencm3.

    Step 3 for Building and using lm4flash, the line to create the udev rule is missing something, it should start with:

    echo 'SUBSYSTEMS=="usb", ATTRS{IdVendor}...

    ReplyDelete
  8. I am currently getting an error at the last step:

    # lm4flash blinky.bin
    Unable to open USB device: LIBUSB_ERROR_ACCESS
    Unable to find any ICDI devices

    I reinstalled the libusb1.0 library as well as the dev version and still no luck. Any help would be awesome.

    Kas

    ReplyDelete
    Replies
    1. Did you successfully create the rule to give permissions to use ICDI interface? (step 3). Try flashing with root permissions (e.g.: "sudo lm4flash blinky.bin"). If it works this way, maybe the rule was not properly created.

      Delete
    2. This is what I got back :(

      $ sudo lm4flash blinky.bin
      sudo: lm4flash: command not found

      Delete
    3. I also tried this:

      sudo lsusb
      Bus 001 Device 003: ID 174f:1403 Syntek Integrated Webcam
      Bus 001 Device 004: ID 067b:2506 Prolific Technology, Inc.
      Bus 002 Device 002: ID 046d:c51b Logitech, Inc. V220 Cordless Optical Mouse for Notebooks
      Bus 005 Device 003: ID 1cbe:00fd Luminary Micro Inc.
      Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
      Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
      Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
      Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
      Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub


      Nothing about a launchpad :(

      Delete
    4. IIRC, the launchpad enumerates as a "Luminary Micro Inc.", so it's properly detected by your system (I presume).

      It looks like sudo isn't getting the path from your current user. Try again but this time instead of "lm4flash" command, write its full path, something like:

      sudo /home/your_username/sat/bin/lm4flash blinky.bin

      But make sure you replace the path I wrote with the correct one for your system.

      Delete
    5. Thank you very much!! That seemed to make it work, I assume I should see a green LED flashing at a fast rate. The question now is how do I make it that I do not need the full path every time ?

      Delete
  9. What a good tutorial! Although it was a bit of a struggle for me, being very new to linux/ubuntu, i got it working so far. Can't wait for the next section.

    A note from my side:
    I got this working on two different machines, both freshly instaleld Ubuntu 12.04.4, and both were zlib.h missing during the building of the toolchain.
    The one machine got "sudo apt-get install libcrypto++-dev" installed, the other one "sudo apt-get install zlib1g-dev". Both worked, which one is better remains unknown to me.

    ReplyDelete
  10. Thanks for review, it was excellent and very informative.
    thank you :)

    ReplyDelete