WARNING: This is still a preliminary version, which will take some more days until it has all the updates.

This is a guide describing how to set up a running OpenMoko
system from scratch.

If you just want to run OpenMoko applications on your PC, just perform the
"Obtaining OpenMoko SVN tree" step below and then go to
How to run OpenMoko Apps on PC. If you want to autoinstall all required tools and resources, consider using MokoMakefile -- script developed by Rod Whitby.

Do not treat this as a linear script! There are various configuration items you
need to set (or skip, as it may be), operations that depend on how your
host(s) is/are set up, and also on the hardware revision of the target platform
(i.e., the phone).

Instead, look at each step, read the instructions, copy and paste what
makes sense for you, and adapt what you disagree with. Links to original and
background material in the Wiki are included wherever useful.

Preparation

Roles

The build process may spread over multiple machines. They have the following
roles:

BUILD

build host, with quick access to the files and CPU power. Must have Internet access.

LAB

lab machine connected to the debug board (serial and JTAG) and to USB on the Neo (since this will probably be just a single machine, the roles are not further divided)

CARD

machine with a USB-attached SD/MMC card reader

All machines are assumed to share the same filesystem layout. At the beginning of
each of the sections below, the respective role is indicated. "(all)" is for
settings that apply to all machines, or that - for simplicity - can be
applied to all of them.

cards inserted in the SD/MMC card reader appear as /dev/uba on CARD and can be mounted on /mnt/tmp (we'll specify the mount point explicitly, so the directory has to be there, but we don't need to specify the mount point in /etc/fstab). If in doubt,

mkdir -p /mnt/tmp

Obtaining Sources and build system

OpenEmbedded build: initial downloads

First, we obtain a snapshot of the OpenEmbedded-based tree used by OpenMoko, plus the OE build tool called BitBake.

Obtaining OpenMoko SVN tree

(Role: BUILD)

Obtain the latest revision of the OpenMoko tree. Unfortunately, at some places, "current" versions of upstream packages may get included, thus the build may still fail. If it does, you may wish to inform the authorities.

The checkout should take about 45 minutes over an Internet connection with a round-trip time to svn.openmoko.org of 350 ms.

cd $OMDIR
svn co http://svn.openmoko.org/ openmoko

NOTE: If the local user name does not match the user name with which you access SVN, you can put your username in the url you use to checkout:

svn+ssh://joe@stuff.org/svn/stuff

Installing BitBake

(Role: BUILD)

Install version 1.6 of BitBake, the build tool of OE. (This is quick.)

Obtaining OpenEmbedded snapshot

(Role: BUILD)

Obtain a snapshot of the Monotone repository of OpenEmbedded, then update it
to the latest version, and finally check out our "known to be good" revision.
We extract things into $OMDIR/openembedded. OE.mtn.bz2 is about 100 MB.

Note that the build will stop several times to ask for SVN access and whether
to accept certificates. If you're not quick enough to respond, the underlying
session may time out. In this case, just restart "bitbake
openmoko-devel-image" and it will pick up from where it left off.

The whole build process involves numerous downloads, takes about 7 hours
on an Athlon 64 3200+ (about 1.5h of delays were caused by ftp.debian.org not
working properly during this test run), and ends with a message like this:

Build statistics:
Attempted builds: 4

Installation

Flash boot loader into NAND

(Role: LAB)

As a first step, we transfer the u-boot bootloader into NAND Flash, through
the JTAG interface. We use JTAG, since this is the most basic way for doing
this, ensuring that we only depend on as little to work on the Neo as
possible.

For this, the u-boot image for the right board version and the desired
build date must be chosen. E.g., an image built for a gta01bv2 board on
February 3, 2007 at 13:40:41 would be called
u-boot_nand-gta01bv2-20070203134041.bin

Copy kernel and root FS to microSD card

(Role: CARD)

There are several ways to provide the Neo with its kernel and the root file
system. (See Bootloader for some of them.)
The most self-contained way is to put everything into NAND Flash.
To transfer the files to the Neo, we first place them on the microSD card.

Memory cards, including microSD, usually come pre-formatted with VFAT. We
prefer ext2 (e.g., because we may want to store a real Linux file system on the
card as well). The following steps are needed to convert the card from VFAT to
ext2:

Now, insert the microSD card into the Neo, but don't power it on yet.
(If you did anyway, don't worry. We'll power cycle it later.)

Serial console

(Role: LAB)

We use a serial console connecting through the debug board. This example uses
"xc", which is a small and simple communications program. Many people prefer
"cu" or the considerably more bloated "minicom", which will work as well.

Prepare xc configuration

cat <<EOF >$HOME/xc.init
set bps 115200
terminal
EOF

Connect to the target

xc -l /dev/ttyS0 -t

Start the Neo and enter the boot prompt

(Role: LAB)

Our first interaction with the target. If this doesn't work, please check
that the debug board is connected properly to the serial port.

Disconnect power and USB from the phone, wait a couple of minutes, then connect power.
You may have to press and hold the power button on the Neo for a few seconds to turn it on.
The power button is located next to the USB port.

Some people have observed stability issues if the device was reset without
power cycling or if USB was not disconnected when power cycling, yet details of what is really happening aren't very clear yet.

Note that the boot prompt changes with the hardware revision you have. If the
message does not appear after a few seconds, try power cycling again.

If xc responds to pressing a button with
"Verify that you are trying to use a valid and operational tty port."
the port may be stuck, waiting for DCD to be asserted. The quickest way to
get out of this situation is to disconnect the serial cable from the debug
board, run the following command

while ! stty -F /dev/ttyS0 clocal; do : ; done

stick something metallic, e.g., a paper clip or a screwdriver, into the plug on the cable,
and keep on fumbling with
it until DCD gets set and the loop above stops spitting out error messages.

Flash kernel and root FS into NAND

(Role: LAB)

We now load the kernel and the root FS from the microSD card into memory and
subsequently transfer them to NAND Flash. All this is done by entering
commands at the boot prompt.

Each time we want to write new data to the NAND Flash, we first have to erase
the previous content. We do this individually for each partition. While it would
also be possible to erase some or all relevant partitions in one step, this would
require the user to look up addresses from the partition table and to perform
calculations which are inconvenient at best.

Configure the boot loader

(Role: LAB)

Last but not least, we have to set up the boot loader to automatically boot
from Flash. For this, we use the default environment settings, which we obtain
by erasing the old content of the environment, and letting u-boot restore the
settings after a restart.

WARNING: This is still a preliminary version, which will take some more days until it has all the updates.

This is a guide describing how to set up a running OpenMoko
system from scratch.

If you just want to run OpenMoko applications on your PC, just perform the
"Obtaining OpenMoko SVN tree" step below and then go to
How to run OpenMoko Apps on PC. If you want to autoinstall all required tools and resources, consider using MokoMakefile -- script developed by Rod Whitby.

Do not treat this as a linear script! There are various configuration items you
need to set (or skip, as it may be), operations that depend on how your
host(s) is/are set up, and also on the hardware revision of the target platform
(i.e., the phone).

Instead, look at each step, read the instructions, copy and paste what
makes sense for you, and adapt what you disagree with. Links to original and
background material in the Wiki are included wherever useful.

Preparation

Roles

The build process may spread over multiple machines. They have the following
roles:

BUILD

build host, with quick access to the files and CPU power. Must have Internet access.

LAB

lab machine connected to the debug board (serial and JTAG) and to USB on the Neo (since this will probably be just a single machine, the roles are not further divided)

CARD

machine with a USB-attached SD/MMC card reader

All machines are assumed to share the same filesystem layout. At the beginning of
each of the sections below, the respective role is indicated. "(all)" is for
settings that apply to all machines, or that - for simplicity - can be
applied to all of them.

cards inserted in the SD/MMC card reader appear as /dev/uba on CARD and can be mounted on /mnt/tmp (we'll specify the mount point explicitly, so the directory has to be there, but we don't need to specify the mount point in /etc/fstab). If in doubt,

mkdir -p /mnt/tmp

Obtaining Sources and build system

OpenEmbedded build: initial downloads

First, we obtain a snapshot of the OpenEmbedded-based tree used by OpenMoko, plus the OE build tool called BitBake.

Obtaining OpenMoko SVN tree

(Role: BUILD)

Obtain the latest revision of the OpenMoko tree. Unfortunately, at some places, "current" versions of upstream packages may get included, thus the build may still fail. If it does, you may wish to inform the authorities.

The checkout should take about 45 minutes over an Internet connection with a round-trip time to svn.openmoko.org of 350 ms.

cd $OMDIR
svn co http://svn.openmoko.org/ openmoko

NOTE: If the local user name does not match the user name with which you access SVN, you can put your username in the url you use to checkout:

svn+ssh://joe@stuff.org/svn/stuff

Installing BitBake

(Role: BUILD)

Install version 1.6 of BitBake, the build tool of OE. (This is quick.)

Obtaining OpenEmbedded snapshot

(Role: BUILD)

Obtain a snapshot of the Monotone repository of OpenEmbedded, then update it
to the latest version, and finally check out our "known to be good" revision.
We extract things into $OMDIR/openembedded. OE.mtn.bz2 is about 100 MB.

Note that the build will stop several times to ask for SVN access and whether
to accept certificates. If you're not quick enough to respond, the underlying
session may time out. In this case, just restart "bitbake
openmoko-devel-image" and it will pick up from where it left off.

The whole build process involves numerous downloads, takes about 7 hours
on an Athlon 64 3200+ (about 1.5h of delays were caused by ftp.debian.org not
working properly during this test run), and ends with a message like this:

Build statistics:
Attempted builds: 4

Installation

Flash boot loader into NAND

(Role: LAB)

As a first step, we transfer the u-boot bootloader into NAND Flash, through
the JTAG interface. We use JTAG, since this is the most basic way for doing
this, ensuring that we only depend on as little to work on the Neo as
possible.

For this, the u-boot image for the right board version and the desired
build date must be chosen. E.g., an image built for a gta01bv2 board on
February 3, 2007 at 13:40:41 would be called
u-boot_nand-gta01bv2-20070203134041.bin

Copy kernel and root FS to microSD card

(Role: CARD)

There are several ways to provide the Neo with its kernel and the root file
system. (See Bootloader for some of them.)
The most self-contained way is to put everything into NAND Flash.
To transfer the files to the Neo, we first place them on the microSD card.

Memory cards, including microSD, usually come pre-formatted with VFAT. We
prefer ext2 (e.g., because we may want to store a real Linux file system on the
card as well). The following steps are needed to convert the card from VFAT to
ext2:

Now, insert the microSD card into the Neo, but don't power it on yet.
(If you did anyway, don't worry. We'll power cycle it later.)

Serial console

(Role: LAB)

We use a serial console connecting through the debug board. This example uses
"xc", which is a small and simple communications program. Many people prefer
"cu" or the considerably more bloated "minicom", which will work as well.

Prepare xc configuration

cat <<EOF >$HOME/xc.init
set bps 115200
terminal
EOF

Connect to the target

xc -l /dev/ttyS0 -t

Start the Neo and enter the boot prompt

(Role: LAB)

Our first interaction with the target. If this doesn't work, please check
that the debug board is connected properly to the serial port.

Disconnect power and USB from the phone, wait a couple of minutes, then connect power.
You may have to press and hold the power button on the Neo for a few seconds to turn it on.
The power button is located next to the USB port.

Some people have observed stability issues if the device was reset without
power cycling or if USB was not disconnected when power cycling, yet details of what is really happening aren't very clear yet.

Note that the boot prompt changes with the hardware revision you have. If the
message does not appear after a few seconds, try power cycling again.

If xc responds to pressing a button with
"Verify that you are trying to use a valid and operational tty port."
the port may be stuck, waiting for DCD to be asserted. The quickest way to
get out of this situation is to disconnect the serial cable from the debug
board, run the following command

while ! stty -F /dev/ttyS0 clocal; do : ; done

stick something metallic, e.g., a paper clip or a screwdriver, into the plug on the cable,
and keep on fumbling with
it until DCD gets set and the loop above stops spitting out error messages.

Flash kernel and root FS into NAND

(Role: LAB)

We now load the kernel and the root FS from the microSD card into memory and
subsequently transfer them to NAND Flash. All this is done by entering
commands at the boot prompt.

Each time we want to write new data to the NAND Flash, we first have to erase
the previous content. We do this individually for each partition. While it would
also be possible to erase some or all relevant partitions in one step, this would
require the user to look up addresses from the partition table and to perform
calculations which are inconvenient at best.

Configure the boot loader

(Role: LAB)

Last but not least, we have to set up the boot loader to automatically boot
from Flash. For this, we use the default environment settings, which we obtain
by erasing the old content of the environment, and letting u-boot restore the
settings after a restart.