(旧)支付宝小程序API 蓝牙

由 ✎﹏๓₯㎕ζั͡❦﹏﹏♛ 创建, 最后一次修改 2017-08-24

支付宝小程序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

常见的蓝牙调用流程

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

常见问题

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