Installing and Using Debian on an OpenMoko FreeRunner
You can install Debian on your OpenMoko FreeRunner, and use that system to fulfill your telephone needs. You can then also 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 installation 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 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.
You can try the installation on the Neo1973, but at your own risk. You will most certainly have to adjust configuration parameters, but you can find correct values in the official FSO image for your device.
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 your power management is not set to suspend.
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 | dd of=sdcard.tgz"
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:
dd if=sdcard.tgz | gzip -d | ssh root@freerunner.address dd of=/dev/mmcblk0
As always, double check you have used the correct syntax for 'dd'.
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:
$ wget 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.0 ----------------------------------------------------------------- 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) Stages: all Runs all the stages in the following order: testing time partition 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 ntp.fu-berlin.de via rdate partition Partitions and formats the microSD card found in /dev/mmcblk0 (WARNING, this will destroy all the data on the microSD card) mount Mounts microSD card partitions under /mnt/debian 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 kernel image and modules unmount Unmounts the Debian filesystem mounted at /mnt/debian 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) For more information, go to http://wiki.debian.org/DebianOnFreeRunner
Please read this introduction to get an overview about what is going to happen. You can then run the installation with
$ ./install.sh all
or, to use a mirror of your choice
$ INST_MIRROR=http://ftp.cc.debian.org/debian ./install.sh all
Note that running 'all' involves 'partition' action mentioned above, which destroys all information on the SD card. You have been warned.
Default filesystem created by install.sh for the boot partition is ext2 and U-Boot needs boot partition is fat. You have two alternatives:
I) Modify your uBoot (as described chapter below), so it can boot straight on 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 default U-Boot setup.
Now be patient for a while, while 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.
The installation script configure [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:
Debian boots by default, from the MicroSD card, with an ext2 boot partition.
- The image installed in Flash can be booted by entering the NAND uBoot menu and selecting the second entry.
To run the script, you need:
- fso-utils, available from the pkg-fso apt source mentioned further down on this page installed on your local machine, not on your Freerunner (Section "Installing the FSO applications on your desktop")
- dfu-util installed, available from the regular Debian archive
FreeRunner booted into NOR-Flash and connected via usb. (See the [http://wiki.openmoko.org/wiki/Flashing_the_Neo_FreeRunner ?OpenMoko Wiki] for more information)
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.
Do not use this script with a device other than the FreeRunner!
Using your Debian system
Once the installation is complete the Debian System from SD-Card is booted by default. To Boot your normal system choose "Boot Flash" from uboot menu. After booting you should see 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.
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:
/UsbKeyboard: Use a USB keyboard.
Mount your partitions with relatime instead of noatime, if you use applications like mutt.
Install apmd. Then, zhone suspends the phone when you press POWER-BUTTON for more than a second. If it does not work, make sure that the apmd daemon is not started, there seems to be a strange bug with Xorg, apmd and the kernel
If you have fast internet connection "apt-get update" can spend considerable time applying pdiffs. You can skip pdiff processing with this command: apt-get update -o Acquire::PDiffs=false, or change the preference permanently by adding the line Acquire::PDiffs "false"; to the file /etc/apt/apt.conf (possibly by creating that file)
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.
When you submit a bug, please:
CC pkg-fso-maint@lists.alioth.debian.org . If you use the [http://packages.debian.org/stable/utils/reportbug reportbug] program, please use the X-Debbugs-CC pseudoheader instead.
mention that the package is not yet in the archive, to prevent confusion for the bugtracker admins, something like This package is not yet in Debian but it will be soon, please see http://wiki.debian.org/pkg-fso.
Known Problems
PIN entry, see http://trac.freesmartphone.org/ticket/90
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:
- Get qemubuilder v0.48 or newer.
Get a kernel from http://ftp.us.debian.org/debian/dists/sid/main/installer-armel/current/images/versatile/netboot/vmlinuz-2.6.24-1-versatile
Create a configuration file armel-rc with this content (adjust paths to your liking):
KERNEL_IMAGE=/var/cache/pbuilder/armel/vmlinuz-2.6.24-1-versatile ARCH=armel BASEPATH=/var/cache/pbuilder/armel/base.qemu MEMORY_MEGS=256 MIRRORSITE=http://mirror/debian
Run qemubuilder --configfile armel-rc --create
Run qemubuilder --configfile armel-rc --login --save-after-login and adjust the apt-sources (see above)
Run qemubuilder --configfile armel-rc --update
Build packages with qemubuilder --configfile armel-rc --build package.dsc
- Extra tip: If you copy armel-rc as ~/.pbuilderrc you don't need to specify "--build armel-rc" every time you use qemubuilder.
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
Mailing list: http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/smartphones-standards
- IRC channel: #openmoko-cdevel on freenode
WikiPage: ["Teams/DebianFSO"]
- IRC channel: #openmoko-debian on freenode (Discuss the installation of Debian ARM package on the Openmoko Freerunner)
FAQ
During the "debian" stage of the install, what does "E: Internal error: install" mean and how do I fix it? Please see the discussion at the [http://lists.linuxtogo.org/pipermail/smartphones-standards/2008-August/000344.html smartphones-standards] mailing list about some possible causes.
If you get error messages like unknown type 255 when accessing SMS or the contact book, you can add the number in question to /var/lib/python-support/python2.5/framework/subsystems/ogsmd/gsm/const.py, line 805, to the list in
phonebookTupleToNumber assert ntype in ( 129, 145, 208 ), "unknown type %i" % ntype
It wold be helpful if you then find out what kind of number that is and suggest at http://trac.freesmartphone.org/ that this number is added to the list.