A runtime is an environment in which you'll run and debug the app. A runtime could be a Firefox OS device connected to the desktop over USB, it could be a Firefox OS Simulator installed on the desktop itself, or it could be another instance of Firefox Desktop.
Under the "Select Runtime" dropdown, runtimes are grouped into four types:
- USB DEVICES
- Firefox OS devices connected over USB. From Firefox 36 this also gets you connected to Firefox for Android over USB.
- WI-FI DEVICES
- Firefox OS devices connected over Wi-Fi. New in Firefox 39.
- Instances of the Firefox OS Simulator that you've installed.
- Remote runtimes to connect WebIDE to an arbitrary host and port. If you have the Valence add-on installed, this section will also list the additional runtimes it enables.
The rest of this section describes how you can add some runtimes.
If you have a sufficiently recent version of Firefox and Firefox OS, you can connect the Firefox OS device over WiFi. Otherwise, you must connect over USB.
Before you can connect a Firefox OS device, there's some setup you have to go through:
- Check your Firefox OS version: Make sure your device is running Firefox OS 1.2/Boot2Gecko 1.2 or higher. To check the version, go to the Settings app on the device, then
Device Information > Software. If you don't have a high enough version, find your device in the developer phone guide and follow the instructions for upgrading.
- Enable remote debugging: In the Settings app on the device, go to
Device information > More information > Developer.
- Firefox OS 1.3 and earlier: "Remote Debugging" is just a simple checkbox. Check it.
- Firefox OS 1.4 and later: "Remote Debugging" asks you to enable for just ADB, or for ADB and DevTools. Select "ADB and DevTools".
- Disable Screen lock on your device: In the Settings app on the device, go to
Screen Lockand uncheck the
Lock Screencheckbox. This is required because when the screen gets locked, the phone connection gets lost, meaning it is no longer available for debugging.
- If you want unrestricted debugging privileges, including certified apps, built-in apps, and apps already installed on a real device: See the section on Unrestricted app debugging (including certified apps, main process, etc.).
- You need to install drivers, as documented in step 3 of this guide to setting up an Android device. You can find drivers for Geeksphone devices on the Geeksphone web site. Windows 8 by default will not let you install unsigned drivers. See this tutorial on "How to install an unsigned driver on Windows 8".
- If WebIDE can't see your device after following all the steps, you may have to edit adb_usb.ini.
If there are any other Android devices connected to your computer, disconnect them. Now connect the device to the computer using USB. You should see the device appear under "USB DEVICES":
If you don't see your device, see the Troubleshooting page.
To connect over WiFi, you need:
- Firefox 39 or later
- a Firefox OS device running a build of Firefox OS 3.0 from 2015-03-27 or later
This doesn't use ADB at all, and is therefore likely to be more reliable than the USB method.
Enable WiFi debugging
First, enable WiFi debugging on the Firefox OS device.
- Open Developer Settings on the device (Settings -> Developer)
- Check "DevTools via Wi-Fi"
- Edit the device name if desired
Select the device
In WebIDE, click the "Select Runtime" menu. You should see a section labeled "Wi-Fi Devices", and your device should appear under it:
Select your device.
Next, in the WebIDE you'll see a prompt with a QR code:
On the device, you'll see a connection prompt giving you options to "Scan" or "Scan and Remember". Choose one of the options and scan the QR code. Now WebIDE should connect to the device, and the device icon next to "Select Runtime" should turn blue to indicate this.
The QR code scanner can be a bit frustrating at the moment, as real devices appear to capture a very low resolution picture. Bug 1145772 aims to improve this soon. If you have trouble with this, try scanning with a few different orientations.
If you chose "Scan and Remember, then you won't have to scan the code again the next time you connect your computer to this device.
From Firefox 36 onwards Android devices connected over USB and running Firefox for Android appear as a runtime under "USB devices". See the article on connecting to Firefox for Android from WebIDE.
Before Firefox 36, you can connect to Firefox for Android without using WebIDE at all, or can use WebIDE by setting up a custom remote runtime.
The Firefox OS Simulator is a version of the higher layers of Firefox OS that simulates a Firefox OS device, but runs on the desktop. It runs in a window the same size as a Firefox OS device, includes the Firefox OS user interface and built-in apps, and simulates many of the Firefox OS device APIs.
This means that in many cases, you don't need a real device to test and debug your app.
The Simulator doesn't ship inside Firefox but as a Firefox add-on. If you click "Install Simulator" in the Runtimes dropdown menu, you will go to a page from which you can install Simulators for various versions of Firefox OS.
You can install as many as you like. Be patient, though: the Simulator may take a few minutes to download. Once you've installed some Simulators you can close this "Extra Components" window, and the Simulators you've installed appear as options in the Runtimes dropdown menu:
To learn more about the Simulator, see its documentation page.
With a remote runtime you can use an arbitrary hostname and port to connect to the remote device.
Under the hood, Firefox OS devices and Android devices connect to the desktop using a program called the Android Debug Bridge, or ADB. By default, WebIDE uses an add-on called the ADB Helper: this simplifies the process for you by installing ADB and setting up port forwarding so the Firefox desktop tools can exchange messages with the device.
This is convenient in most cases, but sometimes you might want to use ADB outside of WebIDE: for example, you might be running ADB directly from the command line. In that case you'll connect to the device by specifying a host and port using the
adb forward command (example:
adb forward tcp:6000 localfilesystem:/data/local/debugger-socket).
If you then want to use WebIDE to connect as well, you should disable the ADB Helper add-on and connect WebIDE using the Custom runtime option, entering the host and port that you passed to
adb forward (example:
Also, before Firefox 36, the ADB Helper does not yet support connecting to Firefox for Android, so if you want to connect WebIDE to Firefox for Android, you'll need to set up your own port forwarding and use a custom runtime. See more about connecting to Firefox for Android using ADB prior to Firefox 36.
If you have the Valence add-on installed, you'll see three additional runtimes:
- Chrome on Android
- Safari on iOS
- Chrome Desktop
For instructions on how to connect to these runtimes, see the relevant entry in the Remote Debugging page.
Once you've set up a runtime you can select it using the "Select Runtime" menu.
- If you select a Simulator, WebIDE launches the Simulator.
- If you select a Firefox OS device WebIDE connects to the device. On the device a dialog will ask you to confirm that you wish to connect: press "OK".
Now the "play" button in the center of the WebIDE toolbar is enabled: click it to install and run the app in the selected runtime.