Aaron Williamson's webl

I’ve been working on developing a free software application market for Android.¹ The obvious place to start was the SlideME Community Edition code, which as far as I know is the only existing free software project that does even part of the job. Unfortunately, SlideME’s Community Edition was abandoned due to “lack of community interest” in April 2008, several months before the first Android phones were even available. So most of the work I’ve done so far was to update the code to work with the current SDK, rework the interface to behave in a more standard way, and rewrite portions that relied on now-unavailable API elements.

FLOSS Dispenser (like SlideME) works in conjunction with a J2EE server application called JVending. JVending’s public repository was also abandoned by SlideME some time ago, so I’m maintaining a fork of JVending along with my fork of FLOSS Dispenser as a part of the Replicant project.

I put up build instructions for FLOSS Dispenser as well as for JVending; using these, you should be able to build both and have them work together. However, neither one is ready, which is why I’m not hosting an application store already. The FLOSS Dispenser code in particular is pretty buggy (most of them aren’t mine, but only because I haven’t written much of it), for one thing. For another, the system doesn’t yet facilitate GPL compliance — you can download and install apk binaries, but they don’t come with source code and license text. Until at least this feature exists, I don’t recommend anyone serve GPL’d apks to the public using JVending. Update: The client application is now in a working alpha state. The really bad bugs have been hammered out and source can be delivered with the apk (the mechanism for this is nonoptimal, but functional). The challenge now is to enable users of the server to submit new apps easily, and to enable admins to moderate them.

I wanted to have this and some other issues hammered out before I put the code up, but I was motivated by Jonathan Corbet’s recent LWN article on Android to just put up what I had and try to get some help. I know other people are interested in something like this, and though I’m hardly proud of the little coding I’ve done on this, it’s the best start we have for a free market.

So by all means, take a look and help me kick this thing out the door.

1. The quick rationale for this is that the Android Market 1) is not itself free software, and 2) doesn’t enable you to search for applications by their license. [↩]

Note: these instructions may be out of date.  Consider trying whatever instructions are posted on the Android-on-Freerunner page at openmoko.org.

I got Android working (as far as it goes) on my Freerunner using Sean McNeil’s kernel and filesystem images.¹  These instructions are intended for the average Ubuntu users who wants to see the magic of Android on his/her phone with as little futzing about as possible.

Step 1: Partition your MicroSD card

You need to put a FAT (DOS) partition and an ext2 (or ext3) partition on your MicroSD card in order for Android to boot properly.  If it’s possible to do this by plugging your Freerunner into USB, I don’t know how.  So you will need some other way of reading your MicroSD card with your PC, for example a MicroSD to SD adapter (if your PC has an SD card reader built in) or a MicroSD to USB adapter.  Once you have one of these…

1. Insert your MicroSD card into your card reader, and your card reader into your PC.
2. If there is a filesystem on your MicroSD card already, it may auto-mount.  You must unmount the drive(s) on the card before proceeding.  You can do this either through Nautilus (right-click the drive and click “Unmount”) or from the command prompt:sudo umount /path/to/disk/²

   Partitions (old or new) may remount themselves after you add or remove them using fdisk (below). If so, you will have to unmount those as well.

3. Run fdisk: sudo fdisk /dev/[device number]

• Enter “p” to display existing partitions and their sizes.
• For each existing partition, enter “d” and then the partition number to delete it.
• Enter “p” again to make sure there are no partitions left on the card, and note the total number of cylinders on the card.
• Create the first partition: enter “n” (new partition), then “p” (for a primary partition), then “1″ (for the first partition), then “1″ (start at the first cylinder), then enter half of the total number of cylinders (to make the first partition half the size of the card).
• Create the second partition:³ enter “n” (new partition), then “p” (for a primary partition), then “2″ (for the second partition), then accept the defaults for the start and end cylinders.
• Enter “p” to make sure that both of your partitions have been created.  If they have not, make sure you have unmounted all of the existing partitions and add any missing partition according to #7 and/or 8 above.
• Enter “w” to write the partition table, then “q” to quit.

1. Create filesystems on the new partitions:

• sudo mkfs.vfat /dev/[first partition device number]
• sudo mkfs.ext3 /dev/[second parition device number]

1. If any of the new partitions are mounted, unmount them (see #2 above).
2. Put the MicroSD card and battery back into your Freerunner and close it up.

Step 2: Download the firmware image files

Android requires three image files: the kernel, the root filesystem, and the bootloader.⁴  For now, the best kernel and rootfs images to use are those packaged by a developer named Sean McNeil.  The latest files can be found here.  I provide links to the existing images below, but the filenames may change.  The Qi bootloader image is packaged by a user named Andy and is available here (for Android, use the file that begins “qi-s3c2442-”).  Again, the names and locations of these files may change as development progresses, so if these links break, just seek out the most recent files.

1. Download the kernel
2. Download the root filesystem
3. Download the Qi bootloader

Step 3: Download and set up the “neotool” flash utility and dfu-util

NeoTool is a handy, lightweight graphical tool for flashing images to your Freerunner’s memory.  It uses a command-line utility called dfu-util to do this, so you’ll need that too.

1. Download the NeoTool script (this is just a text file, so you may want to right-click and “Save Link As…”)
2. Download dfu-util
3. Make both files executable—from the command line, navigate to the directory where you downloaded them and enter: chmod +x neotool dfu-util
4. Run NeoTool—in the same directory, enter: sudo ./neotool
5. In the NeoTool menu, select “Setup NeoTool”, then “Locate dfu-util”.  Find dfu-util on your drive and click “OK”.  Click “OK” again to return to the main NeoTool menu.

Step 4: Flash the images to your Freerunner with NeoTool

Now we will load the images into your Freerunner’s memory.

1. Make sure your Freerunner has a decent charge in its battery, is turned off, and is disconnected from your PC.
2. Boot the Freerunner into its NOR boot menu: while holding down the AUX (side) button on your Freerunner, press and hold the power button until a menu appears.⁵
3. Attach the Freerunner to your PC via USB.
4. From the NeoTool menu, select “Flash your Neo”.
5. Select “Root-Filesystem”, “Kernel”, and “Bootloader” from the list.
6. NeoTool will ask you to locate the image file for the Root FS first.  Locate the file (androidfs.jffs2) on your drive, select it, and click “OK”.
7. Next, do the same for the kernel (uImage-android).
8. Next, do the same for the Bootloader (NeoTool will ask you for UBOOT even though we are using Qi).
9. Click “OK” through the scary message.
10. Wait for NeoTool to finish flashing the firmware (you can follow the progress in the terminal from which you started NeoTool).
11. When NeoTool has finished doing its thing, press the AUX button on your Freerunner until “Power off” is highlighted.  Press the power button to select it and power down your Freerunner.
12. Unplug your Freerunner from USB power.

Step 5: Boot into Android

1. Hold down the Freerunner’s power button until the screen’s backlight turns on (the screen will still be black) and then for a few seconds more.
2. Release the power button and wait for Android to load.
3. Android loads!  Hurrah!  This is way better than Om2008!  It found my network!  Calling works!
4. Oh look, it’s going into suspend.  Wait, why does it look like nuclear winter?  Why is the screen white?  Why doesn’t the power button do anything?  I guess I’ll take out the battery.  (NB: suspend doesn’t work yet.)

I hope this helps someone.  Feel free to send/post feedback.

1. Despite the Freerunner’s agonizing early history, there is still a very active community developing and testing the platform, and though none of the many distributions available for the platform are ready for primetime, that community has actually accomplished a lot.  Unfortunately, relatively little effort is dedicated to “bringing up the rear,” i.e. explaining clearly to less sophisticated users how to do all of the fun stuff the hardcore developers are doing.  Sean McNeil’s kernel and filesystem images go a long way toward making Android accessible to the average user, but his instructions for installing them do not work for me, and I couldn’t find any that did.  I pieced together these from 3 or 4 different sources, none of which contained the whole answer.  I hope they’ll be useful to someone. [↩]
2. When I mounted the MicroSD card using an SD adapter, it mounted as /dev/mmcblk0 and I unmounted the drives using: sudo umount /dev/mmcblk0p*. When I used a USB adapter, it mounted as /dev/sdb and I unmounted the drives using sudo umount /dev/sdb*. Yours may mount differently. Be careful that you have correctly identified the SD card and not some other more important drive on your computer. [↩]
3. Again, you may need to unmount the first partition before you can do this. [↩]
4. Supposedly you can use the default bootloader, u-boot, to load Android if you modify its environment to allow for larger kernels.  I tried this several times and was unsuccessful.  I have had no issues using Qi and it is reportedly faster. [↩]
5. This menu will only be displayed for 30 seconds, and then the phone will turn off again.  If this happens before you begin flashing the firmware, just repeat this step. [↩]