一、蓝牙介绍
官网 蓝牙 (Bluetooth) | 微信开放文档
蓝牙低功耗是从蓝牙 4.0 起支持的协议,与经典蓝牙相比,功耗极低、传输速度更快,但传输数据量较小。常用在对续航要求较高且只需小数据量传输的各种智能电子产品中,比如智能穿戴设备、智能家电、传感器等,应用场景广泛。
1. 角色/工作模式
蓝牙低功耗协议给设备定义了若干角色,或称工作模式。小程序蓝牙目前支持的有以下几种:
1) 中心设备/主机 (Central)
中心设备可以扫描外围设备,并在发现有外围设备存在后与之建立连接,之后就可以使用外围设备提供的服务(Service)。
一般而言,手机会担任中心设备的角色,利用外围设备提供的数据进行处理或展示等等。小程序提供低功耗蓝牙接口是默认设定手机为中心设备的。
2) 外围设备/从机 (Peripheral)
外围设备一直处于广播状态,等待被中心设备搜索和连接,不能主动发起搜索。例如智能手环、传感器等设备。
如果外围设备广播时被设置为不可连接的状态,也被称为广播模式 (Broadcaster),常见的例子是蓝牙信标 (Beacon) 设备。
注意
在小程序中,蓝牙设备可以同时处于主机和从机模式。在安卓设备上,只需要调用 wx.openBluetoothAdapter 初始化一次蓝牙适配器;而在 iOS 设备上,需要分别使用两种不同的 mode 参数分别初始化中心设备和外围设备的蓝牙适配器。建议统一对于主机和从机模式分别进行一次初始化。wx.closeBluetoothAdapter 会同时关闭两种模式的蓝牙适配器。
2. 通信协议
在两个蓝牙低功耗设备建立连接之后,双方的数据交互是基于 GATT (Generic Attribute Profile) 规范,根据该规范可以定义出一个个配置文件 (Profile),描述该蓝牙设备提供的服务 (Service)。
在整个通信过程中,有几个最主要的概念:
-
配置文件 (Profile): Profile 是被蓝牙标准预先定义的一些 Service 的集合,并不真实存在于蓝牙设备中。如果蓝牙设备之间要相互兼容,它们只要支持相同的 Profile 即可。一个蓝牙设备可以支持多个 Profile。
-
服务 (Service): Service 是蓝牙设备对外提供的服务,一个设备可以提供多个服务,比如电量信息服务、系统信息服务等。每个服务由一个 UUID 唯一标识。
-
特征 (Characteristic): 每个 Service 包含 0 至多个 Characteristic。比如,电量信息服务就会有个 Characteristic 表示电量数据。Characteristic 包含一个值 (value)和 0 至多个描述符 (Descriptor) 组成。在与蓝牙设备通信时,主要就是通过读写 Characteristic 的 value 完成。 每个 Characteristic 由一个 UUID 唯一标识。
-
描述符 (Descriptor): Descriptor 是描述特征值的已定义属性。例如,Descriptor 可指定人类可读的描述、特征值的取值范围或特定于特征值的度量单位。每个 Descriptor 由一个 UUID 唯一标识。
3. UUID (Universally Unique Identifier)
根据蓝牙 4.2 协议规范(Vol 3, Part B, section 2.5.1 UUID),UUID 是一个 128 位的唯一标识符,用来标识 Service 和 Characteristic 等。
为了减少存储和传输 128 位 UUID 值的负担,蓝牙技术联盟预分配了一批 UUID,这一批 UUID 拥有一个共同部分,被称为 Bluetooth Base UUID,即 00000000-0000-1000-8000-00805F9B34FB。因此,预分配的 UUID 也可以使用 16 位或 32 位表示,其中 16 位 UUID 最为常用。使用 16/32 位的 UUID 可以降低存储和传输的负载。开发者自定义的 UUID 应注意不能与预分配的 UUID 冲突。
在小程序中,wx.startBluetoothDevicesDiscovery 和 wx.getConnectedBluetoothDevices 的参数支持 16/32/128 位 UUID。在其他接口的参数中,
-
iOS 支持直接使用 16 位 和 128 位的 UUID;
-
Android 8.0.9 版本开始,支持直接使用 16/32/128 位 UUID;
-
Android 8.0.9 以下版本,只支持 128 位的 UUID,需要开发者手动补位到 128 位。补位方式如下
128位UUID = 16位UUID * 2^96 + Bluetooth Base UUID128位UUID = 32位UUID * 2^96 + Bluetooth Base UUID
例如
0x180F -> 0000180F-0000-1000-8000-00805F9B34FB
所有接口的返回值统一为 128 位 UUID。
二、微信小程序蓝牙api
官网 设备/蓝牙wx.stopBluetoothDevicesDiscovery(Object object) | 微信开放文档
主要用到API如下:
1.打开蓝牙适配器:wx.openBluetoothAdapter,后续所有蓝牙模块功能都需要先打开适配器才能进行
2.搜寻蓝牙设备:
2.1 开始搜寻:wx.startBluetoothDevicesDiscovery,此功能比较消耗性能,如果搜索到特定设备可即时停止
2.2 发现设备事件:wx.onBluetoothDeviceFound,在这儿添加实时更新设备列表业务代码
2.3 停止扫描:wx.onBluetoothDeviceFound,停止扫描新的蓝牙设备,当蓝牙扫描到指令设备时,需要即时关闭扫描保证性能
2.4 关闭发现设备事件监听:wx.offBluetoothDeviceFound
3.连接蓝牙设备: wx.createBLEConnection,通过传入蓝牙设备deviceId进行设备直连。这里的deviceId可通过上面扫描时wx.onBluetoothDeviceFound响应值获取
4.监听蓝牙设备连接状态:wx.onBLEConnectionStateChange: 包括开发者主动连接或断开连接,设备丢失,连接异常断开等等
5.获取蓝牙服务
5.1 获取蓝牙低功耗设备所有服务: wx.getBLEDeviceServices,通过
5.2 根据特定服务UUID查询所有特征:[wx.getBLEDeviceCharacteristics](wx.getBLEDeviceCharacteristics),
6.监听蓝牙数据(实时获取蓝牙跳绳回传的电量,跳绳数量等信息)
6.1 订阅特征变化:wx.notifyBLECharacteristicValueChange,开启订阅后续才能监听到蓝牙数据变化
6.2 监听特征值变化:wx.onBLECharacteristicValueChange,通过监听事件触发数据解析业务
7.发送数据(向蓝牙跳绳下发指令)
7.1 下发指令:wx.writeBLECharacteristicValue,通过向蓝牙特定服务的对应特征值写入数据,完成交互。注意:要对应支持“write"属性的特征值
8.关闭蓝牙活动
8.1 wx.stopBluetoothDevicesDiscovery(): 停止扫描新设备
8.2 wx.offBluetoothDeviceFound():关闭扫描新设备监听事件
8.3 wx.offBLECharacteristicValueChange():关闭特征值变化监听(数据监听)
8.4 wx.offBLEConnectionStateChange():移除蓝牙低功耗连接状态改变事件的监听函数
8.5 wx.closeBLEConnection: 断开蓝牙连接
8.6 wx.closeBluetoothAdapter():关闭蓝牙适配器
三、连接流程
1、初始化蓝牙
初次加载,自动获取获取系统信息,检查蓝牙适配器是否可用
初始化蓝牙,提示蓝牙,开始自动搜索蓝牙设备
initBlue(){ var that = this; wx.openBluetoothAdapter({//调用微信小程序api 打开蓝牙适配器接口 success: function (res) { console.log(res) wx.showToast({ title: '初始化成功', icon: 'success', duration: 800 }) that.findBlue();//2.0 }, fail: function (res) {//如果手机上的蓝牙没有打开,可以提醒用户 wx.showToast({ title: '请开启蓝牙', icon: 'error', duration: 1000 }) } }) },
2、搜索蓝牙设备
把搜索到的设备保存在一个数组内,渲染在页面
显示设备名称和连接按钮
//搜索蓝牙设备,并开始连接 findBlue() { var that = this //开始搜索蓝牙 wx.startBluetoothDevicesDiscovery({ allowDuplicatesKey: false, interval: 0, success: function (res) { console.log(res); // wx.showLoading({ // title: '正在搜索设备', // }) // that.getBlue()//3.0 } }) //页面渲染过滤后的蓝牙列表 wx.getBluetoothDevices({ success: function (res) { console.log(res) //蓝牙列表 let arr = [] res.devices.forEach(item => { if (item.name != '未知设备' && item.name) { arr.push(item) } }) that.setData({ deviceList: arr }) console.log(that.data.deviceList) } }) },
3、连接蓝牙与设备
点击连接按钮创建连接,获取设备信息
connetBlueDeviceId(deviceid) { this.setData({ deviceId: deviceid }) var that = this; wx.createBLEConnection({ // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 deviceId: deviceid, //设备id success: function (res) { console.log("res", res) that.setData({ value: 100 }) setTimeout(() => { that.setData({ isgo: true }) }, 1000) // wx.showToast({ // title: '连接成功', // icon: 'success', // duration: 800 // }) that.getServiceId() //5.0 }, fail(err) { console.log(err); if(err.errCode == -1){ that.setData({ value: 100 }) setTimeout(() => { that.setData({ isgo: true }) }, 1000) that.getServiceId() //5.0 } } }) },
4、获取蓝牙设备上所有服务
连接成功停止搜索,获取已连接蓝牙的服务
// 连接上需要的蓝牙设备之后,获取这个蓝牙设备的服务uuid getServiceId() { var that = this wx.getBLEDeviceServices({ // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 deviceId: that.data.deviceId, success: function (res) { console.log(res) var item = res.services[2]; that.setData({ services: item.uuid }) that.getCharacteId(that.data.deviceId, that.data.services) //6.0 }, fail(err) { console.log(err); } }) },
5、获取蓝牙设备某个服务中所有特征值
连接成功获取蓝牙设备服务和特征值(是否能读写)
//获取蓝牙设备某个服务中所有特征值 getCharacteId(deviceId, services) { console.log(this.data.deviceId, this.data.services) var that = this wx.getBLEDeviceCharacteristics({ // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 deviceId: that.data.deviceId, // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取 serviceId: that.data.services, success: function (res) { console.log(res) for (var i = 0; i < res.characteristics.length; i++) { //2个值 var item = res.characteristics[i]; if (item.properties.indicate || item.properties.notify) { that.setData({ propertiesuuId: item.uuid, }) that.startNotice(that.data.propertiesuuId) //7.0 } if (item.properties.write == true) { that.setData({ writeId: item.uuid //用来写入的值 }) } } }, fail(err) { console.log("getBLEDeviceCharacteristics", err); } }) },
6、创建连接,发送指令
startNotice(uuid) { console.log(this.data.deviceId, this.data.services, uuid) wx.notifyBLECharacteristicValueChange({ state: true, // 启用 notify 功能 deviceId: this.data.deviceId, serviceId: this.data.services, characteristicId: uuid, //第一步 开启监听 notityid 第二步发送指令 write type: "notification", success: (res) => { console.log(res,"notify创建连接,发送指令") this.exchange_mtu() } }) },
7、修改mtu
exchange_mtu() { let that = this wx.setBLEMTU({ deviceId: this.data.deviceId, mtu: 247, success: function (res) { console.log(res,"mtu update success") that.onble() }, fail: function (res) { console.log(res,"mtu update failed") }, complete: function (res) { console.log(res,"mtu update complete") } }) },//获取mtugetmtu() { wx.getBLEMTU({ deviceId: this.data.deviceId, writeType: 'write', success(res) { console.log(res) } }) },
8、监听设备返回
onble() { let that = this // 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(''); } function hex2a(hexx) { var hex = hexx.toString(); //force conversion var str = ''; for (var i = 0; i < hex.length; i += 2) str += String.fromCharCode(parseInt(hex.substr(i, 2), 16)); return str; } wx.onBLECharacteristicValueChange(function (res) { console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`) console.log(ab2hex(res.value)) console.log(hex2a(ab2hex(res.value))) }) },
四、通过蓝牙查询配置设备参数
1、查询下发数据帧
compoundPack() { let myData = { cmdType: this.data.type, mtu: "247", devicecode: this.data.devicecode } http.post(http.compoundPack, myData).then((res, err) => { console.log(res) if (res.status) { this.setData({ dataPacks: res.data.dataPacks[0] }) this.writeBleEvent() } }) },
2、将数据帧写入设备
//写入数据 writeBleEvent() { console.log("开始写入值" + this.data.dataPacks); var that = this; var cell = { "writeValue": this.data.dataPacks, } //蓝牙设备特征值对应的值,为 16 进制字符串,限制在 20 字节内。超过可使用分包 // var buffer = this.string2buffer(cell.writeValue); var buffer = this.stringToHex(cell.writeValue); setTimeout(function () { var thisWriteDeviceId = that.data.deviceId; var thisWriteServiceId = that.data.services; var thisWriteCharacteristicId = that.data.writeId; console.log(thisWriteDeviceId, thisWriteServiceId, thisWriteCharacteristicId, buffer) wx.writeBLECharacteristicValue({ deviceId: thisWriteDeviceId, serviceId: thisWriteServiceId, characteristicId: thisWriteCharacteristicId, value: buffer, success: function (res) { console.log(res.errMsg); console.log("发送成功"); that.onble() }, fail: function (res) { console.log(res); console.log("发送失败." + res.errMsg); if (res.errCode == 10006) { that.setData({ isconnect: false }) } }, complete: function () {} }, 1000); }); },
3、接收设备回复
console.log(stat,onble() { let that = this // 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(''); } function hex2a(hexx) { var hex = hexx.toString(); //force conversion var str = ''; for (var i = 0; i < hex.length; i += 2) str += String.fromCharCode(parseInt(hex.substr(i, 2), 16)); return str; } wx.onBLECharacteristicValueChange(function (res) { console.log('res', res) console.log('hex:', ab2hex(res.value)) console.log('hex2astring:', hex2a(ab2hex(res.value))) let view = new Uint8Array(res.value); let stat for (let i = 0; i < view.length; i++) { if ((i + 1) <= view.length) { ab2hex(stat)) if (stat) { const getShort = (a, b) => a << 8 | b << 0 const firstShort = getShort(stat[11], stat[12]) const secondShort = getShort(stat[12], stat[11]) console.log(firstShort, secondShort, '111') let bitbufferlength = firstShort + 17 console.log(bitbufferlength,stat.length,'长度') that.setData({ bufferarr: stat }) if (bitbufferlength == stat.length) { if (ab2hex(stat)) { that.frameParse(ab2hex(stat)) } if (view[i] == '0x7E' && view[i + 1] == '0x7E') { stat = view.subarray(i) } } } console.log(stat, }else if(bitbufferlength < stat.length){ stat = stat.slice(0,bitbufferlength) console.log(stat,ab2hex(stat),'截取') that.frameParse(ab2hex(stat)) } } else { console.log(that.data.bufferarr, ab2hex(that.data.bufferarr), ab2hex(res.value), '拼接') if (that.data.bufferarr.length > 0 && (ab2hex(res.value).indexOf('0d0a') == -1)) { that.frameParse(ab2hex(that.data.bufferarr) + ab2hex(res.value)) } } }) },
4、数据帧解析
frameParse(hex) { console.log('hex1111111111', hex) this.setData({ bufferarr: [] }) let myData = { hexData: hex, devicecode: this.data.devicecode } if (this.data.type == '1') { myData.devicecode = '' } http.post(http.frameParse, myData).then((res, err) => { console.log(res) if (res.status) { wx.showToast({ title: '成功', icon: 'success', duration: 2000 }) //处理json数据回显渲染至页面 } }) },
五、其他-蓝牙断开与重连
1、蓝牙手动断开
let that = this wx.closeBLEConnection({ deviceId, success(res) { console.log(res) wx.showToast({ title: '断开成功', icon: 'success', duration: 800 }) that.setData({ isconnect: false }) } })
2、重新连接
bluetooth.connetBlueDeviceId(device)
封装蓝牙连接 3-6
wx.createBLEConnection()开始
六、遇到的问题及解决
1、onBLECharacteristicValueChange监听不到响应数据
解决方法:
1、给onBLECharacteristicValueChange添加延时器;
2、给notifyBLECharacteristicValueChange添加type: 'notification';
3、给writeBLECharacteristicValue添加 writeType: 'writeNoResponse';
4、更换手机设备:Android、IOS设备;
5、查看特征值:read、notify、write、writeNoResponse;
6、分包发送:蓝牙BLE最大支持20个字节发送,因此超过20个字节需要分包发送;
7、遵循硬件文档:使用指定服务,写入、接收分别使用的特征值;
2、关键概念
字节
字节(Byte):是计算机信息技术用于计量存储容量的一种计量单位,作为一个单位来处理的一个二进制数字串。其中下发指令或处理数据时都可以应用到
-
1B(byte,字节)= 8 bit(比特), 相当于一个字符
-
一个字节能表示的最大的整数就是255
-
例如: 数据为5d000001be5d理解为6个字节(6B)
MAC地址(Media Access Control Address)
蓝牙设备的物理地址,每个设备只有一个唯一值。
UUID:(Universally Unique Identifier)
通用唯一识别码,一种软件识别码,一个设备中可以有 多个UUID,一个UUID对应一个软件服务部分。
通过蓝牙的UUID来标识 蓝牙服务与通讯访问的属性,不同的蓝牙服务和属性使用的是不同的方法,所以在获取到蓝牙服务时需要保持服务一致才能通信
蓝牙的read,write,notification特征属性,都有对应的特征服务字段(同样是UUID)。
厂商可以自定义蓝牙服务以及特征字段,因此实现蓝牙通信的前提是拿到确定的服务特征值
服务(service)
有关特征值的收集,用来操作特定功能,所以一个服务里可以有多个特征值。例如,“体温计”服务包括一个温度测量值,以及测量的时间间隔。
特征值(characteristic)
在蓝牙设备之间传递的数据值,例如当前温度测量值。
3、注意事项
-
iOS 上,对特征值的 read、write、notify 操作,由于系统需要获取特征值实例,传入的 serviceId 与 characteristicId 必须由 wx.getBLEDeviceServices 与 wx.getBLEDeviceCharacteristics 中获取到后才能使用。建议统一在建立连接后先执行 wx.getBLEDeviceServices 与 wx.getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互。
-
考虑到蓝牙功能可以间接进行定位,安卓 6.0 及以上版本,无定位权限或定位开关未打开时,无法进行设备搜索。
-
安卓上,部分机型获取设备服务时会多出 00001800 和 00001801 UUID 的服务,这是系统行为,注意不要使用这两个服务。
-
建立连接和关闭连接必须要成对调用。如果未能及时关闭连接释放资源,安卓上容易导致 state 133 GATT ERROR 的异常。
-
在与蓝牙设备传输数据时,需要注意 MTU(最大传输单元)。如果数据量超过 MTU 会导致错误,建议根据蓝牙设备协议进行分片传输。安卓设备可以调用 wx.setBLEMTU 进行 MTU 协商。在 MTU 未知的情况下,建议使用 20 字节为单位传输。