Updating and Tweaking your Firefox OS Developer Preview phone/Geeksphone

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:

  1. You need to download Android SDK: it’s because you need tools like adb & flashboot.
  2. 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).
  3. 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.

About Frédéric Harper

As a Senior Technical Evangelist at Mozilla, Fred shares his passion about the Open Web, and help developers be successful with Firefox OS. Experienced speaker, t-shirts wearer, long-time blogger, passionate hugger, and HTML5 lover, Fred lives in Montréal, and speak Frenglish. Always conscious about the importance of unicorns, and gnomes, you can read about these topics, and other thoughts at outofcomfortzone.net.

More articles by Frédéric Harper…

About Jason Weathersby

Jason Weathersby is a Technical Evangelist for Mozilla, evangelizing Firefox OS. He is also a committer on the BIRT project at the Eclipse Foundation, and has co-authored several books on BIRT integration. He is a proponent of HTML5, Open Source and all things related to web-based gaming.

More articles by Jason Weathersby…

About Robert Nyman [Editor emeritus]

Technical Evangelist & Editor of Mozilla Hacks. Gives talks & blogs about HTML5, JavaScript & the Open Web. Robert is a strong believer in HTML5 and the Open Web and has been working since 1999 with Front End development for the web - in Sweden and in New York City. He regularly also blogs at http://robertnyman.com and loves to travel and meet people.

More articles by Robert Nyman [Editor emeritus]…


31 comments

  1. Nicolas Hoizey

    What is the potential impact if I comment the “userdata.img” line in “flash_mac.sh” for daily update with nightly builds?

    June 19th, 2013 at 06:37

    1. Christian

      You would not lose your settings and data ;-)

      The Windows flash.bat file offers this option.

      June 19th, 2013 at 07:52

    2. Jason Weathersby

      Meaning you just want to use the nightly userdata? Userdata I believe mainly contains the system webapps, so I do not think that should be an issue. I have not tested that though.

      June 19th, 2013 at 08:02

      1. Nicolas Hoizey

        No, I want to update everything else, NOT my settings and installed apps.

        Or maybe would it be possible to script these things on any fresh install?

        June 19th, 2013 at 08:12

        1. Jason Weathersby

          That should be possible by removing the userdata from the script.

          June 19th, 2013 at 11:05

  2. Christian

    Thank you for sharing this!

    My Keon did not start with images-keon-2013-06-03.Gecko-08a0e76.Gaia-fcae236. After the Geeksphone logo the screen turns black.

    I then flashed nightly-images-keon-2013-06-18.Gecko-42ecd5c.Gaia-adca6e9 and now the startup stops at “based on mozilla technology”.

    Seems I need to undergo the “Ok, I bricked my phone” procedure … That helped — but I lost all my apps and setting ;-)

    Oh, and please remove the “EXIT” line from flash.bat. It closes the command window which is not always the desired behaviour.

    June 19th, 2013 at 06:42

    1. Jason Weathersby

      Thanks for the comment. I will pass it along to the team at Geeksphone.

      June 19th, 2013 at 08:04

  3. Will Eastcott

    Where can I get recovery.img from?

    June 19th, 2013 at 10:45

  4. Jason Weathersby

    Recovery.img should be in the GP download.

    June 19th, 2013 at 11:06

    1. Robert Nyman [Editor]

      It turns out that this is only in the current builds for the Keon, but not the Peak. Please contact Geeksphone for more information.

      June 19th, 2013 at 12:59

  5. Ankit Bahuguna

    I need some information on how to backup contacts and other personal settings from Keon. Is there an app for it in the marketplace?

    June 19th, 2013 at 23:08

  6. Alexandre Girard

    I’d really like to save my contacts to a .vcf file before flashing my device and losing them.

    I’ve begin this app:

    https://github.com/alx/fos-backup-contacts

    I’m able to retrieve my contacts, but I’m stuck on the “write on sdcard” and “create a vcf file” parts, if someone would like to help with these :)

    June 20th, 2013 at 08:04

  7. Jason Weathersby

    You should be able to write out the contacts using something similar to:
    var vcard = "BEGIN:VCARD"+"n"+
    "VERSION:4.0"+"n"+
    "N:Gump;Forrest;;;"+"n"+
    "FN:Forrest Gump"+"n"+
    "ORG:Bubba Gump Shrimp Co."+"n"+
    "TITLE:Shrimp Man"+"n"+
    "PHOTO;MEDIATYPE=image/gif:http://www.example.com/dir_photos/my_photo.gif"+"n"+
    "TEL;TYPE=work,voice;VALUE=uri:tel:+1-111-555-1212"+"n"+
    "TEL;TYPE=home,voice;VALUE=uri:tel:+1-404-555-1212"+"n"+
    "ADR;TYPE=work;LABEL='100 Waters EdgenBaytown, LA 30314nUnited States of America'"+"n"+
    " :;;100 Waters Edge;Baytown;LA;30314;United States of America"+"n"+
    "ADR;TYPE=home;LABEL='42 Plantation St.nBaytown, LA 30314nUnited States of America'"+"n"+
    " :;;42 Plantation St.;Baytown;LA;30314;United States of America"+"n"+
    "EMAIL:forrestgump@example.com"+"n"+
    "REV:20080424T195243Z"+"n"+
    "END:VCARD";

    var sdcard = navigator.getDeviceStorage("sdcard");
    var file = new Blob([vcard], {type: "text/plain"});

    var request = sdcard.addNamed(file, "test/my-file.vcf");

    request.onsuccess = function () {
    var name = this.result;
    alert('File "' + name + '" successfully wrote on the sdcard storage area');
    }

    // An error typically occur if a file with the same name already exist
    request.onerror = function () {
    alert('Unable to write the file: ' + this.error.name);
    }

    June 20th, 2013 at 13:38

  8. Jason Weathersby

    You will also need readwrite permissions on the app
    “device-storage:sdcard”:{ “access”: “readwrite” },
    and the web type should be privileged
    “type”: “privileged”

    June 20th, 2013 at 13:41

    1. Alexandre Girard

      Thanks a lot, I’ll this during the weekend :)

      June 20th, 2013 at 23:44

  9. Lucas Salton Cardinali

    Is there a way to Hard Brick the phones? Like flashing a Peak image over Keon?

    June 20th, 2013 at 16:42

    1. Robert Nyman [Editor]

      It’s no really our intention to teach how to hard brick the phones – we prefer them being usable. :-)

      June 24th, 2013 at 10:01

  10. anptr

    I get Read-only file system error. http://pastebin.mozilla.org/2553357

    June 22nd, 2013 at 15:04

    1. Jason Weathersby

      Nothing was in the link.

      June 24th, 2013 at 09:10

  11. Bob Thulfram

    This is all well and good, but every time I go to the GeeksPhone site, they say they are out of stock. Is there any other way to get a reference device? I’m happy to pay $200 for something that works. Help!

    June 23rd, 2013 at 00:45

    1. Robert Nyman [Editor]

      I’m sorry about that. The demand on the phones are really high, and hopefully we will be able to offer more in the future. We are also looking at official releases within the next few months, so that could potentially be an option.

      So, please keep your eyes open on the Geeksphone web site and here, and I hope you’ll eventually will be able to get one.

      June 24th, 2013 at 10:02

      1. Bob Thulfram

        Well, the good news is that if the demand is high, a lot of folks are going to be supporting Firefox OS. That is very exciting.

        And in the meantime, the development environment is the easiest and quickest I’ve ever seen!

        Thanks for the quick reply!

        June 24th, 2013 at 18:12

  12. daf182

    hi,

    I was stucked with installation of the build. Actually the restarted and froze with the Geeksphone logo. The console told me that .

    The solution was to run flash.sh as root:
    sudo ./flash.sh

    Thanks to: http://javaguirre.net/2013/05/06/flashing-firefox-os-geeksphone-peak/

    Happy hacking, don’t bricking! ;)

    OS: Ubuntu 13.04. 64bit

    June 26th, 2013 at 14:50

  13. Vee Satayamas

    I plug Keon (nighly built 20130703) with Macbook Pro. Remote debug is already enable. But I cannot install gaia from github. I got following messages.

    https://gist.github.com/veer66/5916535

    July 3rd, 2013 at 02:08

    1. Jason Weathersby

      I am not certain what was changed but I got it to work by doing an adb remount command and then run the make command

      July 3rd, 2013 at 15:33

      1. Vee Satayamas

        It works now. Thank you so much.

        July 3rd, 2013 at 20:41

  14. Benjamin Schmidt

    Great info, thanks! I only have one problem: B2G 1.x is installed but a Nightly for 2.x is available. If I install it WiFi does not work and I can’t set the display’s brightness. (Tried it 3 days ago) Is there a workaround for such problems or is it fixed now?

    Also: Can I flash from “stable” to nightlies without losing data?

    July 3rd, 2013 at 04:24

  15. Jason Weathersby

    I am not certain those issues are fixed yet. What nightly did you use? On the flash question, I am not sure this is possible but you could try modifying the flash script to not push certain images, like the userdata.

    July 3rd, 2013 at 15:35

  16. Pluto

    By the way, a much simpler approach for all Windows client to open up an MS app is by opening run through the shortcut WIN + R. That works from WinXP – Win8, and probably older as well. Then just type in cmd and hit enter.

    July 12th, 2013 at 12:30

  17. Ron Gavioli

    Hello all,

    Can I ask a very stupid question, the only video format my Keon reads is MP4, right?

    If I load any other video format to the card memory, Keon is going to ignore it, is that correct?

    Many thanks,
    Ron

    July 16th, 2013 at 05:40

    1. Robert Nyman [Editor]

      To my knowledge, yes. Supported video formats will play, others will be ignored.

      July 16th, 2013 at 06:09

Comments are closed for this article.