WebAPI/WebBluetooth

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);
   nsIDOMBluetoothAdapter getDefaultAdapter();
 };

Adapter

 interface nsIDOMBluetoothAdapter : nsIDOMEventTarget
 {
   nsIDOMDOMRequest setEnabled(bool enabled);
   bool startDiscovery();    // ret: false if bluetooth is not enabled
   void stopDiscovery();    
   nsIDOMBluetoothDevice getDevice(DOMString address);  // Like a device creator
   bool connect(in nsIDOMBluetoothDevice device);
   void disconnect(in nsIDOMBluetoothDevice device);
 
   readonly attribute DOMString address;
   readonly attribute unsigned long class;
   readonly attribute bool enabled;
   readonly attribute bool discovering;
   attribute DOMString name;                      // Set custom device name
   attribute bool discoverable;                   // Set to false if this device would not like to be discovered
   attribute unsigned long discoverabletimeout;   // Unit: sec
   
   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 ondeviceconnected;    // Fired when a remote device is connected
   attribute nsIDOMEventListener ondevicedisconnected; // Fired when a remote device is disconnected
 };

Device

 interface nsIDOMBluetoothDevice : nsISupports
 {
   readonly attribute DOMString address;
   readonly attribute unsigned long class;
   readonly attribute bool connected;
   readonly attribute DOMString name;
   readonly attribute jsval serviceUuids;
 };

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).

On B2G, we'd like to avoid tying glib into the gecko build. We'll be using the dbus-c++ library on that platform in order to keep the dbus code simple and clean.

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