chrome.bluetoothLowEnergy

Description

The chrome.bluetoothLowEnergy API is used to communicate with Bluetooth Smart (Low Energy) devices using the Generic Attribute Profile (GATT).

Availability

ChromeOS only

Manifest

The following keys must be declared in the manifest to use this API.

"bluetooth"

Types

Advertisement

Chrome 47+

Properties

  • manufacturerData

    ManufacturerData[] optional

    List of manufacturer specific data to be included in "Manufacturer Specific Data" fields of the advertising data.

  • serviceData

    ServiceData[] optional

    List of service data to be included in "Service Data" fields of the advertising data.

  • serviceUuids

    string[] 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.

  • solicitUuids

    string[] 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.

AdvertisementType

Chrome 47+

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"

"peripheral"

Characteristic

Properties

  • instanceId

    string 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

    CharacteristicProperty[]

    The properties of this characteristic.

  • service

    Service optional

    The GATT service this characteristic belongs to.

  • uuid

    string

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

  • value

    ArrayBuffer 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.

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"

"encryptAuthenticatedWrite"

ConnectProperties

Properties

  • persistent

    boolean

    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

  • characteristic

    Characteristic optional

    The GATT characteristic this descriptor belongs to.

  • instanceId

    string 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

    DescriptorPermission[]

    Chrome 52+

    The permissions of this descriptor.

  • uuid

    string

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

  • value

    ArrayBuffer optional

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

DescriptorPermission

Chrome 52+

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"

"encryptedAuthenticatedWrite"

Device

Chrome 52+

Properties

  • address

    string

    The address of the device, in the format 'XX:XX:XX:XX:XX:XX'.

  • deviceClass

    number optional

    The class of the device, a bit-field defined by http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband.

  • name

    string optional

    The human-readable name of the device.

ManufacturerData

Chrome 47+

Properties

  • data

    number[]

  • id

    number

Notification

Chrome 52+

Properties

  • shouldIndicate

    boolean optional

    Optional flag for sending an indication instead of a notification.

  • value

    ArrayBuffer

    New value of the characteristic.

NotificationProperties

Properties

  • persistent

    boolean

    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

Chrome 52+

Properties

  • device

    Device

    Device that send this request.

  • requestId

    number

    Unique ID for this request. Use this ID when responding to this request.

  • value

    ArrayBuffer optional

    Value to write (if this is a write request).

Response

Chrome 52+

Properties

  • isError

    boolean

    If this is an error response, this should be true.

  • requestId

    number

    Id of the request this is a response to.

  • value

    ArrayBuffer optional

    Response value. Write requests and error responses will ignore this parameter.

Service

Properties

  • deviceAddress

    string optional

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

  • instanceId

    string 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.

  • isPrimary

    boolean

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

  • uuid

    string

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

ServiceData

Chrome 47+

Properties

  • data

    number[]

  • uuid

    string

Methods

connect()

Promise 
chrome.bluetoothLowEnergy.connect(
  deviceAddress: string,
  properties?: ConnectProperties,
  callback?: function,
): Promise<void>

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

  • deviceAddress

    string

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

  • properties

    ConnectProperties optional

    Connection properties (optional).

  • callback

    function optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

createCharacteristic()

Promise Chrome 52+ 
chrome.bluetoothLowEnergy.createCharacteristic(
  characteristic: Characteristic,
  serviceId: string,
  callback?: function,
): Promise<string>

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.

  • serviceId

    string

    ID of the service to create this characteristic for.

  • callback

    function optional

    The callback parameter looks like: 

    (characteristicId: string) => void

    • characteristicId

      string

Returns

  • Promise<string>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

createDescriptor()

Promise Chrome 52+ 
chrome.bluetoothLowEnergy.createDescriptor(
  descriptor: Descriptor,
  characteristicId: string,
  callback?: function,
): Promise<string>

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.

  • characteristicId

    string

    ID of the characteristic to create this descriptor for.