chrome.bluetoothLowEnergy
- Description
The
chrome.bluetoothLowEnergy
API is used to communicate with Bluetooth Smart (Low Energy) devices using the Generic Attribute Profile (GATT).
Summary
- Types
- Methods
chrome.bluetoothLowEnergy.connect(deviceAddress: string, properties?: ConnectProperties, callback: function)
chrome.bluetoothLowEnergy.createCharacteristic(characteristic: Characteristic, serviceId: string, callback: function)
chrome.bluetoothLowEnergy.createDescriptor(descriptor: Descriptor, characteristicId: string, callback: function)
chrome.bluetoothLowEnergy.createService(service: Service, callback: function)
chrome.bluetoothLowEnergy.disconnect(deviceAddress: string, callback: function)
chrome.bluetoothLowEnergy.getCharacteristic(characteristicId: string, callback: function)
chrome.bluetoothLowEnergy.getCharacteristics(serviceId: string, callback: function)
chrome.bluetoothLowEnergy.getDescriptor(descriptorId: string, callback: function)
chrome.bluetoothLowEnergy.getDescriptors(characteristicId: string, callback: function)
chrome.bluetoothLowEnergy.getIncludedServices(serviceId: string, callback: function)
chrome.bluetoothLowEnergy.getService(serviceId: string, callback: function)
chrome.bluetoothLowEnergy.getServices(deviceAddress: string, callback: function)
chrome.bluetoothLowEnergy.notifyCharacteristicValueChanged(characteristicId: string, notification: Notification, callback: function)
chrome.bluetoothLowEnergy.readCharacteristicValue(characteristicId: string, callback: function)
chrome.bluetoothLowEnergy.readDescriptorValue(descriptorId: string, callback: function)
chrome.bluetoothLowEnergy.registerAdvertisement(advertisement: Advertisement, callback: function)
chrome.bluetoothLowEnergy.registerService(serviceId: string, callback: function)
chrome.bluetoothLowEnergy.removeService(serviceId: string, callback: function)
chrome.bluetoothLowEnergy.resetAdvertising(callback: function)
chrome.bluetoothLowEnergy.sendRequestResponse(response: Response)
chrome.bluetoothLowEnergy.setAdvertisingInterval(minInterval: number, maxInterval: number, callback: function)
chrome.bluetoothLowEnergy.startCharacteristicNotifications(characteristicId: string, properties?: NotificationProperties, callback: function)
chrome.bluetoothLowEnergy.stopCharacteristicNotifications(characteristicId: string, callback: function)
chrome.bluetoothLowEnergy.unregisterAdvertisement(advertisementId: number, callback: function)
chrome.bluetoothLowEnergy.unregisterService(serviceId: string, callback: function)
chrome.bluetoothLowEnergy.writeCharacteristicValue(characteristicId: string, value: ArrayBuffer, callback: function)
chrome.bluetoothLowEnergy.writeDescriptorValue(descriptorId: string, value: ArrayBuffer, callback: function)
- Events
Types
Advertisement
Properties
- manufacturerDataManufacturerData[] optional
List of manufacturer specific data to be included in "Manufacturer Specific Data" fields of the advertising data.
- serviceDataServiceData[] optional
List of service data to be included in "Service Data" fields of the advertising data.
- serviceUuidsstring[] optional
List of UUIDs to include in the "Service UUIDs" field of the Advertising Data. These UUIDs can be of the 16bit, 32bit or 128 formats.
- solicitUuidsstring[] optional
List of UUIDs to include in the "Solicit UUIDs" field of the Advertising Data. These UUIDs can be of the 16bit, 32bit or 128 formats.
Type of advertisement.
Characteristic
Properties
- instanceIdstring optional
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.
- properties
The properties of this characteristic.
- serviceService optional
The GATT service this characteristic belongs to.
- uuidstring
The UUID of the characteristic, e.g. 00002a37-0000-1000-8000-00805f9b34fb.
- valueArrayBuffer optional
The currently cached characteristic value. This value gets updated when the value of the characteristic is read or updated via a notification or indication.
ConnectProperties
Properties
- persistentboolean
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.
Descriptor
Properties
- characteristicCharacteristic optional
The GATT characteristic this descriptor belongs to.
- instanceIdstring optional
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.
- permissions
The permissions of this descriptor.
- uuidstring
The UUID of the characteristic descriptor, e.g. 00002902-0000-1000-8000-00805f9b34fb.
- valueArrayBuffer optional
The currently cached descriptor value. This value gets updated when the value of the descriptor is read.
Device
Properties
- addressstring
The address of the device, in the format 'XX:XX:XX:XX:XX:XX'.
- deviceClassnumber optional
The class of the device, a bit-field defined by http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband.
- namestring optional
The human-readable name of the device.
ManufacturerData
Properties
- datanumber[]
- idnumber
Notification
Properties
- shouldIndicateboolean optional
Optional flag for sending an indication instead of a notification.
- valueArrayBuffer
New value of the characteristic.
NotificationProperties
Properties
- persistentboolean
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
.
Request
Properties
- device
Device that send this request.
- requestIdnumber
Unique ID for this request. Use this ID when responding to this request.
- valueArrayBuffer optional
Value to write (if this is a write request).
Response
Properties
- isErrorboolean
If this is an error response, this should be true.
- requestIdnumber
Id of the request this is a response to.
- valueArrayBuffer optional
Response value. Write requests and error responses will ignore this parameter.
Service
Properties
- deviceAddressstring optional
The device address of the remote peripheral that the GATT service belongs to. Present, if this instance represents a remote service.
- instanceIdstring optional
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.
- isPrimaryboolean
Indicates whether the type of this service is primary or secondary.
- uuidstring
The UUID of the service, e.g. 0000180d-0000-1000-8000-00805f9b34fb.
ServiceData
Properties
- datanumber[]
- uuidstring
AdvertisementType
Type of advertisement. If 'broadcast' is chosen, the sent advertisement type will be ADV_NONCONN_IND and the device will broadcast with a random MAC Address. If set to 'peripheral', the advertisement type will be ADV_IND or ADV_SCAN_IND and the device will broadcast with real Bluetooth Adapter's MAC Address.
Enum
"broadcast"
, or "peripheral"
CharacteristicProperty
Values representing the possible properties of a characteristic. Characteristic permissions are inferred from these properties. Please see the Bluetooth 4.x spec to see the meaning of each individual property.
Enum
"broadcast"
, "read"
, "writeWithoutResponse"
, "write"
, "notify"
, "indicate"
, "authenticatedSignedWrites"
, "extendedProperties"
, "reliableWrite"
, "writableAuxiliaries"
, "encryptRead"
, "encryptWrite"
, "encryptAuthenticatedRead"
, or "encryptAuthenticatedWrite"
DescriptorPermission
Values representing possible permissions for a descriptor. Please see the Bluetooth 4.x spec to see the meaning of each individual permission.
Enum
"read"
, "write"
, "encryptedRead"
, "encryptedWrite"
, "encryptedAuthenticatedRead"
, or "encryptedAuthenticatedWrite"
Methods
connect
chrome.bluetoothLowEnergy.connect(deviceAddress: string, properties?: ConnectProperties, callback: function)
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
- deviceAddressstring
The Bluetooth address of the remote device to which a GATT connection should be opened.
- propertiesConnectProperties optional
Connection properties (optional).
- callbackfunction
Called when the connect request has completed.
The callback parameter should be a function that looks like this:
() => {...}
createCharacteristic
chrome.bluetoothLowEnergy.createCharacteristic(characteristic: Characteristic, serviceId: string, callback: function)
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
The characteristic to create.
- serviceIdstring
ID of the service to create this characteristic for.
- callbackfunction
Called with the created characteristic's unique ID.
The callback parameter should be a function that looks like this:
(characteristicId: string) => {...}
- characteristicIdstring
createDescriptor
chrome.bluetoothLowEnergy.createDescriptor(descriptor: Descriptor, characteristicId: string, callback: function)
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
The descriptor to create.
- characteristicIdstring
ID of the characteristic to create this descriptor for.
- callbackfunction
Called with the created descriptor's unique ID.
The callback parameter should be a function that looks like this:
(descriptorId: string) => {...}
- descriptorIdstring
createService
chrome.bluetoothLowEnergy.createService(service: Service, callback: function)
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
The service to create.
- callbackfunction
Called with the created services's unique ID.
The callback parameter should be a function that looks like this:
(serviceId: string) => {...}
- serviceIdstring
disconnect
chrome.bluetoothLowEnergy.disconnect(deviceAddress: string, callback: function)
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
- deviceAddressstring
The Bluetooth address of the remote device.
- callbackfunction
Called when the disconnect request has completed.
The callback parameter should be a function that looks like this:
() => {...}
getCharacteristic
chrome.bluetoothLowEnergy.getCharacteristic(characteristicId: string, callback: function)
Get the GATT characteristic with the given instance ID that belongs to the given GATT service, if the characteristic exists.
Parameters
- characteristicIdstring
The instance ID of the requested GATT characteristic.
- callbackfunction
Called with the requested Characteristic object.
The callback parameter should be a function that looks like this:
(result: Characteristic) => {...}
- result
getCharacteristics
chrome.bluetoothLowEnergy.getCharacteristics(serviceId: string, callback: function)
Get a list of all discovered GATT characteristics that belong to the given service.
Parameters
- serviceIdstring
The instance ID of the GATT service whose characteristics should be returned.
- callbackfunction
Called with the list of characteristics that belong to the given service.
The callback parameter should be a function that looks like this:
(result: Characteristic[]) => {...}
- result
getDescriptor
chrome.bluetoothLowEnergy.getDescriptor(descriptorId: string, callback: function)
Get the GATT characteristic descriptor with the given instance ID.
Parameters
- descriptorIdstring
The instance ID of the requested GATT characteristic descriptor.
- callbackfunction
Called with the requested Descriptor object.
The callback parameter should be a function that looks like this:
(result: Descriptor) => {...}
- result
getDescriptors
chrome.bluetoothLowEnergy.getDescriptors(characteristicId: string, callback: function)
Get a list of GATT characteristic descriptors that belong to the given characteristic.
Parameters
- characteristicIdstring
The instance ID of the GATT characteristic whose descriptors should be returned.
- callbackfunction
Called with the list of descriptors that belong to the given characteristic.
The callback parameter should be a function that looks like this:
(result: Descriptor[]) => {...}
- result
getIncludedServices
chrome.bluetoothLowEnergy.getIncludedServices(serviceId: string, callback: function)
Get a list of GATT services that are included by the given service.
getService
chrome.bluetoothLowEnergy.getService(serviceId: string, callback: function)
Get the GATT service with the given instance ID.
getServices
chrome.bluetoothLowEnergy.getServices(deviceAddress: string, callback: function)
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.
notifyCharacteristicValueChanged
chrome.bluetoothLowEnergy.notifyCharacteristicValueChanged(characteristicId: string, notification: Notification, callback: function)
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
- characteristicIdstring
The characteristic to send the notication for.
- notification
- callbackfunction
Callback called once the notification or indication has been sent successfully.
The callback parameter should be a function that looks like this:
() => {...}
readCharacteristicValue
chrome.bluetoothLowEnergy.readCharacteristicValue(characteristicId: string, callback: function)
Retrieve the value of a specified characteristic from a remote peripheral.
Parameters
- characteristicIdstring
The instance ID of the GATT characteristic whose value should be read from the remote device.
- callbackfunction
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:
(result: Characteristic) => {...}
- result
readDescriptorValue
chrome.bluetoothLowEnergy.readDescriptorValue(descriptorId: string, callback: function)
Retrieve the value of a specified characteristic descriptor from a remote peripheral.
Parameters
- descriptorIdstring
The instance ID of the GATT characteristic descriptor whose value should be read from the remote device.
- callbackfunction
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:
(result: Descriptor) => {...}
- result
registerAdvertisement
chrome.bluetoothLowEnergy.registerAdvertisement(advertisement: Advertisement, callback: function)
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
- advertisement
The advertisement to advertise.
- callbackfunction
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:
(advertisementId: number) => {...}
- advertisementIdnumber
registerService
chrome.bluetoothLowEnergy.registerService(serviceId: string, callback: function)
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
- serviceIdstring
Unique ID of a created service.
- callbackfunction
Callback with the result of the register operation.
The callback parameter should be a function that looks like this:
() => {...}
removeService
chrome.bluetoothLowEnergy.removeService(serviceId: string, callback: function)
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
- serviceIdstring
Unique ID of a current registered service.
- callbackfunction
Callback called once the service is removed.
The callback parameter should be a function that looks like this:
() => {...}
resetAdvertising
chrome.bluetoothLowEnergy.resetAdvertising(callback: function)
Resets advertising on the current device. It will unregister and stop all existing advertisements.
Parameters
- callbackfunction
Called once the advertisements are reset.
The callback parameter should be a function that looks like this:
() => {...}
sendRequestResponse
chrome.bluetoothLowEnergy.sendRequestResponse(response: Response)
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
- response
The response to the request.
setAdvertisingInterval
chrome.bluetoothLowEnergy.setAdvertisingInterval(minInterval: number, maxInterval: number, callback: function)
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
- minIntervalnumber
Minimum interval between advertisments (in milliseconds). This cannot be lower than 20ms (as per the spec).
- maxIntervalnumber
Maximum interval between advertisments (in milliseconds). This cannot be more than 10240ms (as per the spec).
- callbackfunction
Called once the interval has been set.
The callback parameter should be a function that looks like this:
() => {...}
startCharacteristicNotifications
chrome.bluetoothLowEnergy.startCharacteristicNotifications(characteristicId: string, properties?: NotificationProperties, callback: function)
Enable value notifications/indications from the specified characteristic. Once enabled, an application can listen to notifications using the onCharacteristicValueChanged
event.
Parameters
- characteristicIdstring
The instance ID of the GATT characteristic that notifications should be enabled on.
- propertiesNotificationProperties optional
Notification session properties (optional).
- callbackfunction
Called when the request has completed.
The callback parameter should be a function that looks like this:
() => {...}
stopCharacteristicNotifications
chrome.bluetoothLowEnergy.stopCharacteristicNotifications(characteristicId: string, callback: function)
Disable value notifications/indications from the specified characteristic. After a successful call, the application will stop receiving notifications/indications from this characteristic.
Parameters
- characteristicIdstring
The instance ID of the GATT characteristic on which this app's notification session should be stopped.
- callbackfunction
Called when the request has completed (optional).
The callback parameter should be a function that looks like this:
() => {...}
unregisterAdvertisement
chrome.bluetoothLowEnergy.unregisterAdvertisement(advertisementId: number, callback: function)
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
- advertisementIdnumber
Id of the advertisement to unregister.
- callbackfunction
Called once the advertisement is unregistered and is no longer being advertised.
The callback parameter should be a function that looks like this:
() => {...}
unregisterService
chrome.bluetoothLowEnergy.unregisterService(serviceId: string, callback: function)
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
- serviceIdstring
Unique ID of a current registered service.
- callbackfunction
Callback with the result of the register operation.
The callback parameter should be a function that looks like this:
() => {...}
writeCharacteristicValue
chrome.bluetoothLowEnergy.writeCharacteristicValue(characteristicId: string, value: ArrayBuffer, callback: function)
Write the value of a specified characteristic from a remote peripheral.
Parameters
- characteristicIdstring
The instance ID of the GATT characteristic whose value should be written to.
- valueArrayBuffer
The value that should be sent to the remote characteristic as part of the write request.
- callbackfunction
Called when the write request has completed.
The callback parameter should be a function that looks like this:
() => {...}
writeDescriptorValue
chrome.bluetoothLowEnergy.writeDescriptorValue(descriptorId: string, value: ArrayBuffer, callback: function)
Write the value of a specified characteristic descriptor from a remote peripheral.
Parameters
- descriptorIdstring
The instance ID of the GATT characteristic descriptor whose value should be written to.
- valueArrayBuffer
The value that should be sent to the remote descriptor as part of the write request.
- callbackfunction
Called when the write request has completed.
The callback parameter should be a function that looks like this:
() => {...}
Events
onCharacteristicReadRequest
chrome.bluetoothLowEnergy.onCharacteristicReadRequest.addListener(listener: function)
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.
onCharacteristicValueChanged
chrome.bluetoothLowEnergy.onCharacteristicValueChanged.addListener(listener: function)
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
.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(characteristic: Characteristic) => {...}
- characteristic
The GATT characteristic whose value has changed.
onCharacteristicWriteRequest
chrome.bluetoothLowEnergy.onCharacteristicWriteRequest.addListener(listener: function)
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.
onDescriptorReadRequest
chrome.bluetoothLowEnergy.onDescriptorReadRequest.addListener(listener: function)
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.
onDescriptorValueChanged
chrome.bluetoothLowEnergy.onDescriptorValueChanged.addListener(listener: function)
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
.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(descriptor: Descriptor) => {...}
- descriptor
The GATT characteristic descriptor whose value has changed.
onDescriptorWriteRequest
chrome.bluetoothLowEnergy.onDescriptorWriteRequest.addListener(listener: function)
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.
onServiceAdded
chrome.bluetoothLowEnergy.onServiceAdded.addListener(listener: function)
Fired whan a new GATT service has been discovered on a remote device.
onServiceChanged
chrome.bluetoothLowEnergy.onServiceChanged.addListener(listener: function)
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
chrome.bluetoothLowEnergy.onServiceRemoved.addListener(listener: function)
Fired when a GATT service that was previously discovered on a remote device has been removed.