Under Construction

This is a draft for bluetooth API refinement.
This page is not complete.

Overview

The BluetoothAdapter API is used to handle all the operations requested by Bluetooth networks. A Bluetooth adapter is the physical interface which is used to interact with local Bluetooth device. In the whole Bluetooth API, it's the most important interface because it is used to manage all the interactions between local Bluetooth device and remote Bluetooth devices.

TODO: This section is in the process of an expansion.

Interface

Under construction

interface BluetoothDevice: EventTarget
{
  readonly attribute BluetoothAdapterState state;
  readonly attribute DOMString address;
  readonly attribute DOMString name;
  readonly attribute bool discoverable;
  readonly attribute bool discovering;

  attribute EventHandler onattributechanged;
  attribute EventHandler ondevicepaired;
  attribute EventHandler ondeviceunpaired;

  DOMRequest enable();
  DOMRequest disable();
  DOMRequest setName(DOMString aName);
  DOMRequest setDiscoverable(boolean aDiscoverable);
  DOMRequest startDiscovery();
  DOMRequest stopDiscovery();
  DOMRequest pair(DOMString aAddress);
  DOMRequest unpair();
  DOMRequest setPasskey(DOMString aAddress, DOMString aPasskey);
  DOMRequest setPairingConfirmation(DOMString aAddress, boolean aConfirm);
  DOMRequest getPairedDevices();
};

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

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

Attributes

state

Description: The state provides current state of the local Bluetooth adapter. Possible values are disabled, disabling, enabled, enabling.

Value type: BluetoothAdapterState

Default value: disabled

Sample

var state = instanceOfBluetoothAdapter.state;

address

Description: The address attribute provides the address of the device's adapter on the bluetooth micro-network.

Value type: DOMString

Default value: Empty string ("")

Sample

var address = instanceOfBluetoothAdapter.address;

name

Description: The name attribute provides the human readable name of the device's adapter.

Value type: DOMString

Default value: Empty string ("")

Sample

var name = instanceOfBluetoothAdapter.name;

discoverable

Description: The discoverable attribute indicates if the device is discoverable (true) or not (false) by other bluetooth devices.

Value type: boolean

Default value: false

Sample

var discoverable = instanceOfBluetoothAdapter.discoverable;

discovering

Description: The discovering attribute indicates if the device is in the process of discovering (true) or not (false) surrounding bluetooth devices.

Value type: boolean

Default value: false

Sample

var state = instanceOfBluetoothAdapter.discovering;

Event Handlers

onattributechanged

Description: A handler to trigger when a attribute of the local bluetooth adapter is changed. The event carries evt.attr as the BluetoothAdapterAttribute of the changed attribute, and evt.value as the updated value.

Parameters

aAttr

A BluetoothAdapterAttribute object indicate which attribute has changed.

aValue

A jsval representing the updated value of the changed attribute.

Sample

function bt_onAttributeChanged(aAttr, aValue) {
  switch (aAttr) {
    case BluetoothAdapterAttribute.state:
      // do your things here
      break
    case BluetoothAdapterAttribute.address:
      // do your things here
      break;
    case BluetoothAdapterAttribute.name:
      // do your things here
      break;
    case BluetoothAdapterAttribute.discoverable:
      // do your things here
      break;
    case BluetoothAdapterAttribute.discovering:
      // do your things here
      break;
    default:
      break;
  }
}

instanceOfBluetoothAdapter.onattributechanged = bt_onAttributeChanged;

Note: If users try to access the 'changed' attribute inside this function, they should get the updated value.

ondevicepaired

Description: A handler to trigger paired device updated when a device get paired.
Parameter: device; A BluetoothDevice object representing the paired device.

ondeviceunpaired

Description: A handler to trigger unpaired device updated when a device get unpaired.
Parameter: address; The Bluetooth MAC address of the unpaired device.

ondisplaypasskeyreq

Description: A handler to trigger display Passkey on the screen. The event will be notified to confirm the passkey displayed on the screen. When this event is been triggered, the remote device shall enter the same numeric passkeys as displaying on the screen. The pairing initiator display, the responder input.

This scenario usually applies to Bluetooth HID keyboard.

Parameter: pairingEvent; The event carries a BluetoothPairingEvent object, and only for displaying passkey (BluetoothPairingEvent.passkey).

onenterpasskeyreq

Description: A handler to trigger user or application to enter PIN code or Passkey. The event will be notified for entering key.
Parameter: pairingEvent; The event carries a BluetoothPairingEvent object, BluetoothPairingEvent.passkey shall have remain empty.

onpairingconfirmationreq

Description: The event will be triggered when using the 'numeric comparision' as the authentication model. The user will be prompted to confirm the passkey displayed on the screen or an app will confirm the passkey for the user.
Parameter: pairingEvent; The event carries a BluetoothPairingEvent object, BluetoothPairingEvent.passkey shall be numeric value (passkey) entered by user.; Valid values are decimal 000000 - 999999.

onpairingconsentreq

Description: The event will be triggered when using the 'numeric comparision' authentication if there is an incoming pairing request. The user will be prompted to confirm the incoming pairing request. Usually the remote device only has very limited input/output cababilities.; pairingEvent; The event carries a BluetoothPairingEvent object, BluetoothPairingEvent.passkey shall be 0.
Note: This event will be triggered when: 1. Pairing request is an incoming pairing request 2. Local IO capabilities are DisplayYesNo 3. Remote IO capabiltiies are DisplayOnly or NoInputNoOutput.

Methods

Under construction

enable()

Description: Turn on the local Bluetooth adapter.

Return: A DOMRequest object to handle the success or error of the operation. In case of success, it means that the enable operation has completed.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.enable();
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note: DOMRequest onsucess will be returned after onattributechanged which indicates state of the adapter is enabled.; instanceOfBluetoothAdapter.state should be enabling when the function finish.

disable()

Description: Turn off the local Bluetooth adapter.

Return: A DOMRequest object to handle the success or error of the operation. In case of success, it means that the disable operation has completed; if the bluetooth adapter is currently disabled, the DOMRequest's onerror is called.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.disable();
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note: DOMRequest's onsucess is called after onattributechanged which indicates state of the adapter is disabled.; instanceOfBluetoothAdapter.state should be disabling when the function finish.

setName()

Description: Set the friendly Bluetooth name of the local Bluetooth adapter.; This name is visible to remote Bluetooth devices.; If Bluetooth adapter is not currently enabled, the event onerror would occur.

Parameters

aName

A string representing the new name to set.

Return: A DOMRequest object to handle the success or error of the operation. In case of success, it means that the name has been set.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var name = "The name of Bluetooth adapter";
var request = aAdapter.setName(name);
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note: DOMRequest onsucess will be returned after onattributechanged fired with the new name.; If this parameter aName is same as instanceOfBluetoothDevice.name, the onerror event would occur.

setDiscoverable()

Description: The setDiscoverable method is used to change the value of the discoverable property for the device's adapter.; If Bluetooth adapter is not currently enabled, the event onerror would occur.

Parameters

aDiscoverable

A boolean indicating if the device is discoverable (true) or not (false).

Return: A DOMRequest object to handle the success or error of the operation. In case of success, it means that the adapter could currently be discovered.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.setDiscoverable(BooleanFlag);
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note: DOMRequest onsucess will be returned after onattributechanged which indicates the adapter is discoverable.; If this parameter aDiscoverable is same as instanceOfBluetoothDevice.discoverable, the onerror event would occur.

startDiscovery()

Description: The startDiscovery method is used to have the device's adapter start seeking for remote devices.; If Bluetooth adapter is not currently enabled, the event onerror would occur.; The discovery process may be terminated after discovering a period of time. An onattributechanged event would be fired in that case.

Return

A BluetoothStartDiscoveryRequest object which extends from DOMRequest to handle the discovered devices.

BluetoothStartDiscoveryRequest.ondevicefound

ondevicefound(BluetoothDevice aDevice) is a event listener which receive devicefound events.

The event occur with parameter aDevice when a Bluetooth device is discovered in the surrounding area.

It may or may not be fired. It depends on if there is any discoverable Bluetooth devices around.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.startDiscovery();
request.ondevicefound = function () {
  ...
}
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note: DOMRequest onsucess will be returned after onattributechanged which indicates the adapter is discovering.

stopDiscovery()

Description: The stopDiscovery method is used to have the device's adapter stop seeking for remote devices.; If Bluetooth adapter is not currently enabled, the event onerror would occur.

Return: A DOMRequest object to handle the success or error of the operation.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.stopDiscovery();
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note: DOMRequest onsucess will be returned after onattributechanged which indicates the adapter is not discovering.; Adapter may still receive ondevicefound event until onsuccess is fired.

pair()

Description: The pair method is used to start pairing a remote device with the device's adapter.
Parameters: deviceAddress; A DOMString object representing the device to pair with. Format is Bluetooth valid a known MAC address.
Return

A DOMRequest object to handle the success or error of the operation. In case of success, it means that the pair operation has completed.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.pair('00:80:98:09:0B:5D');
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note: DOMRequest onsucess will be returned after ondevicepaired; Gecko informs Setting app of pairing method via system message

unpair()

Description: The unpair method is used to unpair a remote device from the device's adapter.
Parameters: deviceAddress; A DOMString object representing the device to pair with. Format is Bluetooth valid a known MAC address.
Return: A DOMRequest object to handle the success or error of the operation. In case of success, it means that the pair operation has completed.

Note: DOMRequest onsucess will be returned after ondeviceunpaired

setPasskey()

Description: The setPasskey method is used to send back the requested Passkey when the device's adapter tries to pair with a remote device. The setPasskey method is to reply to onenterpasskeyreq event.
Parameters: deviceAddress; A DOMString object representing the device to pair with. Format is Bluetooth valid a known MAC address.; passkey; A DOMString object representing a number representing the Passkey code set by the user.
Return: A DOMRequest object to handle the success or error of the operation. In case of success, it means that the pair operation has completed.
Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.setPasskey('00:80:98:09:0B:5D', '0000');
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note: This method is to reply onenterpasskeyreq. The passkey can be considered both PIN key reply (legacy pairing) and SSP passkey reply.

setPairingConfirmation()

Description: The setPairingConfirmation method is used to send back the pairing confirmation when the device's adapter tries to pair itself with a remote device.
Parameters: deviceAddress; A DOMString object representing the device to pair with. Format is Bluetooth valid a known MAC address.; confirm; A boolean indicating if the passkey of the numeric comparision pairing event is matched(true) or not matched(false).
Return: A DOMRequest object to handle the success or error of the operation. In case of success, it means that the pair operation has completed.
Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
// when users press the confirmation button
var request = adapter.setPairingConfirmation('00:80:98:09:0B:5D', true);
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note: This method is to reply onpairingconfirmationreq event

getPairedDevices()

Description: The getPairedDevices method is used to retrieve the full list of all devices paired with the device's adapter.
Return: A DOMRequest object to handle the success or error of the operation. In case of success, the request's result is an Array of BluetoothDevice objects.
Sample

var req = defaultAdapter.getPairedDevices();
  req.onsuccess = function bt_getPairedSuccess() {
    var paired = req.result.slice();
    var length = paired.length;
    for (var i = 0; i < length; i++) {
      (function(device) {
        console.log(device.address);
      })(paired[i]);
    }
}

B2G/Bluetooth/WebBluetooth-v2/BluetoothAdapter

Contents

Under Construction

Overview

Interface

Attributes

state

address

name

discoverable

discovering

Event Handlers

onattributechanged

ondevicepaired

ondeviceunpaired

ondisplaypasskeyreq

onenterpasskeyreq

onpairingconfirmationreq

onpairingconsentreq

Methods

enable()

disable()

setName()

setDiscoverable()

startDiscovery()

stopDiscovery()

pair()

unpair()

setPasskey()

setPairingConfirmation()

getPairedDevices()

See also