接口总结
正常使用:

初始化(开启)蓝牙模块wx.openBluetoothAdapter
搜索蓝牙设备(消耗大量资源,要及时结束)wx.startBluetoothDevicesDiscovery
结束搜索wx.stopBluetoothDevicesDiscovery
与蓝牙设备建立连接wx.createBLEConnection
获取蓝牙设备的服务列表wx.getBLEDeviceServices
获取蓝牙设备的某个服务的特征值列表wx.getBLEDeviceCharacteristics
与特征值通信
启用/关闭某个特征值的 notify wx.notifyBLECharacteristicValueChange
读取特征值数据(读取到的数据通过特征值变化事件返回) wx.readBLECharacteristicValue
向特征值写入数据wx.writeBLECharacteristicValue
断开与蓝牙设备的连接wx.closeBLEConnection
停用(关闭)蓝牙模块wx.closeBluetoothAdapter
事件监听:

搜索过程中发现新的蓝牙设备wx.onBluetoothDeviceFound
蓝牙适配器状态变化wx.onBluetoothAdapterStateChange
蓝牙设备连接状态变化wx.onBLEConnectionStateChange
特征值变化(需开启notify)wx.onBLECharacteristicValueChange
其他:

根据uuid获取已连接的设备wx.getConnectedBluetoothDevices
获取当前蓝牙模块周期已发现的设备wx.getBluetoothDevices
获取本机蓝牙适配器的状态wx.getBluetoothAdapterState
踩坑总结
全局
初始化蓝牙模块后才能调用相关API
初始化之前可执行事件监听,但不会触发事件回调
初始化后,如果errCode=10001,那么其实此时小程序蓝牙模块已经初始化完成,可以调用API,也会有事件回调。
iOS 上由于系统需要获取特征值实例,必须要调用获取设备服务和特征值的接口,使用获取到的serviceId和characteristicId,才能对特征值进行read、write、notify操作
Android 上,部分机型获取设备服务时会多出00001800和00001801UUID的服务,这是系统行为,注意不要使用这两个服务
Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 UUID
iOS 上不同手机搜索到的deviceId是不同的
与蓝牙设备通信的 MTU(最大传输单元)系统限定为20字节,如果超过则会出错,这里应该根据蓝牙设备协议进行分片传输。
特征值的读写是二进制数据,ArrayBuffer类型
设备连接
必须成对地调用createBLEConnection和closeBLEConnection接口
Android 上,如果连续多次调用createBLEConnection,可能会导致系统持有同一设备多个连接的实例,导致调用 closeBLEConnection 的时候并不能真正地断开与设备的连接
如果未能及时关闭连接释放资源,容易导致state 133 GATT ERROR的异常
若小程序在之前已有搜索过某个蓝牙设备,并成功建立连接,可直接传入之前搜索获取的deviceId直接尝试连接该设备,无需进行搜索操作
蓝牙连接随时可能断开,建议监听wx.onBLEConnectionStateChange回调事件,当蓝牙设备断开时按需执行重连操作
设备搜索
iOS里面蓝牙状态变化以后不能马上开始搜索,否则会搜索不到设备,必须要等待2秒以上
Android 上,部分机型无定位权限或者是定位开关未打开时会搜不到设备。原因是蓝牙功能是可以获取到定位的,系统基于安全考量,使用蓝牙接口时必须要有定位权限
设备搜索占用大量资源,要及时关闭
wx.getBluetoothDevices获取到的设备列表为蓝牙模块生效期间所有搜索到的蓝牙设备
若在蓝牙模块使用流程结束后未及时调用wx.closeBluetoothAdapter释放资源,那么:
可能不会发现新的设备,因为之前已搜索过
调用wx.getBluetoothDevices时,仍会返回之前的蓝牙使用流程中搜索到的蓝牙设备,即使设备已经不在用户身边,无法连接
蓝牙设备在被搜索到时,系统返回的name字段一般为广播包中的localName字段中的设备名称,而如果与蓝牙设备建立连接,系统返回的name字段会改为从蓝牙设备上获取到的GattName。若需要动态改变设备名称并展示,建议使用localName字段
向特征值写入数据
并行调用多次可能会导致写入失败
若单次写入数据过长,iOS 上存在系统不会有任何回调的情况(包括错误回调)
特征值必须支持 write
读取特征值数据
并行调用多次可能会导致读取失败
接口读取到的信息需要在 onBLECharacteristicValueChange 方法注册的回调中获取
特征值必须支持 read
启用/关闭notify
启用后才会触发特征值变化
监听到的消息要进行过滤处理,有些设备会抽风一样的发送同样的消息,需要在处理逻辑里面去重
开启notify以后并不能马上发送消息,蓝牙设备有个准备的过程,需要延迟1秒以上才能发送,否则会发送失败
特征值必须支持notify或者indicate