tencent cloud

文档反馈

蓝牙-低功耗中心设备

最后更新时间:2024-07-16 18:02:20

    writeBLECharacteristicValue

    该 API 使用方法为 wx.writeBLECharacteristicValue(Object object)
    注意:
    并行调用多次会存在写失败的可能性。
    小程序不会对写入数据包大小做限制,但系统与蓝牙设备会限制蓝牙4.0单次传输的数据大小,超过最大字节数后会发生写入错误,建议每次写入不超过20字节。
    若单次写入数据过长,iOS 上存在系统不会有任何回调的情况(包括错误回调)。
    Android 平台上,在调用 wx.notifyBLECharacteristicValueChange 成功后立即调用本接口,在部分机型上会发生 10008 系统错误。
    功能说明:向蓝牙低功耗设备特征值中写入二进制数据。必须设备的特征支持 write 才可以成功调用
    参数及说明:Object object。
    属性
    类型
    必填
    说明
    deviceId
    string
    蓝牙设备 id
    serviceId
    string
    蓝牙特征对应服务的 UUID
    characteristicId
    string
    蓝牙特征的 UUID
    value
    ArrayBuffer
    蓝牙设备特征对应的二进制值
    writeType
    string
    蓝牙特征值的写模式设置,有两种模式,iOS 优先 write,Android 优先 writeNoResponse。合法值为:
    write:强制回复写,不支持时报错
    writeNoResponse:强制无回复写,不支持时报错
    success
    function
    接口调用成功的回调函数
    fail
    function
    接口调用成功的回调函数
    complete
    function
    接口调用结束的回调函数(调用成功、失败都会执行)
    错误码
    错误码
    错误信息
    说明
    0
    ok
    正常
    -1
    already connect
    已连接
    10000
    not init
    未初始化蓝牙适配器
    10001
    not available
    当前蓝牙适配器不可用
    10002
    no device
    没有找到指定设备
    10003
    connection fail
    连接失败
    10004
    no service
    没有找到指定服务
    10005
    no characteristic
    没有找到指定特征
    10006
    no connection
    当前连接已断开
    10007
    property not support
    当前特征不支持此操作
    10008
    system error
    其余所有系统上报的异常
    10009
    system not support
    Android 系统特有,系统版本低于4.3不支持 BLE
    10012
    operate time out
    连接超时
    10013
    invalid_data
    连接 deviceId 为空或者是格式不正确
    示例代码:
    // 向蓝牙设备发送一个0x00的16进制数据
    let buffer = new ArrayBuffer(1)
    let dataView = new DataView(buffer)
    dataView.setUint8(0, 0)
    
    wx.writeBLECharacteristicValue({
    // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
    deviceId,
    // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
    serviceId,
    // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
    characteristicId,
    // 这里的value是ArrayBuffer类型
    value: buffer,
    success (res) {
    console.log('writeBLECharacteristicValue success', res.errMsg)
    }
    })

    readBLECharacteristicValue

    该 API 使用方法为 wx.readBLECharacteristicValue(Object object)
    注意:
    并行调用多次会存在读失败的可能性。
    接口读取到的信息需要在 wx.onBLECharacteristicValueChange 方法注册的回调中获取。
    功能说明:读取蓝牙低功耗设备特征值的二进制数据。必须设备的特征支持 read 才可以成功调用
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id
    serviceId
    string
    -
    蓝牙特征对应服务的 UUID
    characteristicId
    string
    -
    蓝牙特征的 UUID
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    错误码
    错误码
    错误信息
    说明
    0
    ok
    正常
    -1
    already connect
    已连接
    10000
    not init
    未初始化蓝牙适配器
    10001
    not available
    当前蓝牙适配器不可用
    10002
    no device
    没有找到指定设备
    10003
    connection fail
    连接失败
    10004
    no service
    没有找到指定服务
    10005
    no characteristic
    没有找到指定特征
    10006
    no connection
    当前连接已断开
    10007
    property not support
    当前特征不支持此操作
    10008
    system error
    其余所有系统上报的异常
    10009
    system not support
    Android 系统特有,系统版本低于 4.3 不支持 BLE
    10012
    operate time out
    连接超时
    10013
    invalid_data
    连接 deviceId 为空或者是格式不正确
    示例代码:
    // 必须在这里的回调才能获取
    wx.onBLECharacteristicValueChange(function(characteristic) {
    console.log('characteristic value comed:', characteristic)
    })
    
    wx.readBLECharacteristicValue({
    // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
    deviceId,
    // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
    serviceId,
    // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
    characteristicId,
    success (res) {
    console.log('readBLECharacteristicValue:', res.errCode)
    }
    })

    setBLEMTU

    该 API 使用方法为 wx.setBLEMTU(Object object)
    功能说明:协商设置蓝牙低功耗的最大传输单元 (Maximum Transmission Unit,MTU)。需在 wx.createBLEConnection 调用成功后调用。仅 Android 系统5.1以上版本有效,iOS 因系统限制不支持。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id
    mtu
    number
    -
    最大传输单元。设置范围为 (22,512) 区间内,单位 bytes
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    object.success 回调函数参数:Object res。
    属性
    类型
    说明
    mtu
    number
    最终协商的 MTU 值,与传入参数一致。Android 客户端8.0.9开始支持

    getBLEMTU

    该 API 使用方法为 wx.getBLEMTU(Object object)
    注意:
    小程序中 MTU 为 ATT_MTU,包含 Op-Code 和 Attribute Handle 的长度,实际可以传输的数据长度为 ATT_MTU - 3。
    iOS 系统中 MTU 为固定值;Android 系统中,MTU 会在系统协商成功之后发生改变,建议使用 wx.onBLEMTUChange 监听。
    功能说明:获取蓝牙低功耗的最大传输单元。需在 wx.createBLEConnection 调用成功后调用。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id
    writeType
    string
    write
    写模式 (iOS 特有参数),合法值为:
    write:有回复写
    writeNoResponse:无回复写
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用成功的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    object.success 回调函数参数:Object res。
    属性
    类型
    说明
    mtu
    number
    最大传输单元
    错误码
    错误码
    错误信息
    说明
    0
    ok
    正常
    -1
    already connect
    已连接
    10000
    not init
    未初始化蓝牙适配器
    10001
    not available
    当前蓝牙适配器不可用
    10002
    no device
    没有找到指定设备
    10003
    connection fail
    连接失败
    10004
    no service
    没有找到指定服务
    10005
    no characteristic
    没有找到指定特征
    10006
    no connection
    当前连接已断开
    10007
    property not support
    当前特征不支持此操作
    10008
    system error
    其余所有系统上报的异常
    10009
    system not support
    Android 系统特有,系统版本低于4.3不支持 BLE
    10012
    operate time out
    连接超时
    10013
    invalid_data
    连接 deviceId 为空或者是格式不正确
    示例代码:
    wx.getBLEMTU({
    deviceId: '',
    writeType: 'write',
    success (res) {
    console.log(res)
    }
    })

    onBLEMTUChange

    该 API 使用方法为 wx.onBLEMTUChange(function listener)
    功能说明:监听蓝牙低功耗的最大传输单元变化事件(仅 Android 触发)。
    参数及说明:function listener,蓝牙低功耗的最大传输单元变化事件的监听函数, 参数 Object res 如下:
    属性
    类型
    说明
    deviceId
    string
    蓝牙设备 id
    mtu
    number
    最大传输单元
    示例代码:
    wx.onBLEMTUChange(function (res) {
    console.log('bluetooth mtu is', res.mtu)
    })

    offBLEMTUChange

    该 API 使用方法为 wx.offBLEMTUChange(function listener)
    功能说明:移除蓝牙低功耗的最大传输单元变化事件的监听函数。
    参数及说明:function listener,onBLEMTUChange 传入的监听函数。不传此参数则移除所有监听函数。
    示例代码:
    const listener = function (res) { console.log(res) }
    
    wx.onBLEMTUChange(listener)
    wx.offBLEMTUChange(listener) // 需传入与监听时同一个的函数对象

    onBLEConnectionStateChange

    该 API 使用方法为 wx.onBLEConnectionStateChange(function listener)
    功能说明:监听蓝牙低功耗连接状态改变事件。包括开发者主动连接或断开连接,设备丢失,连接异常断开等。
    参数及说明:function listener,蓝牙低功耗连接状态改变事件的监听函数,参数 Object res 如下:
    属性
    类型
    说明
    deviceId
    string
    蓝牙设备 id
    connected
    boolean
    是否处于已连接状态
    示例代码:
    wx.onBLEConnectionStateChange(function(res) {
    // 该方法回调中可以用于处理连接意外断开等异常情况
    console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)
    })

    offBLEConnectionStateChange

    该 API 使用方法为 wx.offBLEConnectionStateChange(function listener)
    功能说明:移除蓝牙低功耗连接状态改变事件的监听函数。
    参数及说明:function listener,onBLEConnectionStateChange 传入的监听函数。不传此参数则移除所有监听函数。
    示例代码:
    const listener = function (res) { console.log(res) }
    
    wx.onBLEConnectionStateChange(listener)
    wx.offBLEConnectionStateChange(listener) // 需传入与监听时同一个的函数对象

    onBLECharacteristicValueChange

    该 API 使用方法为 wx.onBLECharacteristicValueChange(function listener)
    功能说明:监听蓝牙低功耗设备的特征值变化事件。必须先调用 wx.notifyBLECharacteristicValueChange 接口才能接收到设备推送的 notification。
    参数及说明:function listener,蓝牙低功耗设备的特征值变化事件的监听函数,参数 Object res 如下:
    属性
    类型
    说明
    deviceId
    string
    蓝牙设备 id
    serviceId
    string
    蓝牙特征对应服务的 UUID
    characteristicId
    string
    蓝牙特征的 UUID
    value
    ArrayBuffer
    特征最新的值
    示例代码:
    // ArrayBuffer转16进制字符串示例
    function ab2hex(buffer) {
    let hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function(bit) {
    return ('00' + bit.toString(16)).slice(-2)
    }
    )
    return hexArr.join('');
    }
    wx.onBLECharacteristicValueChange(function(res) {
    console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`)
    console.log(ab2hex(res.value))
    })

    offBLECharacteristicValueChange

    该 API 使用方法为 wx.offBLECharacteristicValueChange()
    功能说明:移除蓝牙低功耗设备的特征值变化事件的全部监听函数。
    示例代码:
    wx.offBLECharacteristicValueChange()

    notifyBLECharacteristicValueChange

    该 API 使用方法为 wx.notifyBLECharacteristicValueChange(Object object)
    注意:
    订阅操作成功后需要设备主动更新特征的 value,才会触发 wx.onBLECharacteristicValueChange 回调。
    Android 平台上,在本接口调用成功后立即调用 wx.writeBLECharacteristicValue 接口,在部分机型上会发生 10008 系统错误。
    必须设备的特征支持 notify 或者 indicate 才可以成功调用。另外,必须先启用 wx.notifyBLECharacteristicValueChange 才能监听到设备 characteristicValueChange 事件。
    功能说明:启用蓝牙低功耗设备特征值变化时的 notify 功能,订阅特征。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id
    serviceId
    string
    -
    蓝牙特征对应服务的 UUID
    characteristicId
    string
    -
    蓝牙特征的 UUID
    state
    boolean
    -
    是否启用 notify
    type
    string
    indication
    设置特征订阅类型,有效值有 notification 和indication
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    错误码
    错误码
    错误信息
    说明
    0
    ok
    正常
    -1
    already connect
    已连接
    10000
    not init
    未初始化蓝牙适配器
    10001
    not available
    当前蓝牙适配器不可用
    10002
    no device
    没有找到指定设备
    10003
    connection fail
    连接失败
    10004
    no service
    没有找到指定服务
    10005
    no characteristic
    没有找到指定特征
    10006
    no connection
    当前连接已断开
    10007
    property not support
    当前特征不支持此操作
    10008
    system error
    其余所有系统上报的异常
    10009
    system not support
    Android 系统特有,系统版本低于4.3不支持 BLE
    10012
    operate time out
    连接超时
    10013
    invalid_data
    连接 deviceId 为空或者是格式不正确
    示例代码:
    // 向蓝牙设备发送一个0x00的16进制数据
    let buffer = new ArrayBuffer(1)
    let dataView = new DataView(buffer)
    dataView.setUint8(0, 0)
    
    wx.writeBLECharacteristicValue({
    // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
    deviceId,
    // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
    serviceId,
    // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
    characteristicId,
    // 这里的value是ArrayBuffer类型
    value: buffer,
    success (res) {
    console.log('writeBLECharacteristicValue success', res.errMsg)
    }
    })

    getBLEDeviceServices

    该 API 使用方法为 wx.getBLEDeviceServices(Object object)
    功能说明:获取蓝牙低功耗设备所有服务 (service)。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id。需要已经通过 wx.createBLEConnection 建立连接
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    object.success 回调函数参数:Object res。
    属性
    类型
    说明
    services
    Array.<Object>
    设备服务列表
    service 结构属性
    属性
    类型
    说明
    uuid
    string
    蓝牙设备服务的 UUID
    isPrimary
    boolean
    该服务是否为主服务
    示例代码:
    wx.getBLEDeviceServices({
    // 这里的 deviceId 需要已经通过 wx.createBLEConnection 与对应设备建立连接
    deviceId,
    success (res) {
    console.log('device services:', res.services)
    }
    })

    getBLEDeviceRSSI

    该 API 使用方法为 wx.getBLEDeviceRSSI(Object object)
    功能说明:获取蓝牙低功耗设备的信号强度 (Received Signal Strength Indication,RSSI)。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    object.success 回调函数参数:Object res。
    属性
    类型
    说明
    RSSI
    Number
    信号强度,单位:dBm

    getBLEDeviceCharacteristics

    该 API 使用方法为 wx.getBLEDeviceCharacteristics(Object object)
    功能说明:获取蓝牙低功耗设备某个服务中所有特征 (characteristic)。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id。需要已经通过 wx.createBLEConnection 建立连接
    serviceId
    string
    -
    蓝牙服务 UUID。需要先调用 wx.getBLEDeviceServices 获取
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    object.success 回调函数参数:Object res。
    属性
    类型
    说明
    characteristics
    Array.<Object>
    设备特征列表
    characteristics 结构属性
    结构属性
    类型
    说明
    uuid
    string
    蓝牙设备特征的 UUID
    properties
    Object
    该特征支持的操作类型
    properties 结构属性
    属性
    类型
    说明
    read
    boolean
    该特征是否支持 read 操作
    write
    boolean
    该特征是否支持 write 操作
    notify
    boolean
    该特征是否支持 notify 操作
    indicate
    boolean
    该特征是否支持 indicate 操作
    writeNoResponse
    boolean
    该特征是否支持 writeNoResponse 操作
    writeDefault
    boolean
    该特征是否支持 writeDefault 操作
    错误码
    错误码
    错误信息
    说明
    0
    ok
    正常
    -1
    already connect
    已连接
    10000
    not init
    未初始化蓝牙适配器
    10001
    not available
    当前蓝牙适配器不可用
    10002
    no device
    没有找到指定设备
    10003
    connection fail
    连接失败
    10004
    no service
    没有找到指定服务
    10005
    no characteristic
    没有找到指定特征
    10006
    no connection
    当前连接已断开
    10007
    property not support
    当前特征不支持此操作
    10008
    system error
    其余所有系统上报的异常
    10009
    system not support
    Android 系统特有,系统版本低于4.3不支持 BLE
    10012
    operate time out
    连接超时
    10013
    invalid_data
    连接 deviceId 为空或者是格式不正确
    示例代码:
    wx.getBLEDeviceCharacteristics({
    // 这里的 deviceId 需要已经通过 wx.createBLEConnection 与对应设备建立链接
    deviceId,
    // 这里的 serviceId 需要在 wx.getBLEDeviceServices 接口中获取
    serviceId,
    success (res) {
    console.log('device getBLEDeviceCharacteristics:', res.characteristics)
    }
    })

    createBLEConnection

    该 API 使用方法为 wx.createBLEConnection(Object object)
    注意:
    请保证尽量成对的调用 wx.createBLEConnection 和 wx.closeBLEConnection 接口。Android 如果重复调用 wx.createBLEConnection 创建连接,有可能导致系统持有同一设备多个连接的实例,导致调用 closeBLEConnection 的时候并不能真正的断开与设备的连接。
    蓝牙连接随时可能断开,建议监听 wx.onBLEConnectionStateChange 回调事件,当蓝牙设备断开时按需执行重连操作
    若对未连接的设备或已断开连接的设备调用数据读写操作的接口,会返回 10006 错误,建议进行重连操作。
    功能说明:连接蓝牙低功耗设备。若小程序在之前已有搜索过某个蓝牙设备,并成功建立连接,可直接传入之前搜索获取的 deviceId 直接尝试连接该设备,无需再次进行搜索操作。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id
    timeout
    number
    -
    超时时间,单位 ms,不填表示不会超时
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    错误码
    错误码
    错误信息
    说明
    0
    ok
    正常
    -1
    already connect
    已连接
    10000
    not init
    未初始化蓝牙适配器
    10001
    not available
    当前蓝牙适配器不可用
    10002
    no device
    没有找到指定设备
    10003
    connection fail
    连接失败
    10004
    no service
    没有找到指定服务
    10005
    no characteristic
    没有找到指定特征
    10006
    no connection
    当前连接已断开
    10007
    property not support
    当前特征不支持此操作
    10008
    system error
    其余所有系统上报的异常
    10009
    system not support
    Android 系统特有,系统版本低于4.3不支持 BLE
    10012
    operate time out
    连接超时
    10013
    invalid_data
    连接 deviceId 为空或者是格式不正确
    示例代码:
    wx.createBLEConnection({
    deviceId,
    success (res) {
    console.log(res)
    }
    })

    closeBLEConnection

    该 API 使用方法为 wx.closeBLEConnection(Object object)
    功能说明:断开与蓝牙低功耗设备的连接。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    错误码
    错误码
    错误信息
    说明
    0
    ok
    正常
    -1
    already connect
    已连接
    10000
    not init
    未初始化蓝牙适配器
    10001
    not available
    当前蓝牙适配器不可用
    10002
    no device
    没有找到指定设备
    10003
    connection fail
    连接失败
    10004
    no service
    没有找到指定服务
    10005
    no characteristic
    没有找到指定特征
    10006
    no connection
    当前连接已断开
    10007
    property not support
    当前特征不支持此操作
    10008
    system error
    其余所有系统上报的异常
    10009
    system not support
    Android 系统特有,系统版本低于 4.3 不支持 BLE
    10012
    operate time out
    连接超时
    10013
    invalid_data
    连接 deviceId 为空或者是格式不正确
    示例代码:
    wx.closeBLEConnection({
    deviceId,
    success (res) {
    console.log(res)
    }
    })
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持