支付宝小程序蓝牙 API列表

my.openBluetoothAdapter

初始化蓝牙适配器。

入参

名称	类型	必填	描述
autoClose	Boolean	否	不传的话默认是true，表示是否在离开当前页面时自动断开蓝牙(仅对android有效)
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	否	调用结束的回调函数（调用成功、失败都会执行）

示例代码

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

my.getBluetoothAdapterState

获取本机蓝牙模块状态。

入参

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

success 返回值

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

示例代码

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

my.startBluetoothDevicesDiscovery

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

入参

名称	类型	必填	描述
services	Array	否	蓝牙设备主 service 的 uuid 列表
allowDuplicatesKey	Boolean	否	是否允许重复上报同一设备， 如果允许重复上报，则onBluetoothDeviceFound 方法会多次上报同一设备，但是 RSSI 值会有不同
interval	Integer	否	上报设备的间隔，默认为0，意思是找到新设备立即上报，否则根据传入的间隔上报
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

示例代码

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

my.stopBluetoothDevicesDiscovery

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

入参

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

示例代码

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

示例代码

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

示例代码

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

my.connectBLEDevice

连接低功耗蓝牙设备。

入参

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

示例代码

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	否	调用结束的回调函数（调用成功、失败都会执行）

示例代码

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进制字符串，限制在20字节内
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

示例代码

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

示例代码

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）
state	Boolean否	-	是否启用notify或indicate
success	Function	否	调用成功的回调函数
fail	Function	否	调用失败的回调函数
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

示例代码

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	否	调用失败的回调函数

success 返回值

名称	类型	描述
services	Array	设备service 对象列表，详见下表特征值信息
complete	Function	否	调用结束的回调函数（调用成功、失败都会执行）

service对象

蓝牙设备service(服务)信息

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

示例代码

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 操作

示例代码

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	读取特征值失败