Developer Preview editions of the Firefox OS phone are now becoming widely available to the community, mainly through Geeksphone. Since these are for developers, naturally we want to encourage you to tinker and play with them as much as possible!

In this post we will cover some basic tips on how to keep your phone up to date and how to tweak the system Gaia applications.

Updating your Geeksphone to the latest images

Firefox OS updates can be be downloaded from within the Settings app, listed under Device information. The phone can be set to check for updates daily, weekly or monthly. In addition a “check now” button is provided. When an update is available you will be prompted to download and install the current version.

The team at Geeksphone is also now providing the latest stable and nightly builds as self contained downloads for flashing your phone. Before proceeding make you have setup your phone as described in “Setting Up the Geeksphone Device” section of the Pushing Firefox OS Apps to the Geeksphone post. This will insure that you can push data to the phone.

The builds are located at the Geeksphone download site. On this site you will be presented with options for selecting your device and what type of build you want to use.

Download your particular build and extract the archive to your filesystem. The archive contains the images and commands required to flash the phone using Windows, Mac OS X or Linux. Before attempting to flash the phone make sure that you have enabled Remote debugging on the phone. This option can be set by launching the Settings app and navigating to the Device information -> More information -> Developer tab. Also do not attempt to flash the phone if the power level is below 50%.

Windows

Open a Command Prompt ( start -> type cmd in search -> enter on windows 7, Windows key + X -> select Command Prompt on Windows 8) and cd to the directory containing the extracted files. Run:

flash.bat

Mac OS X

Open a Terminal ( Cmd + space -> type terminal -> enter ) window and cd to the directory containing the extracted files. Run:

./flash_mac.sh

Updated Nov 12th 2013

There are some new steps you need to do before being able to run the command above:

You need to download Android SDK: it’s because you need tools like adb & flashboot. Unzip the file, and move it to the application folder: optionally, you can rename the folder to something like AndroidSDK (I’ll use AndroidSDK in next steps). Open (or create if it didn’t exists) ~/.bash_profile , and adds this line export PATH=${PATH}:/Applications/AndroidSDK/sdk/platform-tools – change AndroidSDK to reflect the SDK folder name you used in step 2.

Linux

Open a Terminal (control-alt-t on Ubuntu) window and cd to the directory containing the extracted files. Run:

./flash.sh

This should flash the new image to the phone. The phone will need to be setup again as all data will be cleared.

If you have an ‘unagi’ or developer preview phone that is not a Geeksphone

If you have a developer phone that is not a geeksphone such as an ‘unagi’ or a previously Android-based device, you may need to perform the following steps. If this is not you, please skip to the next section.

You will need to install adb and fastboot. These utilities can be found in the Android Developer Toolkit.

It is not necessary to install the entire toolkit. Download a the toolkit from here, and extract the contents. adb and fastboot are found in the /platform-tools/ folder. They can be copied to the /usr/bin of you Linux or Mac OS X machine, or copied to another folder as long as that folder is added to your $PATH.

If you are attempting to flash your device and have another device plugged in via USB, your phone may not be detected by these utilities correctly. Only have your phone plugged in while trying to flash it.

Tweaking Gaia

If you are of the industrious sort, you may want to tweak the default applications in Gaia – the UI in Firefox OS. In this section we will cover some of the basics for cloning Gaia and making changes to the default system apps. Bear in mind these tips are “at your own risk” and may involve you reading the later section “Ok, I bricked my phone”. Before proceeding make sure that you have adb and fastboot installed on your system. To verify if these are installed open a terminal and type adb devices with your phone connected. You should see you phone listed under the attached devices.

You should also be able to run fastboot from the terminal. If you run fastboot, a set of parameter options should be displayed. If you do not have adb or fastboot installed, a quick Google search with your operating system will return several quick starts on how to install them. In addition to adb and fastboot you will need Git. If you do not currently have Git installed have a look at this setup guide. Finally make sure your phone is setup for remote debugging as described in the previous section.

Once you have the prerequisites you can open a terminal and cd to the directory you would like to clone the Gaia source code to and type the following commands.

git clone git://github.com/mozilla-b2g/gaia.git gaia cd gaia

This will clone the current Gaia code to your system. If you plan on submitting changes back to the Gaia source, be sure to fork the source before cloning as described in Hacking Gaia. Currently the Geeksphone Keon uses the v1.0.1 branch of Gaia code, so set the proper branch using the following command.

git checkout -b v1.0.1 origin/v1.0.1

Most of the system apps are located in the apps subdirectory of gaia. You can now make any changes to these Firefox OS apps you wish. Once you have made changes run the following command to push the modified apps to your phone. This will by default push all the system apps to the phone:

B2G_SYSTEM_APPS=1 make install-gaia

If you only changed one of the apps you can specify the particular app using similar syntax. In this example only the calendar app will be pushed to the phone:

APP=calendar B2G_SYSTEM_APPS=1 make install-gaia

If you have issues while making the changes, you can reset the phone to default values using either of the following commands.

make production make reset-gaia

Note: Bear in mind that either of the above commands will clear any data or apps that you have pushed to the phone.

“Ok, I bricked my phone”

If you are in the process of modifying your phone and it becomes “unresponsive” you should be able to recover it using fastboot with a simple procedure. The following illustrates reseting the Keon but other phones should have a similar process. You will also need to verify that you have fastboot installed.

First remove the USB cable and then remove the battery from the phone for thirty seconds. Then reinsert the battery and press the volume down button while holding the power button for a few seconds. Next re-connect the usb cable and run the following commands from a terminal window in the directory that contains the latest img files described in the first section of this post.

fastboot flash recovery recovery.img fastboot flash boot boot.img fastboot flash userdata userdata.img fastboot flash system system.img fastboot reboot

This process should recover your phone.

Go play!

We hope these instructions are useful to you, and naturally we want you to be as happy about Firefox OS and the possibilities as we are! Feel free to play around with updating your devices, making changes/updates to Gaia apps and also to be inspired to take these learnings into building your own Open Web Apps.