Android on Freerunner

From Openmoko

Revision as of 14:51, 7 March 2009 by RzR (Talk | contribs)

Jump to: navigation, search


Contents

Freerunner-android-01.png

Introduction

This page is dedicated to the installation of Android (an Open Handset Alliance Project) on the Neo 1973 and Neo FreeRunner handsets.

You can find other information, such as porting, development and day to day usage here : Android

Before you start

Using this guide

  • 1

If you see a command like this, you must run it as root

#

If you see one like this, you can run it as a regular user

$
  • 2

When you see these commands

adb
dfu-util

it is assumed that you have them installed on your system and inside your /usr/bin. This may not be the case, you may just have downloaded the binary. If so, you need to change to the directory you downloaded the binary too then issue the same commands adding a ./ before it eg.

./adb
./dfu-util

adb connects to Android but you need to have made sure you have set it up first. Make sure your FreeRunner was booted while being plugged in to a USB port. Then following run the following commands:

# ifconfig usb0 192.168.0.200 netmask 255.255.255.0
# adb kill-server
# ADBHOST=192.168.0.202 adb devices

You should now have no trouble using adb.

Registering with the GSM network

Before you install Android on your FreeRunner you should check, using the operating system it came with, that your sim card will register with your network.

The version of internal GSM firmware that comes preloaded on the FreeRunner has compatibility issues with a feature on newer sim cards. This effects 3G, o2 sims and possibly others. if you have one of those you will probably need to upgrade your GSM firmware to get the sim to register with the network. Doing that first means you know it's working before you install Android.

GSM/Flashing

To flash your GSM firmware you will need to have USB networking setup between your desktop and the OM distribution installed on your FreeRunner. However, your FreeRunner does not need internet access as you can download the GSM firmware files on your desktop PC and transfer them to your FreeRunner using scp

USB Networking

Configuring the Bootloader

There are two bootloaders you can use to boot Android; Qi and Uboot. Uboot comes installed on the FreeRunner, Qi is a replacement and is thought to be superior. However there have been, and probably still are, problems when using Qi and Android so Uboot is recommended at this point.

You can download images for them both here:

Andy Tracking Images (For Qi on the FreeRunner grab the image starting qi-s3c2442)

The Android kernel image can be more than 2MB in size. The UBoot environment that comes with your FreeRunner is only able to boot a kernel 2MB in size or less. To use a kernel larger than 2MB you need to:

  • Change to the Qi Bootloader. It supports 2MB kernels out of the box.
setenv bootcmd setenv bootargs \${bootargs_base} \${mtdparts}\; nand read.e 0x32000000 kernel 0x300000\; bootm 0x32000000
saveenv

Installing Android on the Internal Flash

Preparing the SD Card

The SD Card in your FreeRunner needs to be configured with two 2 primary partitions before Android will boot. First a VFAT/MSDOS (16 or 32) which acts as the '/sdcard' storage area (for pictures, movies, music, etc). Second an ext3 primary partition which Android uses as '/data' with in which it stores settings, caches, etc.

On Linux

Insert the Mico SD Card from your FreeRunner into your Linux desktop then bring up a Terminal and type

   $ dmesg | grep sd

You will get an output like this, in this instance we can see that the SD Card has been assigned the device name 'sde'

   ...
   sd 9:0:0:0: [sde] Attached SCSI removable disk
   ...
   

Now, as root, use 'fdisk' to partition the device.

  # fdisk /dev/sde 

Pressing 'p' will show you the current partitions on the SD Card 'd' will delete them and 'n' will create a new one. Create a primary partition for your media. Then another primary partition for Android to store its data on.

On a 1Gig card I used 768MB for the first partition ('+768MB' in fdisk) and the remainder for Android data. Here is fdisk's partition output:

      Device Boot      Start         End      Blocks   Id  System
   /dev/sde1               1         769      750513+  83  Linux
   /dev/sde2             770        1016      241072   83  Linux

Now all that's left to do is format the partitions with the appropriate filesystem But first hit 'w' in fdisk to write the changes to the SD Card.

Then format like this:

   # mkfs.vfat -v -n and-media -F 32 /dev/sde1
   # mkfs.ext3 -v -L and-data /dev/sde2

That's it, you can now remove the SD card from your desktop. If you re-insert it you will have two new usb disk devices.

NOTE: After Android has booted you will only be able to access the 'data' partition as root.

There is no need to populate the ext3 partition at all. The VFAT partition can be populated with media content (ring tones etc.) if you so desire.

NOTE: It can be worth reformatting the data partition when you upgrade the Android OS on your phone. Old settings can result in problems, wifi for example. But remember that formatting the Data partition will result in your preferences, text messages and contacts etc. being erased.


On FreeRunner (2008.x)

The SD card can be formatted from within an existing 2008.x installation on your FreeRunner. SSH as root into the FreeRunner and use 'fdisk' to partition the device.

  # fdisk /dev/mmcblk0

After this create the partitions as described in the step above.

To format the new vfat partition you will need dosfstools which can be downloaded from

   dosfstools_2.11-r0_armv4t.ipk

Use any SCP client to copy this file to your FreeRunner and install using

   opkg install dosfstools_2.11-r0_armv4t.ipk

Once the installation is complete format the partitions:

   # mkfs.vfat -v -n and-media /dev/mmcblk0p1
   # mkfs.ext3 -v -L and-data /dev/mmcblk0p2

NOTE: In case you are unable to format the partitions because they are already mounted for some reason you can get a list of process IDs that are using it by running:

   # fuser -m /media/card

Then kill all the processes that were using the card and try formatting again.

On other OS's

There are no open source or free partition editors on Windows or Mac that can manage an ext3 partition. If you do not have Linux installed you can use the GParted bootable CD. This CD will boot into a graphical environment with which you can partition your SD Card. You may have to boot with the SD Card inserted for GParted to recognize it as a drive.

Downloading Android Images

Next, Grab yourself the latest Android images. There are two parts you need to flash, the kernel (uImage*.bin) and the root fs (android*.jffs2). Koolu release images and you can get them here:

   Release files (Android FreeRunner)

Koolu are not the only people working on porting Android to the FreeRunner and although collaboration is hopefully on the way, there are other places to get images:

Michael Trimarchi's (panicking) images are the most up to date and functional:

   Michael Trimarchi's images with latest fixes

Sean McNeil has placed an older 2.6.26 kernel and root fs at:

   Sean McNeil images

Flashing the FreeRunner

On Linux

To flash your FreeRunner, replace what ever phone stack you have on there at the moment with Android, first download dfu-util, this is the program that will flash your phone.

Once you have that installed (whether by simply downloading the binary or installing an rpm) Open up a terminal and cd to where you downloaded the images too eg.

   # cd /home/joe/Downloads

Plug your FreeRunner into a USB port and boot it into the nand boot loader; Hold down the aux button and then the power button until nor appears.

NOTE: The FreeRunner will only stay in in the nand bootloader state for about 30 seconds with no activity.

Now Flash the kernel image (you will need to be root) with this command:

   # dfu-util -a kernel -R -D uImage-moredrivers-GTA02.bin

and finally the root fs with this one:

   # dfu-util -a rootfs -R -D androidfs-koolu-beta3.jffs2
NOTE: The './' part assumes you are using the binary download and that it was downloaded to the same place as your images. If you are, remember to make the dfu-util binary executable.

If you find that dfu-util complains about there being more than one USB device available it might be because you have a webcam or some other device plugged in. If you can not remove the other device follow this procedure:

Unplug your FreeRunner and run the command

   # dfu-utils --list

This will list the other connected usb devices. Now plug your FreeRunner back in and run the command again, the new device will be your FreeRunner. You can now go ahead and flash with the added command '-d FREERUNNER_DEVICE' eg.

   # dfu-util -d 0x1d50:0x5119 -a rootfs -R -D freerunner-v13.jffs2

Installing Android on an SD card

Images

There are currently a few prebuilt images: Radek Polak's SD card images (install on ext3, first partition on SD must be FAT16)

Using jffs2 images

You can also boot from the SD Card using the pre built images like so :-

  • Mount the image using this script like so
  sudo ./Mntjffs.sh freerunner-v5.jffs2 image/
  • Then copy (cp -R) the files in directory image/ to any of the first three partitions on the SD Card (if using Qi) eg cp -R /your-path/image/* /media/android/
  • cd /media/android.
  • wget http://activationrecord.net/radekp/openmoko/android/init.rc .
  • mkdir boot
  • copy the kernel here and name it uImage-GTA02.bin


Some notes about booting android from sdcard :

Setup

  • Build android from source. See koolu website for directions.
  • Use the first script in this mail (adapt to your filesystem) to stage your android install.
  • copy the contents of this directory on a ext3 partition on your sdcard.
  • add a /boot directory on your sdcard.
  • copy the uImage-android kernel (see above) and copy it inside your /boot with the exact name uImage-GTA02.bin
  • I changed the init.rc (in your root on the sd) to remove mounts that could be problematic (/data for example) :
--- filesystem/root/init.rc	2008-12-15 17:51:14.000000000 +0100
+++ phyce.init.rc	2008-12-19 15:56:25.000000000 +0100
@@ -24,7 +24,7 @@
     mkdir /sqlite_stmt_journals 01777 root root
     mount tmpfs tmpfs /sqlite_stmt_journals size=4m
 
-    mount rootfs rootfs / ro remount
+    mount rootfs rootfs / rw remount
 
     write /proc/sys/kernel/panic_on_oops 1
     write /proc/sys/kernel/hung_task_timeout_secs 0
@@ -38,14 +38,14 @@
 #    mount yaffs2 mtd@system /system ro remount
 
     # We chown/chmod /data again so because mount is run as root + defaults
-    mount ext3 /dev/block/mmcblk0p2 /data nosuid nodev
-    chown system system /data
-    chmod 0771 /data
+#    mount ext3 /dev/block/mmcblk0p2 /data nosuid nodev
+#    chown system system /data
+#    chmod 0771 /data
 
     # Same reason as /data above
-    mount yaffs2 mtd@cache /cache nosuid nodev
-    chown system cache /cache
-    chmod 0770 /cache
+#    mount yaffs2 mtd@cache /cache nosuid nodev
+#    chown system cache /cache
+#    chmod 0770 /cache
  • Install Qi on you NAND flash. You can still boot whatever distro you've got on internal flash using the NOR bootloader. You should try the magic file in /boot to show kernel messages.
  • boot the GTA02, and pray.


Remote access to Android (adb)

Although this is not technically part of installing Android it is very useful to have set up. Android Debug Bridge (adb) is a versatile tool that lets you manage the state of a device, in this case, your FreeRunner.

Some ways you can use adb include:

  • Run shell commands on the phone.
  • Copy files from your desktop to the phone and Vice-versa.

You can find out about it on the Android developers page and a page on this wiki Android debug bridge

However if you would just like a very quick getting started guide, read on. You can download a binary from here. Then if you like copy it to /usr/bin (and don't forget to make it executable).

First you must boot Android while it is plugged in to a USB port, you can unplug it and re-plug it all you like after that but for the USB connection to work it must be connected at boot time.

Next issue this command to set up USB networking...

# ifconfig usb0 192.168.0.200 netmask 255.255.255.0

Then this one because it helps make sure everything works nicely...

# adb kill-server

Followed by this to find your phone...

ADBHOST=192.168.0.202 adb devices
NOTE: Remember that if you didn't copy adb to /usr/bin you will need to run these commands from the directory you downloaded it too and put ./ in front of adb.

Now you are free to remotely connect to your Android phone, here are a couple of commands you might find useful

  • Copy a file to your SD card:
# adb push YOUR_FILE /sdcard/
  • Copy a log file from your phone to your computer:
 # adb logcat -d > android.log
  • If you just want to log in to the Android shell:
# adb shell

Troubleshooting

SD card won't mount

There should be a /sdcard directory on your FreeRunner, for some reason this does not always get created (the command is in the 'init.rc' but does not always work). To create the correct dir on your FreeRunner and so enable your SD card, do the following.

  • Plug your FreeRunner into a USB port, boot Android and then enter these commands:
# ifconfig usb0 192.168.0.200 netmask 255.255.255.0
# adb kill-server
# ADBHOST=192.168.0.202 adb devices
# adb shell mount -o remount,rw /dev/root /
# adb shell
# mkdir /sdcard
# exit
  • Then reboot your FreeRunner

See also

Personal tools


Contents

Freerunner-android-01.png

Introduction

This page is dedicated to the installation of Android (an Open Handset Alliance Project) on the Neo 1973 and Neo FreeRunner handsets.

You can find other information, such as porting, development and day to day usage here : Android

Before you start

Using this guide

  • 1

If you see a command like this, you must run it as root

#

If you see one like this, you can run it as a regular user

$
  • 2

When you see these commands

adb
dfu-util

it is assumed that you have them installed on your system and inside your /usr/bin. This may not be the case, you may just have downloaded the binary. If so, you need to change to the directory you downloaded the binary too then issue the same commands adding a ./ before it eg.

./adb
./dfu-util

adb connects to Android but you need to have made sure you have set it up first. Make sure your FreeRunner was booted while being plugged in to a USB port. Then following run the following commands:

# ifconfig usb0 192.168.0.200 netmask 255.255.255.0
# adb kill-server
# ADBHOST=192.168.0.202 adb devices

You should now have no trouble using adb.

Registering with the GSM network

Before you install Android on your FreeRunner you should check, using the operating system it came with, that your sim card will register with your network.

The version of internal GSM firmware that comes preloaded on the FreeRunner has compatibility issues with a feature on newer sim cards. This effects 3G, o2 sims and possibly others. if you have one of those you will probably need to upgrade your GSM firmware to get the sim to register with the network. Doing that first means you know it's working before you install Android.

GSM/Flashing

To flash your GSM firmware you will need to have USB networking setup between your desktop and the OM distribution installed on your FreeRunner. However, your FreeRunner does not need internet access as you can download the GSM firmware files on your desktop PC and transfer them to your FreeRunner using scp

USB Networking

Configuring the Bootloader

There are two bootloaders you can use to boot Android; Qi and Uboot. Uboot comes installed on the FreeRunner, Qi is a replacement and is thought to be superior. However there have been, and probably still are, problems when using Qi and Android so Uboot is recommended at this point.

You can download images for them both here:

Andy Tracking Images (For Qi on the FreeRunner grab the image starting qi-s3c2442)

The Android kernel image can be more than 2MB in size. The UBoot environment that comes with your FreeRunner is only able to boot a kernel 2MB in size or less. To use a kernel larger than 2MB you need to:

  • Change to the Qi Bootloader. It supports 2MB kernels out of the box.
setenv bootcmd setenv bootargs \${bootargs_base} \${mtdparts}\; nand read.e 0x32000000 kernel 0x300000\; bootm 0x32000000
saveenv

Installing Android on the Internal Flash

Preparing the SD Card

The SD Card in your FreeRunner needs to be configured with two 2 primary partitions before Android will boot. First a VFAT/MSDOS (16 or 32) which acts as the '/sdcard' storage area (for pictures, movies, music, etc). Second an ext3 primary partition which Android uses as '/data' with in which it stores settings, caches, etc.

On Linux

Insert the Mico SD Card from your FreeRunner into your Linux desktop then bring up a Terminal and type

   $ dmesg | grep sd

You will get an output like this, in this instance we can see that the SD Card has been assigned the device name 'sde'

   ...
   sd 9:0:0:0: [sde] Attached SCSI removable disk
   ...
   

Now, as root, use 'fdisk' to partition the device.

  # fdisk /dev/sde 

Pressing 'p' will show you the current partitions on the SD Card 'd' will delete them and 'n' will create a new one. Create a primary partition for your media. Then another primary partition for Android to store its data on.

On a 1Gig card I used 768MB for the first partition ('+768MB' in fdisk) and the remainder for Android data. Here is fdisk's partition output:

      Device Boot      Start         End      Blocks   Id  System
   /dev/sde1               1         769      750513+  83  Linux
   /dev/sde2             770        1016      241072   83  Linux

Now all that's left to do is format the partitions with the appropriate filesystem But first hit 'w' in fdisk to write the changes to the SD Card.

Then format like this:

   # mkfs.vfat -v -n and-media -F 32 /dev/sde1
   # mkfs.ext3 -v -L and-data /dev/sde2

That's it, you can now remove the SD card from your desktop. If you re-insert it you will have two new usb disk devices.

NOTE: After Android has booted you will only be able to access the 'data' partition as root.

There is no need to populate the ext3 partition at all. The VFAT partition can be populated with media content (ring tones etc.) if you so desire.

NOTE: It can be worth reformatting the data partition when you upgrade the Android OS on your phone. Old settings can result in problems, wifi for example. But remember that formatting the Data partition will result in your preferences, text messages and contacts etc. being erased.


On FreeRunner (2008.x)

The SD card can be formatted from within an existing 2008.x installation on your FreeRunner. SSH as root into the FreeRunner and use 'fdisk' to partition the device.

  # fdisk /dev/mmcblk0

After this create the partitions as described in the step above.

To format the new vfat partition you will need dosfstools which can be downloaded from

   dosfstools_2.11-r0_armv4t.ipk

Use any SCP client to copy this file to your FreeRunner and install using

   opkg install dosfstools_2.11-r0_armv4t.ipk

Once the installation is complete format the partitions:

   # mkfs.vfat -v -n and-media /dev/mmcblk0p1
   # mkfs.ext3 -v -L and-data /dev/mmcblk0p2

NOTE: In case you are unable to format the partitions because they are already mounted for some reason you can get a list of process IDs that are using it by running:

   # fuser -m /media/card

Then kill all the processes that were using the card and try formatting again.

On other OS's

There are no open source or free partition editors on Windows or Mac that can manage an ext3 partition. If you do not have Linux installed you can use the GParted bootable CD. This CD will boot into a graphical environment with which you can partition your SD Card. You may have to boot with the SD Card inserted for GParted to recognize it as a drive.

Downloading Android Images

Next, Grab yourself the latest Android images. There are two parts you need to flash, the kernel (uImage*.bin) and the root fs (android*.jffs2). Koolu release images and you can get them here:

   Release files (Android FreeRunner)

Koolu are not the only people working on porting Android to the FreeRunner and although collaboration is hopefully on the way, there are other places to get images:

Michael Trimarchi's (panicking) images are the most up to date and functional:

   Michael Trimarchi's images with latest fixes

Sean McNeil has placed an older 2.6.26 kernel and root fs at:

   Sean McNeil images

Flashing the FreeRunner

On Linux

To flash your FreeRunner, replace what ever phone stack you have on there at the moment with Android, first download dfu-util, this is the program that will flash your phone.

Once you have that installed (whether by simply downloading the binary or installing an rpm) Open up a terminal and cd to where you downloaded the images too eg.

   # cd /home/joe/Downloads

Plug your FreeRunner into a USB port and boot it into the nand boot loader; Hold down the aux button and then the power button until nor appears.

NOTE: The FreeRunner will only stay in in the nand bootloader state for about 30 seconds with no activity.

Now Flash the kernel image (you will need to be root) with this command:

   # dfu-util -a kernel -R -D uImage-moredrivers-GTA02.bin

and finally the root fs with this one:

   # dfu-util -a rootfs -R -D androidfs-koolu-beta3.jffs2
NOTE: The './' part assumes you are using the binary download and that it was downloaded to the same place as your images. If you are, remember to make the dfu-util binary executable.

If you find that dfu-util complains about there being more than one USB device available it might be because you have a webcam or some other device plugged in. If you can not remove the other device follow this procedure:

Unplug your FreeRunner and run the command

   # dfu-utils --list

This will list the other connected usb devices. Now plug your FreeRunner back in and run the command again, the new device will be your FreeRunner. You can now go ahead and flash with the added command '-d FREERUNNER_DEVICE' eg.

   # dfu-util -d 0x1d50:0x5119 -a rootfs -R -D freerunner-v13.jffs2

Installing Android on an SD card

Images

There are currently a few prebuilt images: Radek Polak's SD card images (install on ext3, first partition on SD must be FAT16)

Using jffs2 images

You can also boot from the SD Card using the pre built images like so :-

  • Mount the image using this script like so
  sudo ./Mntjffs.sh freerunner-v5.jffs2 image/
  • Then copy (cp -R) the files in directory image/ to any of the first three partitions on the SD Card (if using Qi) eg cp -R /your-path/image/* /media/android/
  • cd /media/android.
  • wget http://activationrecord.net/radekp/openmoko/android/init.rc .
  • mkdir boot
  • copy the kernel here and name it uImage-GTA02.bin


Some notes about booting android from sdcard :

Setup

  • Build android from source. See koolu website for directions.
  • Use the first script in this mail (adapt to your filesystem) to stage your android install.
  • copy the contents of this directory on a ext3 partition on your sdcard.
  • add a /boot directory on your sdcard.
  • copy the uImage-android kernel (see above) and copy it inside your /boot with the exact name uImage-GTA02.bin
  • I changed the init.rc (in your root on the sd) to remove mounts that could be problematic (/data for example) :
--- filesystem/root/init.rc	2008-12-15 17:51:14.000000000 +0100
+++ phyce.init.rc	2008-12-19 15:56:25.000000000 +0100
@@ -24,7 +24,7 @@
     mkdir /sqlite_stmt_journals 01777 root root
     mount tmpfs tmpfs /sqlite_stmt_journals size=4m
 
-    mount rootfs rootfs / ro remount
+    mount rootfs rootfs / rw remount
 
     write /proc/sys/kernel/panic_on_oops 1
     write /proc/sys/kernel/hung_task_timeout_secs 0
@@ -38,14 +38,14 @@
 #    mount yaffs2 mtd@system /system ro remount
 
     # We chown/chmod /data again so because mount is run as root + defaults
-    mount ext3 /dev/block/mmcblk0p2 /data nosuid nodev
-    chown system system /data
-    chmod 0771 /data
+#    mount ext3 /dev/block/mmcblk0p2 /data nosuid nodev
+#    chown system system /data
+#    chmod 0771 /data
 
     # Same reason as /data above
-    mount yaffs2 mtd@cache /cache nosuid nodev
-    chown system cache /cache
-    chmod 0770 /cache
+#    mount yaffs2 mtd@cache /cache nosuid nodev
+#    chown system cache /cache
+#    chmod 0770 /cache
  • Install Qi on you NAND flash. You can still boot whatever distro you've got on internal flash using the NOR bootloader. You should try the magic file in /boot to show kernel messages.
  • boot the GTA02, and pray.


Remote access to Android (adb)

Although this is not technically part of installing Android it is very useful to have set up. Android Debug Bridge (adb) is a versatile tool that lets you manage the state of a device, in this case, your FreeRunner.

Some ways you can use adb include:

  • Run shell commands on the phone.
  • Copy files from your desktop to the phone and Vice-versa.

You can find out about it on the Android developers page and a page on this wiki Android debug bridge

However if you would just like a very quick getting started guide, read on. You can download a binary from here. Then if you like copy it to /usr/bin (and don't forget to make it executable).

First you must boot Android while it is plugged in to a USB port, you can unplug it and re-plug it all you like after that but for the USB connection to work it must be connected at boot time.

Next issue this command to set up USB networking...

# ifconfig usb0 192.168.0.200 netmask 255.255.255.0

Then this one because it helps make sure everything works nicely...

# adb kill-server

Followed by this to find your phone...

ADBHOST=192.168.0.202 adb devices
NOTE: Remember that if you didn't copy adb to /usr/bin you will need to run these commands from the directory you downloaded it too and put ./ in front of adb.

Now you are free to remotely connect to your Android phone, here are a couple of commands you might find useful

  • Copy a file to your SD card:
# adb push YOUR_FILE /sdcard/
  • Copy a log file from your phone to your computer:
 # adb logcat -d > android.log
  • If you just want to log in to the Android shell:
# adb shell

Troubleshooting

SD card won't mount

There should be a /sdcard directory on your FreeRunner, for some reason this does not always get created (the command is in the 'init.rc' but does not always work). To create the correct dir on your FreeRunner and so enable your SD card, do the following.

  • Plug your FreeRunner into a USB port, boot Android and then enter these commands:
# ifconfig usb0 192.168.0.200 netmask 255.255.255.0
# adb kill-server
# ADBHOST=192.168.0.202 adb devices
# adb shell mount -o remount,rw /dev/root /
# adb shell
# mkdir /sdcard
# exit
  • Then reboot your FreeRunner

See also