微信小程序蓝牙功能开发与问题记录

一、蓝牙支持情况

1. 微信小程序对蓝牙的支持情况

目前普遍使用的蓝牙规格：经典蓝牙和蓝牙低功耗。

经典蓝牙（蓝牙基础率/增强数据率）：常用在对数据传输带宽有一定要求的大数据量传输场景上，比如需要传输音频数据的蓝牙音箱、蓝牙耳机等；

蓝牙低功耗 (Bluetooth Low Energy, BLE): 从蓝牙 4.0 起支持的协议，特点就是功耗极低、传输速度更快，常用在对续航要求较高且只需小数据量传输的各种智能电子产品中，比如智能穿戴设备、智能家电、传感器等。

		IOS	安卓	基础库（当前开发基础库2.23+）
经典蓝牙		不支持	不支持，规划中	/
蓝牙低功耗	主机模式（手机作为客户端，主动连接）	微信客户端6.5.6及以上	微信客户端6.5.7及以上	1.1.0及以上
	从机模式（手机作为服务端，被动连接）	支持	支持	2.10.3及以上
	蓝牙信标（持续广播，但不建立连接）	支持	支持	1.2.0及以上

2. IOS和安卓设备对蓝牙低功耗的支持情况

由于项目所使用的设备是低功耗蓝牙，故对此做调研：

	IOS	安卓
连接设备数量	20个	6-8个
连接速度	正常	部分安卓机经常出现连接速度慢、连接超时的现象
传输数据量（MTU）	20字节	20字节
设备搜索	支持	6.0及以上版本需要打开定位权限

注意点：1）数据量超过 MTU （20 字节）会导致错误，需要根据蓝牙设备协议进行分片传输。其中安卓分片之间的传输需要做延迟 250ms。

2）由于Android 从微信 6.5.7 开始支持，iOS 从微信 6.5.6 开始支持，因此小程序中需要做好版本检测（wx.getSystemInfoSync 获取系统信息）。

二、基本需求

1. 添加页面：开启蓝牙搜索，选择设备并输入识别码（蓝牙连接后发送识别码，匹配成功则与设备正式建立了连接）。

2. 首页：可进行蓝牙连接、切换、断开、消息监听与数据发送（识别码匹配）。

三、蓝牙API的基本使用

整理上述涉及蓝牙API的使用：

1. 添加页面（搜索蓝牙逻辑）：

// 添加页
// 检查蓝牙是否开启
checkBluetoothOn(){
    let sucCallback = this.startDiscovering
    let errCallback = () => {
        // 蓝牙未开启逻辑处理
    } 
    // 如果蓝牙开启状态，就去搜索设备
    this.getBlueState(errCallback, sucCallback)
},
// 判断手机蓝牙是否打开
getBlueState (errCallback, sucCallback) {
    this.$getBlueState(errCallback).then(res=>{
        if(res.errno === 0){
            sucCallback ? sucCallback() : ''
        } else {}
    });
},
// 蓝牙搜索逻辑 15s关闭
startDiscovering(){
    // 开始搜寻附近设备
    this.$discoveryBlue(this.found)
    setTimeout(()=>{
        this.handleStopDiscovery()
    }, 15000)
},
// 找到新设备就触发该方法 处理数据逻辑
found(res) {
    var devices = res.devices;
    devices.map(async item => {
        // 对设备信息处理
    })
},
handleStopDiscovery(){
    let stopLoading = () => {
        this.loading = false
        // 其它关闭逻辑
        
    }
    this.$stopDiscoveryBlue(stopLoading, stopLoading)
},

2. 首页（连接逻辑）：

onShow() {
    // 第一次进来如果没有连接 去自动连接
    let sucCallback = (this.blueDeviceList?.length && this.isAutoConnect) ? 
           this.autoConnect : this.isConnnected
    let errCallback = () => {
        // 未开启逻辑
    }
    // 如果蓝牙开启状态 就去连接
    this.getBlueState(errCallback, sucCallback)
    this.isAutoConnect = false
},
methods: {
    async autoConnect(){
        this.isFound = false
        this.$discoveryBlue(this.found)
        .catch((err) => {
            // 查找失败逻辑处理
        })
         // 15s后未找到数据
        setTimeout(()=>{
            if(!this.isFound){
                this.notFound()
            }
        }, 15000)
    },
    // 找到新设备就触发该方法 处理数据逻辑
    found(res) {
        var devices = res.devices;
        devices.map(async item => {
            // 以 deviceId 为唯一标识，过滤重复设备
            if(item.deviceId == this.connectingDevice.deviceId) {
                this.isFound = true
                this.handleConnect(this.connectingDevice)
                wx.offBluetoothDeviceFound(this.found) // 防止回调函数重复执行导致重复连接
            }
        })
    },
    notFound(){
        let stopLoading = () => {
            // 其它逻辑
        }
        this.$stopDiscoveryBlue(stopLoading, stopLoading)
    },
    async handleConnect(deviceInfo){
        let { deviceId, idCode } = deviceInfo
        this.$connectBlue(deviceId).then(async (res)=>{
            const {notifyServiceId, writeServiceId, notifyCharacteristicId, writeCharacteristicId} = await this.getBasicIds(deviceId)
            let listenValueChange = () => {
                this.$listenCharacteristicValueChange(this.getInfoFromBluetooth)
            }
            this.$notifyBlue(deviceId, listenValueChange, notifyServiceId, notifyCharacteristicId)
            .then(()=>{
                let { buffer } = this.$getBuffer({
                  body: idCode, 
                  length: 11, // 帧长度
                  command, // 绑定命令字
                })
                this.$sendBlue(deviceId, buffer, writeServiceId, writeCharacteristicId )
                .catch(async(err) => {
                    await this.stopConnect(deviceInfo.deviceId)
                    // 其它逻辑
                })
            }).catch(async()=>{
                await this.stopConnect(deviceInfo.deviceId)
                // 其它逻辑
            })

        }).catch(()=>{
            // 逻辑处理
        })
    },
    // 获取蓝牙传输过来的数据处理
    getInfoFromBluetooth(res){
        
    },
    stopConnect(deviceId){
        return new Promise((resolve) => {
            let connectedDevice = this.getStorageInfo('connectedDevice', {})
            let connectedDeviceId = deviceId || connectedDevice?.deviceId 
            if(!connectedDeviceId) return resolve()
            this.$closeConnection(connectedDeviceId).then((res) => {
                // 逻辑处理
                resolve()
            }).catch((err)=>{
                // 断连失败逻辑处理
            })
        })
    },
    isConnnected(){
        const { connected } = this.connectStatus
        let connectedDevice = this.blueDeviceList.find(item => item.status == connected)
        if(connectedDevice){
            this.$getServicesBlue(connectedDevice.deviceId)
            .then(async()=>{
                // 如果连接状态，需要重新建立消息通道
                const {notifyServiceId, notifyCharacteristicId} = await this.getBasicIds(connectedDevice.deviceId)
                let listenValueChange = () => {
                    this.$listenCharacteristicValueChange(this.getInfoFromBluetooth)
                }
                this.$notifyBlue(connectedDevice.deviceId, listenValueChange, notifyServiceId, notifyCharacteristicId)
                .catch(async()=>{
                    await this.stopConnect(deviceInfo.deviceId)
                    // 其它逻辑
                })
            })
            .catch(err => {
                // 连接已断开
                if(err.errCode == 10006){
                    // 其它逻辑
                }
            })
        }
    },
    getBasicIds(deviceId){
        return new Promise(async(resolve, reject) => {
            let {notifyServiceId, writeServiceId} = await this.$getServicesBlue(deviceId)
            let notifyCharacteristicId = await this.$getCharacteristicsBlue(deviceId, notifyServiceId)
            let writeCharacteristicId = await this.$getCharacteristicsBlue(deviceId, writeServiceId)
            resolve({notifyServiceId, writeServiceId, notifyCharacteristicId, writeCharacteristicId})
        })
    },
}

3. 公共方法：

// 公共方法封装小程序蓝牙api
function $getBlueState(errCallback) {
    return new Promise((resolve, reject) => {
        $initBlue().then(res=>{
            resolve(res)
        }).catch(err=> {
            if(err.errCode === 10001){
                return errCallback ? errCallback() :
            }
        })
    })
}
function $initBlue() {
    return new Promise((resolve, reject) => {
        uni.openBluetoothAdapter({
            success(res) {
                resolve(res)
            },
            fail(err) {
                reject(err)
            }
        })
    })
}
function $discoveryBlue(callback) {
    return new Promise((resolve, reject) => {
        uni.startBluetoothDevicesDiscovery({
            services: mainServiceIds,
            allowDuplicatesKey: true,
            success(res) {
                uni.onBluetoothDeviceFound(callback)
            },
            fail(err) {
                console.error(err)
                reject(err)
            }
        })
    })
}
function $stopDiscoveryBlue(sucCallback, errCallback) {
    uni.stopBluetoothDevicesDiscovery({
        success(res) {
            console.log('停止设备搜索')
            sucCallback ? sucCallback() : ''
        },
        fail(err) {
            console.log('停止搜索设备失败')
            console.error(err)
            errCallback ? errCallback() : ''
        }
    })
}
function $getServicesBlue(deviceId) {
    return new Promise((resolve, reject) => {
        uni.getBLEDeviceServices({
            deviceId,
            success(res) {
                // 逻辑（根据硬件给的协议取对应服务ID）
                resolve({
                    notifyServiceId,
                    writeServiceId
                })
            },
            fail(err) {
                console.error(err)
                reject(err)
            }
        })
    })
}
function $getCharacteristicsBlue(deviceId, serviceId) {
    return new Promise((resolve, reject) => {
        uni.getBLEDeviceCharacteristics({
            deviceId,
            serviceId,
            success(res) {
                const characteristicId = res.characteristics[0].uuid
                resolve(characteristicId)
            },
            fail(err) {
                console.error(err)
            }
        })
    })
}
function $notifyBlue(deviceId, callback, serviceId, characteristicId) {
    return new Promise((resolve, reject) => {
        uni.notifyBLECharacteristicValueChange({
            state: true, // 启用 notify 功能
            deviceId, // 设备id
            serviceId: serviceId, // 监听指定的服务
            characteristicId: characteristicId, // 监听对应的特征值
            success(res) {
                callback()
                resolve()
            },
            fail(err) {
                console.log(serialDataChannel.serviceId, serialDataChannel.characteristicId)
                console.error(err)
                reject()
            }
        })
    })
}
function $sendBlue(deviceId, buffer, serviceId, characteristicId) {
    return new Promise((resolve, reject) => {
        uni.writeBLECharacteristicValue({
            deviceId,
            serviceId: serviceId,
            characteristicId: characteristicId,
            value: buffer,
            success(res) {
                resolve(res)
            },
            fail(err) {
                console.error(err)
                reject()
            }
        })
    })
}
function $listenCharacteristicValueChange(callback) {
    uni.onBLECharacteristicValueChange(res => {
        callback(res)
    })
}

四、问题记录

1. 手机开启了蓝牙，但是api openBluetoothAdapter 仍然调用失败？

检查是否给微信授权了蓝牙功能。

2. onBluetoothDeviceFound 搜索到设备以后需要建立连接。接口持续搜索会导致重复连接。

防止回调函数重复执行导致重复连接，需要调用 wx.offBluetoothDeviceFound(this.found) 。

3. 设备Id、特征值Id、服务Id是否是唯一？
设备Id：唯一。

特征值Id和服务Id不唯一：不同蓝牙的服务Id和特征值Id可能是一样的；同一蓝牙设备的服务Id和特征值Id是固定的。

4. 既然蓝牙的特征值Id和服务Id是固定的，那是否可以写死，直接调用读写api（ notifyBLECharacteristicValueChange 和 writeBLECharacteristicValue）？

不能。api会调用失败。需要先调用 getBLEDeviceServices 和 getBLEDeviceCharacteristics 。

5. 蓝牙读写通信的数据如何转化？

通信过程涉及到的转化包括：10进制和16进制互相转化、16进制和 ArrayBuffer 互相转化。

1）10进制转16进制：

let deci = 172;
console.log(deci.toString(16))

2）16进制转10进制：

let hex = '0xAC'
console.log(parseInt(hex, 16))

3）16进制转字符串：

let hexToString = (hex) => {
  let str = '';
  for (let i = 0; i < hex.length; i += 2) {
    let v = parseInt(hex.substr(i, 2), 16);
    if (v) str += String.fromCharCode(v);
  }
  return str;
}
hexToString('68656c6c6f')

4）字符串转16进制：

let stringToHex = (str) => {
  let val= "";
  for(let i = 0; i < str.length; i++){
    if(val == "")
      val = str.charCodeAt(i).toString(16);
    else
      val += "," + str.charCodeAt(i).toString(16);
  }
  return val;
}
stringToHex('hello')

5）字符串转16进制转 ArrayBuffer：

let info = 'hello'
const buffer = new ArrayBuffer(info.length)
const dataView = new DataView(buffer)
for (var i = 0; i < info.length; i++) {
  dataView.setUint8(i, info.charAt(i).charCodeAt())
}
wx.writeBLECharacteristicValue({
  deviceId,
  serviceId,
  characteristicId,
  value: buffer,
  success (res) {
    console.log('writeBLECharacteristicValue success', res)
  }
})

6）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((res) => {
  console.log(ab2hex(res.value))
})

6. 蓝牙帧发送出现分包的情况？

有时蓝牙设备传来的帧会有不完整的情况，需要做拼接处理。此处逻辑为：在监听函数中，获取到不完整的帧时，如果帧头正确，保存并等下一帧，否则舍弃。帧头正确并获取到下一帧后进行拼接。当获取到的帧符合我们期待的长度时，进行之后的帧校验与业务逻辑处理。如果指定时间没有接受到有效帧数据，则断连。

7. 超时间没有获取到接收有效帧数据的断连逻辑？

本项目的协议上规定，状态帧每30s上传一次。如果接收到有效状态帧，则更新状态，并对关闭连接进行延迟；如果没有获取到有效状态帧，则2min后会断开连接。具体如下：

// 有效帧获取到后执行
this.delayStopConnect(this.connectedDevice.deviceId)

// 对 delayStopConnect 进行 debounce，状态帧超过2分钟没有回复则断连
delayStopConnect: utils.debounce(async function(deviceId){
    await this.stopConnect(deviceId)
    uni.hideLoading();
    this.showModalTips('设备连接异常')
}, 120000),

// debounce 函数
function debounce(fn, delay, isImmediate) {
    var timer = null;  //初始化timer，作为计时清除依据
    return function() {
      var context = this;  //获取函数所在作用域this
      var args = arguments;  //取得传入参数
      clearTimeout(timer);
      if(isImmediate && timer === null) {
          //时间间隔外立即执行
          fn.apply(context,args);
        timer = 0;
        return;
      }
      timer = setTimeout(function() {
        fn.apply(context,args);
        timer = null;
      }, delay);
    }
}

8. 如何保证帧的有效性（帧校验）？

一般来说，硬件会在协议上说明。一般是拿到回复帧后，取其中某几段进行和校验。如果校验得到的值和回复帧的值相同，则校验成功。例如：一个回复帧包含帧头+帧长度+命令字+识别码+校验码+帧尾。校验码等于命令字与识别码的和。假设命令字是 0xAB，识别码是 0x01，则正确的校验码是 0xAC 。把它跟蓝牙传来的回复帧的校验码进行比较即可。

9. 保证一次连接一个设备的逻辑处理？

由于当前项目的需求是，一个手机只能连接一个蓝牙设备（小程序做处理），但是实际手机是支持连接多个蓝牙设备的，所以如果用户一次性点了很多个设备，需要做相关处理。我的思路是创建一个数组堆，记录连接的设备。如果连接上则 push()，如果发现数组长度大于1，则 shift() 掉最先连接的。

10. 小程序能否主动监听到蓝牙开启与关闭？
可以通过 onBLEConnectionStateChange 监听到蓝牙断开；蓝牙开启监听不到，除非手动定时请求api判断（如果官方有相关监听api，欢迎指正）。

11. 切换页面，能否持续收到监听数据，是否要重新建立监听？
在页面A建立消息通道（notifyBLECharacteristicValueChange）以后，跳转到页面B，仍然可以监听到数据（不论是 navigateTo 还是 navigateBack）。但如果其它页面此时再次调用此api，会覆盖掉之前的消息通道。

12. 设备A连接后，断开连接。设备B立刻连接，连接不上，需要过1分钟左右（安卓机尤其明显）？
因为程序做了连接超时则请求失败的处理。经排查发现，连接超时的api是设备搜索（startBluetoothDevicesDiscovery）和设备连接（getConnectedBluetoothDevices）。
一个不完美，但管用的解决方法：这两个 api 不设置 services 参数。

13. 关闭再次打开小程序，蓝牙连接是否会中断？
理论上是，实际上有时不会。
首先，2023.23.3 官方回复目前暂时不支持后台下的蓝牙功能（https://developers.weixin.qq.com/community/develop/doc/0008a409c889c0f8d76fd1ec356400?highLine=%25E8%2593%259D%25E7%2589%2599%25E5%2590%258E%25E5%258F%25B0%25E5%259C%25BA%25E6%2599%25AF）
其次，小程序的运行机制是（https://developers.weixin.qq.com/miniprogram/dev/framework/runtime/operating-mechanism.html）：
小程序切换后台（包括息屏）5s，微信会停止小程序js线程执行，在小程序再次进入前台时事件和接口回调会触发；小程序切换后台30分钟，小程序销毁。
二者结合，理论上蓝牙应该在30分钟后被断开。但事实上，发现有时候ios和安卓都没有断开。因为其它手机搜索不到相应设备。

14. 一些 ios 和安卓的 API 兼容问题

1）关于断开连接（closeBLEConnection）：ios 设备在没有连接蓝牙设备时，调用断开接口，显示调用成功；但是安卓机会得到错误码 10006 （当前设备已断开连接）。

2）关于搜索设备（startBluetoothDevicesDiscovery）：安卓机搜索一次以后，再次调用该接口，刚才已经搜索出来的设备搜索不到了，除非加上参数：allowDuplicatesKey。ios 加不加这个参数都可以正常搜索到设备。