tencent cloud

文档反馈

蓝牙-通用

最后更新时间:2024-07-16 18:03:45

    stopBluetoothDevicesDiscovery

    该 API 使用方法为 wx.stopBluetoothDevicesDiscovery(Object object)
    功能说明:停止搜寻附近的蓝牙外围设备。若已经找到需要的蓝牙设备并不需要继续搜索时,建议调用该接口停止蓝牙搜索。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    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.stopBluetoothDevicesDiscovery({
    success (res) {
    console.log(res)
    }
    })

    startBluetoothDevicesDiscovery

    该 API 使用方法为 wx.startBluetoothDevicesDiscovery(Object object)
    注意:
    考虑到蓝牙功能可以间接进行定位,Android 6.0 及以上版本,无定位权限或定位开关未打开时,无法进行设备搜索。这种情况下,Android 8.0.16 前,接口调用成功但无法扫描设备;Android 8.0.16 及以上版本,会返回错误。
    功能说明:开始搜寻附近的蓝牙外围设备。此操作比较耗费系统资源,请在搜索到需要的设备后及时调用 wx.stopBluetoothDevicesDiscovery 停止搜索。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    services
    Array.<string>
    -
    要搜索的蓝牙设备主服务的 UUID 列表(支持 16/32/128 位 UUID)。某些蓝牙设备会广播自己的主 service 的 UUID。如果设置此参数,则只搜索广播包有对应 UUID 的主服务的蓝牙设备。建议通过该参数过滤掉周边不需要处理的其他蓝牙设备
    allowDuplicatesKey
    boolean
    false
    是否允许重复上报同一设备。如果允许重复上报,则wx.onBluetoothDeviceFound 方法会多次上报同一设备,但是 RSSI 值会有不同。
    interval
    number
    0
    上报设备的间隔,单位 ms。0 表示找到新设备立即上报,其他数值根据传入的间隔上报。
    powerLevel
    string
    medium
    扫描模式,越高扫描越快,也越耗电。仅 Android 宿主客户端7.0.12及以上支持,合法值为:
    low:低
    medium:中
    high:高
    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 为空或者是格式不正确
    示例代码:
    // 以宿主客户端硬件平台的蓝牙智能灯为例,主服务的 UUID 是 FEE7。传入这个参数,只搜索主服务 UUID 为 FEE7 的设备
    wx.startBluetoothDevicesDiscovery({
    services: ['FEE7'],
    success (res) {
    console.log(res)
    }
    })

    openBluetoothAdapter

    该 API 使用方法为 wx.openBluetoothAdapter(Object object)
    说明:
    其他蓝牙相关 API 必须在 wx.openBluetoothAdapter 调用之后使用。否则 API 会返回错误(errCode=10000)。
    在用户蓝牙开关未开启或者手机不支持蓝牙功能的情况下,调用 wx.openBluetoothAdapter 会返回错误(errCode=10001),表示手机蓝牙功能不可用。
    功能说明:初始化蓝牙模块。iOS 上开启主机/从机(外围设备)模式时需分别调用一次,并指定对应的mode
    参数及说明:Object object。
    属性
    类型
    合法值及说明
    默认值
    必填
    说明
    mode
    string
    central:主机模式
    peripheral:从机(外围设备)模式
    central
    蓝牙模式,可作为主/从设备,仅 iOS 需要
    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 为空或者是格式不正确
    object.fail 回调函数返回的 state 参数(仅 iOS)
    状态码
    说明
    0
    未知
    1
    重置中
    2
    不支持
    3
    未授权
    4
    未开启
    示例代码:
    wx.openBluetoothAdapter({
    success (res) {
    console.log(res)
    }
    })

    getConnectedBluetoothDevices

    该 API 使用方法为 wx.getConnectedBluetoothDevices(Object object)
    功能说明:根据主服务 UUID 获取已连接的蓝牙设备。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    services
    Array.
    -
    蓝牙设备主服务的 UUID 列表(支持 16/32/128 位 UUID)
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    object.success 回调函数:Object res。
    属性
    类型
    说明
    devices
    Array.<Object>
    搜索到的设备列表
    结构属性
    类型
    说明
    name
    string
    蓝牙设备名称,某些设备可能没有
    deviceId
    string
    用于区分设备的 id
    错误返回值
    错误码
    错误信息
    说明
    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.getConnectedBluetoothDevices({
    services: ['FEE7'],
    success (res) {
    console.log(res)
    }
    })

    getBluetoothDevices

    该 API 使用方法为 wx.getBluetoothDevices(Object object)
    
    注意:
    该接口获取到的设备列表为蓝牙模块生效期间所有搜索到的蓝牙设备,若在蓝牙模块使用流程结束后未及时调用 wx.closeBluetoothAdapter 释放资源,会存在调用该接口会返回之前的蓝牙使用流程中搜索到的蓝牙设备,可能设备已经不在用户身边,无法连接。
    功能说明:获取在蓝牙模块生效期间所有搜索到的蓝牙设备。包括已经和本机处于连接状态的设备。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    object.success 回调函数:Object res。
    属性
    类型
    说明
    devices
    Array.<Object>
    UUID 对应的已连接设备列表
    结构属性
    类型
    说明
    name
    string
    蓝牙设备名称,某些设备可能没有
    deviceId
    string
    蓝牙设备 id
    RSSI
    number
    当前蓝牙设备的信号强度,单位:dBm
    advertisData
    ArrayBuffer
    当前蓝牙设备的广播数据段中的 ManufacturerData 数据段
    advertisServiceUUIDs
    Array.<string>
    当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
    localName
    string
    当前蓝牙设备的广播数据段中的 LocalName 数据段
    serviceData
    Object
    当前蓝牙设备的广播数据段中的 ServiceData 数据段
    connectable
    boolean
    当前蓝牙设备是否可连接( Android 8.0以下不支持返回该值 )
    示例代码:
    // ArrayBuffer转16进度字符串示例
    function ab2hex(buffer) {
    var hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function(bit) {
    return ('00' + bit.toString(16)).slice(-2)
    }
    )
    return hexArr.join('');
    }
    wx.getBluetoothDevices({
    success: function (res) {
    console.log(res)
    if (res.devices[0]) {
    console.log(ab2hex(res.devices[0].advertisData))
    }
    }
    })

    getBluetoothAdapterState

    该 API 使用方法为 wx.getBluetoothAdapterState(Object object)
    功能说明:获取本机蓝牙适配器状态。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    object.success 回调函数:Object res。
    属性
    类型
    说明
    discovering
    boolean
    是否正在搜索设备
    available
    boolean
    蓝牙适配器是否可用
    错误返回值
    错误码
    错误信息
    说明
    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.getBluetoothAdapterState({
    success (res) {
    console.log(res)
    }
    })

    closeBluetoothAdapter

    该 API 使用方法为 wx.closeBluetoothAdapter(Object object)
    功能说明:关闭蓝牙模块。调用该方法将断开所有已建立的连接并释放系统资源。建议在使用蓝牙流程后,与 wx.openBluetoothAdapter 成对调用。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    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.closeBluetoothAdapter({
    success (res) {
    console.log(res)
    }
    })

    onBluetoothDeviceFound

    该 API 使用方法为 wx.onBluetoothDeviceFound(function listener)
    注意:
    若在 wx.onBluetoothDeviceFound 回调了某个设备,则此设备会添加到 wx.getBluetoothDevices 接口获取到的数组中。
    蓝牙设备在被搜索到时,系统返回的 name 字段一般为广播包中的 LocalName 字段中的设备名称,而如果与蓝牙设备建立连接,系统返回的 name 字段会改为从蓝牙设备上获取到的 GattName。若需要动态改变设备名称并展示,建议使用 localName 字段。
    Android 下部分机型需要有位置权限才能搜索到设备,需留意是否开启了位置权限。
    功能说明:监听搜索到新设备的事件。
    参数及说明:function listener,搜索到新设备的事件的监听函数, 参数 object res 如下:
    属性
    类型
    说明
    devices
    Array.<Object>
    新搜索到的设备列表
    devices 结构属性
    结构属性
    类型
    说明
    name
    string
    蓝牙设备名称,某些设备可能没有
    deviceId
    string
    蓝牙设备 id
    RSSI
    number
    当前蓝牙设备的信号强度,单位 dBm
    advertisData
    ArrayBuffer
    当前蓝牙设备的广播数据段中的 ManufacturerData 数据段
    advertisServiceUUIDs
    Array.<string>
    当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
    localName
    string
    当前蓝牙设备的广播数据段中的 LocalName 数据段
    serviceData
    Object
    当前蓝牙设备的广播数据段中的 ServiceData 数据段
    connectable
    boolean
    当前蓝牙设备是否可连接( Android 8.0 以下不支持返回该值 )
    示例代码:
    // ArrayBuffer转16进度字符串示例
    function ab2hex(buffer) {
    var hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function(bit) {
    return ('00' + bit.toString(16)).slice(-2)
    }
    )
    return hexArr.join('');
    }
    wx.onBluetoothDeviceFound(function(res) {
    var devices = res.devices;
    console.log('new device list has founded')
    console.dir(devices)
    console.log(ab2hex(devices[0].advertisData))
    })

    offBluetoothDeviceFound

    该 API 使用方法为 wx.offBluetoothDeviceFound()
    功能说明:移除搜索到新设备的事件的全部监听函数。
    示例代码:
    wx.offBluetoothDeviceFound()

    onBluetoothAdapterStateChange

    该 API 使用方法为 wx.onBluetoothAdapterStateChange(function listener)
    功能说明:监听蓝牙适配器状态变化事件。
    参数及说明:Object res 参数,function listener,蓝牙适配器状态变化事件的监听函数。
    属性
    类型
    说明
    available
    boolean
    蓝牙适配器是否可用
    discovering
    boolean
    蓝牙适配器是否处于搜索状态
    示例代码:
    wx.onBluetoothAdapterStateChange(function (res) {
    console.log('adapterState changed, now is', res)
    })

    offBluetoothAdapterStateChange

    该 API 使用方法为 wx.offBluetoothAdapterStateChange()
    功能说明:移除蓝牙适配器状态变化事件的全部监听函数。
    示例代码:
    wx.offBluetoothAdapterStateChange()

    makeBluetoothPair

    该 API 使用方法为 wx.makeBluetoothPair(Object object)
    功能说明:蓝牙配对接口,仅 Android 支持。通常情况下(需要指定 pin 码或者密码时)系统会接管配对流程,直接调用 wx.createBLEConnection 即可。该接口只应当在开发者不想让用户手动输入 pin 码且真机验证确认可以正常生效情况下用。
    参数及说明:Object object
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id
    pin
    string
    -
    pin 码,Base64 格式。
    timeout
    number
    20000
    超时时间,单位:ms
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)

    isBluetoothDevicePaired

    该 API 使用方法为 wx.isBluetoothDevicePaired(Object object)
    功能说明:查询蓝牙设备是否配对,仅 Android 支持。
    参数及说明:Object object。
    属性
    类型
    默认值
    必填
    说明
    deviceId
    string
    -
    蓝牙设备 id
    success
    function
    -
    接口调用成功的回调函数
    fail
    function
    -
    接口调用失败的回调函数
    complete
    function
    -
    接口调用结束的回调函数(调用成功、失败都会执行)
    
    联系我们

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

    技术支持

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

    7x24 电话支持