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 | 否 | 是否允许重复上报同一设备。如果允许重复上报 |
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. | 搜索到的设备列表 |
结构属性 | 类型 | 说明 |
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)
功能说明:获取在蓝牙模块生效期间所有搜索到的蓝牙设备。包括已经和本机处于连接状态的设备。
参数及说明: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以下不支持返回该值 ) |
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 下部分机型需要有位置权限才能搜索到设备,需留意是否开启了位置权限。
功能说明:监听搜索到新设备的事件。
参数及说明:object res 参数,function listener,搜索到新设备的事件的监听函数。
属性 | 类型 | 说明 |
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()
功能说明:移除搜索到新设备的事件的全部监听函数。
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()
功能说明:移除蓝牙适配器状态变化事件的全部监听函数。
makeBluetoothPair
该 API 使用方法为 wx.makeBluetoothPair(Object object)
功能说明:蓝牙配对接口,仅 Android 支持。通常情况下(需要指定
pin
码或者密码时)系统会接管配对流程。该接口只应当在开发者不想让用户手动输入 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 | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |