全部产品

蓝牙 API 列表

更新时间:2020-07-09 10:23:34

说明
  • mPaaS 10.1.32 及以上版本支持蓝牙接口。
  • 目前不支持在开发者工具上进行调试,需要使用真机才能正常调用小程序蓝牙接口。

my.openBluetoothAdapter

初始化小程序蓝牙模块,生效周期为调用 my.openBluetoothAdapter 至调用 my.closeBluetoothAdapter 或小程序被销毁为止。 在小程序蓝牙适配器模块生效期间,开发者可以正常调用下面的小程序 API,并会收到蓝牙模块相关的 on 事件回调。

入参

名称 类型 必填 描述
autoClose Boolean 表示是否在离开当前页面时自动断开蓝牙,不传的话默认是 true(注意:仅支持 Android 系统)
success Function 调用成功的回调函数
fail Function 调用失败的回调函数
complete Function 调用结束的回调函数(调用成功、失败都会执行)

success 返回值

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

错误码描述

error 描述 解决方案
12 蓝牙未打开 请尝试打开蓝牙
13 与系统服务的链接暂时丢失 请尝试重新连接
14 未授权客户端使用蓝牙功能 请授权客户端使用蓝牙功能
15 未知错误 -

代码示例

  1. <!-- .axml-->
  2. <view class="page">
  3. <view class="page-description">蓝牙 API</view>
  4. <view class="page-section">
  5. <view class="page-section-title">本机蓝牙开关状态</view>
  6. <view class="page-section-demo">
  7. <button type="primary" onTap="openBluetoothAdapter">初始化蓝牙</button>
  8. <button type="primary" onTap="closeBluetoothAdapter">关闭本机蓝牙</button>
  9. <button type="primary" onTap="getBluetoothAdapterState">获取蓝牙状态</button>
  10. </view>
  11. <view class="page-section-title">扫描蓝牙设备</view>
  12. <view class="page-section-demo">
  13. <button type="primary" onTap="startBluetoothDevicesDiscovery">开始搜索</button>
  14. <button type="primary" onTap="getBluetoothDevices">所有搜索到的设备</button>
  15. <button type="primary" onTap="getConnectedBluetoothDevices">所有已连接的设备</button>
  16. <button type="primary" onTap="stopBluetoothDevicesDiscovery">停止搜索</button>
  17. </view>
  18. <view class="page-section-title">连接设备</view>
  19. <view class="page-section-demo">
  20. <input class="input" onInput="bindKeyInput" type="{{text}}" placeholder="输入要连接的设备的deviceId"></input>
  21. <button type="primary" onTap="connectBLEDevice">连接设备</button>
  22. <button type="primary" onTap="getBLEDeviceServices">获取设备服务</button>
  23. <button type="primary" onTap="getBLEDeviceCharacteristics">获取读写特征</button>
  24. <button type="primary" onTap="disconnectBLEDevice">断开设备连接</button>
  25. </view>
  26. <view class="page-section-title">读写数据</view>
  27. <view class="page-section-demo">
  28. <button type="primary" onTap="notifyBLECharacteristicValueChange">监听特征值数据变化</button>
  29. <button type="primary" onTap="readBLECharacteristicValue">读取数据</button>
  30. <button type="primary" onTap="writeBLECharacteristicValue">写入数据</button>
  31. <button type="primary" onTap="offBLECharacteristicValueChange">取消特征值监听</button>
  32. </view>
  33. <view class="page-section-title">其他事件</view>
  34. <view class="page-section-demo">
  35. <button type="primary" onTap="bluetoothAdapterStateChange">本机蓝牙状态变化</button>
  36. <button type="primary" onTap="offBluetoothAdapterStateChange">取消本机蓝牙状态监听</button>
  37. <button type="primary" onTap="BLEConnectionStateChanged">蓝牙连接状态变化</button>
  38. <button type="primary" onTap="offBLEConnectionStateChanged">取消蓝牙连接状态监听</button>
  39. </view>
  40. </view>
  41. </view>
  1. // .js
  2. Page({
  3. data: {
  4. devid: '0D9C82AD-1CC0-414D-9526-119E08D28124',
  5. serid: 'FEE7',
  6. notifyId: '36F6',
  7. writeId: '36F5',
  8. charid: '',
  9. alldev: [{ deviceId: '' }],
  10. },
  11. //获取本机蓝牙开关状态
  12. openBluetoothAdapter() {
  13. my.openBluetoothAdapter({
  14. success: res => {
  15. if (!res.isSupportBLE) {
  16. my.alert({ content: '抱歉,您的手机蓝牙暂不可用' });
  17. return;
  18. }
  19. my.alert({ content: '初始化成功!' });
  20. },
  21. fail: error => {
  22. my.alert({ content: JSON.stringify(error) });
  23. },
  24. });
  25. },
  26. closeBluetoothAdapter() {
  27. my.closeBluetoothAdapter({
  28. success: () => {
  29. my.alert({ content: '关闭蓝牙成功!' });
  30. },
  31. fail: error => {
  32. my.alert({ content: JSON.stringify(error) });
  33. },
  34. });
  35. },
  36. getBluetoothAdapterState() {
  37. my.getBluetoothAdapterState({
  38. success: res => {
  39. if (!res.available) {
  40. my.alert({ content: '抱歉,您的手机蓝牙暂不可用' });
  41. return;
  42. }
  43. my.alert({ content: JSON.stringify(res) });
  44. },
  45. fail: error => {
  46. my.alert({ content: JSON.stringify(error) });
  47. },
  48. });
  49. },
  50. //扫描蓝牙设备
  51. startBluetoothDevicesDiscovery() {
  52. my.startBluetoothDevicesDiscovery({
  53. allowDuplicatesKey: false,
  54. success: () => {
  55. my.onBluetoothDeviceFound({
  56. success: res => {
  57. // my.alert({content:'监听新设备'+JSON.stringify(res)});
  58. var deviceArray = res.devices;
  59. for (var i = deviceArray.length - 1; i >= 0; i--) {
  60. var deviceObj = deviceArray[i];
  61. //通过设备名称或者广播数据匹配目标设备,然后记录deviceID后面使用
  62. if (deviceObj.name == this.data.name) {
  63. my.alert({ content: '目标设备被找到' });
  64. my.offBluetoothDeviceFound();
  65. this.setData({
  66. deviceId: deviceObj.deviceId,
  67. });
  68. break;
  69. }
  70. }
  71. },
  72. fail: error => {
  73. my.alert({ content: '监听新设备失败' + JSON.stringify(error) });
  74. },
  75. });
  76. },
  77. fail: error => {
  78. my.alert({ content: '启动扫描失败' + JSON.stringify(error) });
  79. },
  80. });
  81. },
  82. //停止扫描
  83. stopBluetoothDevicesDiscovery() {
  84. my.stopBluetoothDevicesDiscovery({
  85. success: res => {
  86. my.offBluetoothDeviceFound();
  87. my.alert({ content: '操作成功!' });
  88. },
  89. fail: error => {
  90. my.alert({ content: JSON.stringify(error) });
  91. },
  92. });
  93. },
  94. //获取正在连接中的设备
  95. getConnectedBluetoothDevices() {
  96. my.getConnectedBluetoothDevices({
  97. success: res => {
  98. if (res.devices.length === 0) {
  99. my.alert({ content: '没有在连接中的设备!' });
  100. return;
  101. }
  102. my.alert({ content: JSON.stringify(res) });
  103. devid = res.devices[0].deviceId;
  104. },
  105. fail: error => {
  106. my.alert({ content: JSON.stringify(error) });
  107. },
  108. });
  109. },
  110. //获取所有搜索到的设备
  111. getBluetoothDevices() {
  112. my.getBluetoothDevices({
  113. success: res => {
  114. my.alert({ content: JSON.stringify(res) });
  115. },
  116. fail: error => {
  117. my.alert({ content: JSON.stringify(error) });
  118. },
  119. });
  120. },
  121. bindKeyInput(e) {
  122. this.setData({
  123. devid: e.detail.value,
  124. });
  125. },
  126. //连接设备
  127. connectBLEDevice() {
  128. my.connectBLEDevice({
  129. deviceId: this.data.devid,
  130. success: res => {
  131. my.alert({ content: '连接成功' });
  132. },
  133. fail: error => {
  134. my.alert({ content: JSON.stringify(error) });
  135. },
  136. });
  137. },
  138. //断开连接
  139. disconnectBLEDevice() {
  140. my.disconnectBLEDevice({
  141. deviceId: this.data.devid,
  142. success: () => {
  143. my.alert({ content: '断开连接成功!' });
  144. },
  145. fail: error => {
  146. my.alert({ content: JSON.stringify(error) });
  147. },
  148. });
  149. },
  150. //获取连接设备的server,必须要再连接状态之下才能获取
  151. getBLEDeviceServices() {
  152. my.getConnectedBluetoothDevices({
  153. success: res => {
  154. if (res.devices.length === 0) {
  155. my.alert({ content: '没有已连接的设备' });
  156. return;
  157. }
  158. my.getBLEDeviceServices({
  159. deviceId: this.data.devid,
  160. success: res => {
  161. my.alert({ content: JSON.stringify(res) });
  162. this.setData({
  163. serid: res.services[0].serviceId,
  164. });
  165. },
  166. fail: error => {
  167. my.alert({ content: JSON.stringify(error) });
  168. },
  169. });
  170. },
  171. });
  172. },
  173. //获取连接设备的charid,必须要再连接状态之下才能获取(这里分别筛选出读写特征字)
  174. getBLEDeviceCharacteristics() {
  175. my.getConnectedBluetoothDevices({
  176. success: res => {
  177. if (res.devices.length === 0) {
  178. my.alert({ content: '没有已连接的设备' });
  179. return;
  180. }
  181. this.setData({
  182. devid: res.devices[0].deviceId,
  183. });
  184. my.getBLEDeviceCharacteristics({
  185. deviceId: this.data.devid,
  186. serviceId: this.data.serid,
  187. success: res => {
  188. my.alert({ content: JSON.stringify(res) });
  189. //特征字对象属性见文档,根据属性匹配读写特征字并记录,然后后面读写使用
  190. this.setData({
  191. charid: res.characteristics[0].characteristicId,
  192. });
  193. },
  194. fail: error => {
  195. my.alert({ content: JSON.stringify(error) });
  196. },
  197. });
  198. },
  199. });
  200. },
  201. //读写数据
  202. readBLECharacteristicValue() {
  203. my.getConnectedBluetoothDevices({
  204. success: res => {
  205. if (res.devices.length === 0) {
  206. my.alert({ content: '没有已连接的设备' });
  207. return;
  208. }
  209. this.setData({
  210. devid: res.devices[0].deviceId,
  211. });
  212. my.readBLECharacteristicValue({
  213. deviceId: this.data.devid,
  214. serviceId: this.data.serid,
  215. characteristicId: this.data.notifyId,
  216. //1、安卓读取服务
  217. // serviceId:'0000180d-0000-1000-8000-00805f9b34fb',
  218. // characteristicId:'00002a38-0000-1000-8000-00805f9b34fb',
  219. success: res => {
  220. my.alert({ content: JSON.stringify(res) });
  221. },
  222. fail: error => {
  223. my.alert({ content: '读取失败' + JSON.stringify(error) });
  224. },
  225. });
  226. },
  227. });
  228. },
  229. writeBLECharacteristicValue() {
  230. my.getConnectedBluetoothDevices({
  231. success: res => {
  232. if (res.devices.length === 0) {
  233. my.alert({ content: '没有已连接的设备' });
  234. return;
  235. }
  236. this.setData({
  237. devid: res.devices[0].deviceId,
  238. });
  239. my.writeBLECharacteristicValue({
  240. deviceId: this.data.devid,
  241. serviceId: this.data.serid,
  242. characteristicId: this.data.charid,
  243. //安卓写入服务
  244. //serviceId:'0000180d-0000-1000-8000-00805f9b34fb',
  245. //characteristicId:'00002a39-0000-1000-8000-00805f9b34fb',
  246. value: 'ABCD',
  247. success: res => {
  248. my.alert({ content: '写入数据成功!' });
  249. },
  250. fail: error => {
  251. my.alert({ content: JSON.stringify(error) });
  252. },
  253. });
  254. },
  255. });
  256. },
  257. notifyBLECharacteristicValueChange() {
  258. my.getConnectedBluetoothDevices({
  259. success: res => {
  260. if (res.devices.length === 0) {
  261. my.alert({ content: '没有已连接的设备' });
  262. return;
  263. }
  264. this.setData({
  265. devid: res.devices[0].deviceId,
  266. });
  267. my.notifyBLECharacteristicValueChange({
  268. state: true,
  269. deviceId: this.data.devid,
  270. serviceId: this.data.serid,
  271. characteristicId: this.data.notifyId,
  272. success: () => {
  273. //监听特征值变化的事件
  274. my.onBLECharacteristicValueChange({
  275. success: res => {
  276. // my.alert({content: '特征值变化:'+JSON.stringify(res)});
  277. my.alert({ content: '得到响应数据 = ' + res.value });
  278. },
  279. });
  280. my.alert({ content: '监听成功' });
  281. },
  282. fail: error => {
  283. my.alert({ content: '监听失败' + JSON.stringify(error) });
  284. },
  285. });
  286. },
  287. });
  288. },
  289. offBLECharacteristicValueChange() {
  290. my.offBLECharacteristicValueChange();
  291. },
  292. //其他事件
  293. bluetoothAdapterStateChange() {
  294. my.onBluetoothAdapterStateChange(this.getBind('onBluetoothAdapterStateChange'));
  295. },
  296. onBluetoothAdapterStateChange() {
  297. if (res.error) {
  298. my.alert({ content: JSON.stringify(error) });
  299. } else {
  300. my.alert({ content: '本机蓝牙状态变化:' + JSON.stringify(res) });
  301. }
  302. },
  303. offBluetoothAdapterStateChange() {
  304. my.offBluetoothAdapterStateChange(this.getBind('onBluetoothAdapterStateChange'));
  305. },
  306. getBind(name) {
  307. if (!this[`bind${name}`]) {
  308. this[`bind${name}`] = this[name].bind(this);
  309. }
  310. return this[`bind${name}`];
  311. },
  312. BLEConnectionStateChanged() {
  313. my.onBLEConnectionStateChanged(this.getBind('onBLEConnectionStateChanged'));
  314. },
  315. onBLEConnectionStateChanged(res) {
  316. if (res.error) {
  317. my.alert({ content: JSON.stringify(error) });
  318. } else {
  319. my.alert({ content: '连接状态变化:' + JSON.stringify(res) });
  320. }
  321. },
  322. offBLEConnectionStateChanged() {
  323. my.offBLEConnectionStateChanged(this.getBind('onBLEConnectionStateChanged'));
  324. },
  325. onUnload() {
  326. this.offBLEConnectionStateChanged();
  327. this.offBLECharacteristicValueChange();
  328. this.offBluetoothAdapterStateChange();
  329. this.closeBluetoothAdapter();
  330. },
  331. });

Bug & Tip

  • Tip:在调用 my.openBluetoothAdapter API之前,调用小程序其它蓝牙模块相关 API,API 会返回错误,
    • 错误码:10000
    • 错误描述:未初始化蓝牙适配器
    • 解决方案:请调用 my.openBluetoothAdapter
  • Bug: 在用户蓝牙开关未开启或者手机不支持蓝牙功能的情况下,调用 my.openBluetoothAdapter 会返回错误,错误码见 蓝牙 API 错误码对照表;此时小程序蓝牙模块已经初始化完成,可通过 my.onBluetoothAdapterStateChange 监听手机蓝牙状态的改变。

my.closeBluetoothAdapter

关闭本机蓝牙模块。

入参

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

代码示例

  1. my.closeBluetoothAdapter({
  2. success: (res) => {
  3. },
  4. fail:(res) => {
  5. },
  6. complete: (res)=>{
  7. }
  8. });

Bug & Tip

  • Tip:调用该方法将断开所有已建立的蓝牙连接并释放系统资源。

  • Tip:建议在结束小程序蓝牙流程时调用,与 my.openBluetoothAdapter 成对调用。

  • Tip:调用 my.closeBluetoothAdapter 释放资源为异步操作,不建议使用 my.closeBluetoothAdaptermy.openBluetoothAdapter 作为异常处理流程(相当于先关闭再开启,重新初始化,效率低,易发生线程同步问题)。

my.getBluetoothAdapterState

获取本机蓝牙模块状态。

入参

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

success 返回值

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

代码示例

  1. my.getBluetoothAdapterState({
  2. success: (res) => {
  3. console.log(res)
  4. },
  5. fail:(res) => {
  6. },
  7. complete: (res)=>{
  8. }
  9. });

my.startBluetoothDevicesDiscovery

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

入参

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

代码示例

  1. my.startBluetoothDevicesDiscovery({
  2. services: ['fff0'],
  3. success: (res) => {
  4. console.log(res)
  5. },
  6. fail:(res) => {
  7. },
  8. complete: (res)=>{
  9. }
  10. });

Bug & Tip

  • Tip:该操作比较耗费系统资源,请在搜索并连接到设备后调用 stop 方法停止搜索。

my.stopBluetoothDevicesDiscovery

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

入参

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

代码示例

  1. my.stopBluetoothDevicesDiscovery({
  2. success: (res) => {
  3. console.log(res)
  4. },
  5. fail:(res) => {
  6. },
  7. complete: (res)=>{
  8. }
  9. });

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

代码示例

  1. my.getBluetoothDevices({
  2. success: (res) => {
  3. console.log(res)
  4. },
  5. fail:(res) => {
  6. },
  7. complete: (res)=>{
  8. }
  9. });

Bug & Tip

  • Tip:模拟器可能无法获取 advertisData 及 RSSI,请使用真机调试。

  • Tip:开发者工具和 Android 上获取到的 deviceId 为设备 MAC 地址,iOS 上则为设备 uuid。因此 deviceId 不能硬编码到代码中,需要分平台处理,iOS 可根据设备属性( localName/advertisData/manufacturerData 等属性)进行动态匹配。

my.getConnectedBluetoothDevices

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

入参

名称 类型 必填 描述
deviceId String 蓝牙设备 ID。
success Function 调用成功的回调函数。
fail Function 调用失败的回调函数。
complete Function 调用结束的回调函数(调用成功、失败都会执行)。

代码示例

  1. my.getConnectedBluetoothDevices({
  2. success: (res) => {
  3. console.log(res)
  4. },
  5. fail:(res) => {
  6. },
  7. complete: (res)=>{
  8. }
  9. });

Bug & Tip

  • Tip:若小程序在之前已有搜索过某个蓝牙设备,即可直接传入之前搜索获取的 deviceId 尝试连接该设备,无需进行搜索操作。
  • Tip:若指定的蓝牙设备已经连接,重复连接将直接返回 success。

my.connectBLEDevice

连接低功耗蓝牙设备。

入参

名称 类型 必填 描述
deviceId String 蓝牙设备 ID。
success Function 调用成功的回调函数。
fail Function 调用失败的回调函数。
complete Function 调用结束的回调函数(调用成功、失败都会执行)。

代码示例

  1. my.connectBLEDevice({
  2. // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
  3. deviceId: deviceId,
  4. success: (res) => {
  5. console.log(res)
  6. },
  7. fail:(res) => {
  8. },
  9. complete: (res)=>{
  10. }
  11. });

Bug & Tip

  • Tip:若小程序在之前已有搜索过某个蓝牙设备,可直接传入之前搜索获取的 deviceId 直接尝试连接该设备,无需进行搜索操作。
  • Tip:若指定的蓝牙设备已经连接,重复连接直接返回成功。
  • Tip:支持 iOS 客户端,Android 5.0 及以上版本客户端。

my.disconnectBLEDevice

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

入参

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

代码示例

  1. my.disconnectBLEDevice({
  2. deviceId: deviceId,
  3. success: (res) => {
  4. console.log(res)
  5. },
  6. fail:(res) => {
  7. },
  8. complete: (res)=>{
  9. }
  10. });

Bug & Tip

  • Tip:蓝牙连接随时可能断开,建议监听 my.onBLEConnectionStateChanged 回调事件,当蓝牙设备断开时按需执行重连操作。
  • Tip:若对未连接的设备或已断开连接的设备调用数据读写操作的接口,会返回 10006 错误,详见 蓝牙 API 错误码对照表,建议进行重连操作。
  • Tip:支持 iOS 客户端,Android 5.0 及以上版本客户端。

my.writeBLECharacteristicValue

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

入参

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

代码示例

  1. my.writeBLECharacteristicValue({
  2. deviceId: deviceId,
  3. serviceId: serviceId,
  4. characteristicId: characteristicId,
  5. value: 'fffe',
  6. success: (res) => {
  7. console.log(res)
  8. },
  9. fail:(res) => {
  10. },
  11. complete: (res)=>{
  12. }
  13. });

Bug & Tip

  • Tip:设备的特征值必须支持 write 才可以成功调用,具体参照 characteristic 的 properties 属性。
  • Tip:写入的二进制数据需要进行 hex 编码。
  • Tip:支持 iOS 客户端,Android 5.0 及以上版本客户端。

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

代码示例

  1. my.readBLECharacteristicValue({
  2. deviceId: deviceId,
  3. serviceId: serviceId,
  4. characteristicId: characteristicId,
  5. success: (res) => {
  6. console.log(res)
  7. },
  8. fail:(res) => {
  9. },
  10. complete: (res)=>{
  11. }
  12. });

Bug & Tip

  • Tip:设备的特征值必须支持 read 才可以成功调用,具体参照 characteristic 的 properties 属性`。
  • Tip:并行多次调用读写接口存在读写失败的可能性。
  • Tip:如果读取超时,错误码 10015,my.onBLECharacteristicValueChange 接口之后可能返回数据,需要接入方酌情处理。错误码信息及解决方案请参见 蓝牙 API 错误码对照表
  • Tip:支持 iOS 客户端,Android 5.0 及以上版本客户端。

my.notifyBLECharacteristicValueChange

启用低功耗蓝牙设备特征值变化时的 notify 功能。

入参

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

代码示例

  1. my.notifyBLECharacteristicValueChange({
  2. deviceId: deviceId,
  3. serviceId: serviceId,
  4. characteristicId: characteristicId,
  5. success: (res) => {
  6. console.log(res)
  7. },
  8. fail:(res) => {
  9. },
  10. complete: (res)=>{
  11. }
  12. });

Bug & Tip

  • Tip:设备的特征值必须支持 notify/indicate 才可以成功调用,具体参照 characteristicproperties 属性。
  • Tip:必须先启用 notify 才能监听到设备 characteristicValueChange 事件。
  • Tip:订阅操作成功后需要设备主动更新特征值的 value,才会触发 my.onBLECharacteristicValueChange
  • Tip:订阅方式效率比较高,推荐使用订阅代替 read 方式。

my.getBLEDeviceServices

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

入参

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

success 返回值

名称 类型 描述
services Array 已发现的设备服务列表,详见下表特征值信息

service对象

蓝牙设备 service (服务)信息。

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

代码示例

  1. //获取连接设备的server,必须要在连接状态之下才能获取
  2. getBLEDeviceServices() {
  3. my.getConnectedBluetoothDevices({
  4. success: res => {
  5. if (res.devices.length === 0) {
  6. my.alert({ content: '没有已连接的设备' });
  7. return;
  8. }
  9. my.getBLEDeviceServices({
  10. deviceId: this.data.devid,
  11. success: res => {
  12. my.alert({ content: JSON.stringify(res) });
  13. this.setData({
  14. serid: res.services[0].serviceId,
  15. });
  16. },
  17. fail: error => {
  18. my.alert({ content: JSON.stringify(error) });
  19. },
  20. });
  21. },
  22. });
  23. },

返回值示例

  1. {
  2. "services": [{
  3. "isPrimary": true,
  4. "serviceId": "00001800-0000-1000-8000-00805f9b34fb"
  5. }, {
  6. "isPrimary": true,
  7. "serviceId": "00001801-0000-1000-8000-00805f9b34fb"
  8. }, {
  9. "isPrimary": true,
  10. "serviceId": "d0611e78-bbb4-4591-a5f8-487910ae4366"
  11. }, {
  12. "isPrimary": true,
  13. "serviceId": "9fa480e0-4967-4542-9390-d343dc5d04ae"
  14. }]
  15. }

Bug & Tip

  • Tip:建立连接后先执行 my.getBLEDeviceServicesmy.getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互。
  • Tip:支持 iOS 客户端,Android 5.0 及以上版本客户端。

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

代码示例

  1. my.getBLEDeviceCharacteristics({
  2. deviceId: deviceId,
  3. serviceId: serviceId,
  4. success: (res) => {
  5. console.log(res)
  6. },
  7. fail:(res) => {
  8. },
  9. complete: (res)=>{
  10. }
  11. });

Bug & Tip

  • Tip:建立连接后先执行 my.getBLEDeviceServicesmy.getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互。
  • Tip:支持 iOS 客户端,Android 5.0 及以上版本客户端。

my.onBluetoothDeviceFound(callback)

搜索到新的蓝牙设备时触发此事件。

入参

名称 类型 必填 描述
callback Function 事件发生时回调

callback 返回值

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

device 对象

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

代码示例

  1. Page({
  2. onLoad() {
  3. this.callback = this.callback.bind(this);
  4. my.onBluetoothDeviceFound(this.callback);
  5. },
  6. onUnload() {
  7. my.offBluetoothDeviceFound(this.callback);
  8. },
  9. callback(res) {
  10. console.log(res);
  11. },
  12. })

Bug & Tip

  • Tip:模拟器可能无法获取 advertisDataRSSI ,请使用真机调试。
  • Tip:开发者工具和 Android 上获取到的 deviceId 为设备 MAC 地址,iOS 上则为设备 uuid。因此 deviceId 不能硬编码到代码中,需要分平台处理,iOS 可根据设备属性(localName/advertisData/manufacturerData 等)进行动态匹配。
  • Tip:若在 my.onBluetoothDeviceFound 回调中包含了某个蓝牙设备,则此设备会添加到 my.getBluetoothDevices 接口获取到的数组中。

my.offBluetoothDeviceFound

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

代码示例

  1. my.offBluetoothDeviceFound();

是否需要传 callback 值

  • 不传递 callback 值,则会移除监听所有的事件监听回调。示例代码如下:
    1. my.offBluetoothDeviceFoun();
  • 传递 callback 值,只移除对应的 callback 事件。示例代码如下:
    1. my.offBluetoothDeviceFoun(this.callback);

Bug & Tip

  • Tip:为防止多次注册事件监听导致一次事件多次回调,建议每次调用 on 方法监听事件之前,先调用 off 方法,关闭之前的事件监听。

my.onBLECharacteristicValueChange(callback)

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

入参

名称 类型 必填 描述
callback Function 事件回调函数

callback 返回值

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

代码示例

  1. Page({
  2. onLoad() {
  3. this.callback = this.callback.bind(this);
  4. my.onBLECharacteristicValueChange(this.callback);
  5. },
  6. onUnload() {
  7. my.offBLECharacteristicValueChange(this.callback);
  8. },
  9. callback(res) {
  10. console.log(res);
  11. },
  12. })

Bug & Tip

  • Tip:为防止多次事件监听导致一次事件多次回调的情况,建议每次调用 on 方法监听事件之前,先调用 off 方法,关闭之前的事件监听。

my.offBLECharacteristicValueChange

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

入参

Function 类型。callback 回调函数入参为 Object 类型,属性如下:

属性 类型 描述
deviceId String 蓝牙设备 ID,参考 device 对象。
serviceId String 蓝牙特征值对应 service 的 UUID。
characteristicId String 蓝牙特征值的 UUID。
value Hex String 特征值最新的 16 进制值。

是否传递 callback 值示例

  • 不传递 callback 值,则会移除监听所有的事件监听回调。示例代码如下:
    1. my.offBLECharacteristicValueChange();
  • 传递 callback 值,只移除对应的 callback 事件。示例代码如下:
    1. my.offBLECharacteristicValueChange(this.callback);

代码示例

  1. Page({
  2. onLoad() {
  3. this.callback = this.callback.bind(this);
  4. my.onBLECharacteristicValueChange(this.callback);
  5. },
  6. onUnload() {
  7. my.offBLECharacteristicValueChange(this.callback);
  8. },
  9. callback(res) {
  10. console.log(res);
  11. },
  12. })

my.onBLEConnectionStateChanged(callback)

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

入参

名称 类型 必填 描述
callback Function 事件回调函数

callback 返回值

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

代码示例

  1. /* .acss */
  2. .help-info {
  3. padding:10px;
  4. color:#000000;
  5. }
  6. .help-title {
  7. padding:10px;
  8. color:#FC0D1B;
  9. }
  1. // .json
  2. {
  3. "defaultTitle": "Bluetooth"
  4. }
  1. <!-- .axml-->
  2. <view class="page">
  3. <view class="page-description">蓝牙 API</view>
  4. <view class="page-section">
  5. <view class="page-section-title">本机蓝牙开关状态</view>
  6. <view class="page-section-demo">
  7. <button type="primary" onTap="openBluetoothAdapter">初始化蓝牙</button>
  8. <button type="primary" onTap="closeBluetoothAdapter">关闭本机蓝牙</button>
  9. <button type="primary" onTap="getBluetoothAdapterState">获取蓝牙状态</button>
  10. </view>
  11. <view class="page-section-title">扫描蓝牙设备</view>
  12. <view class="page-section-demo">
  13. <button type="primary" onTap="startBluetoothDevicesDiscovery">开始搜索</button>
  14. <button type="primary" onTap="getBluetoothDevices">所有搜索到的设备</button>
  15. <button type="primary" onTap="getConnectedBluetoothDevices">所有已连接的设备</button>
  16. <button type="primary" onTap="stopBluetoothDevicesDiscovery">停止搜索</button>
  17. </view>
  18. <view class="page-section-title">连接设备</view>
  19. <view class="page-section-demo">
  20. <input class="input" onInput="bindKeyInput" type="{{text}}" placeholder="输入要连接的设备的deviceId"></input>
  21. <button type="primary" onTap="connectBLEDevice">连接设备</button>
  22. <button type="primary" onTap="getBLEDeviceServices">获取设备服务</button>
  23. <button type="primary" onTap="getBLEDeviceCharacteristics">获取读写特征</button>
  24. <button type="primary" onTap="disconnectBLEDevice">断开设备连接</button>
  25. </view>
  26. <view class="page-section-title">读写数据</view>
  27. <view class="page-section-demo">
  28. <button type="primary" onTap="notifyBLECharacteristicValueChange">监听特征值数据变化</button>
  29. <button type="primary" onTap="readBLECharacteristicValue">读取数据</button>
  30. <button type="primary" onTap="writeBLECharacteristicValue">写入数据</button>
  31. <button type="primary" onTap="offBLECharacteristicValueChange">取消特征值监听</button>
  32. </view>
  33. <view class="page-section-title">其他事件</view>
  34. <view class="page-section-demo">
  35. <button type="primary" onTap="bluetoothAdapterStateChange">本机蓝牙状态变化</button>
  36. <button type="primary" onTap="offBluetoothAdapterStateChange">取消本机蓝牙状态监听</button>
  37. <button type="primary" onTap="BLEConnectionStateChanged">蓝牙连接状态变化</button>
  38. <button type="primary" onTap="offBLEConnectionStateChanged">取消蓝牙连接状态监听</button>
  39. </view>
  40. </view>
  41. </view>
  1. // .js
  2. Page({
  3. data: {
  4. devid: '0D9C82AD-1CC0-414D-9526-119E08D28124',
  5. serid: 'FEE7',
  6. notifyId: '36F6',
  7. writeId: '36F5',
  8. charid: '',
  9. alldev: [{ deviceId: '' }],
  10. },
  11. //获取本机蓝牙开关状态
  12. openBluetoothAdapter() {
  13. my.openBluetoothAdapter({
  14. success: res => {
  15. if (!res.isSupportBLE) {
  16. my.alert({ content: '抱歉,您的手机蓝牙暂不可用' });
  17. return;
  18. }
  19. my.alert({ content: '初始化成功!' });
  20. },
  21. fail: error => {
  22. my.alert({ content: JSON.stringify(error) });
  23. },
  24. });
  25. },
  26. closeBluetoothAdapter() {
  27. my.closeBluetoothAdapter({
  28. success: () => {
  29. my.alert({ content: '关闭蓝牙成功!' });
  30. },
  31. fail: error => {
  32. my.alert({ content: JSON.stringify(error) });
  33. },
  34. });
  35. },
  36. getBluetoothAdapterState() {
  37. my.getBluetoothAdapterState({
  38. success: res => {
  39. if (!res.available) {
  40. my.alert({ content: '抱歉,您的手机蓝牙暂不可用' });
  41. return;
  42. }
  43. my.alert({ content: JSON.stringify(res) });
  44. },
  45. fail: error => {
  46. my.alert({ content: JSON.stringify(error) });
  47. },
  48. });
  49. },
  50. //扫描蓝牙设备
  51. startBluetoothDevicesDiscovery() {
  52. my.startBluetoothDevicesDiscovery({
  53. allowDuplicatesKey: false,
  54. success: () => {
  55. my.onBluetoothDeviceFound({
  56. success: res => {
  57. // my.alert({content:'监听新设备'+JSON.stringify(res)});
  58. var deviceArray = res.devices;
  59. for (var i = deviceArray.length - 1; i >= 0; i--) {
  60. var deviceObj = deviceArray[i];
  61. //通过设备名称或者广播数据匹配目标设备,然后记录deviceID后面使用
  62. if (deviceObj.name == this.data.name) {
  63. my.alert({ content: '目标设备被找到' });
  64. my.offBluetoothDeviceFound();
  65. this.setData({
  66. deviceId: deviceObj.deviceId,
  67. });
  68. break;
  69. }
  70. }
  71. },
  72. fail: error => {
  73. my.alert({ content: '监听新设备失败' + JSON.stringify(error) });
  74. },
  75. });
  76. },
  77. fail: error => {
  78. my.alert({ content: '启动扫描失败' + JSON.stringify(error) });
  79. },
  80. });
  81. },
  82. //停止扫描
  83. stopBluetoothDevicesDiscovery() {
  84. my.stopBluetoothDevicesDiscovery({
  85. success: res => {
  86. my.offBluetoothDeviceFound();
  87. my.alert({ content: '操作成功!' });
  88. },
  89. fail: error => {
  90. my.alert({ content: JSON.stringify(error) });
  91. },
  92. });
  93. },
  94. //获取正在连接中的设备
  95. getConnectedBluetoothDevices() {
  96. my.getConnectedBluetoothDevices({
  97. success: res => {
  98. if (res.devices.length === 0) {
  99. my.alert({ content: '没有在连接中的设备!' });
  100. return;
  101. }
  102. my.alert({ content: JSON.stringify(res) });
  103. devid = res.devices[0].deviceId;
  104. },
  105. fail: error => {
  106. my.alert({ content: JSON.stringify(error) });
  107. },
  108. });
  109. },
  110. //获取所有搜索到的设备
  111. getBluetoothDevices() {
  112. my.getBluetoothDevices({
  113. success: res => {
  114. my.alert({ content: JSON.stringify(res) });
  115. },
  116. fail: error => {
  117. my.alert({ content: JSON.stringify(error) });
  118. },
  119. });
  120. },
  121. bindKeyInput(e) {
  122. this.setData({
  123. devid: e.detail.value,
  124. });
  125. },
  126. //连接设备
  127. connectBLEDevice() {
  128. my.connectBLEDevice({
  129. deviceId: this.data.devid,
  130. success: res => {
  131. my.alert({ content: '连接成功' });
  132. },
  133. fail: error => {
  134. my.alert({ content: JSON.stringify(error) });
  135. },
  136. });
  137. },
  138. //断开连接
  139. disconnectBLEDevice() {
  140. my.disconnectBLEDevice({
  141. deviceId: this.data.devid,
  142. success: () => {
  143. my.alert({ content: '断开连接成功!' });
  144. },
  145. fail: error => {
  146. my.alert({ content: JSON.stringify(error) });
  147. },
  148. });
  149. },
  150. //获取连接设备的server,必须要再连接状态之下才能获取
  151. getBLEDeviceServices() {
  152. my.getConnectedBluetoothDevices({
  153. success: res => {
  154. if (res.devices.length === 0) {
  155. my.alert({ content: '没有已连接的设备' });
  156. return;
  157. }
  158. my.getBLEDeviceServices({
  159. deviceId: this.data.devid,
  160. success: res => {
  161. my.alert({ content: JSON.stringify(res) });
  162. this.setData({
  163. serid: res.services[0].serviceId,
  164. });
  165. },
  166. fail: error => {
  167. my.alert({ content: JSON.stringify(error) });
  168. },
  169. });
  170. },
  171. });
  172. },
  173. //获取连接设备的charid,必须要再连接状态之下才能获取(这里分别筛选出读写特征字)
  174. getBLEDeviceCharacteristics() {
  175. my.getConnectedBluetoothDevices({
  176. success: res => {
  177. if (res.devices.length === 0) {
  178. my.alert({ content: '没有已连接的设备' });
  179. return;
  180. }
  181. this.setData({
  182. devid: res.devices[0].deviceId,
  183. });
  184. my.getBLEDeviceCharacteristics({
  185. deviceId: this.data.devid,
  186. serviceId: this.data.serid,
  187. success: res => {
  188. my.alert({ content: JSON.stringify(res) });
  189. //特征字对象属性见文档,根据属性匹配读写特征字并记录,然后后面读写使用
  190. this.setData({
  191. charid: res.characteristics[0].characteristicId,
  192. });
  193. },
  194. fail: error => {
  195. my.alert({ content: JSON.stringify(error) });
  196. },
  197. });
  198. },
  199. });
  200. },
  201. //读写数据
  202. readBLECharacteristicValue() {
  203. my.getConnectedBluetoothDevices({
  204. success: res => {
  205. if (res.devices.length === 0) {
  206. my.alert({ content: '没有已连接的设备' });
  207. return;
  208. }
  209. this.setData({
  210. devid: res.devices[0].deviceId,
  211. });
  212. my.readBLECharacteristicValue({
  213. deviceId: this.data.devid,
  214. serviceId: this.data.serid,
  215. characteristicId: this.data.notifyId,
  216. //1、安卓读取服务
  217. // serviceId:'0000180d-0000-1000-8000-00805f9b34fb',
  218. // characteristicId:'00002a38-0000-1000-8000-00805f9b34fb',
  219. success: res => {
  220. my.alert({ content: JSON.stringify(res) });
  221. },
  222. fail: error => {
  223. my.alert({ content: '读取失败' + JSON.stringify(error) });
  224. },
  225. });
  226. },
  227. });
  228. },
  229. writeBLECharacteristicValue() {
  230. my.getConnectedBluetoothDevices({
  231. success: res => {
  232. if (res.devices.length === 0) {
  233. my.alert({ content: '没有已连接的设备' });
  234. return;
  235. }
  236. this.setData({
  237. devid: res.devices[0].deviceId,
  238. });
  239. my.writeBLECharacteristicValue({
  240. deviceId: this.data.devid,
  241. serviceId: this.data.serid,
  242. characteristicId: this.data.charid,
  243. //安卓写入服务
  244. //serviceId:'0000180d-0000-1000-8000-00805f9b34fb',
  245. //characteristicId:'00002a39-0000-1000-8000-00805f9b34fb',
  246. value: 'ABCD',
  247. success: res => {
  248. my.alert({ content: '写入数据成功!' });
  249. },
  250. fail: error => {
  251. my.alert({ content: JSON.stringify(error) });
  252. },
  253. });
  254. },
  255. });
  256. },
  257. notifyBLECharacteristicValueChange() {
  258. my.getConnectedBluetoothDevices({
  259. success: res => {
  260. if (res.devices.length === 0) {
  261. my.alert({ content: '没有已连接的设备' });
  262. return;
  263. }
  264. this.setData({
  265. devid: res.devices[0].deviceId,
  266. });
  267. my.notifyBLECharacteristicValueChange({
  268. state: true,
  269. deviceId: this.data.devid,
  270. serviceId: this.data.serid,
  271. characteristicId: this.data.notifyId,
  272. success: () => {
  273. //监听特征值变化的事件
  274. my.onBLECharacteristicValueChange({
  275. success: res => {
  276. // my.alert({content: '特征值变化:'+JSON.stringify(res)});
  277. my.alert({ content: '得到响应数据 = ' + res.value });
  278. },
  279. });
  280. my.alert({ content: '监听成功' });
  281. },
  282. fail: error => {
  283. my.alert({ content: '监听失败' + JSON.stringify(error) });
  284. },
  285. });
  286. },
  287. });
  288. },
  289. offBLECharacteristicValueChange() {
  290. my.offBLECharacteristicValueChange();
  291. },
  292. //其他事件
  293. bluetoothAdapterStateChange() {
  294. my.onBluetoothAdapterStateChange(this.getBind('onBluetoothAdapterStateChange'));
  295. },
  296. onBluetoothAdapterStateChange() {
  297. if (res.error) {
  298. my.alert({ content: JSON.stringify(error) });
  299. } else {
  300. my.alert({ content: '本机蓝牙状态变化:' + JSON.stringify(res) });
  301. }
  302. },
  303. offBluetoothAdapterStateChange() {
  304. my.offBluetoothAdapterStateChange(this.getBind('onBluetoothAdapterStateChange'));
  305. },
  306. getBind(name) {
  307. if (!this[`bind${name}`]) {
  308. this[`bind${name}`] = this[name].bind(this);
  309. }
  310. return this[`bind${name}`];
  311. },
  312. BLEConnectionStateChanged() {
  313. my.onBLEConnectionStateChanged(this.getBind('onBLEConnectionStateChanged'));
  314. },
  315. onBLEConnectionStateChanged(res) {
  316. if (res.error) {
  317. my.alert({ content: JSON.stringify(error) });
  318. } else {
  319. my.alert({ content: '连接状态变化:' + JSON.stringify(res) });
  320. }
  321. },
  322. offBLEConnectionStateChanged() {
  323. my.offBLEConnectionStateChanged(this.getBind('onBLEConnectionStateChanged'));
  324. },
  325. onUnload() {
  326. this.offBLEConnectionStateChanged();
  327. this.offBLECharacteristicValueChange();
  328. this.offBluetoothAdapterStateChange();
  329. this.closeBluetoothAdapter();
  330. },
  331. });

Bug & Tip

  • Tip:为防止多次注册事件监听导致一次事件多次回调,建议每次调用 on 方法监听事件之前,先调用 off 方法,关闭之前的事件监听。

my.offBLEConnectionStateChanged

移除低功耗蓝牙连接状态变化事件的监听。

代码示例

  1. my.offBLEConnectionStateChanged();

是否需要传 callback 值

  • 不传递 callback 值,则会移除监听所有的事件监听回调。示例代码如下:
    1. my.offBLEConnectionStateChanged();
  • 传递 callback 值,只移除对应的 callback 事件。示例代码如下:
    1. my.offBLEConnectionStateChanged(this.callback);

Bug & Tip

  • Tip:为防止多次注册事件监听导致一次事件多次回调,建议每次调用 on 方法监听事件之前,先调用 off 方法,关闭之前的事件监听。

my.onBluetoothAdapterStateChange(callback)

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

入参

名称 类型 必填 描述
callback Function 事件回调函数

callback 返回值

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

代码示例

  1. /* .acss */
  2. .help-info {
  3. padding:10px;
  4. color:#000000;
  5. }
  6. .help-title {
  7. padding:10px;
  8. color:#FC0D1B;
  9. }
  1. // .json
  2. {
  3. "defaultTitle": "Bluetooth"
  4. }
  1. <!-- .axml-->
  2. <view class="page">
  3. <view class="page-description">蓝牙 API</view>
  4. <view class="page-section">
  5. <view class="page-section-title">本机蓝牙开关状态</view>
  6. <view class="page-section-demo">
  7. <button type="primary" onTap="openBluetoothAdapter">初始化蓝牙</button>
  8. <button type="primary" onTap="closeBluetoothAdapter">关闭本机蓝牙</button>
  9. <button type="primary" onTap="getBluetoothAdapterState">获取蓝牙状态</button>
  10. </view>
  11. <view class="page-section-title">扫描蓝牙设备</view>
  12. <view class="page-section-demo">
  13. <button type="primary" onTap="startBluetoothDevicesDiscovery">开始搜索</button>
  14. <button type="primary" onTap="getBluetoothDevices">所有搜索到的设备</button>
  15. <button type="primary" onTap="getConnectedBluetoothDevices">所有已连接的设备</button>
  16. <button type="primary" onTap="stopBluetoothDevicesDiscovery">停止搜索</button>
  17. </view>
  18. <view class="page-section-title">连接设备</view>
  19. <view class="page-section-demo">
  20. <input class="input" onInput="bindKeyInput" type="{{text}}" placeholder="输入要连接的设备的deviceId"></input>
  21. <button type="primary" onTap="connectBLEDevice">连接设备</button>
  22. <button type="primary" onTap="getBLEDeviceServices">获取设备服务</button>
  23. <button type="primary" onTap="getBLEDeviceCharacteristics">获取读写特征</button>
  24. <button type="primary" onTap="disconnectBLEDevice">断开设备连接</button>
  25. </view>
  26. <view class="page-section-title">读写数据</view>
  27. <view class="page-section-demo">
  28. <button type="primary" onTap="notifyBLECharacteristicValueChange">监听特征值数据变化</button>
  29. <button type="primary" onTap="readBLECharacteristicValue">读取数据</button>
  30. <button type="primary" onTap="writeBLECharacteristicValue">写入数据</button>
  31. <button type="primary" onTap="offBLECharacteristicValueChange">取消特征值监听</button>
  32. </view>
  33. <view class="page-section-title">其他事件</view>
  34. <view class="page-section-demo">
  35. <button type="primary" onTap="bluetoothAdapterStateChange">本机蓝牙状态变化</button>
  36. <button type="primary" onTap="offBluetoothAdapterStateChange">取消本机蓝牙状态监听</button>
  37. <button type="primary" onTap="BLEConnectionStateChanged">蓝牙连接状态变化</button>
  38. <button type="primary" onTap="offBLEConnectionStateChanged">取消蓝牙连接状态监听</button>
  39. </view>
  40. </view>
  41. </view>
  1. // .js
  2. Page({
  3. data: {
  4. devid: '0D9C82AD-1CC0-414D-9526-119E08D28124',
  5. serid: 'FEE7',
  6. notifyId: '36F6',
  7. writeId: '36F5',
  8. charid: '',
  9. alldev: [{ deviceId: '' }],
  10. },
  11. //获取本机蓝牙开关状态
  12. openBluetoothAdapter() {
  13. my.openBluetoothAdapter({
  14. success: res => {
  15. if (!res.isSupportBLE) {
  16. my.alert({ content: '抱歉,您的手机蓝牙暂不可用' });
  17. return;
  18. }
  19. my.alert({ content: '初始化成功!' });
  20. },
  21. fail: error => {
  22. my.alert({ content: JSON.stringify(error) });
  23. },
  24. });
  25. },
  26. closeBluetoothAdapter() {
  27. my.closeBluetoothAdapter({
  28. success: () => {
  29. my.alert({ content: '关闭蓝牙成功!' });
  30. },
  31. fail: error => {
  32. my.alert({ content: JSON.stringify(error) });
  33. },
  34. });
  35. },
  36. getBluetoothAdapterState() {
  37. my.getBluetoothAdapterState({
  38. success: res => {
  39. if (!res.available) {
  40. my.alert({ content: '抱歉,您的手机蓝牙暂不可用' });
  41. return;
  42. }
  43. my.alert({ content: JSON.stringify(res) });
  44. },
  45. fail: error => {
  46. my.alert({ content: JSON.stringify(error) });
  47. },
  48. });
  49. },
  50. //扫描蓝牙设备
  51. startBluetoothDevicesDiscovery() {
  52. my.startBluetoothDevicesDiscovery({
  53. allowDuplicatesKey: false,
  54. success: () => {
  55. my.onBluetoothDeviceFound({
  56. success: res => {
  57. // my.alert({content:'监听新设备'+JSON.stringify(res)});
  58. var deviceArray = res.devices;
  59. for (var i = deviceArray.length - 1; i >= 0; i--) {
  60. var deviceObj = deviceArray[i];
  61. //通过设备名称或者广播数据匹配目标设备,然后记录deviceID后面使用
  62. if (deviceObj.name == this.data.name) {
  63. my.alert({ content: '目标设备被找到' });
  64. my.offBluetoothDeviceFound();
  65. this.setData({
  66. deviceId: deviceObj.deviceId,
  67. });
  68. break;
  69. }
  70. }
  71. },
  72. fail: error => {
  73. my.alert({ content: '监听新设备失败' + JSON.stringify(error) });
  74. },
  75. });
  76. },
  77. fail: error => {
  78. my.alert({ content: '启动扫描失败' + JSON.stringify(error) });
  79. },
  80. });
  81. },
  82. //停止扫描
  83. stopBluetoothDevicesDiscovery() {
  84. my.stopBluetoothDevicesDiscovery({
  85. success: res => {
  86. my.offBluetoothDeviceFound();
  87. my.alert({ content: '操作成功!' });
  88. },
  89. fail: error => {
  90. my.alert({ content: JSON.stringify(error) });
  91. },
  92. });
  93. },
  94. //获取正在连接中的设备
  95. getConnectedBluetoothDevices() {
  96. my.getConnectedBluetoothDevices({
  97. success: res => {
  98. if (res.devices.length === 0) {
  99. my.alert({ content: '没有在连接中的设备!' });
  100. return;
  101. }
  102. my.alert({ content: JSON.stringify(res) });
  103. devid = res.devices[0].deviceId;
  104. },
  105. fail: error => {
  106. my.alert({ content: JSON.stringify(error) });
  107. },
  108. });
  109. },
  110. //获取所有搜索到的设备
  111. getBluetoothDevices() {
  112. my.getBluetoothDevices({
  113. success: res => {
  114. my.alert({ content: JSON.stringify(res) });
  115. },
  116. fail: error => {
  117. my.alert({ content: JSON.stringify(error) });
  118. },
  119. });
  120. },
  121. bindKeyInput(e) {
  122. this.setData({
  123. devid: e.detail.value,
  124. });
  125. },
  126. //连接设备
  127. connectBLEDevice() {
  128. my.connectBLEDevice({
  129. deviceId: this.data.devid,
  130. success: res => {
  131. my.alert({ content: '连接成功' });
  132. },
  133. fail: error => {
  134. my.alert({ content: JSON.stringify(error) });
  135. },
  136. });
  137. },
  138. //断开连接
  139. disconnectBLEDevice() {
  140. my.disconnectBLEDevice({
  141. deviceId: this.data.devid,
  142. success: () => {
  143. my.alert({ content: '断开连接成功!' });
  144. },
  145. fail: error => {
  146. my.alert({ content: JSON.stringify(error) });
  147. },
  148. });
  149. },
  150. //获取连接设备的server,必须要再连接状态之下才能获取
  151. getBLEDeviceServices() {
  152. my.getConnectedBluetoothDevices({
  153. success: res => {
  154. if (res.devices.length === 0) {
  155. my.alert({ content: '没有已连接的设备' });
  156. return;
  157. }
  158. my.getBLEDeviceServices({
  159. deviceId: this.data.devid,
  160. success: res => {
  161. my.alert({ content: JSON.stringify(res) });
  162. this.setData({
  163. serid: res.services[0].serviceId,
  164. });
  165. },
  166. fail: error => {
  167. my.alert({ content: JSON.stringify(error) });
  168. },
  169. });
  170. },
  171. });
  172. },
  173. //获取连接设备的charid,必须要再连接状态之下才能获取(这里分别筛选出读写特征字)
  174. getBLEDeviceCharacteristics() {
  175. my.getConnectedBluetoothDevices({
  176. success: res => {
  177. if (res.devices.length === 0) {
  178. my.alert({ content: '没有已连接的设备' });
  179. return;
  180. }
  181. this.setData({
  182. devid: res.devices[0].deviceId,
  183. });
  184. my.getBLEDeviceCharacteristics({
  185. deviceId: this.data.devid,
  186. serviceId: this.data.serid,
  187. success: res => {
  188. my.alert({ content: JSON.stringify(res) });
  189. //特征字对象属性见文档,根据属性匹配读写特征字并记录,然后后面读写使用
  190. this.setData({
  191. charid: res.characteristics[0].characteristicId,
  192. });
  193. },
  194. fail: error => {
  195. my.alert({ content: JSON.stringify(error) });
  196. },
  197. });
  198. },
  199. });
  200. },
  201. //读写数据
  202. readBLECharacteristicValue() {
  203. my.getConnectedBluetoothDevices({
  204. success: res => {
  205. if (res.devices.length === 0) {
  206. my.alert({ content: '没有已连接的设备' });
  207. return;
  208. }
  209. this.setData({
  210. devid: res.devices[0].deviceId,
  211. });
  212. my.readBLECharacteristicValue({
  213. deviceId: this.data.devid,
  214. serviceId: this.data.serid,
  215. characteristicId: this.data.notifyId,
  216. //1、安卓读取服务
  217. // serviceId:'0000180d-0000-1000-8000-00805f9b34fb',
  218. // characteristicId:'00002a38-0000-1000-8000-00805f9b34fb',
  219. success: res => {
  220. my.alert({ content: JSON.stringify(res) });
  221. },
  222. fail: error => {
  223. my.alert({ content: '读取失败' + JSON.stringify(error) });
  224. },
  225. });
  226. },
  227. });
  228. },
  229. writeBLECharacteristicValue() {
  230. my.getConnectedBluetoothDevices({
  231. success: res => {
  232. if (res.devices.length === 0) {
  233. my.alert({ content: '没有已连接的设备' });
  234. return;
  235. }
  236. this.setData({
  237. devid: res.devices[0].deviceId,
  238. });
  239. my.writeBLECharacteristicValue({
  240. deviceId: this.data.devid,
  241. serviceId: this.data.serid,
  242. characteristicId: this.data.charid,
  243. //安卓写入服务
  244. //serviceId:'0000180d-0000-1000-8000-00805f9b34fb',
  245. //characteristicId:'00002a39-0000-1000-8000-00805f9b34fb',
  246. value: 'ABCD',
  247. success: res => {
  248. my.alert({ content: '写入数据成功!' });
  249. },
  250. fail: error => {
  251. my.alert({ content: JSON.stringify(error) });
  252. },
  253. });
  254. },
  255. });
  256. },
  257. notifyBLECharacteristicValueChange() {
  258. my.getConnectedBluetoothDevices({
  259. success: res => {
  260. if (res.devices.length === 0) {
  261. my.alert({ content: '没有已连接的设备' });
  262. return;
  263. }
  264. this.setData({
  265. devid: res.devices[0].deviceId,
  266. });
  267. my.notifyBLECharacteristicValueChange({
  268. state: true,
  269. deviceId: this.data.devid,
  270. serviceId: this.data.serid,
  271. characteristicId: this.data.notifyId,
  272. success: () => {
  273. //监听特征值变化的事件
  274. my.onBLECharacteristicValueChange({
  275. success: res => {
  276. // my.alert({content: '特征值变化:'+JSON.stringify(res)});
  277. my.alert({ content: '得到响应数据 = ' + res.value });
  278. },
  279. });
  280. my.alert({ content: '监听成功' });
  281. },
  282. fail: error => {
  283. my.alert({ content: '监听失败' + JSON.stringify(error) });
  284. },
  285. });
  286. },
  287. });
  288. },
  289. offBLECharacteristicValueChange() {
  290. my.offBLECharacteristicValueChange();
  291. },
  292. //其他事件
  293. bluetoothAdapterStateChange() {
  294. my.onBluetoothAdapterStateChange(this.getBind('onBluetoothAdapterStateChange'));
  295. },
  296. onBluetoothAdapterStateChange() {
  297. if (res.error) {
  298. my.alert({ content: JSON.stringify(error) });
  299. } else {
  300. my.alert({ content: '本机蓝牙状态变化:' + JSON.stringify(res) });
  301. }
  302. },
  303. offBluetoothAdapterStateChange() {
  304. my.offBluetoothAdapterStateChange(this.getBind('onBluetoothAdapterStateChange'));
  305. },
  306. getBind(name) {
  307. if (!this[`bind${name}`]) {
  308. this[`bind${name}`] = this[name].bind(this);
  309. }
  310. return this[`bind${name}`];
  311. },
  312. BLEConnectionStateChanged() {
  313. my.onBLEConnectionStateChanged(this.getBind('onBLEConnectionStateChanged'));
  314. },
  315. onBLEConnectionStateChanged(res) {
  316. if (res.error) {
  317. my.alert({ content: JSON.stringify(error) });
  318. } else {
  319. my.alert({ content: '连接状态变化:' + JSON.stringify(res) });
  320. }
  321. },
  322. offBLEConnectionStateChanged() {
  323. my.offBLEConnectionStateChanged(this.getBind('onBLEConnectionStateChanged'));
  324. },
  325. onUnload() {
  326. this.offBLEConnectionStateChanged();
  327. this.offBLECharacteristicValueChange();
  328. this.offBluetoothAdapterStateChange();
  329. this.closeBluetoothAdapter();
  330. },
  331. });

my.offBluetoothAdapterStateChange

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

代码示例

  1. my.offBluetoothAdapterStateChange();

是否需要传 callback 值

  • 不传递 callback 值,则会移除监听所有的事件监听回调。示例代码如下:
    1. my.offBluetoothAdapterStateChange();
  • 传递 callback 值,只移除对应的 callback 事件。示例代码如下:
    1. my.offBluetoothAdapterStateChange(this.callback);

Bug & Tip

  • Tip:为防止多次注册事件监听导致一次事件多次回调,建议每次调用 on 方法监听事件之前,先调用 off 方法,关闭之前的事件监听。