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.

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.

Basic interfaces

The following interfaces provide an app with basic Bluetooth functionality

BluetoothManager
Allows access to all Bluetooth adapters available on the device. Adapters are the connection interface to connect another Bluetooth-enabled device to the current device.
BluetoothAdapter
Used to handle all the operations requested by Bluetooth networks.
BluetoothClassOfDevice
Provides identifying/classification information about a given remote Bluetooth device, available at discovery stage.
BluetoothDevice
Provides information regarding a given remote Bluetooth device.
BluetoothDiscoveryHandle
Used to notify the current application about the discovery of a remote bluetooth device.
BluetoothPairingHandle
Contains the functionality required for completing a device pairing operation, including passkeys, and mechanisms to reply to user-entered pin codes and confirm passkeys.
BluetoothPairingListener
Defines event handlers triggered for different pairing operations.

Gatt interfaces

The following interfaces allow Firefox OS to communicate with and consume Gatt (Generic Attribute Profile)-based services on remote Smart/LE (low energy) devices.

BluetoothGatt
Handles initial communications and connections with Gatt services.
BluetoothGattServer
Provides Bluetooth GATT server functionality to allow creation of Bluetooth Smart/LE services and characteristics.
BluetoothGattService
Represents a service provided by a GATT server, including the service definition, a list of included services, and a list of the characteristics of this service.
BluetoothGattCharacteristic
Represents a GATT service characteristic, which includes characteristic definition, value, properties and configuration info, and a list of descriptors that provide related information.
BluetoothGattDescriptor
Represents a GATT descriptor, which contains related information about a characteristic value.

Bluetooth event interfaces

These objects represent different events occuring within a Bluetooth interaction.

BluetoothAdapterEvent
Provides access to a BluetoothAdapter object and its address as the parameter of a adapteradded or adapterremoved event handler (see BluetoothManager.onadapteradded and BluetoothManager.onadapterremoved), when fired.
BluetoothAttributeEvent
Provides access to changed attributes and their new values as the parameter of attributechanged event handlers (including BluetoothManager.onattributechanged, BluetoothAdapter.onattributechanged, and BluetoothDevice.onattributechanged), when fired.
BluetoothDeviceEvent
Provides access to a found/paired device (BluetoothDevice) object or the address or an unpaired device as the parameter of a devicefounddevicepaired or deviceunpaired event handler (see BluetoothDiscoveryHandle.ondevicefound, BluetoothAdapter.ondevicepaired, BluetoothAdapter.ondeviceunpaired), when fired.
BluetoothGattCharacteristicEvent
Provides access to an updated BluetoothGattCharacteristic object as the parameter of the BluetoothGatt.oncharacteristicchanged, handler, when the characteristicchanged event is fired.
BluetoothLeDeviceEvent
Provides access to an LE device BluetoothDevice object and its RSSI value and advertisement record, as the parameter of a devicefound event handler (see BluetoothDiscoveryHandle.ondevicefound), when fired.
BluetoothPairingEvent
Provides access to a device's name and the BluetoothPairingHandle object required for pairing devices as the parameter of pairing-related handlers (for example including BluetoothPairingListener.ondisplaypasskeyreq and BluetoothPairingListener.onenterpincodereq), when fired.

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.

Obsolete interfaces

BluetoothStatusChangedEvent
Provides access to information regarding any change to the status of a Bluetooth device.

Specifications

Specification Status Comment
Web Bluetooth Draft Rough draft; not part of any official specification yet. It should be discussed as part of the W3C's System Applications Working Group.

Browser Compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support No support No support No support No support No support
Feature Android Android Webview Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile Chrome for Android
Bluetooth 'v2' support No support No support No support 2.1 No support No support No support No support
Bluetooth initial support: BluetoothManager, BluetoothAdapter, BluetoothDevice, BluetoothDeviceEvent, BluetoothStatusChangedEvent No support No support No support 1.0.1 No support No support No support No support

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"

See also

Using the Web Bluetooth API

Document Tags and Contributors

 Last updated by: chrisdavidmills,