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.

Firefox OS Needs

Firefox OS 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, Firefox OS will require its own settings and initialization code, so the focus of the API is on that platform for the time being.

Current Status

Firefox OS v2.2 (feature landing target on: 2014/11/24) will adopt refined Bluetooth APIs as listed in DOM API section. Detailed documentation and the latest refinement progress can be found in WebBluetooth-v2. In addition, Firefox OS v2.2 will also expose Bluetooth Low Energy (BLE) Generic Attribute Profile (GATT) client APIs to 3rd party web apps. Privileged apps will be able to develop BLE profiles and control customized bluetooth LE devices.

W3C Bluetooth Community Group is discussing on specification for Bluetooth APIs to allow websites to communicate with devices in a secure and privacy-preserving way. Google has proposed an intial API and use cases. Mozilla also participates in discussion to integrate Firefox OS Bluetooth APIs into the finalized version. See section Google Bluetooth APIs for more information about Google Bluetooth APIs.

DOM API (Since Firefox OS 2.2)

BluetoothManager.webidl

[CheckPermissions="bluetooth"]
interface BluetoothManager: EventTarget
{
  readonly attribute BluetoothAdapter? defaultAdapter;

           attribute EventHandler onattributechanged;
           attribute EventHandler onadapteradded;
           attribute EventHandler onadapterremoved;

  sequence<BluetoothAdapter> getAdapters();
};

enum BluetoothManagerAttribute
{
  "unknown",
  "defaultAdapter"
};

BluetoothAdapter.webidl

// MediaMetadata and MediaPlayStatus are used to keep data from Applications.
// Please see specification of AVRCP 1.3 for more details.
dictionary MediaMetaData
{
  // track title
  DOMString   title = "";
  // artist name
  DOMString   artist = "";
  // album name
  DOMString   album = "";
  // track number
  long long   mediaNumber = -1;
  // number of tracks in the album
  long long   totalMediaCount = -1;
  // playing time (ms)
  long long   duration = -1;
};

dictionary MediaPlayStatus
{
  // current track length (ms)
  long long   duration = -1;
  // playing time (ms)
  long long   position = -1;
  // one of 'STOPPED'/'PLAYING'/'PAUSED'/'FWD_SEEK'/'REV_SEEK'/'ERROR'
  DOMString   playStatus = "";
};

enum BluetoothAdapterState
{
  "disabled",
  "disabling",
  "enabled",
  "enabling"
};

enum BluetoothAdapterAttribute
{
  "unknown",
  "state",
  "address",
  "name",
  "discoverable",
  "discovering"
};

[CheckPermissions="bluetooth"]
interface BluetoothAdapter : EventTarget {
  readonly attribute BluetoothAdapterState  state;
  readonly attribute DOMString              address;
  readonly attribute DOMString              name;
  readonly attribute boolean                discoverable;
  readonly attribute boolean                discovering;

  [AvailableIn=CertifiedApps]
  readonly attribute BluetoothPairingListener pairingReqs;
 
  // Fired when a2dp connection status changed
           attribute EventHandler   ona2dpstatuschanged;

  // Fired when handsfree connection status changed
           attribute EventHandler   onhfpstatuschanged;

  // Fired when sco connection status changed
           attribute EventHandler   onscostatuschanged;

  // Fired when remote devices query current media play status
           attribute EventHandler   onrequestmediaplaystatus;

  // Fired when attributes of BluetoothAdapter changed
           attribute EventHandler   onattributechanged;

  // Fired when a remote device gets paired with the adapter
           attribute EventHandler   ondevicepaired;

  // Fired when a remote device gets unpaired from the adapter
           attribute EventHandler   ondeviceunpaired;

  /**
   * Enable/Disable a local bluetooth adapter by asynchronus methods and return
   * its result through a Promise.
   *
   * Several onattributechanged events would be triggered during processing the
   * request, and the last one would indicate adapter.state becomes
   * enabled/disabled.
  */
  [NewObject, Throws]
  Promise<void> enable();
  [NewObject, Throws]
  Promise<void> disable();

  [NewObject, Throws]
  Promise<void> setName(DOMString aName);
  [NewObject, Throws]
  Promise<void> setDiscoverable(boolean aDiscoverable);

  [NewObject, Throws]
  Promise<BluetoothDiscoveryHandle> startDiscovery();
  [NewObject, Throws]
  Promise<void> stopDiscovery();

  [NewObject, Throws]
  Promise<void> Promise pair(DOMString deviceAddress);
  [NewObject, Throws]
  Promise unpair(DOMString deviceAddress);

  sequence<BluetoothDevice> getPairedDevices();

  [NewObject, Throws]
  DOMRequest getConnectedDevices(unsigned short serviceUuid);

  /**
   * Connect/Disconnect to a specific service of a target remote device.
   * To check the value of service UUIDs, please check "Bluetooth Assigned
   * Numbers" / "Service Discovery Protocol" for more information.
   *
   * Note that service UUID is optional. If it isn't passed when calling
   * Connect, multiple profiles are tried sequentially based on the class of
   * device (CoD). If it isn't passed when calling Disconnect, all connected
   * profiles are going to be closed.
   *
   * Reply success if the connection of any profile is successfully
   * established/released; reply error if we failed to connect/disconnect all
   * of the planned profiles.
   *
   * @param device Remote device
   * @param profile 2-octets service UUID. This is optional.
   */
  [NewObject, Throws]
  DOMRequest connect(BluetoothDevice device, optional unsigned short serviceUuid);

  [NewObject, Throws]
  DOMRequest disconnect(BluetoothDevice device, optional unsigned short serviceUuid);

  // One device can only send one file at a time
  [NewObject, Throws]
  DOMRequest sendFile(DOMString deviceAddress, Blob blob);
  [NewObject, Throws]
  DOMRequest stopSendingFile(DOMString deviceAddress);
  [NewObject, Throws]
  DOMRequest confirmReceivingFile(DOMString deviceAddress, boolean confirmation);

  // Connect/Disconnect SCO (audio) connection
  [NewObject, Throws]
  DOMRequest connectSco();
  [NewObject, Throws]
  DOMRequest disconnectSco();
  [NewObject, Throws]
  DOMRequest isScoConnected();

  /**
   * Additional HFP methods to handle CDMA network.
   *
   * In GSM network we observe call operations from RIL call state changes;
   * however in CDMA network RIL call states do not change under some call
   * operations, so we need these additional methods to be informed of these
   * operations from dialer.
   *
   * For more information please refer to bug 912005 and 925638.
   */
  [NewObject, Throws]
  DOMRequest answerWaitingCall();
  [NewObject, Throws]
  DOMRequest ignoreWaitingCall();
  [NewObject, Throws]
  DOMRequest toggleCalls();

  // AVRCP 1.3 methods
  [NewObject,Throws]
  DOMRequest sendMediaMetaData(optional MediaMetaData mediaMetaData);
  [NewObject,Throws]
  DOMRequest sendMediaPlayStatus(optional MediaPlayStatus mediaPlayStatus);
};

BluetoothDevice.webidl

[CheckPermissions="bluetooth"]
interface BluetoothDevice : EventTarget
{
  readonly attribute DOMString              address;
  readonly attribute BluetoothClassOfDevice cod;
  readonly attribute DOMString              name;
  readonly attribute boolean                paired;

  [Cached, Pure]
  readonly attribute sequence<DOMString>    uuids;

           attribute EventHandler           onattributechanged;

  /**
   * Fetch the up-to-date UUID list of each bluetooth service that the device
   * provides and refresh the cache value of attribute uuids if it is updated.
   *
   * If the operation succeeds, the promise will be resolved with up-to-date
   * UUID list which is identical to attribute uuids.
   */
  [NewObject, Throws]
  Promise<sequence<DOMString>>              fetchUuids();
};

/*
 * Set of attributes that might be changed and reported by attributechanged
 * event.
 * Address is not included since it should not be changed once BluetoothDevice
 * is created.
 */
enum BluetoothDeviceAttribute
{
  "unknown",
  "cod",
  "name",
  "paired",
  "uuids"
};

DOM API (Until Firefox OS 2.1)

Check pre-2.2 DOM API if you are interested in WebBluetooth API until Firefox OS v2.1.