Bluetooth Extension API
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.