WiFi Information API

This API is available on Firefox OS for internal applications only.

Summary

The WiFi Information API is specifically made to handle WiFi connections on a Firefox OS device. It provides an interface to find available WiFi networks and handle connecting and disconnecting the device from those networks.

Global information

The WifiManager interface provides global information about the status of the WiFi capabilities of the device.

The WifiManager.enabled property simply states if the WiFi adapter is turned on or off.

Note: Enabling or disabling WiFi can only been done by using the Settings API to change the wifi.enabled setting. Each time this setting changes, the WifiManager object will send an enabled or disabled event. Those events can be handled by using the WifiManager.onenabled and WifiManager.ondisabled event handlers.

The WifiManager.macAddress property provides the MAC address of the WiFi adapter.

The WifiManager.connection property provides information about the current connection. It's an object with two properties:

status : A string, one of "disconnected", "connecting", "associated", or "connected".
network : If connected or associated, a network object with all the information about that network (see below).

The WifiManager.connectionInformation property provides some extra information if the device is connected to the WiFi (otherwise, it's null). It's an object with the following properties:

signalStrength : A number indicating the absolute strength of the signal in dBm.
relSignalStrength : A number in the range [0,100] indicating the relative strength of the signal.
linkSpeed : A number representing link speed in Mb/s.
ipAddress : A string representing the IP address of the device in the dotted quad format.

Find and retrieve networks

In order to connect a device to a WiFi network, the first thing to do is get information about the network to connect.

This can be done with the WifiManager.getNetworks() method which scans the area to find all the current available networks. It's also possible to use the WifiManager.getKnownNetworks() method which will provide the list of all the networks the device already knows, regardless if they are available or not.

Both methods return a DOMRequest object to handle the success or error of the operation. In case of success the request's result is an Array of network objects. Each of those objects are regular JavaScript objects with properties about a given network:

ssid : A string representing the ssid of the network.
bssid : A string representing the bssid of the network.
capabilities : An array of strings representing the special abilities of the network (currently, only WPS is supported).
security : An array of strings representing the security model of the network (currently supports WEP, WPA-PSK, and WPA-EAP).
signalStrength : A number indicating the absolute strength of the signal in dBm.
relSignalStrength : A number in the range [0,100] indicating the relative strength of the signal.
connected : A boolean indicating if the device is connected to that network.
known : A boolean indicating if the network is already known by the device (it has been used already).

var wifi = navigator.mozWifiManager;

function sortNetworksByStrength(a, b) {
  return a.signalStrength > b.signalStrength ? -1 : 1;
}

var request = wifi.getNetworks();

request.onsuccess = function () {
  console.log('The following networks are available:');

  var networks = this.result;
  networks.sort(sortNetworksByStrength);
  networks.forEach(function (network) {
    console.log(network.ssid, ' (', network.relSignalStrength.toFixed(0), ')');
  })
}

request.onerror = function (err) {
  console.log('Something goes wrong: ' + err);
}

Handling connections

Handling a connection is pretty simple. If the device found a network it already knows, it connects to it automatically. A known network is any network the device has been previously connected to. Although this is often convenient for the user, it can be annoying sometimes. So, if necessary, it's possible to make the device forget a given network by using the WifiManager.forget() method.

var wifi = navigator.mozWifiManager

// Let's make the device forget about all the networks it knows
request = wifi.getKnownNetworks();

request.onsuccess = function () {
  var networks = this.result;

  networks.forEach(function (network) {
    wifi.forget(network);
  });
}

Manual connection

The connection workflow is quite simple. To try to connect the device to a WiFi network, it just requires to pick a network and associate the device with that network. Such an association is done with the WifiManager.associate() method. Once that method is called the device tries to connect itself to that network, entering the connection workflow. Each step of the connection workflow can be tracked thanks to the connection events (see below).

var wifi = navigator.mozWifiManager;

function sortNetworksByStrength(a, b) {
  return a.signalStrength > b.signalStrength ? -1 : 1;
}

var request = wifi.getNetworks();

request.onsuccess = function () {
  console.log('The following networks are available:');

  var networks = this.result;
  networks.sort(sortNetworksByStrength);
  
  // Let's try to connect the device to the strongest network
  wifi.associate(networks[0]);
}

Once a connection is established, the last thing remaining is setting an IP address for the device. If the network is configured with DHCP, no problem, a dynamic IP will be assigned to the device. However, if it's not the case or if the user wants to set the IP address manually, this can be done with the WifiManager.setStaticIpMode() method. This method expects two parameter, a network object and a configuration object. The configuration object must have the following properties:

enabled : A boolean requesting if the static IP mode must be turned on (true) or off (false).
ipaddr : A string representing the IP address of the device in the dotted quad format.
proxy : A string representing the proxy server address (if any, otherwise an empty string).
maskLength : A number representing the length of the network mask.
gateway : A string representing a gateway address (if any, otherwise an empty string).
dns1 : A string representing the first DNS server address.
dns2 : A string representing the second DNS server address.

Secured connection

Connecting to a secure WiFi network is not really harder but it necessitates taking care of a few things.

WEP/WPA

When retrieving a network, its security property will provide the kind of encryption used by that network. security is an Array of strings, each string representing an encryption method usable with that network. Currently, Firefox OS supports WEP, WPA-PSK, and WPA-EAP.

Associating a secured network with the device is done the same way as for an open network with the WifiManager.associate() method. However, this time it's necessary to set some extra properties to the network object passed to the method, which depend on the encryption method:

For network with WEP encryption method:
- wep : This property must be set with the proper password to access the network.
For network with WPA-PSK encryption method:
- psk : This property must be set with the proper password to access the network.
For network with WPA-EAP encryption method:
- eap : A string representing the EAP method to use.
- password : A string representing the password to access the network.
- identity : A string representing the identity to access the network.
- pin : A string representing the pin code required to access the network.

var wifi = navigator.mozWifiManager;

var request = wifi.getNetworks();

request.onsuccess = function () {
  // Let's get the first network
  var network  = this.result[0];
  var security = network.security[0];

  if (security === 'WEP') {
    network.wep = prompt('This network requires a WEP password:');
  }

  else if (security === 'WPA-PSK') {
    network.psk = prompt('This network requires a WPA Key:');
  }

  else if (security === 'WPA-EAP') {
    network.eap      = prompt('Which EAP method should be used:');
    network.identity = prompt('Which identity should be used:');
    network.password = prompt('This network requires a password:');
    network.pin      = prompt('Thanks to finally provide your own PIN:');
  }
  
  // Let's try to connect the device to the network
  wifi.associate(network);
}

WPS

WPS connection is a simpler way to connect a device to a network. It requires less knowledge from the user and makes things easier for him. Basically, when a user has a WPS enable WiFi router, he can choose that method to connect the device to the network instead of typing a password. It can be useful for WPA-PSK secured networks because their keys can be very long and hard to type.

To know if a network is WPS enabled, just check the network.capabilities array. If the network allows it, it's possible to follow the WPS process to associate the device with the network. Each step of the process is handled through the WifiManager.wps() method, which returns a DOMRequest object to handle the success or error of the process.

There are two ways of initiating a WPS connection up to the user:

The easiest one is by pressing a dedicated button on the WiFi router. In that case, the parameter object passed to the wps() method must have a property named method with the value pbc.
An alternative is by entering a PIN provided by the WiFi router. There are two use cases here:
1. The WiFi router will send a PIN to the device and the user has to type it on the WiFi router interface. In such a case, the parameter object passed to the wps() method must have a property named method with the value pin and a property named bssid with the bssid of the network.
2. The WiFi router expects the user to type a PIN on his device (usually, such a PIN is displayed on the WiFi router itself). In such case, the parameter object passed to the wps() method must have a property named method with the value pin, a property named pin with the PIN provided by the user, and a property named bssid with the bssid of the network.

var wifi = navigator.mozWifiManager;

var request = wifi.getNetworks();

request.onsuccess = function () {
  // Let's get the first network
  var network = this.result[0];
  var isWPSEnabled = network.capabilities.indexOf('WPS') > -1;
  var wpsRequest;

  if (isWPSEnabled) {
    if (comfirm('Do you want to use the push button to connect your device?')) {
      wpsRequest = wifi.wps({
        method : 'pbs'
      });
    }

    else if (confirm('Do you want to type a PIN on your WiFI router interface?')){
      wpsRequest = wifi.wps({
        method : 'pin',
        bssid  : network.bssid
      })

      wpsRequest.onsucces = function () {
        alert('Please, type that number on your WiFi router interface: ' + this.result)
      }
    }

    else {
      wpsRequest = wifi.wps({
        method : 'pin',
        bssid  : network.bssid
        pin    : prompt('Please, provide the PIN for your WiFi router.')
      })
    }
  }
}

Once a connection has been initialized successfully, the completion of the connection process can be tracked through the connection events (see below). As long as the connection process is not complete, it's possible to cancel a WPS connection by calling the wps() method with a parameter object which has a property named method with the value cancel.

Events

Connection events

When a device tries to connect itself to a WiFi network (or is disconnected from such a network), it sends several statuschange events. Possible statuses are the following:

connecting : the device entered the connection workflow.
associated : the device is connected to an access point but does not have an IP address yet.
connected : the device is fully connected via wifi and ready.
connectingfailed : the device was unable to connect itself to a network.
disconnected : the device was connected to a network but has disconnected for any reason.
wps-timedout : the WPS connection has timed out.
wps-failed : the WPS connection failed.
wps-overlapped : a WPS connection overlaps (this happens when two networks in the same area allow a pbs connection at the same time).

To listen to those events it's mandatory to use the WifiManager.onstatuschange event handler. Any callback function associated to that handler receives a MozWifiStatusChangeEvent as its first parameter.

var wifi = navigator.mozWifiManager;

wifi.onstatuschange = function (event) {
  console.log('The connection status is: ' + event.status);
}

Ongoing connection

Once the device is connected to a network, the WifiManager.connectionInformation property provides extra information about the connection (see above). However, each time that information changes, the WiFiManager is notified with a connectioninfoupdate event. Such an event can be listened for with the WifiManager.onconnectioninfoupdate event handler. Any callback function associated to that handler receives a MozWifiConnectionInfoEvent as its first parameter. Such an object provides the same information as the WifiManager.connectionInformation property and also provides the corresponding network object.

var wifi = navigator.mozWifiManager;

wifi.onconnectioninfoupdate = function (event) {
  console.log('Update information for: ' + event.network.ssid);
  console.log('IP: ' + event.ipAddress);
  console.log('Speed: ' + event.linkSpeed.toFixed(2) + 'Mb/s');
  console.log('Signal strength: ' + event.signalStrength.toFixed(2) + 'dBm (' + event.relSignalStrength.toFixed(0) + '%)');
}