说明
chrome.bluetoothLowEnergy
API 用于使用通用属性配置文件 (GATT) 与蓝牙低功耗设备通信。
清单
类型
Advertisement
属性
-
manufacturerData
ManufacturerData[] 可选
要添加到广告数据的“制造商特定数据”字段中的制造商特定数据的列表。
-
serviceData
ServiceData[] 可选
要添加在广告数据的“服务数据”字段中的服务数据列表。
-
serviceUuids
string[] 可选
要添加到广告数据的“服务 UUID”字段的 UUID 列表。这些 UUID 的格式可以是 16 位、32 位或 128。
-
solicitUuids
string[] 可选
要添加到广告数据的“请求 UUID”字段的 UUID 列表。这些 UUID 的格式可以是 16 位、32 位或 128。
-
通告的类型。
AdvertisementType
通告的类型。如果选择“广播”,发送的广告类型将为 ADV_NONCONN_IND,并且设备将使用随机的 MAC 地址进行广播。如果设为“外围设备”,通告类型将为 ADV_IND 或 ADV_SCAN_IND,并且设备将使用真实的蓝牙适配器的 MAC 地址进行广播。
枚举
Characteristic
属性
-
instanceId
字符串(可选)
返回分配给此特征的标识符。使用实例 ID 区分来自具有相同 UUID 的外围设备的特性,并调用接受特征标识符的函数调用。存在(如果此实例代表远程特征)。
-
媒体资源
此特征的属性。
-
服务
服务 可选
此特征所属的 GATT 服务。
-
uuid
string
特征的 UUID,例如 00002a37-0000-1000-8000-00805f9b34fb。
-
值
ArrayBuffer 可选
当前缓存的特征值。通过通知或指示读取或更新特征的值时,此值会更新。
CharacteristicProperty
表示特征可能的属性的值。特征权限是根据这些属性推断得出的。请参阅蓝牙 4.x 规范,了解每个属性的含义。
枚举
"writeWithoutResponse"
"extendedProperties"
"reliableWrite"
"writableAuxiliaries"
ConnectProperties
属性
-
持久性
boolean
此标记指示在应用的事件页面卸载时与设备的连接是否处于打开状态(请参阅管理应用生命周期)。默认值为
false.
。
Descriptor
属性
-
特征
特征(可选)
此描述符所属的 GATT 特征。
-
instanceId
字符串(可选)
返回分配给此描述符的标识符。使用实例 ID 区分来自具有相同 UUID 的外围设备的描述符,并执行接受描述符标识符的函数调用。存在(如果此实例代表远程特征)。
-
权限Chrome 52 及更高版本
此描述符的权限。
-
uuid
string
特征描述符的 UUID,例如 00002902-0000-1000-8000-00805f9b34fb。
-
值
ArrayBuffer 可选
当前缓存的描述符值。当读取描述符的值时,此值会更新。
DescriptorPermission
表示描述符可能的权限的值。请参阅蓝牙 4.x 规范以了解每项权限的含义。
枚举
Device
属性
-
地址
string
设备地址,格式为“XX:XX:XX:XX:XX:XX”。
-
deviceClass
数字可选
设备的类别,一个由 http://www.bluetooth.org/en-us/specification/specified-numbers/baseband 定义的位字段。
-
name
字符串(可选)
直观易懂的设备名称。
ManufacturerData
属性
-
data
数值 []
-
id
number
Notification
属性
-
shouldIndicate
布尔值 选填
用于发送指示而非通知的可选标志。
-
值
ArrayBuffer
特征的新值。
NotificationProperties
属性
-
持久性
boolean
此标记指示在应用的事件页面卸载时应用是否应接收通知(请参阅管理应用生命周期)。默认值为
false
。
Request
属性
-
设备
发送此请求的设备。
-
requestId
number
此请求的唯一 ID。响应此请求时使用此 ID。
-
值
ArrayBuffer 可选
要写入的值(如果是写入请求)。
Response
属性
-
isError
boolean
如果这是一个错误响应,则此值应为 true。
-
requestId
number
所响应的请求的 ID。
-
值
ArrayBuffer 可选
响应值。写入请求和错误响应将忽略此参数。
Service
属性
-
deviceAddress
字符串(可选)
GATT 服务所属的远程外围设备的设备地址。存在(如果此实例代表远程服务)。
-
instanceId
字符串(可选)
返回分配给此服务的标识符。使用实例 ID 区分具有相同 UUID 的外围设备的服务,并调用接受服务标识符的函数调用。存在(如果此实例代表远程服务)。
-
isPrimary
boolean
指明此服务的类型是主要还是次要。
-
uuid
string
服务的 UUID,例如 0000180d-0000-1000-8000-00805f9b34fb。
ServiceData
属性
-
data
数值 []
-
uuid
string
方法
connect()
chrome.bluetoothLowEnergy.connect(
deviceAddress: string,
properties?: ConnectProperties,
callback?: function,
)
使用指定地址在应用与设备之间建立连接。设备可能已经连接,无需调用 connect
即可使用其 GATT 服务,但是,希望访问设备的 GATT 服务的应用应调用此函数,以确保与设备的连接保持连接。如果设备未连接,则在成功调用 connect
后,系统会发现该设备的所有 GATT 服务。
参数
-
deviceAddress
string
应打开 GATT 连接的远程设备的蓝牙地址。
-
媒体资源
连接属性(可选)。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
createCharacteristic()
chrome.bluetoothLowEnergy.createCharacteristic(
characteristic: Characteristic,
serviceId: string,
callback?: function,
)
创建本地托管的 GATT 特征。此特征必须托管在有效服务下。如果服务 ID 无效,则会设置 lastError。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此功能才可用。外围设备权限可能仅适用于部分应用。
参数
-
特征
要创建的特征。
-
serviceId
string
要为其创建此特征的服务的 ID。
-
callback
函数(可选)
callback
参数如下所示:(characteristicId: string) => void
-
characteristicId
string
-
返回
-
Promise<string>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
createDescriptor()
chrome.bluetoothLowEnergy.createDescriptor(
descriptor: Descriptor,
characteristicId: string,
callback?: function,
)
创建本地托管的 GATT 描述符。此描述符必须托管在有效特征下。如果特征 ID 无效,则会设置 lastError。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此功能才可用。外围设备权限可能仅适用于部分应用。
参数
-
描述符
要创建的描述符。
-
characteristicId
string
要为其创建描述符的特征的 ID。
-
callback
函数(可选)
callback
参数如下所示:(descriptorId: string) => void
-
descriptorId
string
-
返回
-
Promise<string>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
createService()
chrome.bluetoothLowEnergy.createService(
service: Service,
callback?: function,
)
创建本地托管的 GATT 服务。此服务可以注册为在本地 GATT 服务器上提供。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此功能才可用。外围设备权限可能仅适用于部分应用。
参数
-
服务
要创建的服务。
-
callback
函数(可选)
callback
参数如下所示:(serviceId: string) => void
-
serviceId
string
-
返回
-
Promise<string>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
disconnect()
chrome.bluetoothLowEnergy.disconnect(
deviceAddress: string,
callback?: function,
)
关闭应用与具有指定地址的设备的连接。请注意,这并不总是会破坏该物理链接本身,因为可能有其他应用打开了连接。
参数
-
deviceAddress
string
远程设备的蓝牙地址。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getCharacteristic()
chrome.bluetoothLowEnergy.getCharacteristic(
characteristicId: string,
callback?: function,
)
获取属于指定 GATT 服务的指定实例 ID 的 GATT 特征(如果存在)。
参数
-
characteristicId
string
所请求的 GATT 特征的实例 ID。
-
callback
函数(可选)
callback
参数如下所示:(result: Characteristic) => void
-
结果
-
返回
-
Promise<Characteristic>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getCharacteristics()
chrome.bluetoothLowEnergy.getCharacteristics(
serviceId: string,
callback?: function,
)
获取属于指定服务的所有已发现 GATT 特征的列表。
参数
-
serviceId
string
应返回其特性的 GATT 服务的实例 ID。
-
callback
函数(可选)
callback
参数如下所示:(result: Characteristic[]) => void
-
结果
特征[]
-
返回
-
Promise<Characteristic[]>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getDescriptor()
chrome.bluetoothLowEnergy.getDescriptor(
descriptorId: string,
callback?: function,
)
获取具有指定实例 ID 的 GATT 特征描述符。
参数
-
descriptorId
string
所请求的 GATT 特征描述符的实例 ID。
-
callback
函数(可选)
callback
参数如下所示:(result: Descriptor) => void
-
结果
-
返回
-
Promise<Descriptor>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getDescriptors()
chrome.bluetoothLowEnergy.getDescriptors(
characteristicId: string,
callback?: function,
)
获取属于指定特征的 GATT 特征描述符列表。
参数
-
characteristicId
string
应返回其描述符的 GATT 特征的实例 ID。
-
callback
函数(可选)
callback
参数如下所示:(result: Descriptor[]) => void
-
结果
描述标签[]
-
返回
-
Promise<Descriptor[]>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getIncludedServices()
chrome.bluetoothLowEnergy.getIncludedServices(
serviceId: string,
callback?: function,
)
获取指定服务包含的 GATT 服务列表。
参数
返回
-
Promise<服务[]>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getService()
chrome.bluetoothLowEnergy.getService(
serviceId: string,
callback?: function,
)
获取具有指定实例 ID 的 GATT 服务。
参数
-
serviceId
string
所请求的 GATT 服务的实例 ID。
-
callback
函数(可选)
callback
参数如下所示:(result: Service) => void
-
结果
-
返回
-
Promise<Service>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getServices()
chrome.bluetoothLowEnergy.getServices(
deviceAddress: string,
callback?: function,
)
获取在远程设备上发现的具有指定设备地址的所有 GATT 服务。
注意:如果设备上尚未完成服务发现,此 API 将返回部分服务(可能为空)。一种权宜解决方法是添加基于时间的延迟和/或反复调用,直到返回预期数量的服务。
参数
返回
-
Promise<服务[]>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
notifyCharacteristicValueChanged()
chrome.bluetoothLowEnergy.notifyCharacteristicValueChanged(
characteristicId: string,
notification: Notification,
callback?: function,
)
通知远程设备某个特征的新值。如果通知对象中的 shouldIndicate 标志为 true,则系统将会发送指示而非通知。请注意,特征需要在创建期间正确设置“notify”或“suggest”属性,才能使此调用成功。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此功能才可用。外围设备权限可能仅适用于部分应用。
参数
-
characteristicId
string
要向其发送通知的特征。
-
通知
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
readCharacteristicValue()
chrome.bluetoothLowEnergy.readCharacteristicValue(
characteristicId: string,
callback?: function,
)
从远程外围设备检索指定特征的值。
参数
-
characteristicId
string
GATT 特征的实例 ID,其值应从远程设备读取。
-
callback
函数(可选)
callback
参数如下所示:(result: Characteristic) => void
-
结果
-
返回
-
Promise<Characteristic>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
readDescriptorValue()
chrome.bluetoothLowEnergy.readDescriptorValue(
descriptorId: string,
callback?: function,
)
从远程外围设备检索指定特征描述符的值。
参数
-
descriptorId
string
GATT 特征描述符的实例 ID,其值应从远程设备读取。
-
callback
函数(可选)
callback
参数如下所示:(result: Descriptor) => void
-
结果
-
返回
-
Promise<Descriptor>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
registerAdvertisement()
chrome.bluetoothLowEnergy.registerAdvertisement(
advertisement: Advertisement,
callback?: function,
)
创建一个广告,并将其注册用于广告投放。如需调用此函数,应用必须将 bluetooth:low_energy 和 bluetooth:外围设备权限设置为 true。此外,此 API 仅适用于在自助服务终端模式下或通过设置“--enable-ble-advertising-in-apps”命令行开关自动启动的应用。请参阅 https://developer.chrome.com/apps/manifest/bluetooth。注意:在某些硬件上,可以同时支持中央模式和外围设备模式,但在不支持这些模式的硬件上,进行此调用会将设备切换到外围设备模式。对于不支持中央模式和外围设备模式的硬件,尝试在这两种模式下使用设备会导致未定义行为,或阻止其他核心角色应用正常运行(包括发现蓝牙低功耗设备)。
参数
-
广告
要宣传的广告。
-
callback
函数(可选)
callback
参数如下所示:(advertisementId: number) => void
-
advertisementId
number
-
返回
-
Promise<数字>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
registerService()
chrome.bluetoothLowEnergy.registerService(
serviceId: string,
callback?: function,
)
向本地 GATT 服务器注册指定服务。如果服务 ID 无效,则会设置 lastError。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此功能才可用。外围设备权限可能仅适用于部分应用。
参数
-
serviceId
string
已创建服务的唯一 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
removeService()
chrome.bluetoothLowEnergy.removeService(
serviceId: string,
callback?: function,
)
移除指定的服务,如果已注册,则将其取消注册。如果服务 ID 无效,则会设置 lastError。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此功能才可用。外围设备权限可能仅适用于部分应用。
参数
-
serviceId
string
当前注册服务的唯一 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
resetAdvertising()
chrome.bluetoothLowEnergy.resetAdvertising(
callback?: function,
)
重置当前设备上的通告。此操作将取消注册并停止所有现有广告。
参数
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
sendRequestResponse()
chrome.bluetoothLowEnergy.sendRequestResponse(
response: Response,
)
发送针对特征或描述符读/写请求的响应。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此功能才可用。外围设备权限可能仅适用于部分应用。
参数
-
条回复
对请求的响应。
setAdvertisingInterval()
chrome.bluetoothLowEnergy.setAdvertisingInterval(
minInterval: number,
maxInterval: number,
callback?: function,
)
设置两个连续广告之间的时间间隔。注意:这是尽力而为。实际间隔可能与所请求的时间间隔有很大差异。在某些硬件上,最小间隔为 100 毫秒。最小值和最大值不能超过蓝牙 4.2 规范所允许的范围。
参数
-
minInterval
number
广告之间的最小时间间隔(以毫秒为单位)。该时间不得低于 20 毫秒(根据规范)。
-
maxInterval
number
广告之间的最大时间间隔(以毫秒为单位)。该时间不得超过 10240 毫秒(根据规范)。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
startCharacteristicNotifications()
chrome.bluetoothLowEnergy.startCharacteristicNotifications(
characteristicId: string,
properties?: NotificationProperties,
callback?: function,
)
启用来自指定特征的值通知/指示。启用后,应用可以使用 onCharacteristicValueChanged
事件来监听通知。
参数
-
characteristicId
string
应启用通知的 GATT 特征的实例 ID。
-
媒体资源
通知会话属性(可选)。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
stopCharacteristicNotifications()
chrome.bluetoothLowEnergy.stopCharacteristicNotifications(
characteristicId: string,
callback?: function,
)
停用来自指定特征的值通知/指示。调用成功后,应用将停止接收来自此特征的通知/指示。
参数
-
characteristicId
string
应停止此应用的通知会话的 GATT 特征的实例 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
unregisterAdvertisement()
chrome.bluetoothLowEnergy.unregisterAdvertisement(
advertisementId: number,
callback?: function,
)
取消注册通告并停止其通告。如果通告未能取消注册,则停止通告的唯一方式可能是重启设备。
参数
-
advertisementId
number
要取消注册的通告的 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
unregisterService()
chrome.bluetoothLowEnergy.unregisterService(
serviceId: string,
callback?: function,
)
向本地 GATT 服务器取消注册指定服务。如果服务 ID 无效,则会设置 lastError。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此功能才可用。外围设备权限可能仅适用于部分应用。
参数
-
serviceId
string
当前注册服务的唯一 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
writeCharacteristicValue()
chrome.bluetoothLowEnergy.writeCharacteristicValue(
characteristicId: string,
value: ArrayBuffer,
callback?: function,
)
从远程外围设备写入指定特征的值。
参数
-
characteristicId
string
应写入其值的 GATT 特征的实例 ID。
-
值
ArrayBuffer
应作为写入请求的一部分发送到远程特征的值。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
writeDescriptorValue()
chrome.bluetoothLowEnergy.writeDescriptorValue(
descriptorId: string,
value: ArrayBuffer,
callback?: function,
)
从远程外围设备写入指定特征描述符的值。
参数
-
descriptorId
string
应写入其值的 GATT 特征描述符的实例 ID。
-
值
ArrayBuffer
应作为写入请求的一部分发送到远程描述符的值。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 91 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
活动
onCharacteristicReadRequest
chrome.bluetoothLowEnergy.onCharacteristicReadRequest.addListener(
callback: function,
)
当已连接的中央设备请求读取在本地 GATT 服务器上注册的特征的值时触发。长时间不响应该请求可能会导致连接断开。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此事件才可用。外围设备权限可能仅适用于部分应用。
参数
-
callback
功能
callback
参数如下所示:(request: Request, characteristicId: string) => void
-
request
-
characteristicId
string
-
onCharacteristicValueChanged
chrome.bluetoothLowEnergy.onCharacteristicValueChanged.addListener(
callback: function,
)
当远程 GATT 特征的值发生更改(由于读取请求或值更改通知/指示)时触发。只有在应用已通过调用 startCharacteristicNotifications
启用通知时,系统才会发送此事件。
参数
-
callback
功能
callback
参数如下所示:(characteristic: Characteristic) => void
-
特征
-
onCharacteristicWriteRequest
chrome.bluetoothLowEnergy.onCharacteristicWriteRequest.addListener(
callback: function,
)
当已连接的中央设备请求写入在本地 GATT 服务器上注册的特征的值时触发。长时间不响应该请求可能会导致连接断开。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此事件才可用。外围设备权限可能仅适用于部分应用。
参数
-
callback
功能
callback
参数如下所示:(request: Request, characteristicId: string) => void
-
request
-
characteristicId
string
-
onDescriptorReadRequest
chrome.bluetoothLowEnergy.onDescriptorReadRequest.addListener(
callback: function,
)
当已连接的中央设备请求读取在本地 GATT 服务器上注册的描述符的值时触发。长时间不响应该请求可能会导致连接断开。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此事件才可用。外围设备权限可能仅适用于部分应用。
参数
-
callback
功能
callback
参数如下所示:(request: Request, descriptorId: string) => void
-
request
-
descriptorId
string
-
onDescriptorValueChanged
chrome.bluetoothLowEnergy.onDescriptorValueChanged.addListener(
callback: function,
)
在远程 GATT 特征描述符的值发生更改时触发,通常是由于读取请求而触发的。此事件主要用于方便起见,并且始终在成功调用 readDescriptorValue
后发送。
参数
-
callback
功能
callback
参数如下所示:(descriptor: Descriptor) => void
-
描述符
-
onDescriptorWriteRequest
chrome.bluetoothLowEnergy.onDescriptorWriteRequest.addListener(
callback: function,
)
当已连接的中央设备请求写入在本地 GATT 服务器上注册的描述符的值时触发。长时间不响应该请求可能会导致连接断开。仅当应用将 bluetooth:low_energy 和 bluetooth:外围设备权限都设置为 true 时,此事件才可用。外围设备权限可能仅适用于部分应用。
参数
-
callback
功能
callback
参数如下所示:(request: Request, descriptorId: string) => void
-
request
-
descriptorId
string
-
onServiceAdded
chrome.bluetoothLowEnergy.onServiceAdded.addListener(
callback: function,
)
当在远程设备上发现新的 GATT 服务时触发。
onServiceChanged
chrome.bluetoothLowEnergy.onServiceChanged.addListener(
callback: function,
)
在远程 GATT 服务的状态发生变化时触发。这涉及到服务中添加或移除的所有特征和/或描述符,以及来自远程设备的“ServiceChanged”通知。
onServiceRemoved
chrome.bluetoothLowEnergy.onServiceRemoved.addListener(
callback: function,
)
当之前在远程设备上发现的 GATT 服务被移除时触发。