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
  pwd
  ls *
  

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

  # gumstix
  pwd
  ls *
  

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

  # gumstix-chroot
  pwd
  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.

• http://paul-strefling.blogspot.com/2011/06/installing-debian-on-gumstix-overo.html: These instructions are adapted from this post on the blog Necessarily Complicated. Many thanks to that post and you may find it helpful as well.
• http://www.gumstix.org: Official Gumstix Software Page
• http://wiki.gumstix.org/index.php?title=Main_Page: Gumstix User Wiki

• 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).

• 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.

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. http://packages.ubuntu.com/oneiric/multistrap) because it has minimal dependencies.

Required packages:

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

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: http://www.gumstix.org/create-a-bootable-microsd-card.html.

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.

Download the relevant boot files (http://cumulus.gumstix.org/images/angstrom/factory/2011-08-30-1058/):

• 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

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:

   [General]
   arch=armel
   directory=~/gumstix/rootfs
   noauth=true
   unpack=true
   debootstrap=Grip Networking Debian Misc
   aptsources=Grip Debian
   
   [Grip]
   packages=locales udev adduser sudo nano build-essential less
   source=http://www.emdebian.org/grip
   keyring=emdebian-archive-keyring
   components=main
   suite=wheezy-grip
   
   [Misc]
   packages=wget
   source=http://www.emdebian.org/grip
   keyring=emdebian-archive-keyring
   components=main
   suite=wheezy-grip
   
   [Networking]
   packages=netbase ifupdown iproute net-tools iputils-ping ntp
   source=http://www.emdebian.org/grip
   keyring=emdebian-archive-keyring
   suite=wheezy-grip
   
   [Debian]
   packages=zile
   source=http://mirrors.mit.edu/debian
   keyring=debian-archive-keyring
   suite=wheezy
   

   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: http://www.emdebian.org/grip/search.php?arch=armel&distro=stable and Debian packages are listed here: http://www.debian.org/distrib/packages. 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
    passwd
    

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 8.8.8.8" > /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
    address 192.168.0.20
    netmask 255.255.255.0
    gateway 192.168.0.1
    

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
    ping 8.8.8.8
    

    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 "127.0.0.1   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 (http://en.wikipedia.org/wiki/Procfs) 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.

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
   

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

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 http://www.emdebian.org/debian 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.

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 '192.168.1.0/24'

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

DISTCC_HOSTS=192.168.1.100 make -j4

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

DISTCC_POTENTIAL_HOSTS=192.168.1.100 pump make -j4

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 http://www.emdebian.org/debian/ 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.