支付宝小程序API 蓝牙
蓝牙 API 概览
- 错误码信息及解决方案，请参见下文 蓝牙 API 错误码对照表。
- 常见问题及解决方法，请参见下文 蓝牙 API FAQ。
版本需求
| 蓝牙类型 | 支付宝客户端版本需求 | Android 或 iOS 版本需求 |
|---|---|---|
| BLE 低功耗蓝牙 | 支付宝客户端 10.0.18 或更高版本，若版本较低，建议做 兼容处理。 | Android： 5.0 及以上版本iOS：无版本需求 |
| 传统蓝牙 | 支付宝客户端 10.0.18 或更高版本，若版本较低，建议做 兼容处理。my.startBluetoothDevicesDiscovery 方法的 allowDuplicatesKey 和 interval 参数，从支付宝客户端 10.0.20 版本开始支持。 | - |
| iBeacon | 支付宝客户端 10.1.8 或更高版本，若版本较低，建议做 兼容处理。 | - |
基本流程
低功耗蓝牙流程图
传统蓝牙流程图
蓝牙 API
示例代码
//初始化
my.openBluetoothAdapter({
success: (res) => {
console.log(res);
}
});
//注册发现事件
my.onBluetoothDeviceFound({
success: (res) => {
let device = res.devices[0];
//连接发现的设备
my.connectBLEDevice({
deviceId: deviceId,
success: (res) => {
console.log(res)
},
fail:(res) => {
},
complete: (res)=>{
}
});
//停止搜索
my.stopBluetoothDevicesDiscovery({
success: (res) => {
console.log(res)
},
fail:(res) => {
},
complete: (res)=>{
}
});
}
});
//注册连接事件
my.onBLEConnectionStateChanged({
success: (res) => {
console.log(res);
if (res.connected) {
//开始读写notify等操作
my.notifyBLECharacteristicValueChange({
deviceId: deviceId,
serviceId: serviceId,
characteristicId: characteristicId,
success: (res) => {
console.log(res)
},
fail:(res) => {
},
complete: (res)=>{
}
});
}
}
});
//注册接收read或notify的数据
my.onBLECharacteristicValueChange({
success: (res) => {
console.log(res);
}
});
//开始搜索
my.startBluetoothDevicesDiscovery({
services: ['fff0'],
success: (res) => {
console.log(res)
},
fail:(res) => {
},
complete: (res)=>{
}
});
//断开连接
my.disconnectBLEDevice({
deviceId: deviceId,
success: (res) => {
console.log(res)
},
fail:(res) => {
},
complete: (res)=>{
}
});
//注销事件
my.offBluetoothDeviceFound();
my.offBLEConnectionStateChanged();
my.offBLECharacteristicValueChange();
//退出蓝牙模块
my.closeBluetoothAdapter({
success: (res) => {
},
fail:(res) => {
},
complete: (res)=>{
}
});蓝牙 API 错误码对照表
| 错误码 | 说明 | 解决方案 | |
|---|---|---|---|
| 10000 | 未初始化蓝牙适配器。 | 调用 my.openBluetoothAdapter，进行蓝牙适配器初始化。 | |
| 10001 | 当前蓝牙适配器不可用。 | 检查当前设备对 BLE 的支持情况，并开启蓝牙功能。 | |
| 10002 | 没有找到指定设备。 | 检查 deviceId，并确认已开启目标蓝牙外设的广播。 | |
| 10003 | 连接失败。 | 检查 deviceId，并确认已开启目标蓝牙外设的广播。 | |
| 10004 | 没有找到指定服务。 | 检查 serviceId，并确认目标外设已拥有该服务。 | |
| 10005 | 没有找到指定特征值。 | 确保 characteristicId 正确、检查目标外设特定 service 下已具备该特征。 | |
| 10006 | 当前连接已断开。 | 连接断开，重新连接。 | |
| 10007 | 当前特征值不支持此操作。 | 检查特征值具备读、写、通知等功能。 | |
| 10008 | 其余所有系统上报的异常。 | 其他未知错误，具体问题具体分析。 | |
| 10009 | Android 系统特有，系统版本低于 4.3 不支持 BLE。 | 提示用户该安卓系统版本不支持使用 。 | |
| 10010 | 没有找到指定描述符。 | 使用正确的 serviceId、characteristicId。 | |
| 10011 | 设备 ID 不可用，或为空。 | 使用正确的 deviceId。 | |
| 10012 | 服务 ID 不可用，或为空。 | 使用正确的 serviceId。 | |
| 10013 | 特征 ID 不可用，或为空。 | 使用正确的 characteristicId。 | |
| 10014 | 发送的数据为空或格式错误。 | 确保写数据或者 HEX 转化正确。 | |
| 10015 | 操作超时。 | 重新操作。 | |
| 10016 | 缺少参数。 | 检查调用的参数，并重新操作。 | |
| 10017 | 写入特征值失败。 | 写失败。确保外设特征支持写操作，不要断开连接。 | |
| 10018 | 读取特征值失败。 | 读失败。确保外设特征支持读操作，不要断开连接。 |
蓝牙 API FAQ
Q：调用 my.writeBLECharacteristicValue 的返回值是空对象吗？
A：不是，调用此 API 返回的是您写入成功的值。
Q：调用 my.onBLECharacteristicValueChange 为何监听不到？一定要先写入才能监听到吗？
A：是的，调用此 API 需要先写入才能监听到。为防止多次注册事件监听导致一次事件多次回调，建议每次调用 on 方法监听事件之前，先调用 off 方法，关闭之前的事件监听。
Q：调用 my.writeBLECharacteristicValue 为何报错10014？
A：10014 错误是由于发送的数据为空或者格式错误导致，建议检查写入的数据或 HEX 转化是否有错误。
Q：调用 my.writeBLECharacteristicValue 写入特征值，使用 16 进制的数组可以吗？
A：不可以，写入特征值需要使用 16 进制的字符串，并限制在 20 字节内。
Q：安卓和 iOS 获取到的 deviceId 格式分别是什么样的？
A：
- Android 获取到的是蓝牙的 mac 地址。如：
11:22:33:44:55:66 - iOS 获取到的是蓝牙的 UUID。如：
00000000-0000-0000-0000-000000000000
Q：调用 my.startBluetoothDevicesDiscovery 接口为何搜索不到设备？
A：请确保设备已发出广播。若接口传入 services，请确保设备的广播内容中包含 service 的 UUID。
Q：调用蓝牙 API 时如果不开启 GPS 定位，部分机型会报错：定位服务未开启。连接不了蓝牙？
A：小程序蓝牙功能需要依赖 GPS 定位，因为大概 5 分之一的手机蓝牙需要依赖 GPS。 建议接入蓝牙时先引导用户打开 GPS 定位服务。
Q：如何解决连接设备失败?
A：请确保传入的 deviceId 正确，并且设备发出的信号足够强。在信号弱的情况下，可能会出现连接设备失败。
Q：如何解决写 / 读数据失败？
A：
- 请确保传入的 deviceId、serviceId、characteristicId 格式正确。
- deviceId 已连接上（可调用 my.onBLEConnectionStateChanged 监听连接状态的变化；调用 my.getConnectedBluetoothDevices 获取处于已连接状态的设备。）
- 在连接状态下写入方法。
- 检查 characteristicId 属于此 service。
- 此特征值支持写 / 读。
Q：如何收到数据通知？
A：
- 请确保已调用 my.notifyBLECharacteristicValueChange 方法，并且传入的参数正确。
- 传入的 characteristicId 特征值支持 notify 或 indicate 操作。
- 确保硬件已发出通知。
- 注意基本流程顺序，在连接之后就调用 my.notifyBLECharacteristicValueChange 方法。
Q：为何事件回调会多次被调用？
A：由于多次匿名函数注册监听了同一事件。所以建议在每次调用 on 方法监听事件之前，先调用 off 方法关闭之前的事件监听。