Using Firefox OS Simulator

The Firefox OS Simulator is a desktop platform tool that shows you what apps will look like on a phone that is running the Firefox OS. It is the easiest way to try out apps on Firefox OS before submitting them to the Firefox Marketplace. The Firefox OS Simulator was formerly called "r2d2b2g", but that name is too difficult.

The Simulator is packaged as a desktop Firefox add-on. You can use any recent version of Firefox from Firefox 17 onward.

Although there are other ways to run the Firefox OS desktop, the best and most convenient way for app developers is this one. If you're a core Firefox OS platform developer, or are working on localization, there are other tools that are better suited for your needs. The Simulator add-on includes support for adding apps to the test environment, and is configured to support remote debugging, remote Web console, and other features. It also provides a visible Home button you can click, and sets the user-agent string to the one used by Firefox OS on devices. The result is, in nearly every way, a better environment for app developers.

Installing Firefox OS Simulator

  1. Using Firefox, go to this link:
  2. Click Add to Firefox. It's a large download. Follow the prompts that appear.

Because of the size of the add-on, Firefox may freeze for several seconds while installing it, and its unresponsive script dialog may appear, due to bug 814505. If it does, just click the Continue button, and Firefox will continue installing the add-on.

Starting the Simulator

  1. On the Firefox menu (Windows) or the Tools menu (Mac, Linux), go to Web Developer and click Firefox OS Simulator. The dashboard appears.


  2. Click the Stopped button. It changes into the Running button and Firefox OS boots up in its own window. The default size for this window is 320x480.


    To stop the Simulator, click the Running button in the dashboard, or just close the Simulator window.

Note: You can also start and stop the Simulator in the Developer Toolbar command line using firefoxos start and firefoxos stop.

Imitate swipe motions in the Simulator by clicking and dragging with the mouse. The mouse scroll wheel will move a list up and down, such as in the Settings app. Click and hold down the mouse button to simulate a long press.

To get back to the home screen, click the home button at the bottom of the Simulator, or press the Home key on your keyboard. On Mac keyboards without a Home key, use Fn + Left Arrow.

Console checkbox

Click the Console check box before you start the Simulator to open an error console so you can spot errors that might occur while you're working on your app.

Web APIs in the Simulator

Mozilla is working on many Web APIs to make native platform capabilities available to Open Web Apps. The Web APIs currently supported in the Simulator are:

  • Contacts API
  • Settings API
  • ? what other APIs ?

Installing an app in the Simulator

To install a hosted app in the Simulator, type the URL to the app's manifest in the URL box, and click Add Manifest. This will install the app in the Simulator. Here is a simple weather app that you can use as a test:

The app's icon will be added to one of the home screens in the Simulator.

You can also install a plain website in the same way. Just type the website's URL in the box and click Add URL, and an icon for the site will be added to a home screen. Autocompletion works if you have the website open in another tab.

To install a packaged app in the Simulator, click the Add Directory button, then select the mini-manifest of the app on your local filesystem.

To remove an app from the Simulator, click the Remove link for the app in the dashboard. You may have to restart the Simulator to see it gone.

Updating an app

If you are working on an app and need to update it in the Simulator, click the app's Update button in the dashboard. You will have to restart the Simulator. Hosted apps follow the usual rules for Website caching and working with appcache.

Reporting bugs

Remember that the Simulator is a brand-new tool and is still heavily under development. Please let us know if you find any bugs.

More information

The Simulator itself is the Firefox OS desktop client (also called the B2G desktop client), which is a build of Firefox OS that runs on Windows, Mac, and Linux. Firefox OS Simulator makes it easier to test apps on Firefox OS desktop because it includes functionality for adding apps to the environment and is configured/extended in a variety of ways to better meet the needs of app developers.

However, because the Simulator uses the Firefox OS desktop client, the documentation for B2G Desktop, Gaia, and B2G generally will also apply to the Simulator to some extent. Here are a couple of those docs:

Using the Firefox OS desktop client

Hacking Gaia