Hacking FirefoxOS

by Yorik on 10.01.2014 in firefoxos , opensource

The following guidelines were made with an Alcatel One Touch Fire from Vivo operator (Brazil) on a debian testing system, you may need to adapt a bit if you use another distribution, and adapt a LOT if you use a non-linux OS... Most of the information presented here was gathered from several sources:

Disclaimer: hacking your FirefoxOS device can easily - it happened several times to me - "brick" your phone (turn it as useful as a brick, meaning it won't start anymore). There is no reason to panic, if you made backups of your system, you can always restore things to their original state (if not, many kind people have copies of the original ROMs laying around on the net). I recommend you to read first through this page, but never do anything that involves flashing (overwriting the phone data) before having installed the clockworkmod recovery (see below) and made a complete backup. After that, you should be safe to play

Adding usb access to sdcard

First check what are the vendor and product numbers of your device. Run the command "lsusb" with your phone plugged to find out (mine are 05c6:9025). Add to /etc/udev/rules.d/51-firefoxos.rules:
```
SUBSYSTEM=="usb",ATTR=="05c6",MODE="0666",GROUP="plugdev"SUBSYSTEM=="usb", ATTR=="18d1", ATTR=="d00d", MODE="0666"SUBSYSTEM=="usb",ATTR=="05c6",ATTR=="9025",SYMLINK+="alcatel-phone"SUBSYSTEM=="usb",ATTR=="05c6",ATTR=="9026",SYMLINK+="alcatel-phone-dev"
```
The first line allows normal users to mount the phone, the second line does the same when the phone is in fastboot mode (see below), it has then a different vendor number, don't ask me why... the third line creates a symlink, so you can check in /dev if the device was successfully picked (not really useful at this point, but handy anyway), the third line is for me to test, since I noticed that sometimes my phone connects as product id 9026.
restart udev (/etc/init.d/udev restart), or restart your computer

on the phone, enable these 2 settings:

Settings > Enable USB storageSettings > Media storage > Share using USB

Plug the phone, check in /dev if the symlink was created. There should be also (in my case) a sdb entry. The sdb1 entry (the sdcard partition) is created only when you unlock the phone's home screen. Then normally your system creates an entry in /media/youruser, that file managers recognize.
In some cases (still couldn't find out why) the sdb1 entry is not created on unlocking the phone. Issuing this command solves it:
```
mkdir tmp && sudo mount -t vfat /dev/sdb tmp
```

Gaining shell access

Install android-tools-adb

On the phone, activate:

Settings > Device information > More information > Developer > Remote debugging

As root (doesn't work as normal user):
```
adb kill-serveradb start-serveradb devices
```
the last line should list your device. If says ???????????? something is wrong. If you have an Alcatel One Touch Fire, it says: device: MSM7627A (which is the qualcomm CPU of my device)
Gain shell access:
```
adb shell.
```
You can now navigate with a minimal shell. Some folders are not readable, because you still have no root access. See below...

Note: adb should also connect to your phone when running as a normal user (needed below for compiling). If it doesn't, try 1) adding OWNER="yourusername to the udev rule above, and restart udev. If you get a message like: cannot bind local:5037 check if there isn't a file names 5037 in your /tmp folder. If yes, deleting it solved the problem for me. After that, adb starts as normal user.

Using the FirefoxOS simulator

The FirefoxOS simulator (also called r2d2b2g) is a very cool addon for your desktop Firefox. It is made primarily for you to test FirefoxOS, but it also has another nice use: it detects when your phone is connected via USB (Remote debugging must be activated, see above), and can install applications on the phone. This allows you, for example, to take the code of an application, tweak something (it is sometimes very easy, it is all html and javascript), and install that new version on your phone. There is another hidden but very useful advantage, it allows you to explore the source code of any application, even those that don't publish their source code. For example, you can do this:

Install an application on the FirefoxOS simulator.
With your file manager, navigate to /home/youruser/.mozilla/firefox/somecode.default/extensions/2d2b2g@mozilla.org/profile/webapps, and explore the different folders, one of them is the application you just installed. Read the manifest.webapp file with a text editor to find out which application it is. Together with the manifest.webapp, is a zip file containing all the application. Unzip that file in another directory
Do all the tweaks you want, something simple is to change the icon of the application.
To install the tweaked app on your phone, connect your phone with the USB cable, and open the simulator. It will show a "device connected" icon. Press the "open directory", browse for your manifest.webapp file. It will open the simulator and install the app there. If all seems ok, you can push the app to your phone too by pressing the "push" button. That's it!
That app can be uninstalled like any other, by long-pressing its icon then pressing the delete button.

Note: From version 1.2, firefoxOS doesn't use this simulator anymore. Instead, there is a way more interesting system called "Apps manager", that allows very cool stuff such as tweaking the css of your phone from your desktop firefox, or issueing javascript commands to the phone... One more reason to upgrade as quick as we can!

Getting root access

FirefoxOS, being based on the Android kernel (yes!) benefits from the same abilities, it can be connected to using the adb tools, like we saw above, but it can also be booted with another kernel than the one installed on the device. This has the extra advantage to be totally safe, since nothing is installed on the device. If something goes wrong, just reboot the phone and everything goes back to normal.

Unless you have a phone geared for developers, such as the geekphones, your kernel doesn't permit root access. That is why we cannot see some of the contents from the adb shell. Luckily, many people have made unlocked kernels. We can use one of them, such as the one provided on http://elsimpicuitico.wordpress.com/2013/12/17/rooteando-el-alcatel-ot-fire-metodo-recovery/ (download the root_alcatel-signed.zip file). Unzip that file, and you will get a nice boot.img file, which is a bootable, rooted kernel for the Alcatel One Touch Fire. Inside the zip file, you will also find other goodies that the author has kindly packed, on the page I linked here there are instructions to install the whole package.

But since the guy is from Venezuela, and my phone is bought in Brazil, I was not sure that his image, being made from a phone from another mobile operator, would not cause problems on my phone. So, instead of installing the whole zip package, I decided to only use his kernel to boot remotely, without acually overwriting my own. This is actually pretty simple:

install android-tools-fastboot
Reboot your phone into fastboot mode: Turn it off, then press the power button to turn it on again, and immediately after pressing that button, keep the "volume down" button pressed for 5 seconds. The phone will stop at the alcatel logo, meaning you are in fastboot mode.
From a terminal, issue as root:
```
fastboot devices
```
it should give the same answer as adb devices.
Boot your rooted kernel (I assume you are in the same folder as your boot.img file):
```
fastboot boot boot.img
```
You will see your phone start booting, display the firefox logo, etc. I didn't see any difference between this kernel and my own, even the logo of my operator is still ther (unfortunately ) so I believe my fears were unfounded.
Open the adb shell again, and check that you are indeed root (issue the "id" command, try browsing through the different folders, etc). It can be that your phone is still read-only (the "mount" command will tell you), in this case you usually only need to unplug/replug your phone. If you still have a readonly filesystem, then there is something wrong with your udev rules above.
When you are done playing, simply reboot your phone normally, it will get back to its normal kernel.

Backing up the default system

Before beginning to play with custom kernels and all that bright side of life, it is absolutely necessary to have backups of your current system. I've read many posts on the net where people screwed their entire system. Once you have root and read/write access like we did in the previous step, it is a piece of cake:

In adb shell, copy the 4 components of the FirefoxOS system into separate .img files on the sdcard:

cat /dev/mtd/mtd0 >/mnt/sdcard/boot.imgcat /dev/mtd/mtd1 >/mnt/sdcard/system.imgcat /dev/mtd/mtd5 >/mnt/sdcard/userdata.imgcat /dev/mtd/mtd7 >/mnt/sdcard/recovery.img

Exit the adb shell, create a backup directory on your computer, then copy these 4 files from the phone's sdcard to your backup directory:
```
adb pull /mnt/sdcard/boot.img backup/boot.imgadb pull /mnt/sdcard/system.img backup/system.imgadb pull /mnt/sdcard/userdata.img backup/userdata.imgadb pull /mnt/sdcard/recovery.img backup/recovery.img
```
Done, you now have 4 nice images that reflect your whole FirefoxOS system in its current state. Keep these safe for the case something happens...

Installing the ClockworkMod recovery

FirefoxOS, like Android, comes with a recovery mode, which allows you to restore the system to its original factory state. On my phone, you access that mode by turning the phone off, then pressing the volume down button, then the power button, and keep them pressed until you enter the recovery screen. It has only one option, labeled "wipe everything and restore factory settings? y/n"... Amuch more interesting thing to do is to install an alternate recovery mode called clockworkmod. It has many interesting features such as the ability to backup your whole system, like we just did manually, manage backups, and restore from these backups. Installing it is pretty easy:

Download the hamachi-clockworkmod-recovery.img image from http://elsimpicuitico.wordpress.com/2013/12/17/backups-del-sistema-entero-en-firefoxos-alcatel-ot-fire/. (Warning, this image is for Hamachi (Mozilla's codename for the Alcatel One Touch Fire) only!)
Out of security, if you did the previous step, make sure your clockworkmod image has the exact same size as your backed up recovery.img. I read a lot of stories about people trying to flash images too big for the partition.
Boot your phone into fastboot mode (volume down + power up during 5 seconds)
Check that your phone is seen by fastboot (as root):
```
fastboot devices
```
Flash the clockworkmod image to the "recovery" partition of your phone:
```
fastboot flash recovery hamachi_clockworkmod_recovery.img
```
In a couple of seconds, if all goes well, your new recovery is installed
Remove the battery for 5 seconds, then reboot into recovery mode (volume up + power up until the recovery menu appears). Options are self-explanatory, but on the website here above you have more explanations too. Now is a good time to do a backup, so if something goes wrong later, we have an easy way to restore the system to its current point.

Hacking the kernel

One of the first thing you will want to do is to modify your boot image to give you root access always, so you won't need to use a special boot image like we did above each time you want to do some stuff on your device. This is rather simple, it involves basically unpacking the boot.img, changing a property, repacking it, then flashing it back on your device.

Install abootimg
Unpack your boot.img with the following command:
```
abootimg -x boot.img
```
This will create 3 files: bootimg.cfg (general configurations), zImage (the kernel) and initrd.img (the ramdisk image, a "virtual disk" image that the kernel creates after booting).

Unpack the ramdisk:

mkdir ramdiskcd ramdiskgunzip -c ../initrd.img | cpio -i

Edit default.prop in the ramdisk, and set "ro.secure=1" to "ro.secure=0".

Repack the ramdisk:

find . | cpio -o -H newc | gzip > ../myramdisk.gz

recreate a new boot image:

abootimg --create myboot-rooted.img -f bootimg.cfg -k zImage -r myramdisk.gz

First make sure everything works fine: reboot the phone in fastboot mode, and boot your new boot image with the method explained above. If all goes well, you can flash your new image permanently with:
```
fastboot flash boot myboot-rooted.img
```

Installing custom ROMs

The guy who runs http://elsimpicuitico.wordpress.com/2013/12/16/instalado-las-roms-de-firefox-os-en-b2g-vegnux-org-ve/ kindly uploaded many experimental ROMs for the Alcatel One Touch Fire, that you can download and try on your phone. At time of writing, my phone runs the 1.1 version, but 1.3 is already available, although not totally stable. Your mileage might vary, as they say. I had to try several versions before finding a combination that works for me. But this is an easy way to try newer versions without the need to compile stuff yourself. On the page, there are instructions for windows, here go the same for linux:

Make sure you have a backup, the next steps give a high chance to brick your phone
Download an image of your choice from http://b2g.vegnux.org.ve/ and unzip it somewhere
Turn off your phone, remove the battery for 10 seconds, reboot into fastboot mode

Execute the following as root (flashing the recovery is optional):

fastboot flash boot boot.imgfastboot flash userdata userdata.imgfastboot flash system system.imgfastboot flash recovery recovery.imgfastboot erase cachefastboot reboot

If all goes well, you are now rebooted into your new version. If all goes wrong, you will likely be stuck to the white Alcatel logo screen. Then, you can either redo the same and try to flash another version (some people on the site above successfully tried mixing different versions) or restore one of your backups with the clockworkmod recovery

Until now, the only one that works for me is the 1.2 version from 23/12/2013 with the boot.img from 13/12/2013... Version 1.3 is still too unstable at the time I'm writing this.

Compiling FirefoxOS

The full compilation guide at Mozilla is a bit in-depth and tedious, but it is a good idea to read it, it lists many options and pitfalls. Be sure to read the entire page before following any of the instructions, because they have a bad habit to write things like: "now, do this" and, a few paragraphs later, "instead of having done this, do that"... But I'll resume here the most important steps to give you an overview:

Have all the usual stuff to compile ready, with gcc/g++ 4.6 multiarch installed (b2g wants 4.6, and it's a 32bits app), adb, plus a couple of weird things from https://github.com/andreasgal/B2G/blob/master/INSTALL#L29.
Clone B2G (older name of FirefoxOS, true hackers don't say firefoxOS, they say b2g):
```
git clone git clone git://github.com/mozilla-b2g/B2G.git
```
Configure the build:
```
./config.sh hamachi
```
The above command will download about 12Gb of data, so be ready to wait a long time. If you need to update at a later time:
```
git pull && ./repo sync
```
set to use gcc4.6 (at time of writing, build will fail with a more recent one)
```
export CC=gcc-4.6export CXX=g++-4.6
```
Finallt, compile with:
```
./build.sh
```
When everything is done (around 40 minutes here), your new system lies in out/target/product/hamachi/. All that remains is to flash it on your device with a simple:
```
./flash.sh
```
You device will reboot automatically, and hopefully everything will just work. But expect some bugs, because you are compiling the latest bleeding-edge version, which is not meant for "normal" use. But I found it good enough to use, and if you did your backups you can revert anytime. Other cool thing, this upgrade will keep your user-made settings (homescreen, bookmarks etc)

Reporting bugs

Of course, if you don't use the stable version, you cannot expect your bugs to be solved immediately by the Mozilla people. But if you find bugs, it might be interesting to report them, so they are aware of it and can fix them. The place to report FirefoxOS bugs is https://bugzilla.mozilla.org. I'll remeber some common rules when submitting bugs, in case this is the first time you are doing it:

Make sure what you have is really a bug, and not something you are doing wrong. If you are in doubt, search on the net to see if other people experience the problem, talk about it on the forums, on irc (there is a #b2g channel on freenode), etc. You only waste people's time if they need to reply "this is not a bug, you are doing something wrong".
Make sure your bug hasn't been reported already. Make a very cautious search on the bug tracker, maybe your bug has been reported in another form.
A bug can only be solved if the developer can reproduce it on his machine/device. So yourself must be able to reproduce the bug, and in your bug report you should explain how to make the bug happen
There is never too much information. Include as much information as you can: Your device, the version of your FirefoxOS, any error or strange message that appears, anything.
Be courteous. Not everybody there is Mozilla employee, many are volunteers, and anyway nobody is forced to help you.

Compiling a specific version of FirefoxOS

The latest development version, like we compiled above, is very likely to contain bugs, since it is where developers are currently experimenting new stuff. A better option is to compile the latest "released" version. At the moment, the version compiled by the methos above is 1.4. So we could compile version 1.3, which will probably be more stable. To do that is easy, we just need to compile a branch rather than the master code.

Note: If you are going to do this often, there is a nice way to keep your specific configuration settings, by creating a userconfig file. all the specific settings such as the branch, the GCC version, etc... can go there.

First, if you compiled a previous version, we need to clean it:
```
./build.sh clean
```
Then we run config.sh, this time specifying a branch number:
```
BRANCH=v1.3 ./config.sh hamachi
```
Finally, we only need to build again, and, if successful, flash the build to the phone:
```
./build.sh./flash.sh
```