Using the B2G emulators

This article provides a brief guide to some key things you should know when using the boot to Gecko emulators. This doesn't appear to be a complete user manual; instead, it simply tells you a few useful things that you might not learn on your own.

This guide assumes you've already built one of the emulators; if you haven't, rewind to Building and installing Firefox OS!

About the B2G emulators

There are two B2G emulators. The first, built by configuring for "emulator" when running config.sh, is an ARM device emulator. While this is slower than running directly on an x86 processor, it's more stable and a more accurate representation of what an actual device will work like. Configuring for "emulator-x86" when running config.sh gets you the x86 device emulator instead.

Note: In recent months the Automation Team has stopped using the x86 emulator due to stability issues. As such, there's a fair chance that things might just not work at all on emulator-x86. Use the ARM emulator unless you have a good reason to do otherwise.

Once you've selected, configured, and built an emulator, the rest works the same way from a user standpoint, so the rest of this guide is common to both.

Note: On Mac OS X, the B2G emulator requires a Core 2 Duo processor or later; that is, a system that is compatible with Mac OS X 10.7 "Lion." You do not actually have to be running Lion, you just have to be compatible with it.

Starting the emulator

To start the B2G emulator, type the following command:

./run-emulator.sh

This will handle all the emulator startup tasks for you. Now wait patiently while the emulator starts up and Boot to Gecko boots up on it. It can take a couple of minutes, so be patient.

When the emulator doesn't work

Sometimes the emulator fails to start up. Welcome to the bleeding edge of technology! Here are some tips for resolving problems.

Are you trying to work in a VM?

VirtualBox and Parallels have problematic accelerated graphics support which causes a boot failure in the emulator, something about an OpenGL device. The device will start booting, fail, and restart in a loop, or start up, but then display nothing in the screen of the emulator. There is no solution unfortunately (there is a workaround for VirtualBox) - you need to use VMWare Player (Freeware), Workstation or Fusion. For VirtualBox - either do not install Guest Addons, or disable vboxvideo module.

Make sure the adb server is running

This usually happens because the adb server that handles interacting with the emulated device is either not running or has malfunctioned. In this case you can usually see the following error message in the terminal where you launched the emulator:

emulator: control console listening on port 5554, ADB on port 5555
emulator: can't connect to ADB server: Connection refused

Note: If you're using the adb built by the B2G build system (which you probably are), it's located in the $B2G/out/host/<platform>/bin directory. On Mac, this is $B2G/out/host/darwin-x86/bin, for example.

Look to see if adb is even running by doing:

ps aux | grep adb

If it's there, do this to kill it, because it's probably not working correctly.

adb kill-server

If it's not there, do this:

adb start-server

Then try running the emulator again. If it's still not working, time to drop in on #b2g on irc.mozilla.org for help.

Erase configuration settings

Sometimes, out of date configuration settings on your emulated device can cause it to misbehave. You can delete the IndexedDB database fix this, as follows:

Make sure adb is running, as described in Make sure the adb server is running.
Start up the emulator.
in the terminal on the host computer, go into the root code build directory for your emulator, then type: out/host/<platform>/bin/adb -e shell; on Mac, this would be out/host/darwin-x86/bin/adb -e shell.
Now you're in the adb shell, and can execute shell commands on your emulated device. Let's stop B2G on the device: stop b2g.
Delete the IndexedDB database: rm -rf /data/local/indexedDB.
Restart B2G on the emulated device: start b2g.

Hopefully at this point you will wind up in the Gaia interface and all will be well.

If the emulator starts but the screen is black before or after the "mozilla technology" splash screen

If this happens it could be a driver bug of the machine that is running the emulator. It has been observed on the Linux open source nouveau drivers. The easiest solution is to change the drivers on the machine. In the case of the nouveau driver it could be to install proprietary ("additional" in Ubuntu) drivers instead. In the case of on-board intel graphics chipsets, the default Linux open source driver may cause an emulator error 'eglMakeCurrent failed' which appears to be as it supports an OpenGL version less than the 2.0 needed for GPU emulation. The solution is to deactivate the GPU by editing run-emulator.sh script (this will be slower).

Configuring the emulator

There are several options you can change to adjust the emulator to be more similar to the device you want to emulate. This section provides some basic information on how to do that. You can adjust the emulator's configuration by editing the run-emulator.sh script (or, ideally, a copy of it). Only a few of the most useful parameters are discussed here; you'll want to look at the qemu site for details on the others.

Tip: Create one copy of run-emulator.sh for each device you want to simulate; this makes it easy to start up with different configurations.

Changing skins

By default, the emulator starts up in HVGA mode; that's half-VGA, or 320x480 pixels. This is specified by the -skin parameter given to the emulator when started up. You can switch to a different display mode by editing the run-emulator.sh script (or, ideally, a copy of it). The provided skins are:

HVGA (320x480)
QVGA (240x320)
WQVGA (240x400)
WQVGA432 (240x432)
WSVGA (1024x600)
WVGA800 (480x800)
WVGA854 (480x854)
WXGA720 (1280x720)
WXGA800 (1280x800)

The skins are located in the B2G/development/tools/emulator/skins directory. It's worth noting that the format for skins is quite simple; if you look at them, they're simply folders filled with PNG files for the various user interface objects and a text file called layout which describes the layout of the interface and screen area. It's fairly simple to create custom skins if needed.

Changing memory size

Another option you may wish or need to configure is the device memory size. The default is 512 MB; however, if the device you're emulating has more or less memory, it is likely important that you adjust this setting to match, to ensure your app will run on the baseline device you want to work on. To do this, change the value of the -memory parameter to the size you need in megabytes. Other than the 512 MB default, 256 MB and 1024 MB are likely ones you'll want to test with.

To change the amount of emulated storage capacity for the device (that is, the storage space for local data, like the flash storage on a mobile phone or the hard drive on a computer), change the value of the -partition-size parameter. The default is 512 MB, but you can specify any size in MB you need in order to simulate the kind of device you need to test for.

Network Connectivity

If for some reason you cannot connect your emulator to the internet you can run the following command from your commandline:

adb shell setprop net.dns1 10.0.2.3

If you run emulator-jb or emulator-kk, the command to set up the DNS server is different.
Please run the following commands:

adb shell ndc resolver setdefaultif eth0
adb shell ndc resolver setifdns eth0 10.0.0.0 10.0.2.3