chrome.bluetoothLowEnergy

Description: The chrome.bluetoothLowEnergy API is used to communicate with Bluetooth Smart (Low Energy) devices using the Generic Attribute Profile (GATT).
Availability: Since Chrome 37.
Manifest: "bluetooth": {...}
Learn More: Bluetooth

Important: This API works only on Chrome OS.

Summary

Types
Service
Characteristic
Descriptor
Methods
connect − chrome.bluetoothLowEnergy.connect(string deviceAddress, object properties, function callback)
disconnect − chrome.bluetoothLowEnergy.disconnect(string deviceAddress, function callback)
getService − chrome.bluetoothLowEnergy.getService(string serviceId, function callback)
getServices − chrome.bluetoothLowEnergy.getServices(string deviceAddress, function callback)
getCharacteristic − chrome.bluetoothLowEnergy.getCharacteristic(string characteristicId, function callback)
getCharacteristics − chrome.bluetoothLowEnergy.getCharacteristics(string serviceId, function callback)
getIncludedServices − chrome.bluetoothLowEnergy.getIncludedServices(string serviceId, function callback)
getDescriptor − chrome.bluetoothLowEnergy.getDescriptor(string descriptorId, function callback)
getDescriptors − chrome.bluetoothLowEnergy.getDescriptors(string characteristicId, function callback)
readCharacteristicValue − chrome.bluetoothLowEnergy.readCharacteristicValue(string characteristicId, function callback)
writeCharacteristicValue − chrome.bluetoothLowEnergy.writeCharacteristicValue(string characteristicId, ArrayBuffer value, function callback)
startCharacteristicNotifications − chrome.bluetoothLowEnergy.startCharacteristicNotifications(string characteristicId, object properties, function callback)
stopCharacteristicNotifications − chrome.bluetoothLowEnergy.stopCharacteristicNotifications(string characteristicId, function callback)
readDescriptorValue − chrome.bluetoothLowEnergy.readDescriptorValue(string descriptorId, function callback)
writeDescriptorValue − chrome.bluetoothLowEnergy.writeDescriptorValue(string descriptorId, ArrayBuffer value, function callback)
Events
onServiceAdded
onServiceChanged
onServiceRemoved
onCharacteristicValueChanged
onDescriptorValueChanged

Types

Service

properties
string uuid

The UUID of the service, e.g. 0000180d-0000-1000-8000-00805f9b34fb.

boolean isPrimary

Indicates whether the type of this service is primary or secondary.

string (optional) instanceId

Returns the identifier assigned to this service. Use the instance ID to distinguish between services from a peripheral with the same UUID and to make function calls that take in a service identifier. Present, if this instance represents a remote service.

string (optional) deviceAddress

The device address of the remote peripheral that the GATT service belongs to. Present, if this instance represents a remote service.

Characteristic

properties
string uuid

The UUID of the characteristic, e.g. 00002a37-0000-1000-8000-00805f9b34fb.

Service service

The GATT service this characteristic belongs to.

array of enum of "broadcast", "read", "writeWithoutResponse", "write", "notify", "indicate", "authenticatedSignedWrites", "extendedProperties", "reliableWrite", or "writableAuxiliaries" properties

The properties of this characteristic.

string (optional) instanceId

Returns the identifier assigned to this characteristic. Use the instance ID to distinguish between characteristics from a peripheral with the same UUID and to make function calls that take in a characteristic identifier. Present, if this instance represents a remote characteristic.

ArrayBuffer (optional) value

The currently cached characteristic value. This value gets updated when the value of the characteristic is read or updated via a notification or indication.

Descriptor

properties
string uuid

The UUID of the characteristic descriptor, e.g. 00002902-0000-1000-8000-00805f9b34fb.

Characteristic characteristic

The GATT characteristic this descriptor belongs to.

string (optional) instanceId

Returns the identifier assigned to this descriptor. Use the instance ID to distinguish between descriptors from a peripheral with the same UUID and to make function calls that take in a descriptor identifier. Present, if this instance represents a remote characteristic.

ArrayBuffer (optional) value

The currently cached descriptor value. This value gets updated when the value of the descriptor is read.

Methods

connect

chrome.bluetoothLowEnergy.connect(string deviceAddress, object properties, function callback)

Establishes a connection between the application and the device with the given address. A device may be already connected and its GATT services available without calling connect, however, an app that wants to access GATT services of a device should call this function to make sure that a connection to the device is maintained. If the device is not connected, all GATT services of the device will be discovered after a successful call to connect.

Parameters
string deviceAddress

The Bluetooth address of the remote device to which a GATT connection should be opened.

object (optional) properties

Connection properties (optional).

boolean persistent

Flag indicating whether a connection to the device is left open when the event page of the application is unloaded (see Manage App Lifecycle). The default value is false.

function callback

Called when the connect request has completed.

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

function() {...};

disconnect

chrome.bluetoothLowEnergy.disconnect(string deviceAddress, function callback)

Closes the app's connection to the device with the given address. Note that this will not always destroy the physical link itself, since there may be other apps with open connections.

Parameters
string deviceAddress

The Bluetooth address of the remote device.

function (optional) callback

Called when the disconnect request has completed.

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

function() {...};

getService

chrome.bluetoothLowEnergy.getService(string serviceId, function callback)

Get the GATT service with the given instance ID.

Parameters
string serviceId

The instance ID of the requested GATT service.

function callback

Called with the requested Service object.

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

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

getServices

chrome.bluetoothLowEnergy.getServices(string deviceAddress, function callback)

Get all the GATT services that were discovered on the remote device with the given device address.

Parameters
string deviceAddress

The Bluetooth address of the remote device whose GATT services should be returned.

function callback

Called with the list of requested Service objects.

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

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

getCharacteristic

chrome.bluetoothLowEnergy.getCharacteristic(string characteristicId, function callback)

Get the GATT characteristic with the given instance ID that belongs to the given GATT service, if the characteristic exists.

Parameters
string characteristicId

The instance ID of the requested GATT characteristic.

function callback

Called with the requested Characteristic object.

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

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

getCharacteristics

chrome.bluetoothLowEnergy.getCharacteristics(string serviceId, function callback)

Get a list of all discovered GATT characteristics that belong to the given service.

Parameters
string serviceId

The instance ID of the GATT service whose characteristics should be returned.

function callback

Called with the list of characteristics that belong to the given service.

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

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

getIncludedServices

chrome.bluetoothLowEnergy.getIncludedServices(string serviceId, function callback)

Get a list of GATT services that are included by the given service.

Parameters
string serviceId

The instance ID of the GATT service whose included services should be returned.

function callback

Called with the list of GATT services included from the given service.

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

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

getDescriptor

chrome.bluetoothLowEnergy.getDescriptor(string descriptorId, function callback)

Get the GATT characteristic descriptor with the given instance ID.

Parameters
string descriptorId

The instance ID of the requested GATT characteristic descriptor.

function callback

Called with the requested Descriptor object.

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

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

getDescriptors

chrome.bluetoothLowEnergy.getDescriptors(string characteristicId, function callback)

Get a list of GATT characteristic descriptors that belong to the given characteristic.

Parameters
string characteristicId

The instance ID of the GATT characteristic whose descriptors should be returned.

function callback

Called with the list of descriptors that belong to the given characteristic.

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

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

readCharacteristicValue

chrome.bluetoothLowEnergy.readCharacteristicValue(string characteristicId, function callback)

Retrieve the value of a specified characteristic from a remote peripheral.

Parameters
string characteristicId

The instance ID of the GATT characteristic whose value should be read from the remote device.

function callback

Called with the Characteristic object whose value was requested. The value field of the returned Characteristic object contains the result of the read request.

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

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

writeCharacteristicValue

chrome.bluetoothLowEnergy.writeCharacteristicValue(string characteristicId, ArrayBuffer value, function callback)

Write the value of a specified characteristic from a remote peripheral.

Parameters
string characteristicId

The instance ID of the GATT characteristic whose value should be written to.

ArrayBuffer value

The value that should be sent to the remote characteristic as part of the write request.

function callback

Called when the write request has completed.

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

function() {...};

startCharacteristicNotifications

chrome.bluetoothLowEnergy.startCharacteristicNotifications(string characteristicId, object properties, function callback)

Enable value notifications/indications from the specified characteristic. Once enabled, an application can listen to notifications using the onCharacteristicValueChanged event.

Parameters
string characteristicId

The instance ID of the GATT characteristic that notifications should be enabled on.

object (optional) properties

Notification session properties (optional).

boolean persistent

Flag indicating whether the app should receive notifications when the event page of the application is unloaded (see Manage App Lifecycle). The default value is false.

function callback

Called when the request has completed.

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

function() {...};

stopCharacteristicNotifications

chrome.bluetoothLowEnergy.stopCharacteristicNotifications(string characteristicId, function callback)

Disable value notifications/indications from the specified characteristic. After a successful call, the application will stop receiving notifications/indications from this characteristic.

Parameters
string characteristicId

The instance ID of the GATT characteristic on which this app's notification session should be stopped.

function (optional) callback

Called when the request has completed (optional).

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

function() {...};

readDescriptorValue

chrome.bluetoothLowEnergy.readDescriptorValue(string descriptorId, function callback)

Retrieve the value of a specified characteristic descriptor from a remote peripheral.

Parameters
string descriptorId

The instance ID of the GATT characteristic descriptor whose value should be read from the remote device.

function callback

Called with the Descriptor object whose value was requested. The value field of the returned Descriptor object contains the result of the read request.

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

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

writeDescriptorValue

chrome.bluetoothLowEnergy.writeDescriptorValue(string descriptorId, ArrayBuffer value, function callback)

Write the value of a specified characteristic descriptor from a remote peripheral.

Parameters
string descriptorId

The instance ID of the GATT characteristic descriptor whose value should be written to.

ArrayBuffer value

The value that should be sent to the remote descriptor as part of the write request.

function callback

Called when the write request has completed.

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

function() {...};

Events

onServiceAdded

Fired whan a new GATT service has been discovered on a remote device.

addListener

chrome.bluetoothLowEnergy.onServiceAdded.addListener(function callback)
Parameters
function callback

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

function( Service service) {...};
Service service

The GATT service that was added.

onServiceChanged

Fired when the state of a remote GATT service changes. This involves any characteristics and/or descriptors that get added or removed from the service, as well as "ServiceChanged" notifications from the remote device.

addListener

chrome.bluetoothLowEnergy.onServiceChanged.addListener(function callback)
Parameters
function callback

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

function( Service service) {...};
Service service

The GATT service whose state has changed.

onServiceRemoved

Fired when a GATT service that was previously discovered on a remote device has been removed.

addListener

chrome.bluetoothLowEnergy.onServiceRemoved.addListener(function callback)
Parameters
function callback

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

function( Service service) {...};
Service service

The GATT service that was removed.

onCharacteristicValueChanged

Fired when the value of a remote GATT characteristic changes, either as a result of a read request, or a value change notification/indication This event will only be sent if the app has enabled notifications by calling startCharacteristicNotifications.

addListener

chrome.bluetoothLowEnergy.onCharacteristicValueChanged.addListener(function callback)
Parameters
function callback

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

function( Characteristic characteristic) {...};
Characteristic characteristic

The GATT characteristic whose value has changed.

onDescriptorValueChanged

Fired when the value of a remote GATT characteristic descriptor changes, usually as a result of a read request. This event exists mostly for convenience and will always be sent after a successful call to readDescriptorValue.

addListener

chrome.bluetoothLowEnergy.onDescriptorValueChanged.addListener(function callback)
Parameters
function callback

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

function( Descriptor descriptor) {...};
Descriptor descriptor

The GATT characteristic descriptor whose value has changed.