Installing and Using Debian on an OpenMoko Neo1973

You can install Debian on your OpenMoko Neo1973, 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.


This installer is based on the FreeRunner installer version (here). It's 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. Indeed, I recomend installing Debian on your Neo1973 this way.

At the moment, only the 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.


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 Neo1973 with network access (USB) 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 Neo1973:

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 233MHz). To restore, run the following from your backup server:

dd if=sdcard.tgz | gzip -d | ssh root@neo1973.address dd of=/dev/mmcblk0

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


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, I have only test the installation with one of the first uBoot released in 2007-08, so you should not have any problem with newer versions. Ensure that your Neo1973 is connected to the Internet via USB.

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

(it says it is for freerunner in first comment; that's a simple oversight AFAICT. If it fails to download cdebootstrap (it currently does), edit the script to download latest version. Old one does not exist on the server. Hmm, oops, it tries to pull non-existent kernel from

$ chmod +x
$ ./
Auto-Installer for Debian on the Openmoko Neo1973 (GTA01) v1.0
Copyright 2008 Joachim Breitner <>
Copyright 2008 Luca Capello <>
Modified for Neo by Juan Cañete <>
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 ...] ./ stage1 [stage2 ...]
  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, this script only works with this type)
  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
  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)
  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 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
  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

For more information, go to ["DebianOnNeo1973"]

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

$ ./ all

or, to use a mirror of your choice

$ INST_MIRROR= ./ all

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

The filesystem created by for the boot partition is ext2. In the next sections we will configure uBoot to be able to load an ext2 boot partition.

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:

./  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 configures dash as the default shell (i.e. /bin/sh). If you still prefer bash as /bin/sh, either do this by running DASH_BINSH=false ./ all at installation time or, once Debian is running, with dpkg-reconfigure dash.

At this point, if you want to run Debian from the !Neo1973's internal flash instead of the uSD card, see ?/MovingToFlash (I haven't tested that on Neo1973 because the image was bigger than the flash capacity so I can't say it works)

Adjusting your uBoot environment

The installation script doesn't modify the uBoot environment automatically, because I don't have a debug board in case of earthquake and don't have so much knowledge about uboot. So The modifications here are done manually.

First, you have to shutdown your Neo. Connect to it through ssh (you should be connected alredy) and shutdown.

Second, enter in the bootloader prompt by pressing the AUX button and the power button at the same time and connecting to the Neo through the USB port. If you don't know how to enter the bootloader prompt see this

Once you are in the bootloader prompt, you have to change the value of the variable menu_4, which is, in my case, the one used to boot from uSD card. To see the values of the variables type:

GTA01Bv4 # printenv

You will see the value of the variable menu_4. We must modify this value to the following so that the system can boot from uSD card. To modify the value type:

GTA01Bv4 # setenv menu_4 Boot Debian Boot: setenv bootargs \${bootargs} root=/dev/mmcblk0p2 rootdelay=5 \${mtdparts} ro\; mmcinit\; ext2load mmc 0 0x32000000 uImage.bin\; bootm 0x32000000

After that type printenv again to see if the changes have been applied. If you navigate through the bootloader prompt pressing the AUX button you should see that the menu that loads from uSD card has been rename to "Boot Debian Boot", in the setenv section you can name like you want.

Now, to apply the changes permanently you must type the following, but I recommend youdon't save the changes unless you have boot once using this method and you have tested that boots ok, then repeat the steps of this section and save using:

GTA01Bv4 # saveenv

To boot into Debian as default you may use.

GTA01Bv4 # setenv bootcmd setenv bootargs rootfstype=ext2 root=/dev/mmcblk0p2 quiet rootdelay=5 \${mtdparts} ro\; mmcinit\;ext2load mmc 0 0x32000000 uImage.bin\; bootm 0x32000000

Remember to saveenv if you want to keep settings.

You may remove the quiet if you want you default boot up to be more verbose

Using your Debian system

To Boot your Debian system choose "Boot Debian Boot" 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.


The alsa state files that are distributed with Debian don't work on the 1973, only on the freerunner. Following these instructions will put the right files (originally from here) in place:

cd /usr/share/openmoko/scenarios/
tar xvfz alsa_state_files-working1973.tar.gz

Then restart frameworkd:

/etc/init.d/fso-frameworkd stop
/etc/init.d/fso-frameworkd start

Frameworkd will now change the alsa states depending on whether one is entering or exiting a call, using headphones, etc.


Install gllin v1.1 on your handheld. You'll have to extract it from the ipkg at

Copy /usr/share/doc/fso-frameworkd/examples/frameworkd.conf to /etc and then modify the ogpsd section:

device = NMEADevice
channel = GllinChannel
path = /etc/init.d/gllin

then restart frameworkd.