mozilla
Your Search Results

    WebBluetooth

    Non-standard
    This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

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

    Summary

    The Web Bluetooth API lets an open web app discover, pair with, and connect to Bluetooth devices. As it is a completely experimental and non-standard API, the Bluetooth API is currently available for certified applications only. However, there is some traction to have such an API available for regular Web content; this will be discussed as part of the W3C's System Applications Working Group.

    Note: App developers who wish to send data to a Bluetooth device can use the share activity. This activity allows sharing of images, audio, video and vCard content only.

    API overview

    The main entry point for the API is the navigator.mozBluetooth property, which returns a BluetoothManager object.

    Interfaces

    System messages

    Because some actions from remote devices can require waking up an app to handle them, there are several system messages related to Bluetooth:

    • bluetooth-dialer-command
    • bluetooth-cancel
    • bluetooth-hid-status-changed
    • bluetooth-pairing-request
    • bluetooth-opp-transfer-complete
    • bluetooth-opp-update-progress
    • bluetooth-opp-receiving-file-confirmation
    • bluetooth-opp-transfer-start

    Note: An App can react to these messages by requesting them in its app manifest file and by using the navigator.mozSetMessageHandler() function to define a message handler.

    Permission

    Certified applications that want to use the Web Bluetooth API must request the relevant permission within their app manifest.

    "permission": {
      "bluetooth":{}
    }

    It is also recommended to ask for the settings permission because currently enabling and disabling Bluetooth has to be done by changing the value of navigator.mozSettings setting named "bluetooth.enabled". Code to accomplish this would look something like this:

    var lock = navigator.mozSettings.createLock();
    var lockCompleteReq = lock.set({
      'bluetooth.enabled': true
    });
    
    result.onsuccess = function() {
      /* do what you need to do now that Bluetooth is on */
    }
    
    result.onerror = function() {
      /* deal with the error; Bluetooth was not enabled successfully */
    }
    

    Pairing Bluetooth devices

    The most important step when dealing with a Bluetooth environment is pairing devices in order to build a Bluetooth micro-network of devices working together in a secure way. Pairing is a procedure by which two Bluetooth devices come to share a common "key", called the "Link Key". Once two devices have been paired, it becomes possible to set up more advanced connections using profiles in order to access specific features of the devices.

    The pairing procedure depends on the I/O capabilities of each device.

    Each time a remote device wants to be paired with a Firefox OS device, a system message called bluetooth-pairing-request is sent. To intercept that system message, the application in charge of handling the pairing must register the message within its application manifest:

    "messages": [
      { "bluetooth-pairing-request": "/pairing.html" }
    ]

    It must also register a message handler for that message:

    navigator.mozSetMessageHandler("bluetooth-pairing-request", function (message) {
      // Get the information about the pairing request
      var request = message.detail;
    
      // Handle the pairing request. For this simple example, we're just logging
      // the name of the remote device that wants to be paired with your device
    
      console.log(request.name);
    });

    The message's detail property contains all the information needed to start pairing the two devices:

    • address: the address of the remote device on the Bluetooth micro-network (see: BluetoothDevice.address)
    • name   : the name of the remote device (see: BluetoothDevice.name)
    • icon   : An icon name to use (see: BluetoothDevice.icon)
    • passkey: A pass key the user has to type if the remote device is an input device
    • method : The pairing method to use, one of confirmation, pincode or passkey.

    Finalizing the pairing request depends on the specified method. Each method provides a mechanism for ensuring that both devices are controlled by the same user, in order to prevent unauthorized usage.

    confirmation
    Both devices display a 6-digit number on their screens; the user must confirm that both devices show the same number in order to initiate the connection
    pincode
    The remote device does not have a screen (for example, it might be a headset or a mouse). The device's manufacturer provides a PIN code which must be entered on the other device to complete pairing.
    passkey
    If the remote device is a text input device (such as a keyboard), a 6-digit number may be shown and the user must enter the key using that remote device.

    So an application managing pairing must handle three different pairing methods. To send the user answer to the remote device, the Bluetooth API provides the following methods: BluetoothAdapter.setPairingConfirmation(), BluetoothAdapter.setPinCode(), and BluetoothAdapter.setPasskey()

    var adapter;
    
    // Retreving the local device adapter is asynchronous, handle this carefully.
    navigator.mozBluetooth.getDefaultAdapter().success = function(evt) {
      adapter = evt.target.result;
    }
    
    function onPairing(message) {
      var reponse,
          request = message.detail,
          passkey = request.passkey;
    
      switch (request.method) {
        case 'confirmation':
          // Make sure the passkey is a string
          passkey = String(passkey);
          // Make sure the string is 6 characters long (pad with 0 if necessary)
          passkey = (new Array((6 - passkey.length) + 1)).join('0') + passkey;
          // Let's prompt the user
          response = confirm('Is that same number visible on the remote device screen: ' + passkey)
          // Let's send the confirmation
          adapter.setPairingConfirmation(request.address, response);
          break;
    
        case 'pincode':
          // Let's prompt the user
          response = prompt('Thanks to provide the remote device PIN code');
          // Let's send the pin code
          adapter.setPinCode(request.address, response);
          break;
    
        case 'passkey':
          // Let's prompt the user
          response = alert('Thanks to type the following code on the remote device');
          // Let's send back the passkey
          adapter.setPasskey(request.address, response);
          break;
      }
    }
    
    navigator.mozSetMessageHandler("bluetooth-pairing-request", onPairing);
    

    Once the pairing operation is complete on both sides, the application is notified of the success or failure of the operation through the pairedstatuschanged event where the callback handler is getting a BluetoothStatusChangedEvent.

    adapter.onpairedstatuschanged = function (evt) {
      if (evt.status) {
        alert("The pairing operation has been successfully completed");
      } else {
        alert("The pairing operation has failed. Please, try again");
      }
    }

    Compatibility notes

    • The Web Bluetooth API is implemented in Firefox OS 1.0.1 and above.
    • However, on Firefox OS <1.2, you need to be careful with Bluetooth file sharing. If you are sharing a file directly from the SDCard you are ok, but if you are sharing say, an image blob directly from the camera via a Web Activity you will run into problems, as Bluetooth is expecting a valid path to the SDCard as a file location (see B2G 1.0.1 Gaia Bluetooth app.) This is fixed in Firefox OS 1.2. In Firefox <1.2 you'd have to write it to an SDCard via Device Storage first, then transfer it via Bluetooth.
    • There is an added complication too: Device Storage is only available to privileged (packaged) apps, so if your app is hosted then you can't use Device Storage to solve the above problem.
    • Another problem you may run into when attempting to use Bluetooth File sharing between Firefox OS and another device is that the other devce may not have Bluetooth Sharing enabled (Firefox OS has it enabled by default.) For eample on Mac OSX 10.9 it is turned on via System Preferences > Sharing > check "Bluetooth Sharing"

    Specification

    Not part of any specification yet. It should be discussed as part of the W3C's System Applications Working Group.

     

    Document Tags and Contributors

    Last updated by: SpencerG,