支付宝小程序API 蓝牙

蓝牙 API 概览

• 错误码信息及解决方案，请参见下文 蓝牙 API 错误码对照表。
• 常见问题及解决方法，请参见下文 蓝牙 API FAQ。

版本需求

基本流程

低功耗蓝牙流程图

传统蓝牙流程图

蓝牙 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 错误码对照表

蓝牙 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 方法关闭之前的事件监听。