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 article we cover some basic tips on how to keep your phone up to date and how to tweak the system Gaia applications.
(Note that these instructions are for the older Keon and Peak, not necessarily the latest Geeksphone Revolution phone)
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.
Flashing your phone
The team at Geeksphone is also now providing the latest stable and nightly builds as self contained downloads for flashing your phone.
Set up your phone and computer
Before trying to flash your phone make sure you have set it up as described in the section “Setting Up the Geeksphone Device” in Pushing Firefox OS Apps to the Geeksphone. This will ensure that you can push data to the phone. In that same section, follow the instructions to make sure your computer has the right USB drivers.
Note: It is particularly important that Windows computers be set up with the right USB drivers.
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, 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
Note: You might need to install USB drivers on Windows. For instructions, see the section “Setting Up the Geeksphone Device” in Pushing Firefox OS Apps to the Geeksphone.
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
Open a Terminal (Cmd + space -> type terminal -> enter) window and cd to the directory containing the extracted files. Run:
./flash_mac.sh
Linux
To flash a Keon from Linux add the following rules to /etc/udev/rules.d/51-android.rules
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 set up again as all data will be cleared. If you want to backup your data and restore afterwards, you can follow the instructions at Backup the phone system partition.
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 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 your Linux or Mac OS 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 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 later referring to the 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 your 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 set up 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. 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 before you do anything else:
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, make sure your device is mounted properly by first running:
adb remount
Next, 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. If you want to backup your data and restore afterwards, you can follow the instructions at Backup the phone system partition.
"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 resetting 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 30 seconds. Then reinsert the battery and press the volume down button while holding the power button for a few seconds. Next reconnect 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. If it doesn't seem to work, you may have to try it a second time.
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, make changes/updates to Gaia apps, and also be inspired to build you own open web apps.