Toby Schneider edited this page May 26, 2016 · 8 revisions

This page is out-of-date and is only kept here for reference. I would suggest using for new images.

This walk-through teaches you how to set up Debian on an embedded ARM computer, the Gumstix Overo. If you already have a working Linux distribution on your Gumstix and want only to install Goby, you may want to skip straight to InstallFromSource. Please make any changes or corrections to this document (create a wiki account first if you don't have one).


This wiki entry uses a few conventions:

  • Commands intended to be typed into the host will be formatted as such:

    # host
    ls *
  • Commands intended to be typed into the gumstix over serial console (picocom) or SSH will be formatted as such:

    # gumstix
    ls *
  • Commands that are to be typed into a chroot environment on the host representing the gumstix will be formatted:

    # gumstix-chroot
    ls *
  • Where no directive is given, # host is assumed.

  • Sometimes, I'll use zile instead of emacs since the basic commands are the same and zile is much smaller. You can always use nano, vi, etc. instead wherever I have zile.

  • I like picocom for connecting to the serial console terminal, as it's very easy to configure (one line). You are, of course, welcome to use minicom or kermit if you prefer.

Other useful websites

Hardware you need

  • A computer, the host, capable of running Debian. Using a virtual machine is discouraged, especially if this is your first time.
  • A Gumstix Overo COM and expansion board. I'm using the Tobi expansion board and Overo "Water", which is sold separately or as a kit.
  • A micro-SDHC card. I'm using a Transcend 32GB card, which is the largest available size in SDHC.
  • An SDHC reader (some SD readers do not read SDHC cards).

Software we will install

  • Official Gumstix bootloaders and kernel (2.6.39) image. If you prefer to compile your own kernel (e.g. to use the power management features described in Sakoman's blog, see [CompileGumstixKernel](CompileGumstixKernel]].
  • Debian 6 squeeze which was the stable release at the time of this writing. The architecture is armel. We'll be making use of the Emdebian grip distribution which provides some tools and a subset of packages adapted from squeeze to use less disk space. We'll also be getting some packages from the main squeeze repository as well.

Setup: Host

I'm using Ubuntu 12.04 as the host machine distribution. You need to use a new Debian or Debian-derivative (Ubuntu, Mint, etc.) as your host. Older versions of multistrap seem to broken, such as the one packaged with Ubuntu 10.04. If necessary, you can safely manually install a newer multistrap (e.g. because it has minimal dependencies.

Required packages:

sudo apt-get install multistrap qemu-user-static picocom

Partition the SD Card

I will walk through one way of formatting the SD card. Further details of formatting the SD card for the Gumstix are available on their website:

You will need two primary partitions (you can probably have more if you want):

  1. a 64 MB fat32 (vfat) partition for the bootloaders and kernel. (I'm calling this "boot", as does Gumstix).
  2. an ext3 partition for the filesystem ("/") that uses the remaining space on the card. (I'm calling this "rootfs", as does Gumstix).

I prefer gparted for partition editing, which you can get with

sudo apt-get install gparted

The SD card is usually seems to usually be /dev/mmcblk0, so I'll assume that's what it is here.

sudo gparted
  1. Locate the SD card /dev/mmcblk0
  2. Unmount and delete any existing partitions (be sure you have the SD card, not another drive!)
  3. Add the two partitions mentioned above.
  4. Set the "boot" flag on the fat32 partition.

When you're done, the SD card should look something like this:

When you're done, close gparted and let the SD card partitions automount by removing the card and reinserting it. Alternatively you can mount on the command line with mount.

Copy the Gumstix Bootloader and Kernel

Download the relevant boot files (

  • a x-loader binary image e.g. MLO
  • a u-boot bootloader binary image e.g. u-boot.bin
  • a kernel binary image e.g. uImage

The copying order matters!

sudo cp MLO /media/boot
sudo cp u-boot.bin /media/boot
sudo cp uImage /media/boot

Obtain a root filesystem

Create a Emdebian root filesystem on the host

We will use multistrap to create a bootable Debian root armel filesystem on the host that we can later copy to the Gumstix.

  1. Pick a folder to work from, e.g. ~/gumstix.

  2. Make a directory to hold the root fileystem:

    # host
    cd ~/gumstix
    mkdir rootfs
  3. Create a file called emdebian.conf in ~/gumstix and put in the following:

    debootstrap=Grip Networking Debian Misc
    aptsources=Grip Debian
    packages=locales udev adduser sudo nano build-essential less
    packages=netbase ifupdown iproute net-tools iputils-ping ntp

    These packages will be installed on the new root filesystem that we will later copy to the SD card. Feel free to add/remove packages to suit your needs; however, you can always use apt-get later to add/remove the packages listed here. Emdebian packages are listed here: and Debian packages are listed here: When present, prefer Emdebian packages to Debian packages as they are supposed to be smaller.

  4. Create the root filesystem in the directory given in emdebian.conf:

    # host
    sudo multistrap -f emdebian.conf
  5. Copy the QEMU ARM emulator into the new root filesystem so that it is on the path once we chroot to ~/gumstix/rootfs:

    # host
    sudo cp /usr/bin/qemu-arm-static ~/gumstix/rootfs/usr/bin/
  6. Mount the real /dev in the chroot to give it access to /dev/random, etc. Then, run bash in the root ~/gumstix/rootfs as it will be seen by the Gumstix when we're all done:

    # host
    sudo mount -o bind /dev ~/gumstix/rootfs/dev
    sudo chroot ~/gumstix/rootfs /bin/bash
  7. Finish setting up packages:

    # gumstix-chroot
    dpkg --configure -a
  8. Answer "no" when asked if you want to use "dash" as "/bin/sh".

  9. ifupdown may fail to configure. Just run dpkg again:

    # gumstix-chroot
    dpkg --configure -a
  10. Set the root user password

    # gumstix-chroot
  11. Add a user and (if desired) give it sudo permissions

    # gumstix-chroot
    adduser mituser
    printf "mituser       ALL=(ALL) ALL" >> /etc/sudoers
  12. Configure locales for your language(s). I'm assuming you're US English (en_US.UTF-8); if not, choose other locales.

    # gumstix-chroot
    dpkg-reconfigure locales

    (136 is en_US.UTF-8, probably set this to default)

  13. Add a DNS server (Google is good)

    # gumstix-chroot
    printf "nameserver" > /etc/resolv.conf
  14. Add a sane static network (if you need DHCP install the isc-dhcp-client package using apt-get))

    # gumstix-chroot
    zile /etc/network/interfaces
    auto eth0
    iface eth0 inet static
  15. Restart networking to apply the new interface eth0

    # gumstix-chroot
    /etc/init.d/networking restart

    You might get an error here depending on the status of eth0 on the host. Try pinging something to see if that works anyway: :

    # gumstix-chroot

    If it doesn't, make sure the host's networking is working.

  16. Update the apt repositories

    # gumstix-chroot
    apt-get update
  17. Give the computer a name (I'm using Italian for shrimp)

    # gumstix-chroot
    printf "gambero" > /etc/hostname
    printf "   gambero\n" >> /etc/hosts
  18. Add a tty (console) on the appropriate serial port (ttyO2 for the Tobi board for this kernel version; older kernels used ttyS2)

    # gumstix-chroot
    printf "T0:2345:respawn:/sbin/getty -L 115200 ttyO2 vt102\n" >> /etc/inittab
  19. Add a proc filesystem ( to fstab

    # gumstix-chroot
    zile /etc/fstab
    # /etc/fstab: static file system information.
    # <file system> <mount point>   <type>  <options>       <dump>  <pass>
    proc            /proc           proc    defaults        0       0
  20. Do anything else you want to do in the chroot environment, such as installing Goby: InstallFromSource. Your host computer (even running QEMU) is likely much faster than the Gumstix itself.

  21. Type "exit" or Ctrl-C from the chroot'd bash.

Copy over the root filesystem and boot the Gumstix

  1. Copy over the files to the SD card (recursive, preserving permissions and showing progress):

    # host
    cd ~/gumstix/rootfs
    sudo rsync -aP . /media/rootfs/

    In the future, if you make changes to the rootfs on the host computer that you can to propagate to the SD card, simply run this command again. Run it with source and destination reversed to update the host computer rootfs if you make changes directly on the SD card.

  2. Unmount the SD card partitions:

    # host
    sudo umount /media/boot
    sudo umount /media/rootfs
  3. Remove the SD card from the host and insert into the Gumstix.

  4. Attach the mini USB-B to USB-A cable from the Console port on the Tobi board to the host. A USB serial device (e.g. /dev/ttyUSB0) will be created on the host.

  5. Start a serial console on the host

    # host
    picocom /dev/ttyUSB0 -b 115200
  6. Power on the Gumstix.

  7. Login using "mituser" and the password you gave when creating that user ("mitmit" for the downloaded filesystems).

  8. Install SSH

    # gumstix
    sudo apt-get install openssh-server

Cross Compiling

Native compilation of c++ code on the gumstix can be quite slow, but it's not difficult to setup cross compilation.

Install the Cross Compiler

On your development machine, or wherever you would like the cross compiler to run, add the emdebian squeeze main repository to your apt sources list (something like /etc/apt/sources.list):

deb squeeze main

Install aptitude if you don't already have it. Update your package list and install the emdebian version of g++-4.4-arm-linux-gnueabi (currently 4.4.5-8). The ubuntu version may have some issues, so we download the emdebian version just to be safe.

aptitude update
sudo aptitude install g++-4.4-arm-linux-gnueabi=4.4.5-8

Aptitude will probably list a number of unresolved dependencies such as gcc-4.4-arm-linux-gnueabi=4.4.5-8. Accept the solution that installs the emdebian version of these packages (this was the second solution in my case). You should be able to use synaptic package manager or similar to do this as well.

Setting up DistCC

Distcc let's us cross compile without having to worry about any differences between the gumstix and your host machine. Distcc can operate in two modes - standard and pump. In its standard mode distcc only does compilation remotely while preprocessing and linking is performed locally. In pump mode, header files are also distributed so that preprocessing can be done remotely as well.

We'll need to install distcc on both the client (the gumstix) and the host (the computer you want running the cross compiler). On your host computer this should be as easy as installing the distcc package.

sudo apt-get install distcc

Once you've done this add the following two symlinks:

cd /usr/lib/distcc
sudo ln -s `which distcc` arm-linux-gnueabi-gcc-4.4
sudo ln -s `which distcc` arm-linux-gnueabi-g++-4.4

Now to install on the gumstix. If only using standard mode then you can just install the distcc package here as well. The distcc-pump package seems to have a python dependency issue though so you'll need to build from source to be able to use it. Just download the most recent tarball from the distcc website and following their instructions for building and installing. After it's done you should have a bunch of symlinks in /usr/lib/distcc including arm-linux-gnueabi-g++-4.4 -> distcc and arm-linux-gnueabi-gcc-4.4 -> distcc.

To use distcc in a cmake project such as goby or moos you'll need to tell cmake to use distcc. One way to do this is using cmake-curses-gui. Use advanced mode to set the c and c++ compilers to /usr/lib/distcc/arm-linux-gnueabi-gcc-4.4 and /usr/lib/distcc/arm-linux-gnueabi-g++-4.4.

Start the distcc daemon on your host machine with appropriate allows. The following will allow any machine with a 192.168.1.x ip address to connect.

distccd --daemon --allow ''

On the gumstix start distcc in standard mode after providing it the host machine's ip address.

DISTCC_HOSTS= make -j4

Or to use pump mode: (pump may also be named distcc-pump)


Since linking is still performed locally on the gumstix you probably won't get much benefit past 4 jobs. Distcc-pump will be faster than plain distcc, but sometimes has trouble finding all the necessary includes for certain projects (including Goby).

If you're using Ubuntu 12.04 to compile for Debian squeeze, you'll need to "apt-pin" the arm packages for Debian squeeze. Use /etc/apt/preferences:

Package: *-4.4-arm-linux-gnueabi* *-4.4-dev-armel-cross
Pin: release a=stable
Pin-Priority: 1100

And add /etc/apt/sources.list.d/emdebian.list:

deb squeeze main


  • Problem (library package in Emdebian (-em1) but dev package only in Debian):

    Some packages could not be installed. This may mean that you have
    requested an impossible situation or if you are using the unstable
    distribution that some required packages have not yet been created
    or been moved out of Incoming.
    The following information may help to resolve the situation:
    The following packages have unmet dependencies:
     libcrypto++-dev : Depends: libcrypto++8 (= 5.6.0-6) but 5.6.0-6em1 is to be installed

    Solution: Use aptitude instead of apt-get. Usually the second solution will properly "downgrade" the lib package to the Debian version so the Debian dev package can be installed.

    apt-get install aptitude
    aptitude install libcrypto++-dev

    Alternative solution (force Debian version to be installed): :

    apt-get install libcrypto++8=5.6.0-6
  • Problem (gumstix-chroot has no hardware entropy for ssh, etc.)

    Fatal: no entropy gathering module detected

    Solution (bind your real /dev to the chroot /dev so the chroot can see the real /dev/random, etc) :

    # host
    sudo mount -o bind /dev /media/rootfs/dev

    When you're done, remember to :

    # host
    sudo umount /media/rootfs/dev

    before removing the SD card.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.