WebAPI/WebBluetooth

This page is out-of-date. Needs to update.

WebBluetooth

Goals

The aim of WebBluetooth is to establish a DOM API to set up and communicate with Bluetooth devices. This includes setting properties on adapters and devices, scanning for devices, bonding, and socket initialization for audio and communication.

Future versions may include OBEX and profile support.

B2G Needs

Boot2Gecko is the main consumer of WebBluetooth for the moment. Most operating systems already provide a configuration layer for bluetooth, and we do not plan on overriding that. However, B2G will require its own settings and initialization code, so the focus of the API is on that platform for the time being.

Implementation Specifics

For communicating with the bluetooth adapter and devices on B2G, we will be using the DBus message system. This allows us to easily access all parts of the bluetooth system on B2G based platforms, without having to worry about GPL licensing issues.

DOM API

Manager

 interface nsIDOMBluetoothManager : nsIDOMEventTarget
 {
   readonly attribute bool enabled;
 
   nsIDOMDOMRequest setEnabled(in boolean enabled);
   nsIDOMDOMRequest getDefaultAdapter();
 };

Adapter

 interface nsIDOMBluetoothAdapter : nsIDOMEventTarget
 {    
   readonly attribute DOMString address;
   readonly attribute unsigned long class;
   readonly attribute bool enabled;
   readonly attribute bool discovering;
   readonly attribute DOMString name;                      // Set custom device name
   readonly attribute bool discoverable;                   // Set to false if this device would not like to be discovered
   readonly attribute unsigned long discoverabletimeout;   // Unit: sec
   
   // Since setting properties can require IPC calls based on the
   // bluetooth implementation, set properties via DOMRequests to
   // handle callbacks.
   nsIDOMDOMRequest setName(DOMString name);
   nsIDOMDOMRequest setDiscoverable(bool discoverable);
   nsIDOMDOMRequest setDiscoverableTimeout(unsigned long timeout);

   nsIDOMDOMRequest startDiscovery();
   nsIDOMDOMRequest stopDiscovery();    
   nsIDOMDOMRequest pair(in nsIDOMBluetoothDevice aDevice);
   nsIDOMDOMRequest unpair(in nsIDOMBluetoothDevice aDevice);
   nsIDOMDOMRequest getPairedDevices();
   nsIDOMBluetoothServerSocket listenRfcommSocket(in DOMString serviceName, in DOMString serviceUuid);
   
   attribute nsIDOMEventListener ondevicefound;        // Fired when discoverying and any device is discovered.
   attribute nsIDOMEventListener ondevicedisappeared;  // Fired when any device is out of discoverable range.
   attribute nsIDOMEventListener onpropertychanged;    // Fired when a property of the adapter is changed
 };

Device

 interface nsIDOMBluetoothDevice : nsISupports
 {
   readonly attribute DOMString address;
   readonly attribute unsigned long class;
   readonly attribute bool connected;
   readonly attribute DOMString icon;
   readonly attribute DOMString name;
   readonly attribute bool paired;
   readonly attribute jsval serviceUuids; // DOMString[]
   nsIDOMBluetoothSocket createRfcommSocket(in DOMString aServiceUuid);

   attribute nsIDOMEventListener onpropertychanged;
 };

Socket

 // Created by nsIDOMBluetoothDevice
 interface nsIDOMBluetoothSocket : nsISupports
 {
   void close();
   void connect();
   jsval read(in unsigned long length);
   void write(in jsval dataBuffer, in unsigned long offset, in unsigned long length);

   nsIDOMBluetoothDevice getRemoteDevice();
 };

 // Created by nsIDOMBluetoothAdapter
 interface nsIDOMBluetoothServerSocket : nsISupports
 {
   void close();
   nsIDOMBluetoothSocket accept();
 };

DBus Usage and Licensing

Bluetooth on Linux and B2G is accessed via the Bluez bluetooth stack. This stack is GPL, and the libraries that come with it to access bluetooth sockets are also GPL. To remove the licensing issues involved with this, the DBus communications layer is used to provide an IPC route for bluetooth related code. The WebBluetooth API (on Linux and B2G) will use DBus to keep the code compatible with the MPL.

DBus on Linux and Android

There are many ways to access DBus from code. On linux, gecko already uses the glib bindings for battery information on linux (UPowerClient.cpp). Android uses the low level DBus bindings, mainly made for writing language binding systems. This tends to create very complicated code, which even the DBus maintainers warn developers off of (See DBus API Documentation). Even so, due to the dbus-c++ library depending on exceptions (though the Chromium project is working on fixing that) and not wanting to fold in glib to B2G, we'll be using the low-level DBus API for B2G's WebBluetooth layer.

Links

Bugzilla

• bug 674737

External

• DBus Intro
• Android Bluetooth Manual
• Android Bluetooth Architecture
• Bluetool C++ Bluez Interaction Code
• Android Bluetooth FAQ

Relevant Source Code

• Frameworks JNI Core
  • BluetoothService JNI
  • BluetoothEventLoop JNI
• Bluedroid