Firefox OS at its Peak: Upgrading Gaia on Your Geeksphone

I received my Geeksphone Peak Firefox OS Developer device today. Firefox OS consists of two core parts:

  1. Boot2Gecko, which is essentially a Gecko rendering engine stapled on top of the Linux (Android) kernel
  2. Gaia, which is the HTML/JS/CSS front-end

The Geeksphones are aimed at developers, so you’ll want to live on the bleeding edge (and in this case: you really should). Out of the box the Geeksphones come with Gaia 1.0.1 installed, which is pretty old. There’s some significant improvement going on for 1.1. Here’s how you upgrade to the latest and greatest version of Gaia. I tested this on a Mac, I assume on Linux and perhaps Windows it works similarly. I own the Peak phone myself, but for the other models the steps should be the same (other than the HIDPI thing, which I’ll note later).



Make sure the Android SDK’s platform tools are on your path:

export PATH=<android-sdk-path>/sdk/platform-tools:$PATH

Then, enable remote debugging on your Firefox OS device:

Settings > Device information > More information > Developer > Enable “Remote debugging”

To verify this worked, in a terminal type:

adb devices

You should see something like this (at least one device):

List of devices attached
06af7088f488 device

In my case this worked fine, but steps failed. To be very sure that everything is ok, enter:

adb shell

You should now get a prompt that you can exit out of with Ctrl-D. If the prompt doesn’t load, try reconnecting the phone or rebooting it, then try again.

Next up: clone Gaia

git clone git://

If you have a Peak (which has a HiDPI screen), you may want to build Gaia in HiDPI mode (it’s also fun not to do this, you’ll get a lot more content on your screen that way):

export HIDPI=1

Then, to build and install (and reset your profile, which means your device is reset) — you don’t have to do this every time, but it’s a good idea to do this after a big upgrade:

make reset-gaia

For minor upgrades you can just:

make install-gaia

At this point your phone will ideally reboot by itself. In my case the whole system locked up, the only way to fix it was to pull the battery to restart it.

Done! You should now be running the latest and greatest bleeding edge Gaia (version 1.1 at the time of this writing).

Revert, revert!

In case stuff breaks, you can easily revert to an older version of Gaia. It’s just git, so: checkout an older branch, e.g.:

git checkout v1.0.1

and run make reset-gaia again.

I’m still working on upgrading the Boot2Gecko build on the phone, if I succeed I’ll post on how to do that later.

Thanks to Sergi Mansilla for his help with this.