Installing and Using Debian on an OpenMoko FreeRunner

You can install Debian on your [http://wiki.openmoko.org/wiki/Neo_FreeRunner ?OpenMoko FreeRunner], and use that system to fulfill your telephone needs. You can then use almost all of the packages available for Debian, with just one call to apt-get install. It’s still the same full featured Distribution that you know from your desktop or server.

Notes

This installer is relatively new and probably contains bugs. You use it at your own risk.

If you want to learn something about your new Debian system, you can read the installation script and do the steps by hand. This also allows you to be more flexible with regard to partitioning, package selection and configuration.

At the moment, only the [http://wiki.openmoko.org/wiki/FSO freesmartphone.org] software stack is packaged for Debian, this means: frameworkd and zhone. Illume will be available once the next Enlightment snapshot is packaged. But this does not mean that you will not be able to use your favourite stack (e.g. SHR) on Debian, it just needs to be packaged by someone.

Instructions for installing on the Neo1973 can be found at DebianOnNeo1973

Card size

The Debian installation will take up most of the 512 megabytes of the stock MicroSD card that comes with the FreeRunner, leaving little room for installing additional .deb packages. One will soon find oneself purchasing a larger card and doing the Debian installation all over again. Hence one should consider purchasing a larger card first before proceeding.

Backup

If you do not have a card reader to backup your MicroSD card, you can copy the contents of the card including partition data over a network. You will need a booted Freerunner with network access (USB, Wireless etc.) and a *nix-based machine. Make sure power management is not set to suspend on the FreeRunner.

If you wish to take a backup of your MicroSD card to restore from later, run the following from your Freerunner:

dd if=/dev/mmcblk0 | ssh user@backup.server "gzip -9 > sdcard.gz"

This will create a compressed backup of your card performing the compression on the backup server (assuming that it's more powerful than 400MHz). To restore, run the following from your backup server:

zcat sdcard.gz | ssh root@freerunner.address dd of=/dev/mmcblk0

As always, double check you have used the correct syntax for 'dd'.

Swap partition

[http://lists.openmoko.org/pipermail/community/2008-September/031106.html Some have reported] a swap partition helps.

The user could consider integrating one into the plans below, as it would be much harder to do later when there is no free space left. Also consider where to place it when considering [http://wiki.openmoko.org/wiki/Qi Qi]'s boot order.

If it's too late to make a swap partition, [http://www.go2linux.org/Swap-memory-increase-with-swap-file consider a swap file]. See also [http://lists.openmoko.org/pipermail/support/2008-December/003892.html thread]. [http://lists.openmoko.org/pipermail/community/2008-October/032964.html Another swap file success].

Installation

To install Debian on your MicroSD card, you need to have any Linux system running already in flash. All official images (2007.2, 2008.8, FSO Milestone 2) should be fine. So far, the installation has only been tested with an up-to-date uBoot (from 2008-08-05), so it is recommended to upgrade that. Ensure that your FreeRunner is connected to the Internet, either via USB or wireless.

Log into your FreeRunner and download and run the installation script:

Note: using a local mirror, the installation should take around 30 minutes to complete given an Internet connection of 5MB/s or 50 minutes with a 575kB/s one. You will download approximately 250MB.

$ wget -O install.sh http://pkg-fso.alioth.debian.org/freerunner/install.sh
$ chmod +x install.sh
$ ./install.sh
Auto-Installer for Debian on the Openmoko FreeRunner (GTA02) v1.1
-----------------------------------------------------------------
Copyright 2008 Joachim Breitner <nomeata@debian.org>
Copyright 2008 Luca Capello <luca@pca.it>
This program is licensed under the terms of GNU General Public
License either version 2, or (at your option) any later version.
Usage: [variable1 variable2 ...] ./install.sh stage1 [stage2 ...]
Variables:
  HOSTNAME         the name of the machine (default to debian-gta02)
  SD_DEVICE        the character device to access the microSD card
                   (default to /dev/mmcblk0)
  SD_PART1_FS      the filesystem for the first microSD card partition,
                   i.e. the one containing the uImage.bin (default to
                   ext2, possible values are ext2/vfat)
  INST_DIR         the directory where the microSD card partitions
                   will be mounted to (default to /mnt/debian)
  INST_MIRROR      the Debian mirror used during installation, it
                   should be set to a mirror nearby that carries armel
                   binaries for unstable and experimental (default to
                   http://ftp2.de.debian.org/debian)
  APT_RECOMMENDS   control if APT should install recommends by default
                   (default to false, possible values are false/true)
  DASH_BINSH       configure dash as default /bin/sh (default to true,
                   possible values are true/false)
  FSO_MIRROR       the Debian FSO repository (default to
                   http://pkg-fso.alioth.debian.org/debian)
  FSO_DEVICE       the device the installation is being performed on
                   (default to gta02, possible value is gta02 only)
  QI               if you use Qi bootloader set this to true
                   (default to false)
  QI_VERBOSE_BOOT  set this to true if you want to see the kernel messages
                   do this only when QI=true (default to false)
  SINGLE_PART      set this to true if only one partition should be created
                   this is true by default for QI=true and false if SD_PART1_FS=vfat
Stages:
  all              Runs all the stages in the following order:
                   testing time partition format mount debian
                   apt fso configuration kernel unmount
  testing          Verifys that everything is in place for this
                   installer to work
  time             Fetches the current time from $RDATEHOST via rdate
  partition        Partitions the microSD card found in $SD_DEVICE
                   (WARNING, this will destroy all the data on the
                   microSD card unless the partioning is the same as
                   used before; this can be used to recover a broken
                   partiton table due to the suspend/resume problem)
  format           Formats the microSD card found in $SD_DEVICE
                   (WARNING, this will destroy all the data on the
                   microSD card)
  mount            Mounts microSD card partitions under $INST_DIR
  debian           Installs a basic Debian system, including an SSH
                   server
  apt              Sets up APT repositories
  fso              Installs packages required to use the Zhone GUI
  configuration    Configures various parts of the system, such as
                   the X server
  kernel           Downloads and installs the Debian kernel package
                   (only when $SD_PART1_FS is set to ext2)
  unmount          Unmounts the Debian filesystem mounted at $INST_DIR
Unsupported or buggy stages, use at your own risk:
  uboot            Configures the U-Boot environment to boot Debian
                   (it needs to run between the debian and the unmount
                   stage, only when $SD_PART1_FS is set to ext2)
For more information, go to http://wiki.debian.org/DebianOnFreeRunner

Please read these introductions to get an overview about what is going to happen. You can then run the installer with

$ ./install.sh all

or, to use a [http://www.debian.org/mirror/list mirror of your choice]. Mirrors might be unreliable and give E: Couldn't download Release! errors.

$ INST_MIRROR=http://ftp.cc.debian.org/debian ./install.sh all

Note that running 'all' involves the 'partition' action mentioned above, which destroys all information on the uSD card. You have been warned.

The default filesystem created by install.sh for the boot partition is ext2, but U-Boot needs the boot partition to be fat. You have some options:

I) Modify your NAND uBoot (as described below) so it can boot straight off ext2,

OR

II) Set boot partition to be vfat by running SD_PART1_FS=vfat ./install.sh all. Now you do not need to mess with modifying U-Boot's default setup, and can still boot to Debian using NOR boot. (Note this creates a tiny 8MB partition at the front of the card, which will be very hard to increase the size of later. So consider manually increasing the size. Even if not planning to use this partition now, it will be handy for emergency NOR boots later, as it is one of the places the NOR booter knows about.)

III) Instead learn about [http://wiki.openmoko.org/wiki/Qi Qi] , which however needs /boot to be on the same partition as / .

Now be patient for a while, as the script downloads, installs and sets up everything it needs. Once it finishes without an error, you have to adjust your uBoot environment:

In case of temporary errors (for example network problems), you can re-enter the installation by specifying the stages you want to run:

./install.sh  debian apt fso configuration kernel unmount

It is your responsibility to make sure that the installer finds a setup that equals that provided by previous stages, especially with regard to mounted filesystems.

With [http://wiki.openmoko.org/wiki/Supported_microSD_cards some larger SD cards], there is a known issue which prevents them from working properly. There is [https://docs.openmoko.org/trac/ticket/1743 a workaround] that involves modifying the uboot environment.

The installation script configures [http://gondor.apana.org.au/~herbert/dash/ dash] as the default shell (i.e. /bin/sh). If you still prefer [http://www.gnu.org/software/bash/ bash] as /bin/sh, either do this by running DASH_BINSH=false ./install.sh all at installation time or, once Debian is running, with dpkg-reconfigure dash.

At this point, if you want to run Debian from the FreeRunner's internal flash instead of the uSD card, see /MovingToFlash

Adjusting your uBoot environment

If you have installed your Debian with vfat as the boot partition file system, you can use the standard "Boot from SD (fat+ext2)" entry from the NAND uBoot and skip reading this chapter. If not, you need to modify your uBoot environment. You are welcome to do this manually, and set it up to your liking. We do however provide a script that configures uBoot so that:

(Note that we're talking about modifying the NAND boot, not the NOR boot (which one reaches via pressing AUX then POWER)!)

To run the script, you need:

Now you can configure your uBoot using these commands, run as root:

wget http://pkg-fso.alioth.debian.org/freerunner/configure-uboot.sh
chmod +x configure-uboot.sh
./configure-uboot.sh

Instead of this configure-uboot.sh script you can also take this one [http://paste.ubuntuusers.de/391456/ configure-uboot.sh] which will speed up the booting by using the quiet-mode. It also adds an additional boot-parameter for booting without quiet-mode for debugging purpose.You need to install the package dfu-util, despite the script's request to install dfo-util. Simple spelling mistake.

Do not use this script with a device other than the FreeRunner!

(Note that ANY errors probably mean the write failed, despite any final "all done" messages.)

Note that at the end of the script it tells you to reboot. Do it by pushing buttons, no just typing reboot, otherwise you will just reboot into the previous non-debian world.

Using your Debian system

If you have applied the above uboot configuration, the Debian System from SD-Card is booted by default. To Boot your normal system choose "Boot Flash" from uboot menu.

If you did not modify the uboot configuration, enter the NAND uboot menu and select Boot from SD (fat+ext2) to boot Debian.

After booting you should see [http://wiki.openmoko.org/wiki/Zhone Zhone] running, and you should (theoretically) be able to make and accept Phonecalls, send and receive SMS, access the on-SIM phonebook and use the GPS (more details at [http://wiki.openmoko.org/wiki/FSO_UI_Tutorial FSO UI Tutorial]. Debian, at the moment, does not ship Illume, so you do not have the status bars at the top. See below for alternatives.

If you are still using the factory uBoot image, then you may not be able to boot successfully. (For example, you may see the openmoko splash screen followed by bright white screen recursively.) Please get the newest uboot image from: http://downloads.openmoko.org/daily/testing/gta02v5_and_up-u-boot.bin and if you do not already know how to use dfu-util, then follow the instructions given at:http://wiki.openmoko.org/wiki/Flashing_the_Neo_FreeRunner#Flashing_the_boot_loader_to_the_NAND.

There is no Illume running, but you can pop up (and down) the matchbox keyboard using the AUX button. From the keyboard, you can run an xterm using the key combination Alt-Ctrl-x, and then switch between these two applications with Alt-Tab. From there on, there is nothing special about your telephone any more – it’s a Debian system!

Some ideas what you can do do from here:

Reporting bugs

When something is not working, please help us by first checking if it works with the official FSO image. If it does not work there, it is likely not a Debian specific bug, and should be reported at http://trac.freesmartphone.org/.

Although some packages are not yet in the official Debian repository, you can use the [http://bugs.debian.org/ bugtracking system] to file bugs against them, preferentially using the [http://packages.debian.org/stable/utils/reportbug reportbug] program. We will find them, and eventually the packages will be added to the repository and the bugs will apply to them.

The first time you use [http://packages.debian.org/stable/utils/reportbug reportbug], please configure it with:

reportbug --configure

Be sure to select a working [http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol SMTP server], most of the ISPs block outgoing traffic on the port 25, which results in the following error ([http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=488417 bug #488417]):

Submit this report on reportbug (e to edit) [Y|n|a|c|e|i|l|m|p|q|?]? y
Connecting to bugs.debian.org via SMTP...
SMTP send failure: (111, 'Connection refused')
Wrote bug report to /tmp/reportbug-reportbug-20080628-22940-UXH7BH

Before reporting any bug, please check if it has not been already submitted yet. All known bugs are listed [http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=pkg-fso-maint@lists.alioth.debian.org here]. It is always better to check each single package page, too. In case you have discovered a new bug, then submit it, but please:

Known Problems

Installing the FSO applications on your desktop

For development reasons, you might want to have the FSO applications available on your desktop. For that, add these lines to your sources.list:

deb http://pkg-fso.alioth.debian.org/debian unstable main
deb-src http://pkg-fso.alioth.debian.org/debian unstable main

and install the keyring:

apt-get update
apt-get install pkg-fso-keyring

Develop Applications for and on Debian

You can develop and test your applications for Debian on your desktop (just as you can run Zhone on your desktop, if you like). If the application is architecture-independent (such as a python application), you can just install that package on your FreeRunner. For architecture-dependent packages, you can compile clean packages using [http://packages.debian.org/sid/qemubuilder qemubuilder].

To build packages for armel with qemubuilder, you can use this setup (everything run as root)

Qemubuilder always starts from a clean base image and installs only build dependencies needed by the package that is being built. This is nice for repeatable builds but can be slow if you only need to make test many small changes or want to debug the builds process interactively. For this reason you might want to fetch a complete arm installation from e.g. http://people.debian.org/~aurel32/qemu/armel/.

Getting involved

Debian on the FreeRunner was brought to you by the pkg-fso team. We provide the phone-specific packages and created the installation script. If you have questions, you can contact us at

FAQ

See also