WebAPI/WebBluetooth
Contents
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.