该 API 还在 beta 测试中，仅对 beta 分支和 dev 分支的 Chrome 用户可用。

chrome.bluetoothLowEnergy

描述： chrome.bluetoothLowEnergy API 用来和使用 GATT 的蓝牙智能（低耗能）设备通信。
可用版本： 从 Chrome 37 开始支持。警告：目前为 Beta 分支。了解更多内容
清单文件： "bluetooth": {...}
了解更多： 蓝牙

摘要

类型
Service
Characteristic
Descriptor
方法
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)
事件
onServiceAdded
onServiceChanged
onServiceRemoved
onCharacteristicValueChanged
onDescriptorValueChanged

类型

Service

属性
string uuid

服务的 UUID，例如 0000180d-0000-1000-8000-00805f9b34fb。

boolean isPrimary

表示服务类型是主要的还是辅助的。

string （可选）
instanceId

返回分配给该服务的标识符，使用实例标识符区分相同 UUID 外设中的不同服务，调用接收服务标识符的函数时也要使用。如果该实例代表远程服务的话就存在该属性。

string （可选）
deviceAddress

GATT 服务所属远程外设的设备地址，如果该实例代表远程服务的话就存在该属性。

Characteristic

属性
string uuid

特征的 UUID，例如 00002a37-0000-1000-8000-00805f9b34fb。

Service service

该特征属于哪个 GATT 服务。

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

该特征的属性。

string （可选）
instanceId

返回分配给该特征的标识符，使用实例标识符区分相同 UUID 外设中的不同特征，调用接收特征标识符的函数时也要使用。如果该实例代表远程特征的话就存在该属性。

ArrayBuffer （可选）
value

目前缓存的特征值，读取或通过通知或指示的方式更新特征值时也会更新该属性。

Descriptor

属性
string uuid

特征描述符的 UUID，例如 00002902-0000-1000-8000-00805f9b34fb。

Characteristic characteristic

该描述符属于哪个 GATT 特征。

string （可选）
instanceId

返回分配给该描述符的标识符，使用实例标识符区分相同 UUID 外设中的不同描述符，调用接收描述符标识符的函数时也要使用。如果该实例代表远程特征的话就存在该属性。

ArrayBuffer （可选）
value

目前缓存的描述符值，读取描述符值时也会更新该属性。

方法

connect

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

在应用程序与指定地址的设备之间建立连接。设备可能已经连接，并且它的 GATT 服务也可用，而不需要调用 connect。但是希望访问设备 GATT 服务的应用应该调用该函数，确保与设备维持连接。如果设备未连接，设备上的所有 GATT 服务都会在成功调用 connect 后发现。

参数
string deviceAddress

打开 GATT 连接的远程设备蓝牙地址。

object （可选）
properties

连接属性（可选）。

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

连接请求完成时调用。

callback 参数应该是一个如下形式的函数：

function() {...};

disconnect

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

关闭应用与指定地址设备的连接。注意，该函数并不一定会撤销物理连接本身，因为可能还有其他应用打开了连接。

参数
string deviceAddress

远程设备的蓝牙地址。

function （可选）
callback

断开连接的请求完成时调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

getService

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

获取指定实例标识符的 GATT 服务。

参数
string serviceId

请求的 GATT 服务的实例标识符。

function callback

调用时传递请求的 Service 对象。

callback 参数应该是一个如下形式的函数：

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

getServices

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

获取指定设备地址的远程设备上发现的所有 GATT 服务。

参数
string deviceAddress

要返回 GATT 服务的远程设备蓝牙地址。

function callback

调用时传递请求的 Service 对象列表。

callback 参数应该是一个如下形式的函数：

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

getCharacteristic

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

获取属于指定 GATT 服务、具有指定实例标识符的 GATT 特征（如果特征存在的话）。

参数
string characteristicId

请求的 GATT 特征的实例标识符。

function callback

调用时传递请求的 Characteristic 对象。

callback 参数应该是一个如下形式的函数：

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

getCharacteristics

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

获取发现的属于指定服务的所有 GATT 特征。

参数
string serviceId

要返回特征的 GATT 服务实例标识符。

function callback

调用时传递属于指定服务的特征列表。

callback 参数应该是一个如下形式的函数：

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

getIncludedServices

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

获取指定服务包含的 GATT 服务列表。

参数
string serviceId

要返回包含服务的 GATT 服务实例标识符。

function callback

调用时传递指定服务包含的 GATT 服务列表。

callback 参数应该是一个如下形式的函数：

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

getDescriptor

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

获取指定实例标识符对应的 GATT 特征描述符。

参数
string descriptorId

要请求 GATT 特征描述符的实例标识符。

function callback

调用时传递请求的 Descriptor 对象。

callback 参数应该是一个如下形式的函数：

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

getDescriptors

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

获取属于指定特征的 GATT 特征描述符列表。

参数
string characteristicId

要返回描述符的 GATT 特征实例标识符。

function callback

调用时传递属于指定特征的描述符列表。

callback 参数应该是一个如下形式的函数：

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

readCharacteristicValue

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

从远程外设获取指定特征的值。

参数
string characteristicId

要从远程设备读取的 GATT 特征实例标识符。

function callback

调用时返回请求的 Characteristic 对象，返回的 Characteristic 对象中 value 字段包含读取请求的结果。

callback 参数应该是一个如下形式的函数：

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

writeCharacteristicValue

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

从远程外设写入指定特征的值。

参数
string characteristicId

要写入 GATT 特征值的实例标识符。

ArrayBuffer value

作为写入请求的一部分发送给远程特征的值。

function callback

写入请求完成后调用。

callback 参数应该是一个如下形式的函数：

function() {...};

startCharacteristicNotifications

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

启用指定特征值的通知/指示，启用后应用可以通过 onCharacteristicValueChanged 事件监听通知。

参数
string characteristicId

需要启用通知的 GATT 特征实例标识符。

object （可选）
properties

通知会话属性（可选）。

boolean persistent

该标志表示应用的事件页面卸载时是否应该接收通知（请参见 管理应用的生命周期。默认值为 false。

function callback

请求完成后调用。

callback 参数应该是一个如下形式的函数：

function() {...};

stopCharacteristicNotifications

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

禁用指定特征值的通知/指示。调用成功后，应用不再接收该特征的通知/指示。

参数
string characteristicId

需要停用通知的 GATT 特征实例标识符。

function （可选）
callback

请求完成后调用（可选）。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

readDescriptorValue

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

从远程外设获取指定特征描述符的值。

参数
string descriptorId

要从远程设备读取的 GATT 特征实例标识符。

function callback

调用时传递请求值的 Descriptor 对象，返回的 Descriptor 中 value 字段包含读取请求的结果。

callback 参数应该是一个如下形式的函数：

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

writeDescriptorValue

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

从远程外设写入指定特征描述符的值。

参数
string descriptorId

要写入的 GATT 特征描述符的实例标识符。

ArrayBuffer value

作为写入请求的一部分发送给远程描述符的值。

function callback

写入请求完成时调用。

callback 参数应该是一个如下形式的函数：

function() {...};

事件

onServiceAdded

远程设备上发现新的 GATT 服务时产生。

addListener

chrome.bluetoothLowEnergy.onServiceAdded.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

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

添加的 GATT 服务。

onServiceChanged

远程 GATT 服务状态更改时产生，包括服务的特征和/或描述符添加或移除，还有来自远程设备“ServiceChanged”通知。

addListener

chrome.bluetoothLowEnergy.onServiceChanged.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

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

状态更改的 GATT 服务。

onServiceRemoved

之前在远程设备上发现的 GATT 服务移除时产生。

addListener

chrome.bluetoothLowEnergy.onServiceRemoved.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

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

移除的 GATT 服务。

onCharacteristicValueChanged

远程 GATT 特征值更改时产生，无论是由于读取请求，还是值更改通知/指示。只有当应用调用 startCharacteristicNotifications 启用通知后才会发送该事件。

addListener

chrome.bluetoothLowEnergy.onCharacteristicValueChanged.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

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

值更改的 GATT 特征。

onDescriptorValueChanged

远程 GATT 特征描述符的值更改时产生，通常是读取请求的结果。该事件只是为了方便而存在，成功调用 readDescriptorValue 后都会发送该事件。

addListener

chrome.bluetoothLowEnergy.onDescriptorValueChanged.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

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

值更改的 GATT 特征描述符。