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.
Note: With Chrome 56, users can select nearby Bluetooth Low Energy devices to provide to web sites that use the Web Bluetooth API.
Summary
Types | |
---|---|
Service | |
Characteristic | |
Descriptor | |
Request | |
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)
| |
createService −
chrome.bluetoothLowEnergy.createService( Service service, function callback)
| |
getServices −
chrome.bluetoothLowEnergy.getServices(string deviceAddress, function callback)
| |
getCharacteristic −
chrome.bluetoothLowEnergy.getCharacteristic(string characteristicId, function callback)
| |
createCharacteristic −
chrome.bluetoothLowEnergy.createCharacteristic( Characteristic characteristic, string serviceId, 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)
| |
createDescriptor −
chrome.bluetoothLowEnergy.createDescriptor( Descriptor descriptor, string characteristicId, 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)
| |
notifyCharacteristicValueChanged −
chrome.bluetoothLowEnergy.notifyCharacteristicValueChanged(string characteristicId, object notification, function callback)
| |
readDescriptorValue −
chrome.bluetoothLowEnergy.readDescriptorValue(string descriptorId, function callback)
| |
writeDescriptorValue −
chrome.bluetoothLowEnergy.writeDescriptorValue(string descriptorId, ArrayBuffer value, function callback)
| |
registerService −
chrome.bluetoothLowEnergy.registerService(string serviceId, function callback)
| |
unregisterService −
chrome.bluetoothLowEnergy.unregisterService(string serviceId, function callback)
| |
removeService −
chrome.bluetoothLowEnergy.removeService(string serviceId, function callback)
| |
registerAdvertisement −
chrome.bluetoothLowEnergy.registerAdvertisement(object advertisement, function callback)
| |
unregisterAdvertisement −
chrome.bluetoothLowEnergy.unregisterAdvertisement(integer advertisementId, function callback)
| |
resetAdvertising −
chrome.bluetoothLowEnergy.resetAdvertising(function callback)
| |
setAdvertisingInterval −
chrome.bluetoothLowEnergy.setAdvertisingInterval(integer minInterval, integer maxInterval, function callback)
| |
sendRequestResponse −
chrome.bluetoothLowEnergy.sendRequestResponse(object response)
| |
Events | |
onServiceAdded | |
onServiceChanged | |
onServiceRemoved | |
onCharacteristicValueChanged | |
onDescriptorValueChanged | |
onCharacteristicReadRequest | |
onCharacteristicWriteRequest | |
onDescriptorReadRequest | |
onDescriptorWriteRequest |
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 | (optional) service |
The GATT service this characteristic belongs to. |
array of enum of "broadcast" , "read" , "writeWithoutResponse" , "write" , "notify" , "indicate" , "authenticatedSignedWrites" , "extendedProperties" , "reliableWrite" , "writableAuxiliaries" , "encryptRead" , "encryptWrite" , "encryptAuthenticatedRead" , or "encryptAuthenticatedWrite" |
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 | (optional) characteristic |
The GATT characteristic this descriptor belongs to. |
array of enum of "read" , "write" , "encryptedRead" , "encryptedWrite" , "encryptedAuthenticatedRead" , or "encryptedAuthenticatedWrite" |
permissions |
Since Chrome 52. The permissions of this descriptor. |
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. |
Request
Since Chrome 52.
properties | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
integer | requestId |
Unique ID for this request. Use this ID when responding to this request. |
|||||||||
object | device |
Device that send this request.
|
|||||||||
ArrayBuffer | (optional) value |
Value to write (if this is a write request). |
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).
|
|||
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)
createService
chrome.bluetoothLowEnergy.createService( Service service, function callback)
Since Chrome 52.
Create a locally hosted GATT service. This service can be registered to be available on a local GATT server. This function is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
Parameters | |||||
---|---|---|---|---|---|
Service | service |
The service to create. |
|||
function | callback |
Called with the created services's unique ID. The callback parameter should be a function that looks like this: function(string serviceId) {...};
|
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.
Note: If service discovery is not yet complete on the device, this API will return a subset (possibly empty) of services. A work around is to add a time based delay and/or call repeatedly until the expected number of services is returned.
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) {...};
|
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) {...};
|
createCharacteristic
chrome.bluetoothLowEnergy.createCharacteristic( Characteristic characteristic, string serviceId, function callback)
Since Chrome 52.
Create a locally hosted GATT characteristic. This characteristic must be hosted under a valid service. If the service ID is not valid, the lastError will be set. This function is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
Parameters | |||||
---|---|---|---|---|---|
Characteristic | characteristic |
The characteristic to create. |
|||
string | serviceId |
ID of the service to create this characteristic for. |
|||
function | callback |
Called with the created characteristic's unique ID. The callback parameter should be a function that looks like this: function(string characteristicId) {...};
|
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) {...};
|
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) {...};
|
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) {...};
|
createDescriptor
chrome.bluetoothLowEnergy.createDescriptor( Descriptor descriptor, string characteristicId, function callback)
Since Chrome 52.
Create a locally hosted GATT descriptor. This descriptor must be hosted under a valid characteristic. If the characteristic ID is not valid, the lastError will be set. This function is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
Parameters | |||||
---|---|---|---|---|---|
Descriptor | descriptor |
The descriptor to create. |
|||
string | characteristicId |
ID of the characteristic to create this descriptor for. |
|||
function | callback |
Called with the created descriptor's unique ID. The callback parameter should be a function that looks like this: function(string descriptorId) {...};
|
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) {...};
|
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 The callback parameter should be a function that looks like this: function( 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).
|
|||
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() {...};
|
notifyCharacteristicValueChanged
chrome.bluetoothLowEnergy.notifyCharacteristicValueChanged(string characteristicId, object notification, function callback)
Since Chrome 52.
Notify a remote device of a new value for a characteristic. If the shouldIndicate flag in the notification object is true, an indication will be sent instead of a notification. Note, the characteristic needs to correctly set the 'notify' or 'indicate' property during creation for this call to succeed. This function is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
Parameters | ||||||||
---|---|---|---|---|---|---|---|---|
string | characteristicId |
The characteristic to send the notication for. |
||||||
object | notification |
|
||||||
function | callback |
Callback called once the notification or indication has been sent successfully. The callback parameter 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 The callback parameter should be a function that looks like this: function( 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() {...};
|
registerService
chrome.bluetoothLowEnergy.registerService(string serviceId, function callback)
Since Chrome 52.
Register the given service with the local GATT server. If the service ID is invalid, the lastError will be set. This function is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
Parameters | ||
---|---|---|
string | serviceId |
Unique ID of a created service. |
function | callback |
Callback with the result of the register operation. The callback parameter should be a function that looks like this: function() {...};
|
unregisterService
chrome.bluetoothLowEnergy.unregisterService(string serviceId, function callback)
Since Chrome 52.
Unregister the given service with the local GATT server. If the service ID is invalid, the lastError will be set. This function is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
Parameters | ||
---|---|---|
string | serviceId |
Unique ID of a current registered service. |
function | callback |
Callback with the result of the register operation. The callback parameter should be a function that looks like this: function() {...};
|
removeService
chrome.bluetoothLowEnergy.removeService(string serviceId, function callback)
Since Chrome 52.
Remove the specified service, unregistering it if it was registered. If the service ID is invalid, the lastError will be set. This function is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
Parameters | ||
---|---|---|
string | serviceId |
Unique ID of a current registered service. |
function | (optional) callback |
Callback called once the service is removed. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
registerAdvertisement
chrome.bluetoothLowEnergy.registerAdvertisement(object advertisement, function callback)
Since Chrome 47.
Create an advertisement and register it for advertising. To call this function, the app must have the bluetooth:low_energy and bluetooth:peripheral permissions set to true. Additionally this API is only available to auto launched apps in Kiosk Mode or by setting the '--enable-ble-advertising-in-apps' command-line switch. See https://developer.chrome.com/apps/manifest/bluetooth Note: On some hardware, central and peripheral modes at the same time is supported but on hardware that doesn't support this, making this call will switch the device to peripheral mode. In the case of hardware which does not support both central and peripheral mode, attempting to use the device in both modes will lead to undefined behavior or prevent other central-role applications from behaving correctly (including the discovery of Bluetooth Low Energy devices).
Parameters | |||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | advertisement |
The advertisement to advertise.
|
|||||||||||||||||||||||||||
function | callback |
Called once the registeration is done and we've started advertising. Returns the id of the created advertisement. The callback parameter should be a function that looks like this: function(integer advertisementId) {...};
|
unregisterAdvertisement
chrome.bluetoothLowEnergy.unregisterAdvertisement(integer advertisementId, function callback)
Since Chrome 47.
Unregisters an advertisement and stops its advertising. If the advertisement fails to unregister the only way to stop advertising might be to restart the device.
Parameters | ||
---|---|---|
integer | advertisementId |
Id of the advertisement to unregister. |
function | callback |
Called once the advertisement is unregistered and is no longer being advertised. The callback parameter should be a function that looks like this: function() {...};
|
resetAdvertising
chrome.bluetoothLowEnergy.resetAdvertising(function callback)
Since Chrome 61.
Resets advertising on the current device. It will unregister and stop all existing advertisements.
Parameters | ||
---|---|---|
function | callback |
Called once the advertisements are reset. The callback parameter should be a function that looks like this: function() {...};
|
setAdvertisingInterval
chrome.bluetoothLowEnergy.setAdvertisingInterval(integer minInterval, integer maxInterval, function callback)
Since Chrome 55.
Set's the interval betweeen two consecutive advertisements. Note: This is a best effort. The actual interval may vary non-trivially from the requested intervals. On some hardware, there is a minimum interval of 100ms. The minimum and maximum values cannot exceed the the range allowed by the Bluetooth 4.2 specification.
Parameters | ||
---|---|---|
integer | minInterval |
Minimum interval between advertisments (in milliseconds). This cannot be lower than 20ms (as per the spec). |
integer | maxInterval |
Maximum interval between advertisments (in milliseconds). This cannot be more than 10240ms (as per the spec). |
function | callback |
Called once the interval has been set. The callback parameter should be a function that looks like this: function() {...};
|
sendRequestResponse
chrome.bluetoothLowEnergy.sendRequestResponse(object response)
Since Chrome 52.
Sends a response for a characteristic or descriptor read/write request. This function is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
Parameters | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
object | response |
The response to the request.
|
Events
onServiceAdded
Fired whan a new GATT service has been discovered on a remote device.
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.
onServiceRemoved
Fired when a GATT service that was previously discovered on a remote device has been 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) {...};
|
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) {...};
|
onCharacteristicReadRequest
Since Chrome 52.
Fired when a connected central device requests to read the value of a characteristic registered on the local GATT server. Not responding to this request for a long time may lead to a disconnection. This event is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
addListener
chrome.bluetoothLowEnergy.onCharacteristicReadRequest.addListener(function callback)
onCharacteristicWriteRequest
Since Chrome 52.
Fired when a connected central device requests to write the value of a characteristic registered on the local GATT server. Not responding to this request for a long time may lead to a disconnection. This event is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
addListener
chrome.bluetoothLowEnergy.onCharacteristicWriteRequest.addListener(function callback)
onDescriptorReadRequest
Since Chrome 52.
Fired when a connected central device requests to read the value of a descriptor registered on the local GATT server. Not responding to this request for a long time may lead to a disconnection. This event is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
addListener
chrome.bluetoothLowEnergy.onDescriptorReadRequest.addListener(function callback)
onDescriptorWriteRequest
Since Chrome 52.
Fired when a connected central device requests to write the value of a descriptor registered on the local GATT server. Not responding to this request for a long time may lead to a disconnection. This event is only available if the app has both the bluetooth:low_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps.
addListener
chrome.bluetoothLowEnergy.onDescriptorWriteRequest.addListener(function callback)