Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
https://github.com/gumstix/live-build for new images.This page is out-of-date and is only kept here for reference. I would suggest using
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,
# hostis assumed.
Sometimes, I'll use
emacssince the basic commands are the same and
zileis much smaller. You can always use
vi, etc. instead wherever I have
picocomfor connecting to the serial console terminal, as it's very easy to configure (one line). You are, of course, welcome to use
kermitif you prefer.
Other useful websites
- 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
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.
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.
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: http://www.gumstix.org/create-a-bootable-microsd-card.html.
You will need two primary partitions (you can probably have more if you want):
- a 64 MB fat32 (vfat) partition for the bootloaders and kernel. (I'm calling this "boot", as does Gumstix).
- an ext3 partition for the filesystem ("/") that uses the remaining space on the card. (I'm calling this "rootfs", as does Gumstix).
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.
- Locate the SD card
- Unmount and delete any existing partitions (be sure you have the SD card, not another drive!)
- Add the two partitions mentioned above.
- 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
Copy the Gumstix Bootloader and Kernel
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
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.
Pick a folder to work from, e.g.
Make a directory to hold the root fileystem:
# host cd ~/gumstix mkdir rootfs
Create a file called
~/gumstixand 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-getlater 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.
Create the root filesystem in the directory given in
# host sudo multistrap -f emdebian.conf
Copy the QEMU ARM emulator into the new root filesystem so that it is on the path once we
# host sudo cp /usr/bin/qemu-arm-static ~/gumstix/rootfs/usr/bin/
Mount the real /dev in the chroot to give it access to /dev/random, etc. Then, run bash in the root
~/gumstix/rootfsas 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
Finish setting up packages:
# gumstix-chroot dpkg --configure -a
Answer "no" when asked if you want to use "dash" as "/bin/sh".
ifupdownmay fail to configure. Just run
# gumstix-chroot dpkg --configure -a
Set the root user password
# gumstix-chroot passwd
Add a user and (if desired) give it sudo permissions
# gumstix-chroot adduser mituser printf "mituser ALL=(ALL) ALL" >> /etc/sudoers
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)
Add a DNS server (Google is good)
# gumstix-chroot printf "nameserver 220.127.116.11" > /etc/resolv.conf
Add a sane static network (if you need DHCP install the
# 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
Restart networking to apply the new interface
# 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 18.104.22.168
If it doesn't, make sure the host's networking is working.
Update the apt repositories
# gumstix-chroot apt-get update
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
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
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
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.
Type "exit" or Ctrl-C from the chroot'd bash.
Copy over the root filesystem and boot the Gumstix
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.
Unmount the SD card partitions:
# host sudo umount /media/boot sudo umount /media/rootfs
Remove the SD card from the host and insert into the Gumstix.
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.
Start a serial console on the host
# host picocom /dev/ttyUSB0 -b 115200
Power on the Gumstix.
Login using "mituser" and the password you gave when creating that user ("mitmit" for the downloaded filesystems).
# 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.
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 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.
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 '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
Package: *-4.4-arm-linux-gnueabi* *-4.4-dev-armel-cross Pin: release a=stable Pin-Priority: 1100
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
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.