How (not) to brick the Android Developer Phone

The path to exercising this freedom is long and poorly documented, though. Eventually somebody will certainly pull together a definitive resource for developers wanting to hack on their Android phones; until then, one is left digging through a long series of web sites and forums (a few of which are listed below). This article will not be that resource, but, hopefully, it can help to point interested people in the right direction. Please note that this article assumes that you have an ADP1 phone; if you have a locked-down G1 you can still participate in all of the fun and games that follow, but you will need to root the phone first.

The first stop, unfortunately, is the decidedly non-free Android SDK. Actually, this package is only truly mandatory for those wanting to build Android applications of their own. But it contains a pre-built version of the Android Debug Bridge (adb) tool, which is essential for working with the phone over a USB connection. With adb, one can connect to a shell running on the phone, move files back and forth, forward network ports to and from the phone, and more. Yes, one can run a shell directly on the device using the terminal emulator application, but life is certainly much easier when one can use a real keyboard.

Note that it may be necessary to either (1) run adb as root, or (2) play with your udev setup to be able to access the phone via USB.

Putting new software onto the phone involves flashing its NVRAM. There are six partitions on the onboard flash:

    dev:    size   erasesize  name
    mtd0: 00040000 00020000 "misc"
    mtd1: 00500000 00020000 "recovery"
    mtd2: 00280000 00020000 "boot"
    mtd3: 04380000 00020000 "system"
    mtd4: 04380000 00020000 "cache"
    mtd5: 04ac0000 00020000 "userdata"

Details about these partitions can be found on this page. Most of them will be fairly obvious in purpose. The "recovery" partition holds a recovery image which can be used to un-brick the phone. In "boot" is the initial system image, while "system" is the root filesystem. Application settings and such go into "userdata". With any luck at all, it should be possible to put a new system onto the phone by flashing only the "boot" and "system" partitions, leaving settings and such in place.

First, though, comes that sweaty-palms moment when one realizes that one is about to overwrite the operating software on an expensive new toy. A fairly nice new toy that, mostly likely, has become an important working tool. The idea of turning this nice device into an expensive brick lacks appeal. It might be different if the second-generation Android devices were available; then, at least, one could rationalize an update disaster as a celestial sign that it's time to get a newer phone. In the absence of such an ulterior motive, your editor stepped back from the brink and pondered ways to recover from a failed update.

[PULL QUOTE: Everybody should be able to run vi on their phone (though emacs appears to be a bit too much to hope for). END QUOTE] One method your editor has seen recommended is to simply make copies of the various /dev/mtd/mtd? devices, then use adb to lift those copies off the phone. The system running on the phone has a rather minimal command set, so this copying must be done using cat and shell redirection operators. This experience gives a quick thrill, as if one were reliving the very earliest days of Unix before advanced commands like cp had been invented, but said thrill is quick indeed. Thereafter, one usually wants to go out and install busybox on the device. After making a few strategic symbolic links, one will have something that looks a lot more like an ordinary Linux shell environment. Everybody should be able to run vi on their phone (though emacs appears to be a bit too much to hope for).

Back to backups: an alternative is to use the nandroid script. With nandroid, a simple command will back up all of the useful partitions on the device in a way which lets them be quickly restored. Unfortunately, though, nandroid will not work with a stock phone. At a minimum, one must install busybox, then make links for commands like nc, tar, and md5sum. Alternatively, one can install the modified recovery image from the amazingly productive "JesusFreke," then back up the phone while it is in recovery mode. Either way, one will, once again, end up with a set of image files containing copies of the phone's flash partitions.

So what does one do with these image files? The key tool here is fastboot, a command-line tool which runs on a Linux-based host system. With fastboot, one can flash one or more partitions to a USB-connected phone, then reboot into the new code. First, though, one must know the secret handshake: power up the phone while holding down the camera button, connect the USB cable, then hit the "back" button until the display reads "fastboot." Needless to say, the manual that came with the ADP1 did not mention this little detail.

Of course, said "manual" is a single slip of paper showing how to insert the battery.

Once one is convinced of one's ability to recover from a disaster, it's time to try to put some new software onto the phone. If you have built the Android platform from source (a process which will be addressed in the next installment), the result will be new "boot" and "system" images which can be flashed to the phone using fastboot. System images built by others can also take that form, but the more common approach is to package the whole thing up into a Zip file. In such cases, the recipe is as follows:

• Using adb, put the update image onto the SD card on the phone (mounted under /sdcard) as update.zip.

• Reboot the phone into recovery mode (secret handshake: hold down the "home" key while booting).

• Press alt l, followed by alt s. Note that, unlike ordinary ADP1/G1 keyboard operation, you need to actually hold down the "alt" key while pressing the associated letter.

This sequence will cause the phone to rewrite its software with the image found in the update.zip file. Once the process is complete, hitting the "home" and "back" buttons together will reboot the phone into the new image.

So, what might one install via this method? The set of modified images provided by JesusFreke are a good place to start. The JFv1.31 image makes a lot of things work more nicely; it includes busybox with a set of useful links, a fancier recovery image with built-in backup capability, a version of su which asks the user for confirmation (and which, thus, should be harder to exploit from an evil application), and more. Also worth noting is that the JF images disable any over-the-air updates. Such updates should not be happening with an ADP1 phone in any case, but, when one has control over one's own phone, there is no reason to allow outside agencies to drop new software into it.

Rather more fun can be had by going to the JFv1.43 image. This version includes an update from Android, which is said to fix a number of small issues and improve battery life. It adds a voice calling capability which was notably lacking in the original Android distribution. Your editor's first attempt, "call home," was turned into "call mom" though; Google does not appear (yet) to have achieved a level of omniscience sufficient to know that those two have not been synonymous for some years now. Also added is a voice search mechanism. But that's not all: this update includes the multitouch functionality that Google left out; the "pinch" gesture now zooms web pages in and out. Other applications have not yet been enhanced to use multitouch, yet.

Arguably even nicer than multitouch at this point is the new "autorotate" setting in the browser. The ADP1 can report its orientation to an application, but almost no applications make use of that information. So, on a stock ADP1, using the browser in landscape mode requires opening the keyboard. With autorotate turned on, the browser senses when the phone has been turned and adjusts the display accordingly. It's one of those little features which should have been there from the outset.

And that, of course, gets to the heart of why an open phone is such a nice thing to have. We're no longer dependent on the manufacturer to get everything right, and we're no longer dependent on wireless carriers to hold off from crippling our devices. We bought the hardware, and we wrote the software. We are well within our rights to change how it all works - even if we want to do something crazy like install Debian over Android. It is unfortunate that, at this time, so few devices afford this kind of freedom; ADP1 and OpenMoko appear to be about the only options. With any luck at all, awareness of the value of this freedom will spread over time, and vendors will find that their customers will settle for nothing less.

Of course, real freedom doesn't stop at the ability to install software images created by others. The next installment in this series will start to delve into the process of generating a new system image from source. Among other things, your editor intends to take the "cupcake" development version - which includes, among other things, the much-requested on-screen keyboard feature - for a spin. Stay tuned.

Resources. Information about working with Android is spread around the net; here are a few useful places your editor has found:

• There is, of course, good information to be found at source.android.com.

• developer.android.com is the source for the software development kit and related information.

• The xda-developers site is a repository for vast amounts of useful - if noisy and slowly-served - information. In particular, the Dream Android development forums seem to be the primary gathering point for people hacking on this platform.

• Some information - notably new pre-built image announcements - can be found on andblogs.net.