（旧）支付宝小程序API 蓝牙

支付宝小程序API蓝牙

my.openBluetoothAdapter

初始化蓝牙适配器。

入参

名称	类型	必填	描述
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
isSupportBLE	Boolean	是否支持 BLE

错误码描述

error	描述
12	蓝牙未打开
13	与系统服务的链接暂时丢失
14	未授权支付宝使用蓝牙功能
15	未知错误

示例代码

my.openBluetoothAdapter({
  success: (res) => {
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.closeBluetoothAdapter

关闭本机蓝牙模块。

入参

名称	类型	必填	描述
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

错误码描述

error	描述
12	蓝牙关闭失败

示例代码

my.closeBluetoothAdapter({
  success: (res) => {
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.getBluetoothAdapterState

获取本机蓝牙模块状态。

入参

名称	类型	必填	描述
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
discovering	Boolean	是否正在搜索设备
available	Boolean	蓝牙模块是否可用(需支持 BLE 并且蓝牙是打开状态)

错误码描述

error	描述
12	获取失败

示例代码

my.getBluetoothAdapterState({
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.startBluetoothDevicesDiscovery

开始搜寻附近的蓝牙外围设备。搜索结果将在 onBluetoothDeviceFound 事件中返回。

入参

名称	类型	必填	描述
services	Array	否	蓝牙设备主 service 的 uuid 列表
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

错误码描述

error	描述
12	开始搜索失败

示例代码

my.startBluetoothDevicesDiscovery({
  services: ['fff0'],
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.stopBluetoothDevicesDiscovery

停止搜寻附近的蓝牙外围设备。

入参

名称	类型	必填	描述
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

错误码描述

error	描述
12	停止搜索失败

示例代码

my.stopBluetoothDevicesDiscovery({
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.getBluetoothDevices

获取所有已发现的蓝牙设备，包括已经和本机处于连接状态的设备。

入参

名称	类型	必填	描述
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
devices	Array	已发现的设备列表

device对象

名称	类型	描述
name	String	蓝牙设备名称，某些设备可能没有
deviceName(兼容旧版本)	String	值与 name 一致
localName	String	广播设备名称
deviceId	String	设备 Id
RSSI	Number	设备信号强度
advertisData	Hex String	设备的广播内容
manufacturerData	Hex String	设备的manufacturerData

错误码描述

error	描述
12	获取失败

示例代码

my.getBluetoothDevices({
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.getConnectedBluetoothDevices

获取处于已连接状态的设备。

入参

名称	类型	必填	描述
services	Array	否	蓝牙设备主 service 的 uuid 列表
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
devices	Array	已连接的设备列表

device对象

名称	类型	描述
name	String	蓝牙设备名称，某些设备可能没有
deviceName(兼容旧版本)	String	值与 name 一致
localName	String	广播设备名称
deviceId	String	设备 Id
RSSI	Number	设备信号强度
advertisData	Hex String	设备的广播内容
manufacturerData	Hex String	设备的manufacturerData

错误码描述

error	描述
12	获取失败

示例代码

my.getConnectedBluetoothDevices({
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.connectBLEDevice

连接低功耗蓝牙设备。

入参

名称	类型	必填	描述
deviceId	String	是	蓝牙设备id
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

错误码描述

error	描述
12	连接失败

示例代码

my.connectBLEDevice({
  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
  deviceId: deviceId,
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.disconnectBLEDevice

断开与低功耗蓝牙设备的连接。

入参

名称	类型	必填	描述
deviceId	String	是	蓝牙设备id
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

错误码描述

error	描述
12	断开失败

示例代码

my.disconnectBLEDevice({
  deviceId: deviceId,
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.writeBLECharacteristicValue

向低功耗蓝牙设备特征值中写入数据。

入参

名称	类型	必填	描述
deviceId	String	是	蓝牙设备 id，参考 device 对象
serviceId	String	是	蓝牙特征值对应 service 的 uuid
characteristicId	String	是	蓝牙特征值的 uuid
value	Hex String	是	蓝牙设备特征值对应的值，16进制字符串
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

错误码描述

error	描述
12	写入数据失败

示例代码

my.writeBLECharacteristicValue({
  deviceId: deviceId,
  serviceId: serviceId,
  characteristicId: characteristicId,
  value: 'fffe',
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.readBLECharacteristicValue

读取低功耗蓝牙设备特征值中的数据。调用后在my.onBLECharacteristicValueChange() 事件中接收数据返回。

入参

名称	类型	必填	描述
deviceId	String	是	蓝牙设备 id，参考 device 对象
serviceId	String	是	蓝牙特征值对应 service 的 uuid
characteristicId	String	是	蓝牙特征值的 uuid
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
characteristic	Object	设备特征值信息

characteristic对象

蓝牙设备characteristic(特征值)信息

名称	类型	描述
characteristicId	String	蓝牙设备特征值的 uuid
serviceId	String	蓝牙设备特征值对应服务的 uuid
value	Hex String	蓝牙设备特征值的value

错误码描述

error	描述
12	读取数据失败

示例代码

my.readBLECharacteristicValue({
  deviceId: deviceId,
  serviceId: serviceId,
  characteristicId: characteristicId,
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.notifyBLECharacteristicValueChange

启用低功耗蓝牙设备特征值变化时的 notify 功能。注意：必须设备的特征值支持notify才可以成功调用，具体参照 characteristic 的 properties 属性另外，必须先启用notify才能监听到设备 characteristicValueChange 事件。

入参

名称	类型	必填	描述
deviceId	String	是	蓝牙设备 id，参考 device 对象
serviceId	String	是	蓝牙特征值对应 service 的 uuid
characteristicId	String	是	蓝牙特征值的 uuid
descriptorId	String	否	notify 的 descriptor 的 uuid （只有android 会用到，非必填，默认值00002902-0000-10008000-00805f9b34fb）
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

错误码描述

error	描述
12	启动失败

示例代码

my.notifyBLECharacteristicValueChange({
  deviceId: deviceId,
  serviceId: serviceId,
  characteristicId: characteristicId,
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.getBLEDeviceServices

获取蓝牙设备所有 service（服务）

入参

名称	类型	必填	描述
deviceId	String	是	蓝牙设备 id，参考 device 对象
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
services	Array	设备service 对象列表，详见下表特征值信息

service对象

蓝牙设备service(服务)信息

名称	类型	描述
serviceId	String	蓝牙设备服务的 uuid
isPrimary	Boolean	该服务是否为主服务

错误码描述

error	描述
12	获取失败

示例代码

my.getBLEDeviceServices({
  deviceId: deviceId,
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.getBLEDeviceCharacteristics

获取蓝牙设备所有 characteristic（特征值）

入参

名称	类型	必填	描述
deviceId	String	是	蓝牙设备 id，参考 device 对象
serviceId	String	是	蓝牙特征值对应 service 的 uuid
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
characteristics	Array	设备特征值列

characteristic对象

蓝牙设备 characteristic （特征值）信息

名称	类型	描述
characteristicId	String	蓝牙设备特征值的 uuid
serviceId	String	蓝牙设备特征值对应服务的 uuid
value	Hex String	蓝牙设备特征值对应的16进制值
properties	Object	该特征值支持的操作类型

properties 对象

名称	类型	描述
read	boolean	该特征值是否支持 read 操作
write	boolean	该特征值是否支持 write 操作
notify	boolean	该特征值是否支持 notify 操作
indicate	boolean	该特征值是否支持 indicate 操作

错误码描述

error	描述
12	获取失败

示例代码

my.getBLEDeviceCharacteristics({
  deviceId: deviceId,
  serviceId: serviceId,
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.onBluetoothDeviceFound

寻找到新的蓝牙设备时触发此事件。

入参

名称	类型	必填	描述
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
devices	Array	新搜索到的设备列表

device对象

名称	类型	描述
name	String	蓝牙设备名称，某些设备可能没有
deviceName(兼容旧版本)	String	值与 name 一致
localName	String	广播设备名称
deviceId	String	设备 Id
RSSI	Number	设备信号强度
advertisData	Hex String	设备的广播内容

示例代码

my.onBluetoothDeviceFound({
  success: (res) => {
    console.log(res);
  }
});

my.offBluetoothDeviceFound

移除寻找到新的蓝牙设备事件的监听。

示例代码

my.offBluetoothDeviceFound();

my.onBLECharacteristicValueChange

监听低功耗蓝牙设备的特征值变化的事件。

入参

名称	类型	必填	描述
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
deviceId	String	蓝牙设备 id，参考 device 对象
serviceId	String	蓝牙特征值对应 service 的 uuid
characteristicId	String	蓝牙特征值的 uuid
value	Hex String	特征值最新的16进制值

示例代码

my.onBLECharacteristicValueChange({
  success: (res) => {
    console.log(res);
  }
});

my.offBLECharacteristicValueChange

移除低功耗蓝牙设备的特征值变化事件的监听。

示例代码

my.offBLECharacteristicValueChange();

my.onBLEConnectionStateChanged

监听低功耗蓝牙连接的错误事件，包括设备丢失，连接异常断开等。

入参

名称	类型	必填	描述
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
deviceId	String	蓝牙设备 id，参考 device 对象
connected	Boolean	连接目前的状态

示例代码

my.onBLEConnectionStateChanged({
  success: (res) => {
    console.log(res);
  }
});

my.offBLEConnectionStateChanged

移除低功耗蓝牙连接的错误事件的监听。

示例代码

my.offBLEConnectionStateChanged();

my.onBluetoothAdapterStateChange

监听本机蓝牙状态变化的事件。

入参

名称	类型	必填	描述
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

success 返回值

名称	类型	描述
available	Boolean	蓝牙模块是否可用
discovering	Boolean	蓝牙模块是否处于搜索状态

示例代码

my.onBluetoothAdapterStateChange({
  success: (res) => {
    console.log(res);
  }
});

my.offBluetoothAdapterStateChange

移除本机蓝牙状态变化的事件的监听。

示例代码

my.offBluetoothAdapterStateChange();

错误码

错误码	说明
10000	未初始化蓝牙适配器
10001	当前蓝牙适配器不可用
10002	没有找到指定设备
10003	连接失败
10004	没有找到指定服务
10005	没有找到指定特征值
10006	当前连接已断开
10007	当前特征值不支持此操作
10008	其余所有系统上报的异常
10009	Android 系统特有，系统版本低于 4.3 不支持BLE
10010	没有找到指定描述符
10011	设备 id 不可用/为空
10012	服务 id 不可用/为空
10013	特征 id 不可用/为空
10014	发送的数据为空或格式错误
10015	操作超时
10016	缺少参数
10017	写入特征值失败
10018	读取特征值失败10001

常见的蓝牙调用流程

常见的支付宝小程序蓝牙调用流程

常见问题

支持版本 android4.3以上支持ble
ios6以上都支持
deviceId，android取到的是蓝牙的mac地址(11:22:33:44:55:66)，ios取到的是UUID(00000000-0000-0000-0000-000000000000这种格式)
调startBluetoothDevicesDiscovery接口搜索不到设备，请确保设备发出了广播。如果接口中有传入services，请确保设备的广播内容中包含了service的UUID
连接设备失败，请确认传入的deviceId是否正确，以及设备发出的信号是否足够强，在信号弱的时候可能会出现连接不上的情况
写数据失败，查看传入的deviceId、serviceId、characteristicId格式是否正确，deviceId是否已连接上(onBLEConnectionStateChanged这个事件中可以监听连接状态变化，getConnectedBluetoothDevices这个方法可以拿到)，确保是在连接状态下调写入方法，查看characteristicId是否属于这个service，以及这个特征值是否支持写
读数据失败，同上，查看这个特征值是否支持读
收不到数据通知，请确认调了notifyBLECharacteristicValueChange这个方法以及传入的参数是否正确，传入的characteristicId特征值是否支持notify或indicate，以及确认硬件是否发出了通知。注意调用notifyBLECharacteristicValueChange方法的以及注册onBluetoothDeviceFound事件的顺序，最好是在连接之后就调用notifyBLECharacteristicValueChange方法。