Hacking Gaia with Firefox OS Simulator

From my point of view, the real potential of Firefox OS is not developing applications for Gaia but modifying the system itself. It is true that nowadays Gaia and Gecko suffer from some hard coupling but you have all the code in the web so learn, improve and distribute. This is free software, bro!

The common way to hack Gaia itself in order to replace components such as the keyboard, the homescreen or even the system application is to clone the repository and use make to push your modifications to the device and adb for debugging. But the other day I found a way of doing the same but using Firefox OS simulator. I.e. with no need of pushing to the device!

NOTE: At the present moment, it is somehow annoying to manually discover in which port the simulator is listening in order to connect the debugger to it and to make this every time you modify the application but I will update the post as I receive news about improving the process. Furthermore, the guide is written for Linux but I hope the procedure will be the same for Windows replacing symbolic links by direct links ,)

Step 0: set-up

So, the first thing you need is to follow the step 0 from my other post Firefox OS: applications 101. In addition you’ll need Python 2.7 to be in the path. It is convenient you read all the 101 to get used to the Simulator.

Now, assuming you have Nightly, show the developer tools opening the Tools menu, then Web developer > Toggle tools. Here, look for the gear in the top-left corner, click and check Enable remote debugging under Advanced Settings. This ask you for restart Nightly. Do it.

To work with the most recent version of Gaia you need to clone the repository in GitHub. From a terminal, write:

$ git clone https://github.com/mozilla-b2g/gaia.git

Now enter Gaia directory and build a Gaia profile by writing:

$ make

After finishing, you’ll end with a new folder called profile. The profile in Firefox OS is the same as in Firefox, it holds the extensions (nope, you can not develop extensions for Firefox OS), user preferences and, in this case, the webapps pre-installed in the device.

So you have Firefox OS Simulator, Nightly remote debugging enabled and latest Gaia with a working profile. The concept is simple: the simulator uses a static Gaia profile to run the simulation. The simulator profile has a webapps folder inside with all Gaia’s applications. We are going to replace some of these application by those in our profile. In addition, the simulator has a remote debugging session listening in some port so we are going to discover this port and connect to it via remote client of Nightly.

Step 1: hacking the keyboard

Go to Gaia’s root folder, and open:

apps/keyboard/js/keboard.js

Go to line 1423, it looks something like:

  // Normal key
  default:
    inputMethod.click(keyCode);
    break;

Below  the `default` keyword, add:

console.log('Key pressed: ' + keyCode);

In the root of Gaia’s directory, regenerate the profile by writing:

make

Enter the new profile folder, inside you’ll find a webapp directory with all the Gaia’s application:

$ cd profile/webapps
$ ls 
bluetooth.gaiamobile.org       geoloc.gaiamobile.org                   mochitest.gaiamobile.org       testpermission.gaiamobile.org
browser.gaiamobile.org         homescreen.gaiamobile.org               music2.gaiamobile.org          test-receiver-1.gaiamobile.org
calendar.gaiamobile.org        hoststubtest                            music.gaiamobile.org           test-receiver-2.gaiamobile.org
camera.gaiamobile.org          hoststubtest.gaiamobile.org             packstubtest                   test-receiver-inline.gaiamobile.org
clock.gaiamobile.org           image-uploader.gaiamobile.org           packstubtest.gaiamobile.org    test-sensors.gaiamobile.org
communications.gaiamobile.org  keyboard.gaiamobile.org                 pdfjs.gaiamobile.org           twittershare.gaiamobile.org
costcontrol.gaiamobile.org     lost-messages.gaiamobile.org            settings.gaiamobile.org        uitest.gaiamobile.org
crystalskull.gaiamobile.org    marketplace.firefox.com                 share-receiver.gaiamobile.org  video.gaiamobile.org
cubevid.gaiamobile.org         marketplace.firefox.com.gaiamobile.org  sms.gaiamobile.org             wallpaper.gaiamobile.org
ds-test.gaiamobile.org         membuster.gaiamobile.org                system.gaiamobile.org          webapps.json
email.gaiamobile.org           m.here.com                              template.gaiamobile.org
fm.gaiamobile.org              m.here.com.gaiamobile.org               test-agent.gaiamobile.org
gallery.gaiamobile.org         mochitest                               test-container.gaiamobile.org

Step 2: replacing the keyboard application in the simulator

Now we need to find where is the webapps directory of the Simulator. In Linux it is normally in:

~/.mozilla/firefox/<your_firefox_profile>/extensions/r2d2b2g@mozilla.org/profile

Go here. If you have several profile folders, open the profiles.ini file inside firefox folder to find which one is the default one. In my case:

[Profile1]
Name=default-1372117340198
IsRelative=1
Path=6kdbsht4.default-1372117340198
Default=1

Note it is marked as the default one (Default=1).

Take in count this is your Firefox Nightly profile, not the Firefox OS Simulator profile.

Once located, enter the Firefox OS profile and the webapps folder. In my case:

$ cd ~/.mozilla/firefox/6kdbsht4.default-1372117340198/extensions/r2d2b2g@mozilla.org/profile/webapps

List this directory to see one folder by application in Gaia:

$  ls
bluetooth.gaiamobile.org  communications.gaiamobile.org  homescreen.gaiamobile.org       music.gaiamobile.org     video.gaiamobile.org
browser.gaiamobile.org    costcontrol.gaiamobile.org     keyboard.gaiamobile.org         pdfjs.gaiamobile.org     wallpaper.gaiamobile.org
calendar.gaiamobile.org   email.gaiamobile.org           settings.gaiamobile.org         webapps.json             camera.gaiamobile.org
fm.gaiamobile.org         marketplace.firefox.com        sms.gaiamobile.org              clock.gaiamobile.org     gallery.gaiamobile.org
m.here.com                system.gaiamobile.org

Backup the keyboard application and make a symbolic link to your modified keyboard application in the Gaia profile folder, so:

$ mv keyboard.gaiamobile.org keyboard.gaiamobile.org.backup
$ ln -s ~/path/to/gaia/root/profile/webapps/keyboard.gaiamobile.org

Now, when launching Firefox OS simulator, it will run our modified Keyboard app instead.

Step 3: remote debugging

How do we know we are using our keyboard? More important, how to debug our code!? Did you remember we added a log instruction in step 1? Let’s show how to see these traces. First, run Firefox OS Simulator.

Now open a terminal and use netstat command to see in which port the process b2g is listening for:

$ netstat -tulnp | grep b2g
tcp        0      0 127.0.0.1:38550         0.0.0.0:*               LISTEN      18105/b2g

So, once located the the port, go to Tools menu, then Web Developer, Connect… . Leave address as localhost and enter the proper port in the port input. Then click Connect and select Main process in the next screen. This will open a window with developers tools connected to the Simulator.

Now check if your logs are being printed by opening the browser application and introducing some text…

They should appear.

Further hacking…

Now you want to continue hacking Gaia or its components. It is as easy as repeat steps from 1 to 3. Not forget to regenerate the profile by launching make each time you modify a Gaia application!!

It should be great if the Simulator were able to auto-connect with the remote debugging. So I’ll try to add it directly or ask the author for implement this feature.

Hope it helps!