This API is experimental. It is only available to Chrome users on the dev channel.

chrome.bluetooth

Description: Use the chrome.bluetooth API to connect to a Bluetooth device. All functions report failures via chrome.runtime.lastError.
Availability: Dev channel only.
Manifest: "bluetooth": {...}
Learn More: Bluetooth

Summary

Types
AdapterState
Device
Profile
Socket
OutOfBandPairingData
Methods
getAdapterState chrome.bluetooth.getAdapterState(function callback)
getDevices chrome.bluetooth.getDevices(function callback)
getDevice chrome.bluetooth.getDevice(string deviceAddress, function callback)
addProfile chrome.bluetooth.addProfile( Profile profile, function callback)
removeProfile chrome.bluetooth.removeProfile( Profile profile, function callback)
connect chrome.bluetooth.connect(object options, function callback)
disconnect chrome.bluetooth.disconnect(object options, function callback)
send chrome.bluetooth.send(integer socketId, ArrayBuffer data, function callback)
updateSocket chrome.bluetooth.updateSocket(integer socketId, object properties, function callback)
setSocketPaused chrome.bluetooth.setSocketPaused(integer socketId, boolean paused, function callback)
getSocket chrome.bluetooth.getSocket(integer socketId, function callback)
getSockets chrome.bluetooth.getSockets(function callback)
getLocalOutOfBandPairingData chrome.bluetooth.getLocalOutOfBandPairingData(function callback)
setOutOfBandPairingData chrome.bluetooth.setOutOfBandPairingData(object options, function callback)
startDiscovery chrome.bluetooth.startDiscovery(function callback)
stopDiscovery chrome.bluetooth.stopDiscovery(function callback)
Events
onAdapterStateChanged
onDeviceAdded
onDeviceChanged
onDeviceRemoved
onConnection
onReceive
onReceiveError

Types

AdapterState

properties
string address The address of the adapter, in the format 'XX:XX:XX:XX:XX:XX'.
string name The human-readable name of the adapter.
boolean powered Indicates whether or not the adapter has power.
boolean available Indicates whether or not the adapter is available (i.e. enabled).
boolean discovering Indicates whether or not the adapter is currently discovering.

Device

properties
string address The address of the device, in the format 'XX:XX:XX:XX:XX:XX'.
string (optional) name The human-readable name of the device.
integer (optional) deviceClass The class of the device, a bit-field defined by http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband.
enum of "bluetooth", or "usb" (optional) vendorIdSource The Device ID record of the device, where available.
integer (optional) vendorId
integer (optional) productId
integer (optional) deviceId
enum of "computer", "phone", "modem", "audio", "carAudio", "video", "peripheral", "joystick", "gamepad", "keyboard", "mouse", "tablet", or "keyboardMouseCombo" (optional) type The type of the device, if recognized by Chrome. This is obtained from the |deviceClass| field and only represents a small fraction of the possible device types. When in doubt you should use the |deviceClass| field directly.
boolean (optional) paired Indicates whether or not the device is paired with the system.
boolean (optional) connected Indicates whether the device is currently connected to the system.
array of string (optional) uuids UUIDs of protocols, profiles and services advertised by the device. For classic Bluetooth devices, this list is obtained from EIR data and SDP tables. For Low Energy devices, this list is obtained from AD and GATT primary services. For dual mode devices this may be obtained from both.

Profile

properties
string uuid Unique profile identifier, e.g. 00001401-0000-1000-8000-00805F9B23FB
string (optional) name Human-readable name of the Profile, e.g. "Health Device"
integer (optional) channel The RFCOMM channel id, used when the profile is to be exported to remote devices.
integer (optional) psm The LS2CAP PSM number, used when the profile is to be exported to remote devices.
boolean (optional) requireAuthentication Specifies whether pairing (and encryption) is required to be able to connect.
boolean (optional) requireAuthorization Specifies whether user authorization is required to be able to connect.
boolean (optional) autoConnect Specifies whether this profile will be automatically connected if any other profile of device also exporting this profile connects to the host.
integer (optional) version Specifies the implemented version of the profile.
integer (optional) features Specifies the profile-specific bit field of features the implementation supports.

Socket

properties
integer id The socket identifier.
Device device The remote Bluetooth device associated with this socket.
string uuid The remote Bluetooth uuid associated with this socket.
boolean persistent Flag indicating whether the socket is left open when the application is suspended (see SocketProperties.persistent).
string (optional) name Application-defined string associated with the socket.
integer (optional) bufferSize The size of the buffer used to receive data. If no buffer size has been specified explictly, the field is not provided.
boolean paused Flag indicating whether a connected socket blocks its peer from sending more data (see setPaused).

OutOfBandPairingData

properties
ArrayBuffer hash Simple Pairing Hash C. Always 16 octets long.
ArrayBuffer randomizer Simple Pairing Randomizer R. Always 16 octets long.

Methods

getAdapterState

chrome.bluetooth.getAdapterState(function callback)

Get information about the Bluetooth adapter.

Parameters
function callback Called with an AdapterState object describing the adapter state.

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

function( AdapterState result) {...};
AdapterState result

getDevices

chrome.bluetooth.getDevices(function callback)

Get a list of Bluetooth devices known to the system, including paired and recently discovered devices.

Parameters
function callback Called when the search is completed.

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

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

getDevice

chrome.bluetooth.getDevice(string deviceAddress, function callback)

Get information about a Bluetooth device known to the system.

Parameters
string deviceAddress Address of device to get.
function callback Called with the Device object describing the device.

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

function( Device result) {...};
Device result

addProfile

chrome.bluetooth.addProfile( Profile profile, function callback)

Registers the JavaScript application as an implementation for the given Profile; if a channel or PSM is specified, the profile will be exported in the host's SDP and GATT tables and advertised to other devices.

Parameters
Profile profile
function callback

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

function() {...};

removeProfile

chrome.bluetooth.removeProfile( Profile profile, function callback)

Unregisters the JavaScript application as an implementation for the given Profile; only the uuid field of the Profile object is used.

Parameters
Profile profile
function callback

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

function() {...};

connect

chrome.bluetooth.connect(object options, function callback)

Connect to a service on a device.

Parameters
object options The options for the connection.
Device device The connection is made to |device|.
Profile profile The connection is made to |profile|.
function callback Called to indicate success or failure.

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

function() {...};

disconnect

chrome.bluetooth.disconnect(object options, function callback)

Closes a Bluetooth connection.

Parameters
object options The options for this function.
integer socketId The socket identifier.
function (optional) callback Called to indicate success or failure.

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

function() {...};

send

chrome.bluetooth.send(integer socketId, ArrayBuffer data, function callback)

Sends data to a Bluetooth connection.

Parameters
integer socketId The socket identifier.
ArrayBuffer data The data to send.
function (optional) callback Called with the number of bytes sent.

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

function(integer result) {...};
integer result

updateSocket

chrome.bluetooth.updateSocket(integer socketId, object properties, function callback)

Updates the socket properties.

Parameters
integer socketId The socket identifier.
object properties The properties to update.
boolean (optional) persistent Flag indicating whether the socket is left open when the event page of the application is unloaded (see Manage App Lifecycle). The default value is false. When the application is loaded, any sockets previously opened with persistent=true can be fetched with $ref:getSockets.
string (optional) name An application-defined string associated with the socket.
integer (optional) bufferSize The size of the buffer used to receive data. The default value is 4096.
function (optional) callback Called when the properties are updated.

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

function() {...};

setSocketPaused

chrome.bluetooth.setSocketPaused(integer socketId, boolean paused, function callback)

Enables or disables the application from receiving messages from its peer. The default value is false. Pausing a socket is typically used by an application to throttle data sent by its peer. When a socket is paused, no $ref:onReceive event is raised. When a socket is connected and un-paused, $ref:onReceive events are raised again when messages are received.

Parameters
integer socketId
boolean paused
function (optional) callback

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

function() {...};

getSocket

chrome.bluetooth.getSocket(integer socketId, function callback)

Retrieves the state of the given socket.

Parameters
integer socketId The socket identifier.
function callback Called when the socket state is available.

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

function( Socket socket) {...};
Socket socket Object containing the socket information.

getSockets

chrome.bluetooth.getSockets(function callback)

Retrieves the list of currently opened sockets owned by the application.

Parameters
function callback Called when the list of sockets is available.

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

function(array of Socket sockets) {...};
array of Socket sockets Array of object containing socket information.

getLocalOutOfBandPairingData

chrome.bluetooth.getLocalOutOfBandPairingData(function callback)

Get the local Out of Band Pairing data.

Parameters
function callback Called with the data.

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

function( OutOfBandPairingData data) {...};
OutOfBandPairingData data

setOutOfBandPairingData

chrome.bluetooth.setOutOfBandPairingData(object options, function callback)

Set the Out of Band Pairing data for a remote device. Any previous Out Of Band Pairing Data for this device is overwritten.

Parameters
object options The options for this function.
string address The address of the remote device that the data should be associated with. |deviceAddress| should be in the format 'XX:XX:XX:XX:XX:XX'.
OutOfBandPairingData (optional) data The Out Of Band Pairing Data. If this is omitted, the data for the device is cleared instead.
function (optional) callback Called to indicate success or failure.

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

function() {...};

startDiscovery

chrome.bluetooth.startDiscovery(function callback)

Start discovery. Newly discovered devices will be returned via the onDeviceAdded event. Previously discovered devices already known to the adapter must be obtained using getDevices and will only be updated using the |onDeviceChanged| event if information about them changes.

Discovery will fail to start if this application has already called startDiscovery. Discovery can be resource intensive: stopDiscovery should be called as soon as possible.

Parameters
function (optional) callback Called to indicate success or failure.

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

function() {...};

stopDiscovery

chrome.bluetooth.stopDiscovery(function callback)

Stop discovery.

Parameters
function (optional) callback Called to indicate success or failure.

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

function() {...};

Events

onAdapterStateChanged

Fired when the state of the Bluetooth adapter changes.

addListener

chrome.bluetooth.onAdapterStateChanged.addListener(function callback)
Parameters
function callback

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

function( AdapterState state) {...};
AdapterState state The new state of the adapter.

onDeviceAdded

Fired when information about a new Bluetooth device is available.

addListener

chrome.bluetooth.onDeviceAdded.addListener(function callback)
Parameters
function callback

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

function( Device device) {...};
Device device

onDeviceChanged

Fired when information about a known Bluetooth device has changed.

addListener

chrome.bluetooth.onDeviceChanged.addListener(function callback)
Parameters
function callback

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

function( Device device) {...};
Device device

onDeviceRemoved

Fired when a Bluetooth device that was previously discovered has been out of range for long enough to be considered unavailable again, and when a paired device is removed.

addListener

chrome.bluetooth.onDeviceRemoved.addListener(function callback)
Parameters
function callback

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

function( Device device) {...};
Device device

onConnection

Fired when a connection has been made for a registered profile.

addListener

chrome.bluetooth.onConnection.addListener(function callback)
Parameters
function callback

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

function( Socket socket) {...};
Socket socket The socket for the connection.

onReceive

Event raised when data has been received for a given socket.

addListener

chrome.bluetooth.onReceive.addListener(function callback)
Parameters
function callback

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

function(object info) {...};
object info The event data.
integer socketId The socket identifier.
ArrayBuffer data The data received, with a maximum size of bufferSize.

onReceiveError

Event raised when a network error occured while the runtime was waiting for data on the socket. Once this event is raised, the socket is set to paused and no more onReceive events are raised for this socket.

addListener

chrome.bluetooth.onReceiveError.addListener(function callback)
Parameters
function callback

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

function(object info) {...};
object info The event data.
integer socketId The socket identifier.
string errorMessage The error message.
enum of "disconnected", or "system_error" error An error code indicating what went wrong.
disconnected
The connection was disconnected.
system_error
A system error occurred and the connection may be unrecoverable.