This walk-through teaches you how to set up Ubuntu 12.04 on an embedded ARM computer, the Gumstix OveroSTORM. 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://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 Ubuntu. Using a virtual machine is discouraged, especially if this is your first time.
• A Gumstix Overo STORM COM and expansion board. I'm using the Tobi and Thumbo expansion boards and Overo "WaterSTORM."
• A micro-SDHC card. I'm using a Samsung Pro 32GB card.
• An SDHC reader (some SD readers do not read SDHC cards).

• Gumstix bootloaders and kernel (3.2) image. I built these images from the repositories: Linux 3.2 (commit 7d06c6e) and u-boot 2014-07. If you prefer to compile your own kernel, see [CompileGumstixKernel](CompileGumstixKernel]].
• Ubuntu 12.04 precise which was the long term support (LTS) release compatible with Linux 3.2. The architecture is armhf.

I'm using Ubuntu 14.04 as the host machine distribution. You need to use a 12.04 or newer Ubuntu machine as your host.

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.

The SD card is usually seems to usually be /dev/mmcblk0, so I'll assume that's what it is here. Download the Gumstix partition tool: mk2partsd.

1. Unmount any existing partitions, e.g.

   sudo umount /dev/mmcblk0p1
   

2. Make the mk2partsd tool executable:

   chmod a+x mk2partsd
   

3. Run the partitioner

   sudo ./mk2partsd /dev/mmcblk0
   

When you're done, 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:

• a x-loader binary image i.e MLO
• a u-boot bootloader binary image i.e. u-boot.img
• a kernel binary image i.e. uImage
• kernel modules

The copying order matters!

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

We will use multistrap to create a bootable Ubuntu root armhf 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 ubuntu.conf in ~/gumstix and put in the following:

   [General]
   arch=armhf
   directory=rootfs
   # same as --tidy-up option if set to true
   cleanup=true
   # same as --no-auth option if set to true
   # keyring packages listed in each debootstrap will
   # still be installed.
   noauth=true
   # whether to add the /suite to be explicit about where apt
   # needs to look for packages. Default is false.
   explicitsuite=false
   # extract all downloaded archives (default is true)
   unpack=true
   # the order of sections is not important.
   # the debootstrap option determines which repository
   # is used to calculate the list of Priority: required packages.
   debootstrap=Ubuntu
   aptsources=Ubuntu
   
   [Ubuntu]
   packages=apt zile adduser makedev less isc-dhcp-client netbase ifupdown iproute net-tools iputils-ping openssh-server sudo picocom minicom build-essential wget curl locales gnu-fdisk traceroute socat zip unzip nano m4 psmisc rsync lsof vim cpufrequtils aptitude iperf module-init-tools udev rsyslog ntp
   source=http://ports.ubuntu.com/ubuntu-ports/
   keyring=ubuntu-keyring
   suite=precise
   components=main restricted multiverse universe
   

   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.

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

   # host
   sudo multistrap -f ubuntu.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
   /var/lib/dpkg/info/dash.preinst install
   ln -s /usr/lib/insserv/insserv /sbin/insserv
   dpkg --configure -a
   

8. base-files may fail to configure. If it does, try the following

   # gumstix-chroot
   mv /var/run /var/run2
   mkdir /var/run
   dpkg --configure -a
   

9. Set the root user password

   # gumstix-chroot
   passwd
   

10. Add a user and (if desired) give it sudo permissions

    # gumstix-chroot
    adduser gobysoft
    printf "gobysoft      ALL=(ALL) ALL" >> /etc/sudoers
    

11. Add a DNS server (Google is good)

    # gumstix-chroot
    printf "nameserver 8.8.8.8" > /etc/resolv.conf
    

12. 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
    
    // optional usb
    auto usb0
    iface usb0 inet dhcp
    

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

14. Update the apt repositories

    # gumstix-chroot
    apt-get update
    

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

16. Add a tty (console) on the appropriate serial port (ttyO2 for the Tobi board for this kernel version; older kernels used ttyS2). Add a file called "/etc/init/ttyO2.conf" with the following contents:

    # tty02 - getty
    #
    # This service maintains a getty on ttyS0 from the point the system is
    # started until it is shut down again.
    
    start on stopped rc or RUNLEVEL=[12345]
    stop on runlevel [!12345]
    
    respawn
    exec /sbin/getty -L 115200 ttyO2 vt102
    

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

18. If you are using a "STORM" board, these are not stable at 1GHz using Linux 3.2 (non-"STORM" boards can skip this step). To avoid this problem, underclock the CPU. To do this, in /etc/init.d/cpufrequtils, set:

    ENABLE="true"
    GOVERNOR="conservative"
    MAX_SPEED="800000"
    MIN_SPEED="0"
    

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

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

21. Unmount the bind mounted dev

    sudo umount ~/gumstix/rootfs/dev
    

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. Install the kernel modules

   #host
   cd /media/rootfs/
   sudo tar xfJ /path/to/modules.tar.xz
   

3. Unmount the SD card partitions:

   # host
   sudo umount /media/boot
   sudo umount /media/rootfs
   

4. Remove the SD card from the host and insert into the Gumstix.

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

6. Start a serial console on the host

   # host
   picocom /dev/ttyUSB0 -b 115200
   

7. Power on the Gumstix.

8. Login using "gobysoft" and the password you gave when creating that user.