Web Bluetooth API (Firefox OS)

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.

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 devicefound, devicepaired 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

Obsolete interfaces

BluetoothStatusChangedEvent

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

Specifications

Browser Compatibility

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