Bluetooth Extension API

For Developers‎ > ‎Design Documents‎ > ‎Extensions‎ > ‎Proposed & Proposing New Changes‎ > ‎API Proposals (New APIs Start Here)‎ > ‎

Proposal Date

Last updated 2012-03-07

Who is the primary contact for this API?
keybuk@chromium.org

Who will be responsible for this API? (Team please, not an individual)

Apps Extension API Team

Overview
A bluetooth API that is (eventually) at least on par with the Android and iOS APIs. Version 1 will support basic RFCOMM communication. Profile support will be left for a future version.

Use cases
This API will allow extensions to communicate with bluetooth devices.

Do you know anyone else, internal or external, that is also interested in this API?

I'm not aware of anyone at this time.

Could this API be part of the web platform?
Eventually, yes.

Do you expect this API to be fairly stable? How might it be extended or changed in the future?
I expect the functionality proposed in this API to be stable. Additional functionality may be added in the future, but changes will be backwards-compatible.

List every UI surface belonging to or potentially affected by your API:
Bluetooth Settings Panel.

How could this API be abused?
- bluetooth can be very resource intensive, causing battery drain for devices running extensions using this API

Describe any concerns you have with exposing this API. Particular attention should be given to issues of security, privacy and performance.

Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):
1)
2)
3)

Alright Doctor, one last challenge:
Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?
Another main tenet of the Chrome Web Platform is that extensions and apps should “leave no trace” when they are removed. If someone using your API could leave lasting changes, we need to know.

How would you implement your desired features if this API didn't exist?
It would be impossible.

Draft API spec

Methods

acceptConnections

chrome.experimental.bluetooth.acceptConnections(string uuid, stringservice_name, string service_description, function callback)

Accept incoming bluetooth connections by advertising as a service.

Parameters

uuid ( string ): The UUID of the service being advertised.
service_name ( string ): The human-readable name of the service being advertised.
service_description ( string ): The human-readable description of the service being advertised.
callback ( function ): Called once for each connection that is established.

Callback function

The callback parameter should specify a function that looks like this:

function(BluetoothSocket result) {...};

result ( BluetoothSocket ): A bluetooth socket identifier that can be used to communicate with the connected device.

connect

chrome.experimental.bluetooth.connect(BluetoothDevice device, string uuid, function callback)

Connect to a service on a bluetooth device.

Parameters

device ( BluetoothDevice ): The target device of the connection.
uuid ( string ): The target service of the connection.
callback ( function ): Called when the connection is established.

Callback function

The callback parameter should specify a function that looks like this:

function(BluetoothSocket result) {...};

result ( BluetoothSocket ): A bluetooth socket identifier that can be used to communicate with the connected device.

disconnect

chrome.experimental.bluetooth.disconnect(BluetoothSocket socket, function callback)

Close the bluetooth connection specified by socket.

Parameters

socket ( BluetoothSocket ): The bluetooth socket to read from.
callback ( optional function ): Called with a boolean value to indicate success.

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(boolean result) {...};

result ( boolean ): True if successful, false otherwise.

getBluetoothAddress

chrome.experimental.bluetooth.getBluetoothAddress(function callback)

Get the bluetooth address of the system.

Parameters

callback ( function ): Called with the result.

Callback function

The callback parameter should specify a function that looks like this:

function(string result) {...};

result ( string ): The bluetooth address of the system.

getDevicesWithService

chrome.experimental.bluetooth.getDevicesWithService(string service_uuid, function callback)

Request a list of bluetooth devices that support service.

Parameters

service_uuid ( string ): The UUID of the desired service.
callback ( function ): Called with a list of bluetooth devices.

Callback function

The callback parameter should specify a function that looks like this:

function(array of BluetoothDevice results) {...};

results ( array of BluetoothDevice ): An array of BluetoothDevice objects, all of which provide the specified service.

getOutOfBandPairingData

chrome.experimental.bluetooth.getOutOfBandPairingData(function callback)

Get the local Out of Band Pairing data.

Parameters

callback ( function ): Called with the Out of Band Pairing data.

Callback function

The callback parameter should specify a function that looks like this:

function(array of ArrayBuffer result) {...};

result ( array of ArrayBuffer ): The local Out of Band Pairing data. The array will have length exactly 2 (or be null, in case of an error).

isBluetoothCapable

chrome.experimental.bluetooth.isBluetoothCapable(function callback)

Check if this extension has access to bluetooth.

Parameters

callback ( function ): Called with the result.

Callback function

The callback parameter should specify a function that looks like this:

function(boolean result) {...};

result ( boolean ): True if the extension has access to bluetooth, false otherwise.

isBluetoothPowered

chrome.experimental.bluetooth.isBluetoothPowered(function callback)

Check if the bluetooth adapter has power.

Parameters

callback ( function ): Called with the result.

Callback function

The callback parameter should specify a function that looks like this:

function(boolean result) {...};

result ( boolean ): True if the bluetooth adapter has power, false otherwise.

read

chrome.experimental.bluetooth.read(BluetoothSocket socket, function callback)

Read data from a bluetooth connection.

Parameters

socket ( BluetoothSocket ): The bluetooth socket to read from.
callback ( function ): Called when data is available.

Callback function

The callback parameter should specify a function that looks like this:

function(ArrayBuffer result) {...};

result ( ArrayBuffer ): An ArrayBuffer of data.

setOutOfBandPairingData

chrome.experimental.bluetooth.setOutOfBandPairingData(string bluetooth_address, array of ArrayBuffer data,function callback)

Set the Out of Band Pairing data for the bluetooth device at bluetooth_address.

Parameters

bluetooth_address ( string ): The bluetooth address that is supplying the data.
data ( array of ArrayBuffer ): An array of length exactly equal to 2 containing the Out of Band Pairing data for the device at bluetooth_address.
callback ( optional function ): Called with a boolean value to indicate success.

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(boolean result) {...};

result ( boolean ): True if successful, false otherwise.

write

chrome.experimental.bluetooth.write(BluetoothSocket socket, ArrayBuffer data, function callback)

Write data to a bluetooth connection.

Parameters

socket ( BluetoothSocket ): The bluetooth socket to read from.
data ( ArrayBuffer ): The data to be written.
callback ( function ): Called with a boolean value to indicate success.

Callback function

The callback parameter should specify a function that looks like this:

function(boolean result) {...};

result ( boolean ): True if successful, false otherwise.

Events

onBluetoothAvailabilityChange

chrome.experimental.bluetooth.onBluetoothAvailabilityChange.addListener(function(boolean available) {...});

Fired when the availability of bluetooth on the system changes.

Listener parameters

available ( boolean ): True if bluetooth is available, false otherwise.

onBluetoothPoweredChange

chrome.experimental.bluetooth.onBluetoothPoweredChange.addListener(function(boolean powered) {...});

Fired when the powered state of bluetooth on the system changes.

Listener parameters

powered ( boolean ): True if bluetooth is powered on, false otherwise.

Types

BluetoothDevice

( object )

Used to identify a specific bluetooth device to the system.

address ( string ): The address of the bluetooth device.
name ( string ): The name of the bluetooth device.

BluetoothSocket

( object )

Used to identify a bluetooth socket to the system.

id ( integer ): The id of the socket.

Open questions
Note any unanswered questions that require further discussion.

Comments